graphql-sse

In this mode, every operation request is its own SSE stream.

Requirements:

• Content-Type must be text/event-stream.
• Validation Errors: Do not return a 400 status code for validation errors, as this will cause the browser's EventSource to terminate the connection. Instead, emit a next event containing the errors in the data field.
• Termination: To stop streaming operations (like subscriptions, @stream, or @defer), the client simply closes the SSE connection.

Event Stream Format:

• next event: Contains the ExecutionResult.
• complete event: Indicates the operation is finished. Note: When using the browser's native EventSource, you MUST include an empty data: field in the complete event, otherwise the listener may not trigger.

// next event structure
interface NextMessage {
  event: 'next';
  data: ExecutionResult;
}

// complete event structure
interface CompleteMessage {
  event: 'complete';
}

The graphql-sse protocol supports two distinct modes of operation depending on your server's HTTP capabilities and connection limits:

1. Distinct Connections Mode: Best for HTTP/2+ powered servers. Each GraphQL operation request establishes its own dedicated SSE connection. This mode follows the standard GraphQL over HTTP spec but requires Content-Type: text/event-stream and mandates that validation errors be sent as next events rather than 400 Bad Request to prevent the client's EventSource from failing.

2. Single Connection Mode: Designed to bypass the browser's connection limit (typically 6 connections per domain) on HTTP/1 servers. In this mode, a single long-lived SSE connection is used to stream results for all GraphQL operations. Separate HTTP requests are used to trigger operations, and a "reservation" system is used to link these requests to the single stream.

To implement Persisted Queries, use the onSubscribe hook on the server to look up the query in a store using an ID provided in the client's extensions.persistedQuery field. If found, return the stored ExecutionArgs. On the client, you can leave the query field empty and provide the ID in the extensions.

Server Implementation: Use onSubscribe to match params.extensions?.persistedQuery against your store.

Client Implementation: Pass the ID in the extensions object of the subscription request.

// Server
export const handler = createHandler({
  onSubscribe: (_req, params) => {
    const persistedQuery = queriesStore[String(params.extensions?.persistedQuery)];
    if (persistedQuery) {
      return {
        ...persistedQuery,
        variableValues: params.variables,
        contextValue: undefined,
      };
    }
    return [null, { status: 404, statusText: 'Not Found' }];
  },
});

// Client
client.subscribe(
  {
    query: '',
    extensions: {
      persistedQuery: 'iWantTheGreetings',
    },
  },
  {
    next: onNext,
    error: reject,
    complete: resolve,
  },
);

When using createHandler, you can provide an authenticate function to handle user authorization.

There are two modes of operation to consider:

1. Distinct Connections Mode: Clients request an event-stream using a POST method. For these requests, you can simply return an empty string '' (or the token) to indicate the client is authenticated.
2. Single Connection Mode: Clients use a single connection for multiple operations. These subsequent requests will include an X-GraphQL-Event-Stream-Token header. You must extract this token from the header to identify the stream. If the token is missing for a single-connection request, you must generate or retrieve a unique token (e.g., from cookies or an Authorization header).

If authentication fails, you can return a tuple containing null and a response object with a status code, such as [null, { status: 401, statusText: 'Unauthorized' }].

import { createHandler } from 'graphql-sse';

export const handler = createHandler({
  schema,
  authenticate: async (req) => {
    let token = req.headers.get('x-graphql-event-stream-token');
    if (token) {
      // Handle Single Connection Mode
      return Array.isArray(token) ? token.join('') : token;
    }

    // Logic to find/create token for new connections
    token = await getOrCreateTokenFromCookies(req);

    if (!token) {
      return [null, { status: 401, statusText: 'Unauthorized' }];
    }

    // Handle Distinct Connections Mode
    if (req.method === 'POST' && req.headers.get('accept') === 'text/event-stream') {
      return '';
    }

    return token;
  },
});