From fc424fdb062c714abd70444e31178b728c16bc2e Mon Sep 17 00:00:00 2001 From: rstoyanchev Date: Thu, 5 May 2022 16:21:40 +0100 Subject: [PATCH] Improve WebSocket and RSocket client reference docs Provide advice around number of client instances and connection-oriented nature. Closes gh-368 --- .../src/docs/asciidoc/client.adoc | 61 ++++++++++++------- .../src/docs/asciidoc/testing.adoc | 21 +++++-- 2 files changed, 55 insertions(+), 27 deletions(-) diff --git a/spring-graphql-docs/src/docs/asciidoc/client.adoc b/spring-graphql-docs/src/docs/asciidoc/client.adoc index 0d318464..6dbe5192 100644 --- a/spring-graphql-docs/src/docs/asciidoc/client.adoc +++ b/spring-graphql-docs/src/docs/asciidoc/client.adoc @@ -73,18 +73,34 @@ existing `HttpGraphQlClient` to create a new instance with customized settings: [[client-websocketgraphqlclient]] === WebSocket -`WebSocketGraphQlClient` uses +`WebSocketGraphQlClient` executes GraphQL requests over a shared WebSocket connection. +It is built using the {spring-framework-ref-docs}/web-reactive.html#webflux-websocket-client[WebSocketClient] -from Spring WebFlux to execute GraphQL requests over WebSocket: +from Spring WebFlux and you can create it as follows: [source,java,indent=0,subs="verbatim,quotes"] ---- - String url = "http://localhost:8080/graphql"; + String url = "wss://localhost:8080/graphql"; WebSocketClient client = new ReactorNettyWebSocketClient(); WebSocketGraphQlClient graphQlClient = WebSocketGraphQlClient.builder(url, client).build(); ---- +In contrast to `HttpGraphQlClient`, the `WebSocketGraphQlClient` is connection oriented, +which means it needs to establish a connection before making any requests. As you begin +to make requests, the connection is established transparently. Alternatively, use the +client's `start()` method to establish the connection explicitly before any requests. + +In addition to being connection-oriented, `WebSocketGraphQlClient` is also multiplexed. +It maintains a single, shared connection for all requests. If the connection is lost, +it is re-established on the next request or if `start()` is called again. You can also +use the client's `stop()` method which cancels in-progress requests, closes the +connection, and rejects new requests. + +TIP: Use a single `WebSocketGraphQlClient` instance for each server in order to have a +single, shared connection for all requests to that server. Each client instance +establishes its own connection and that is typically not the intent for a single server. + Once `WebSocketGraphQlClient` is created, you can begin to <> using the same API, independent of the underlying transport. If you need to change any transport specific details, use `mutate()` on an @@ -110,22 +126,6 @@ existing `WebSocketGraphQlClient` to create a new instance with customized setti ---- -[[client-websocketgraphqlclient-connection]] -==== Connection - -A connection is established transparently when requests are made. There is only one -shared, active connection at a time. If the connection is lost, it is re-established on -the next request. - -`WebSocketGraphQlClient` also exposes lifecycle methods: - -- `start()` - connect the WebSocket and initialize the GraphQL session. This can be used -on startup up to be ready for requests, but it is not required. -- `stop()` - cancels ongoing requests and subscriptions, and closes the connection. A -stopped client rejects new requests. Use `start()` to re-establish the connection and -allow requests again. - - [[client-websocketgraphqlclient-interceptor]] ==== Interceptor @@ -169,12 +169,27 @@ to execute GraphQL requests over RSocket requests. [source,java,indent=0,subs="verbatim,quotes"] ---- - RSocketGraphQlClient graphQlClient = - RSocketGraphQlClient.builder() - .websocket(URI.create("http://localhost:8080/graphql")) - .build(); + URI uri = URI.create("wss://localhost:8080/rsocket"); + WebsocketClientTransport transport = WebsocketClientTransport.create(url); + + RSocketGraphQlClient client = RSocketGraphQlClient.builder() + .clientTransport(transport) + .build(); ---- +In contrast to `HttpGraphQlClient`, the `RSocketGraphQlClient` is connection oriented, +which means it needs to establish a connection before making any requests. As you begin +to make requests, the connection is established transparently. + +`RSocketGraphQlClient` is also multiplexed. It maintains a single, shared connection for +all requests. If the connection is lost, it is re-established on the next request. You +can use the `dispose()` method on the underlying `RSocketRequester` to close the +connection explicitly. + +TIP: Use a single `RSocketGraphQlClient` instance for each server in order to have a +single, shared connection for all requests to that server. Each client instance +establishes its own connection and that is typically not the intent for a single server. + Once `RSocketGraphQlClient` is created, you can begin to <> using the same API, independent of the underlying transport. diff --git a/spring-graphql-docs/src/docs/asciidoc/testing.adoc b/spring-graphql-docs/src/docs/asciidoc/testing.adoc index 984c4b63..cd9b6560 100644 --- a/spring-graphql-docs/src/docs/asciidoc/testing.adoc +++ b/spring-graphql-docs/src/docs/asciidoc/testing.adoc @@ -139,9 +139,10 @@ existing `HttpSocketGraphQlTester` to create a new instance with customized sett [[testing-websocketgraphqltester]] === WebSocket -`WebSocketGraphQlTester` uses +`WebSocketGraphQlTester` executes GraphQL requests over a shared WebSocket connection. +It is built using the {spring-framework-ref-docs}/web-reactive.html#webflux-websocket-client[WebSocketClient] -from Spring WebFlux to execute GraphQL requests over WebSocket: +from Spring WebFlux and you can create it as follows: [source,java,indent=0,subs="verbatim,quotes"] ---- @@ -151,6 +152,10 @@ from Spring WebFlux to execute GraphQL requests over WebSocket: WebSocketGraphQlTester tester = WebSocketGraphQlTester.builder(url, client).build(); ---- +`WebSocketGraphQlTester` is connection oriented and multiplexed. Each instance establishes +its own single, shared connection for all requests. Typically, you'll want to use a single +instance only per server. + Once `WebSocketGraphQlTester` is created, you can begin to <> using the same API, independent of the underlying transport. If you need to change any transport specific details, use `mutate()` on an @@ -188,11 +193,19 @@ requests over RSocket: [source,java,indent=0,subs="verbatim,quotes"] ---- - RSocketGraphQlTester tester = RSocketGraphQlTester.builder() - .webSocket(URI.create("http://localhost:8080/graphql")) + URI uri = URI.create("wss://localhost:8080/rsocket"); + WebsocketClientTransport transport = WebsocketClientTransport.create(url); + + RSocketGraphQlTester client = RSocketGraphQlTester.builder() + .clientTransport(transport) .build(); ---- +`RSocketGraphQlTester` is connection oriented and multiplexed. Each instance establishes +its own single, shared connection for all requests. Typically, you'll want to use a single +instance only per server. You can use the `dispose()` method on the underlying +`RSocketRequester` to close the connection explicitly. + Once `RSocketGraphQlTester` is created, you can begin to <> using the same API, independent of the underlying transport.