diff --git a/docs/advanced/subscriptions.md b/docs/advanced/subscriptions.md index 2152c6bb..f7313580 100644 --- a/docs/advanced/subscriptions.md +++ b/docs/advanced/subscriptions.md @@ -15,9 +15,9 @@ import org.reactivestreams.Publisher; @DgsSubscription public Publisher stocks() { - //Create a never-ending Flux that emits an item every second - return Flux.interval(Duration.ofSeconds(1)).map({ t -> Stock("NFLX", 500 + t) }) -} + //Create a never-ending Flux that emits an item every second + return Flux.interval(Duration.ofSeconds(1)).map({ t -> Stock("NFLX", 500 + t) }) + } ``` The `Publisher` interface is from Reactive Streams. @@ -36,14 +36,24 @@ To enable WebSockets support, add the following module to your `build.gradle`: ```groovy implementation 'com.netflix.graphql.dgs:graphql-dgs-subscriptions-websockets-autoconfigure:latest.release' ``` +Please note: DGS does not currently support the newer version of the WebSocket protocol as specified [here](https://github.com/enisdenjo/graphql-ws/blob/master/PROTOCOL.md) + +## Server Sent Events (SSE) + +The GraphQL specification doesn't specify a transport protocol. +HTTP2 is coming along which doesn't support WebSockets, instead using something new call [Server Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events), which is also supported by the DGS Framework. +Apollo defines a [sub-protocol](https://github.com/enisdenjo/graphql-sse/blob/master/PROTOCOL.md), which is supported by client libraries and implemented by the DGS framework. + +To enable SSE support, add the following module to your `build.gradle`: + +```groovy +implementation 'com.netflix.graphql.dgs:graphql-dgs-subscriptions-sse-autoconfigure:latest.release' +``` The subscription endpoint is on `/subscriptions`. Normal GraphQL queries can be sent to `/graphql`, while subscription requests go to `/subscriptions`. -Apollo client supports WebSockets through a [link](https://www.apollographql.com/docs/link/links/ws/). -Typically, you want to configure Apollo Client with both an HTTP link and a WS link, and [split](https://www.apollographql.com/docs/link/composition/#directional-composition) between them based on the query type. - -A simple example of using the Apollo client can be found in the [example project](https://github.com/Netflix/dgs-framework/blob/master/graphql-dgs-example-shared/ui-example/src/index.tsx#L39) of the DGS Framework repository. +Please see the [graphql-sse](https://github.com/enisdenjo/graphql-sse) package for information on how to set up a client to use SSE. ## Unit Testing Subscriptions Similar to a "normal" data fetcher test, you use the `DgsQueryExecutor` to execute a query. diff --git a/docs/configuration.md b/docs/configuration.md index 3ea9f184..416f6f7e 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -71,9 +71,9 @@ dgs: | management.metrics.dgs-graphql.autotime.percentiles-histogram | Boolean | `false` | Enables publishing percentile histograms for the DGS Micrometer Timers. [^1] | !!!hint - You can configure percentiles, and enable percentile histograms, directly via the per-meter customizations available - out of the box in Spring Boot. For example, to enable percentile histograms for all `gql.*` meters you can - set the following property: +You can configure percentiles, and enable percentile histograms, directly via the per-meter customizations available +out of the box in Spring Boot. For example, to enable percentile histograms for all `gql.*` meters you can +set the following property: ``` management.metrics.distribution.percentiles-histogram.gql=true @@ -81,6 +81,18 @@ dgs: For more information please refer to [Spring Boot's Per Meter Properties]. +### DGS Subscriptions (WebSocket): graphql-dgs-subscription-websockets + +| Name | Type | Default | Description | +| ------------------------------------------------------------------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- | +| dgs.graphql.websockets.path | String | `"/subscriptions"` | Path to the endpoint that will serve websocket subscription requests. | + +### DGS Subscriptions (SSE): graphql-dgs-subscription-sse + +| Name | Type | Default | Description | +| ------------------------------------------------------------------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- | +| dgs.graphql.sse.path | String | `"/subscriptions"` | Path to the endpoint that will serve sse subscription requests. | + [^1]: [Spring Boot's Per Meter Properties] can be used to configure percentiles, and histograms, out of the box. [Spring Boot's Per Meter Properties]: https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#actuator.metrics.customizing.per-meter-properties