GraphQL over WebSocket

Two Protocols Sharing Port 443

The wire format for GraphQL over WebSocket is not part of the GraphQL specification, and there are two of them. subscriptions-transport-ws shipped first and is deprecated; graphql-ws is its maintained replacement. Both handshake against the same endpoint, so a mismatch surfaces as a confusing protocol error rather than a version complaint — the classic symptom being "Connection must be initialized" from a server that just received connection_init.

Two rows drive real migration decisions. Start versus subscribe: an old client sends start, a new server ignores an unknown message type and the client waits forever for a payload that will never come. And keepalive: the old protocol pushed ka frames from the server only, so a client could not tell a half-open TCP connection from a healthy idle one — graphql-ws makes keepalive bidirectional, which is what lets either side detect a dead peer.

Note also that in graphql-ws, connection_init may carry auth as its payload, and the server may answer with connection_ack or reject the connection outright with error before any operation starts. That single frame is where identity for the whole socket is established.

The npm package is also called graphql-ws, so protocol name, library name, and spec collapse into one string. Every debugging session on this transport starts by confirming which of the two is actually on the wire — with a proxy or a framework in the middle, the answer is not always what the package.json suggests.

Walking the Handshake

client                                   server
  |
  |---- connection_init {token} ----------->| auth payload, sent once
  |<--- connection_ack ---------------------|
  |                                         |
  |---- subscribe id:"1" {query,vars} ----->|  operation 1 starts
  |<--- next id:"1" {data:{...}} -----------|
  |---- subscribe id:"2" {query} ---------->|  operation 2, same socket
  |<--- next id:"1" {data:{...}} -----------|
  |<--- next id:"2" {data:{...}} -----------|
  |<--- ping -------------------------------|  keepalive, either direction
  |---- pong ------------------------------>|
  |                                         |
  |---- complete id:"1" ------------------->|  client unsubscribed
  |<--- error id:"2" {message} -------------|  event source failed
  |---- complete id:"2" ------------------->|  client released the failed op

The id is the whole multiplexing story: one socket carries many independent operations, so a client can hold a chat subscription, a notification subscription, and still run a query over the same connection if the server permits it. Each subscribe message carries an id and a payload with query, variables, and operationName — the same document a POST body would carry.

A minimal client:

import { createClient } from 'graphql-ws';

const client = createClient({
  url: 'wss://api.example.com/graphql',
  connectionParams: { authorization: 'Bearer ' + token },
  keepAlive: 20_000, // sends ping every 20s
  retryAttempts: 5,
});

const stop = client.subscribe(
  { query: SUB_ORDER_SHIPPED, variables: { orderId: '42' } },
  {
    next: (msg) => render(msg.data),
    error: (err) => showToast(err),
    complete: () => console.log('stream ended'),
  },
);

Three behaviors worth knowing before you debug this library. connection_init is sent lazily on the first operation, so a bad token surfaces at subscribe time rather than at connect. retryAttempts reconnects and re-subscribes every active id after a drop, which is why clients recover from deploys without app code. And stop() sends complete for that id only — the socket and every other operation stay alive.

Termination Semantics and Operational Traps

Three different endings look identical to a naive client:

1. complete for an id — that one operation ended normally. Other operations on the socket keep running.
2. error for an id — that operation failed; the socket survives and can start more work.
3. Socket close — everything dies. Closing the socket terminates every active operation the client had open on that connection, and the close frame carries no per-operation detail.

That third rule is what makes deployments and idle proxies dangerous. A load balancer that kills quiet WebSockets after 60 seconds of silence will silently drop a subscription that stopped producing events; the client sees a close and must reconnect and re-subscribe every operation it held. Sending ping more often than the shortest idle timeout in your path — typically every 15-30 seconds — keeps the connection visibly alive.

A checklist for production sockets

• Keepalive: client pings under the proxy idle timeout; server answers pong. If you only rely on server ping, a client behind NAT that cannot speak first still looks dead.
• Reconnect: exponential backoff with jitter, then re-subscribe every id you were holding. createClient({ retryAttempts }) does both; doing only the first leaves you connected with zero operations.
• Graceful shutdown: on SIGTERM, stop accepting new subscribe messages, send complete for the rest, wait briefly for in-flight writes, then close. Clients that receive complete know the server ended things on purpose; clients that only see a TCP reset reconnect immediately, all at once, against a fleet still starting up.
• Transport choice: mutations and short queries over HTTP stay easier to cache, retry, and trace. Multiplexing everything onto one socket is convenient, but it ties query availability to socket health.

Interview answer that lands: name the three termination signals, state that a socket close is global to all operations on it, and mention the proxy idle timeout as the failure you actually debug in production.