Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: update documentation for SSE subscriptions and update configura… #100

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

feat: update documentation for SSE subscriptions and update configura… #100

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5813cad
feat: update documentation for SSE subscriptions and update configura…
Ancient-Dragon Jul 3, 2022
b6ac35a
fix the documentation around support for websockets in DGS as per PR …
Ancient-Dragon Jul 5, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 17 additions & 7 deletions docs/advanced/subscriptions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,9 @@ import org.reactivestreams.Publisher;

@DgsSubscription
public Publisher<Stock> 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.
Expand All @@ -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.
Expand Down
18 changes: 15 additions & 3 deletions docs/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,16 +71,28 @@ 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
```

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