Working with Subprotocols

1. Understanding Subprotocols

A subprotocol is a named application-layer protocol negotiated via the Sec-WebSocket-Protocol header. The server picks one (or none) from the client's preference list.

2. Negotiating Subprotocol

new WebSocketServer({
  port: 8080,
  handleProtocols: (protocols, req) => {
    const supported = ["chat.v2","chat.v1"];
    return supported.find(p => protocols.has(p)) || false;
  }
});

3. Specifying Client Subprotocols

const ws = new WebSocket("wss://x/", ["chat.v2","chat.v1"]);

4. Selecting Server Subprotocol

5. Accessing Active Subprotocol

ws.addEventListener("open", () => {
  if (ws.protocol === "chat.v2") useV2();
  else useV1();
});

6. Implementing Custom Protocol

7. Using Standard Subprotocols

8. Handling Protocol Mismatch

ws.addEventListener("open", () => {
  if (!ws.protocol) ws.close(4000, "no-subprotocol-agreed");
});

9. Versioning Subprotocols

10. Documenting Protocol Specification