GraphQL over Server-Sent Events

When the WebSocket Upgrade Never Comes

WebSocket traffic starts as an ordinary HTTP request carrying an Upgrade: websocket header, and anything in the path that does not understand upgrades can refuse it: corporate forward proxies, some mobile carriers, older load balancers, TLS-terminating middleboxes configured for plain HTTP. The client sees a connection that fails before GraphQL is ever involved, and no amount of resolver debugging helps.

Server-Sent Events skip the negotiation. The response is a normal 200 with Content-Type: text/event-stream, so it travels through the same infrastructure as a REST response, survives HTTP/1.1 keep-alive, and rides an existing connection under HTTP/2.

The last two rows carry the trade. SSE is unidirectional by construction: the stream carries server-to-client bytes only, so a client that wants to stop a subscription must open a second HTTP request. And while EventSource reconnects by itself, that automatic behavior is also how events get missed or delivered twice — covered below.

Reach for SSE when subscriptions must work behind restrictive proxies or when you want reconnect logic you did not write. Reach for WebSockets when the client also sends frequent messages over the same channel — typing indicators, bidirectional editing — and you control the network path. Polling remains the honest answer when updates are rare; see realtime feature patterns for that decision in full.

Frames on the Wire

The transport opens one long-lived response and writes newline-delimited records into it:

POST /graphql/stream HTTP/1.1
Content-Type: application/json

{"query":"subscription { messageAdded { id body } }"}

HTTP/1.1 200 OK
Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

retry: 3000

id: 1712000001
event: next
data: {"data":{"messageAdded":{"id":"m1","body":"hi"}}}

id: 1712000002
event: next
data: {"data":{"messageAdded":{"id":"m2","body":"there"}}}

: ping

event: complete
data:

Read the records line by line:

• retry: 3000 tells the browser how long to wait before reconnecting after a drop.
• id: is remembered by the client and replayed as Last-Event-ID on the next connection — that pair is the resume hook.
• event: names the record type. The default name is message, so a bare data: line is an ordinary event.
• data: carries one JSON document. Several data: lines in one record are joined with newlines before parsing, which is why generators write arrays as one line rather than one line per element.
• : ping is a comment. It resets proxy idle timers and never reaches application code — the keepalive.

The server side is small:

res.writeHead(200, {
  'Content-Type': 'text/event-stream',
  'Cache-Control': 'no-cache',
  Connection: 'keep-alive',
});

const keepalive = setInterval(() => res.write(': ping\n\n'), 15000);

const send = (id, type, payload) =>
  res.write('id: ' + id + '\nevent: ' + type + '\ndata: ' + JSON.stringify(payload) + '\n\n');

const teardown = () => {
  clearInterval(keepalive);
  iterator.return && iterator.return();
  res.end();
};
req.on('close', teardown);

Two lines deserve a pause. req.on('close', teardown) is the only cancellation signal SSE gives you — there is no unsubscribe message on the stream — and the keepalive comment is what stops a proxy from declaring the connection idle during a quiet period.

One transport caveat: raw EventSource only issues GET requests and cannot set headers, so subscriptions that need a POST body or an Authorization header use a fetch-based SSE client such as graphql-sse instead of the browser built-in. The frame format above stays the same either way.

Reconnection, Duplicates, and Cancellation

EventSource reconnects on its own. It also drops everything that happened while it was away, unless the server cooperates.

The gap problem

t0  client receives id 1712000005
t1  connection drops; server emits events 6, 7, 8
t2  client reconnects with Last-Event-ID: 1712000005
t3  server replays 6, 7, 8 from its buffer, then continues live

Without the id / Last-Event-ID pair, t2 reconnects as a brand-new subscriber and events 6-8 are gone. Buffers are bounded, so a client absent longer than the buffer window must be told the gap is too large and to refetch state with a normal query — pretending the stream was continuous is how clients end up rendering stale data with confidence.

Duplicates are the price of resumption

Replay is not exactly-once: a client that received event 7 but crashed before persisting it receives 7 again. Make handlers idempotent — key on the event id, ignore anything at or below the highest stored — instead of chasing exactly-once from the transport.

Stopping requires a second request

SSE carries no client-to-server message, so cancellation is a separate HTTP call. With a fetch-based SSE client that means disposing the stream:

const client = createClient({ url: 'https://api.example.com/graphql/stream' });
const abort = new AbortController();

const stop = client.subscribe(
  { query: SUBSCRIBE_MESSAGES },
  { next: render, error: report, complete: done },
);

// later, when the user navigates away:
abort.abort();
stop(); // issues the protocol stop request on its own connection

From the server's perspective, cancellation arrives either as req.on('close') or as a dedicated stop request, depending on the protocol variant — and it must trigger the same iterator teardown a WebSocket complete would. If the only cleanup path is "the client sent a polite unsubscribe," quiet proxies and closed laptops will leak your timers.

Choosing between them: if your environment blocks WebSocket upgrades, or you want browser-native reconnect, take SSE and pay for the second cancellation request plus duplicate handling. If you need frequent client-to-server messages or binary frames, take WebSockets and pay for the handshake, keepalive, and reconnect logic you now own.