WebSocket Subprotocol Negotiation

## Why there is a choice at all The GraphQL specification defines `subscription` as an operation type and defines how one is executed, but it says nothing about how the resulting stream reaches a client. The GraphQL over HTTP specification — itself a working draft — covers a request and a response over HTTP and likewise defines no socket protocol. So the wire format for a long-lived subscription connection was filled in by the community, and the community filled it in twice. Both answers are WebSocket **subprotocols**: a named message vocabulary that both ends agree to speak over an already-open socket. The identifier is chosen once, when the connection is established: the client offers one or more identifiers, the server answers with exactly one of them, and that one governs every message on that connection until it closes. There is no renegotiation mid-connection and no per-operation override. ## The two identifiers **`graphql-transport-ws`** is the current identifier. It is what a modern subscription client offers by default and what a modern server registers. **`graphql-ws`** is the legacy identifier, belonging to the older **subscriptions-transport-ws** protocol, which was the de-facto standard for years and is still on the wire in shipped applications, embedded devices and internal tools that nobody has rebuilt. ## The crossed names, which is the whole reason this is an interview question Read those two facts together and the trap appears. The *protocol project* whose common name is **graphql-ws** does **not** use the string `graphql-ws`; it defines and uses `graphql-transport-ws`. The string `graphql-ws` selects the *other*, older protocol — the one whose project name is subscriptions-transport-ws. Each name points at the wrong thing. Every remaining problem on this subject descends from that one crossing: an engineer reads "we use graphql-ws" in a runbook, types `"graphql-ws"` into the client's subprotocol list, and has silently asked for the legacy vocabulary from a server that only speaks the modern one. Say both halves out loud in an interview — the identifier *and* which protocol it selects. "We're on graphql-ws" is exactly the ambiguous sentence that causes the outage, because the listener cannot tell whether you mean the project or the wire string. ## What does not change between them The schema does not change. The executable document does not change. A subscription over a parcel-locker graph is written the same way on either subprotocol: ```graphql subscription CompartmentOpened($lockerId: ID!) { compartmentOpened(lockerId: $lockerId) { compartmentId state openedAt } } ``` What changes is the wrapper carrying that document to the server and carrying results back: the two vocabularies use different message type names for the same lifecycle steps, and they differ in what keep-alive and error signalling look like. A resolver author never notices which subprotocol a subscriber used; a client author and an operator notice immediately. ## Why a mismatch is not loud You might expect asking for an unsupported vocabulary to fail hard. Often it does — a server that supports only the modern identifier and is offered only the legacy one should refuse to establish the connection. But two softer outcomes are common enough that they dominate real incidents. First, a server can complete the connection without selecting any subprotocol at all, leaving a socket that is open, healthy by every network check, and understood by nobody. Second, the two vocabularies happen to agree on the very first message a client sends and on its acknowledgement, so a mismatched pair can connect, acknowledge each other, and only diverge when the first actual operation is sent. Either way, the symptom is a subscription that never delivers — not an error at connect time. ## What a junior is expected to do with this Three habits cover most of it. Write the identifier down explicitly in client configuration rather than relying on a default, because defaults differ. When you are told which protocol a server speaks, confirm the *string*, not the project name. And when a subscription silently produces nothing, check the negotiated identifier on the open connection before you go looking at resolvers, publishers or authorization — it is the cheapest hypothesis on the list and it is right surprisingly often. ## A note on where each name came from The ordering explains the mess. The legacy protocol arrived first and took the plain, obvious wire string `graphql-ws` for itself. When a replacement protocol was written years later, that string was already spoken for by an incompatible vocabulary, so the replacement had to pick a different one and chose `graphql-transport-ws` — while its own project came to be known, colloquially, as graphql-ws. The result is two names that each point at the other's protocol in casual conversation. Nothing about it is subtle once you know it, and nothing about it is guessable if you do not, which is precisely why it is asked.