graphql / graphql/graphql-over-http
X-GraphQL-Event-Stream for being notified that the GraphQL schema has updated
- Dominant language
- JavaScript
- Stars
- 427
- Forks
- 70
- Avg merge
- 1m
- Merged PRs (30d)
- 5
Description
[Server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) are a perfect mechanism for informing a GraphQL client that the schema has been updated. They don't require the complexity of websockets, and they are uni-directional.
I'm proposing that when introspecting a GraphQL API, if the header `X-GraphQL-Event-Stream` is detected then interested clients should subscribe to the `text/event-stream` at that (relative or absolute) URL and when it receives the `change` event it should automatically re-introspect the GraphQL schema.
Not much code should be required to implement this, just something like:
```js
// refreshSchema is a function you provide which triggers re-introspection
const streamUrl = response.headers["x-graphql-event-stream"];
if (streamUrl) {
const endpointUrl = new URL(endpoint);
const streamUrl = new URL(streamUrl, endpointUrl);
if (endpointUrl.host !== streamUrl.host) {
throw new Error(
`Stream and endpoint hosts don't match - '${streamUrl.host}' !== '${endpointUrl.host}'`
);
}
const eventSource = new EventSource(streamUrl);
eventSource.addEventListener("change", refreshSchema, false);
eventSource.addEventListener("open", () => { /* ... */ }, false);
eventSource.addEventListener("error", () => { /* ... */ }, false);
}
```
(You may want to throttle the refreshSchema method.)
This has been baked into PostGraphile for a while; I opened [an implementation PR](https://github.com/skevy/graphiql-app/pull/120) to @skevy's GraphiQL.app a good while ago; and @imolorhe has [implemented it independently](https://github.com/imolorhe/altair/commit/0b3ccc188597efbe1a57e8f026071743ff6ebffc) in Altair. Samuel wrote more about it here: https://sirmuel.design/a-better-graphql-developer-experience-with-x-graphql-event-stream-1256aef96f24. We'll probably be implementing it in the new version of GraphiQL too, once we have the plugin system in place.
What are your thoughts?
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.