What messages must a GraphQL-over-WebSocket client and server exchange before the first subscribe?

## The socket is open. Nothing works yet. Opening a WebSocket to a GraphQL endpoint gets you a duplex channel and nothing more. What travels over that channel is JSON messages whose meaning comes from a **subprotocol** — a small application-level protocol layered on top of the connection — and that subprotocol insists on a handshake of its own before it will accept a single operation. Engineers who have only ever used a client library often miss this, because the library runs the handshake invisibly and exposes nothing but `subscribe`. Say plainly where this comes from, because interviewers do ask: **the GraphQL specification defines `subscription` as an operation type and an execution algorithm, and defines no transport at all.** The GraphQL over HTTP working draft covers queries and mutations travelling over HTTP. The WebSocket message flow described here is the `graphql-ws` subprotocol document — a community protocol that the ecosystem converged on, not a ratified edition of anything. It is a convention with a written specification behind it, which is a different thing from being in the spec. ## The two messages `connection_init` is client to server. It must be the **first** message the client sends on the socket. It carries a `type` of `connection_init` and an optional `payload`, which is a free-form object: the subprotocol assigns it no structure and no meaning. `connection_ack` is server to client, sent in response, also with an optional free-form `payload`. Between the socket opening and that acknowledgement arriving, the connection is in a state the protocol calls *not acknowledged*, and the client is not permitted to send anything else — no `subscribe`, no operation, nothing. That is the whole handshake. Two messages, one round trip, per socket. ## Why the payload slot exists at all The reason is a browser limitation, and it is worth being able to state precisely. JavaScript opening a WebSocket may supply a URL and a list of subprotocol identifiers. It may **not** set arbitrary request headers, so there is no `Authorization` header available on the opening request. Cookies scoped to the origin do ride along, and a token can be stuffed into the query string — where it lands in access logs, referrers and browser history. The subprotocol's answer is to give the application a slot in its own first message, after the socket exists but before anything can be run on it. So the near-universal convention is that credentials go in the `connection_init` payload, the server reads them, and it either acknowledges or closes the socket. *Whether* a server should also re-check on each operation, and what an expiring credential costs mid-stream, is a policy question beyond the message flow. ## A worked sequence A clinical-trial registry graph publishes a live adverse-event feed. A monitoring dashboard opens a socket and wants `adverseEventReported(trialId: "NCT-48213")`. 1. The socket opens. 2. The client sends `{"type":"connection_init","payload":{"authorization":"Bearer …"}}`. 3. The server validates the payload and replies `{"type":"connection_ack"}`. 4. Only now does the client send its `subscribe` message, carrying an id it chose and the operation document. A well-written client queues subscriptions requested before step 3 and flushes them after it, which is exactly why the handshake is invisible to application code. ## What the server does when the sequence is broken The subprotocol defines close codes in the 4xxx range, which WebSocket reserves for application use, so these are the subprotocol's own vocabulary rather than the transport's: * **4401** — a message such as `subscribe` arrived before the connection was acknowledged. The socket is closed; no error message is sent for the operation. * **4408** — the client never sent `connection_init` inside the server's initialisation window. The window length is a server setting, not a protocol constant. * **4429** — the client sent `connection_init` more than once on the same socket. * **4400** — a message the server could not interpret at all: an unknown `type`, a missing `id` where one is required, a body that is not valid JSON. Notice that all four are **closes**, not error responses. The subprotocol treats a handshake violation as a reason to end the connection rather than to reply, which is why a broken client shows up in logs as sockets dying rather than as failed operations. ## The handshake is per socket There is no notion of resuming a previous session. Every new socket, including every reconnect after a network blip, repeats `connection_init` and `connection_ack` from scratch — and a client that restores a table of active subscriptions on reconnect must re-run the handshake before replaying any of them. ## What the interviewer is really checking Two things. First, that you know the socket being open is not the same as the connection being usable — the commonest junior bug in this area is firing `subscribe` from the socket's open event. Second, that you can separate the GraphQL specification from the conventions layered around it. A candidate who says "the spec defines the WebSocket handshake" has revealed they learned GraphQL entirely through one library.