graphql / graphql/graphql-over-http

X-GraphQL-Event-Stream for being notified that the GraphQL schema has updated

Open
#48 7 comments 2 reactions 0 assignees View on GitHub
enhancement Experiment 🧪
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.