In a WebSocket opening handshake, what does the client's `Sec-WebSocket-Protocol` field offer, and how must the server answer?

## What the client offers A WebSocket connection begins as an ordinary HTTP/1.1 request that asks to change protocols. Alongside `Upgrade: websocket`, `Connection: Upgrade`, `Sec-WebSocket-Version: 13` and `Sec-WebSocket-Key`, the client may send `Sec-WebSocket-Protocol`. Its value is a comma-separated list of **subprotocol names** — the application-level protocols this client can speak once the socket carries bytes. Two properties of that list do the work: - It is **ordered**, and the order states the client's preference. It does not bind the server, which may select any name from the list. - Each entry is a **token**, not a description. Published subprotocols register their names; a private protocol conventionally uses a domain-scoped name so it cannot collide with anybody else's. The field is optional. A client that sends none is saying it proposes no named protocol, and if the socket opens, whatever the two sides speak was agreed somewhere outside the handshake — in a document, or by both ends shipping from the same repository. ## What the server is allowed to answer RFC 6455 gives the server a narrow choice: it selects **zero or one** of the offered values and echoes the selected one in the `101 Switching Protocols` response. | The 101 response carries | What it means | What the client does | |---|---|---| | exactly one name from the offer | that subprotocol is agreed | speak that protocol | | no `Sec-WebSocket-Protocol` field | no subprotocol was agreed | the application decides: continue, or close | | a name that was never offered | the server broke the rule | fail the WebSocket connection | | more than one name | the server broke the rule | fail the WebSocket connection | The last two rows matter more than they look. Validating the response is part of completing the handshake, so a client that rejects it never reaches an established connection — which means there is no socket on which to send a Close control frame. The client abandons the connection and reports the failure. That is a different shape of ending from a close code, and it is the ending the specification prescribes here. Row two is the one candidates most often get wrong. An absent field is **not** an error: the server is entitled to accept the upgrade and agree to no named protocol at all. Whether that is usable is an application question, not a protocol one. ## The name is opaque, and that is the real trap The WebSocket protocol does not know what any subprotocol name means. It carries the token through the handshake, hands the agreed string to both applications, and stops. Nothing on the wire checks that the messages that follow match the protocol named, because the frames carry text or binary payloads and no schema at all. So the genuine production failure is not a rejected handshake. It is two ends that **both believe the negotiation succeeded** and disagree about what the messages mean — most often because the message grammar behind one name changed while the name stayed the same, and half the fleet is running the old reading of it. The defence is to make a semantic change a **new token**. Put the version in the name, offer the new and old names together, and let the handshake record which reading is in force: 1. The client offers `cue.v2.example.com, cue.v1.example.com`. 2. A server that still understands both selects the first one it prefers. 3. A server that has dropped the old reading selects the new name — or, if it cannot speak either, returns no subprotocol rather than pretending. 4. Every connection's negotiated name is then a fact you can log, which turns a schema mismatch into something visible at connect time instead of a decoding error an hour later. ## When the response carries no subprotocol A client that genuinely requires a named protocol must check the response and decide for itself. Some applications carry a sensible default and continue. A client that cannot continue closes the connection it has just opened — and here it **does** have an established socket, so it sends a Close control frame. The specification defines no code meaning "you agreed to no subprotocol", so applications use a policy-violation code or one from the ranges reserved for application use, and put the explanation in the close reason. ## What to check on every connection - The negotiated name is on the offered list. - Exactly one name came back, not several. - The application actually implements the name that was selected, rather than assuming its own first preference won.