Utilizing SSE (Server Side Events) to support GraphQL Schema Auto Refresh

[dannysofftie]

Following Sir Muel's Medium post,

TL;DR — Implementing X-GraphQL-Event-Stream header in your server allows GraphQL IDEs like Altair to update your schema without you having to refresh manually.

Assuming I am working on a GraphQL server implementation — adding new data points within the schema and modifying others — usually I would have my Altair GraphQL Client open where I can make the requests and view the schema, which is awesome! When I make a change on the server implementation, there is a Reload Docs button which refetches the schema for the server, which is also great and convenient.

I will break down how to implement SSE on a GraphQL server. I will be using:

1. Mercurius, a GraphQL adapter for Fastify
2. Altair, ✨ ⚡ A beautiful feature-rich GraphQL Client for all platforms, as it has great support for Schema auto refresh

Enable GraphQL Event Stream

The first step to make SSE for GraphQL work is to add support for X-GraphQL-Event-Stream header. Ideally, your server would respond with this header for every request, to inform your GraphQL IDEs that the supports SSEs.

Using Fastify, below onRequest hook appends X-GraphQL-Event-Stream to response

import fastify from 'fastify';
const app = fastify();

app.addHook('onRequest', (req, res, done) => {
  res.headers({ 'X-GraphQL-Event-Stream': '/graphql/stream', 'Access-Control-Expose-Headers': 'X-GraphQL-Event-Stream' });
  done();
});

Two things happen above:

1. X-GraphQL-Event-Stream header sets a valid stream URL for all. Ideally a GET endpoint that you'd have to implement on your server. (Discussed below)
2. Access-Control-Expose-Headers header for X-GraphQL-Event-Stream to allow browser clients to be able to pick it up.

With the server informing GraphQL clients for SSE support, you'd need to implement a GET endpoint as mentioned in 1 above.

Implement GET endpoint stream URL

Continuation using Fastify

app.get('/graphql/stream', async (req, res) => {
  /**
   * You'd implement support for SSE here.
   *
   * GraphQL clients with SSE support will send request to this endpoint.
   *
   * The server will push events to connected GraphQL clients, and they will refetch updated schema.
   */
});

Implement SSE support

I must tag PostGraphile, instant lightning-fast GraphQL API backed primarily by your PostgreSQL database. It has a great implementation of SSE, I have borrowed a lot, actually I have borrowed their implementation.

Here is their implementation.

This function will work with Express.js, Koa, Fastify and other Node.js frameworks.

import { IncomingMessage, ServerResponse } from 'http';
import { PassThrough } from 'stream';

export default function setupServerSentEvents(req: IncomingMessage, res: ServerResponse, options: any): void {
  // Making sure these options are set.
  req.socket.setTimeout(0);
  req.socket.setNoDelay(true);
  req.socket.setKeepAlive(true);

  // Set headers for Server-Sent Events.
  res.statusCode = 200;
  res.setHeader('Content-Type', 'text/event-stream');
  res.setHeader('Cache-Control', 'no-cache');
  if (req.httpVersionMajor >= 2) {
    // NOOP
  } else {
    res.setHeader('Connection', 'keep-alive');
  }

  const koaCtx = (req as object)['_koaCtx'];
  const isKoa = !!koaCtx;
  const stream = isKoa ? new PassThrough() : null;
  if (isKoa) {
    koaCtx.response.body = stream;
    koaCtx.compress = false;
  }

  const sse = (str: string) => {
    if (isKoa) {
      stream!.write(str);
    } else {
      if (!res.writableEnded) res.write(str);

      // support running within the compression middleware.
      // https://github.com/expressjs/compression#server-sent-events
      if (typeof res.flushHeaders === 'function') {
        res.flushHeaders();
      }
    }
  };

  // Notify client that connection is open.
  sse('event: open\n\n');

  // Setup listeners.
  const schemaChangedCb = () => sse('event: message\ndata: schema\n\n');

  setTimeout(() => {
    // Am introducing this delay to allow browser IDEs to connect to this server
    // especially in development when schema changes, and the server restarts
    // Ideally, you'd have to refresh your browser, but with this, updates will be sent on server restart
    schemaChangedCb();
  }, 2000);

  // Clean up when connection closes.
  const cleanup = () => {
    if (stream) {
      stream.end();
    } else {
      res.end();
    }
  };
  req.on('close', cleanup);
  req.on('finish', cleanup);
  req.on('error', cleanup);
}

Working with this function, our GET implementation would look like below

app.get('/graphql/stream', async (req, res) => {
  // Every client that connects will receive events
  // So in this case, GraphQL IDEs will subscribe to `message` event
  // and in `schemaChangedCb` function in `setupServerSentEvents` above, we push `message` event to connected clients
  // IDEs with SSE support will auto refetch schema automatically.
  setupServerSentEvents(req.raw, res.raw, {});
});

[imolorhe]

@dannysofftie This is an amazing breakdown! This can practically be included to the docs almost as-is 😄 It's worth mentioning @benjie here as well as he pioneered this idea.

One part that is still missing is the part about how to reload the schema without actually restarting the GraphQL server. The ideal development experience I envision should be:

• developer updates GraphQL schema
• server receives schema update
• server updates its internal references to the schema
• server sends the SSE to clients to update

Honestly I've not been able to come up with an ideal solution to this problem myself. The solution I came up with involves watching the files for the schema using a watcher like chokidar and then deleting the cache for the module, so as to refresh the module internally. Besides this approach being not general enough, I also feel it would incur unnecessary performance costs as well. So still looking forward to seeing an optimal solution for this 🙂

[dannysofftie]

I was working for a quick solution to complement my development workflows. In development the server has to restart to compile the schema whenever it changes, but this won't be always the case.

Am really curious to hear @benjie 's thoughts on this approach.

[benjie]

I have PostGraphile requests call await getGraphQLSchema() which generally returns a pre-resolved promise, but when a new schema is coming it returns the promise to that new schema. (We then have some optimisations over this, but that's by the by.) Of course we build schemas in memory using new GraphQLSchema(...) so we don't have the same module requirement concerns that others do.