WebSocket Subprotocols and Sec-WebSocket-Protocol: Negotiation and Errors

GET /chat HTTP/1.1 Host: server.example.com Upgrade: websocket Connection: Upgrade Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== Sec-WebSocket-Version: 13 Sec-WebSocket-Protocol: chat, superchat 

HTTP/1.1 101 Switching Protocols Upgrade: websocket Connection: Upgrade Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo= Sec-WebSocket-Protocol: chat 

package main import ( "fmt" "log" "net/http" "strings" "github.com/gorilla/websocket" ) // Server accepts connections and selects subprotocols. func runServer() { upgrader := websocket.Upgrader{ CheckOrigin: func(r *http.Request) bool { return true }, } http.HandleFunc("/ws", func(w http.ResponseWriter, r *http.Request) { // Client proposes subprotocols in the request. clientProposals := r.Header.Get("Sec-WebSocket-Protocol") fmt.Printf("Client proposed: %s\n", clientProposals) // Parse proposals (comma-separated, may have spaces). var selected string if clientProposals != "" { proposals := strings.Split(clientProposals, ",") for i := range proposals { proposals[i] = strings.TrimSpace(proposals[i]) } // Server policy: prefer "json.rpc" if available, else "chat". for _, p := range proposals { if p == "json.rpc" { selected = "json.rpc" break } if p == "chat" { selected = "chat" } } } // If no acceptable subprotocol, reject the upgrade. if selected == "" && clientProposals != "" { http.Error(w, "No acceptable subprotocol", http.StatusBadRequest) return } // Upgrade, setting the selected subprotocol. // The Sec-WebSocket-Protocol response header is set via the Subprotocols field. upgrader.Subprotocols = []string{selected} conn, err := upgrader.Upgrade(w, r, nil) if err != nil { log.Println("Upgrade error:", err) return } defer conn.Close() fmt.Printf("Connection established with subprotocol: %s\n", conn.Subprotocol()) // Echo messages (subprotocol-aware, in production). for { _, msg, err := conn.ReadMessage() if err != nil { log.Println("Read error:", err) break } fmt.Printf("Received on %s: %s\n", conn.Subprotocol(), string(msg)) if err := conn.WriteMessage(websocket.TextMessage, msg); err != nil { log.Println("Write error:", err) break } } }) log.Println("Server listening on :8080") log.Fatal(http.ListenAndServe(":8080", nil)) } // Client connects, proposing subprotocols. func runClient() { url := "ws://localhost:8080/ws" header := http.Header{} header.Add("Sec-WebSocket-Protocol", "json.rpc, chat") conn, _, err := websocket.DefaultDialer.Dial(url, header) if err != nil { log.Fatal("Dial error:", err) } defer conn.Close() fmt.Printf("Client connected. Server selected subprotocol: %s\n", conn.Subprotocol()) // Send a message. if err := conn.WriteMessage(websocket.TextMessage, []byte("hello")); err != nil { log.Fatal("Write error:", err) } _, msg, err := conn.ReadMessage() if err != nil { log.Fatal("Read error:", err) } fmt.Printf("Client received: %s\n", string(msg)) } func main() { // Uncomment one: runServer() // runClient() } 

import asyncio import websockets from websockets.server import WebSocketServerProtocol from websockets.client import WebSocketClientProtocol # Server: select subprotocol. async def server_handler(websocket: WebSocketServerProtocol, path: str): # websockets library provides request_headers. client_proposals_header = websocket.request_headers.get("sec-websocket-protocol", "") print(f"Server: client proposed: {client_proposals_header}") if client_proposals_header: proposals = [p.strip() for p in client_proposals_header.split(",")] selected = None # Server preference: json.rpc first, then chat, then mqtt. for preferred in ["json.rpc", "chat", "mqtt"]: if preferred in proposals: selected = preferred break if selected: # Set response subprotocol header via websocket.subprotocol. websocket.subprotocol = selected print(f"Server: selected subprotocol: {selected}") else: # No acceptable subprotocol; reject. await websocket.close(code=1002, reason="No acceptable subprotocol") print(f"Server: no acceptable subprotocol, rejected.") return else: print("Server: no subprotocol proposed, proceeding without one.") try: async for message in websocket: subproto = websocket.subprotocol or "(none)" print(f"Server: received on {subproto}: {message}") await websocket.send(f"Echo: {message}") except websockets.exceptions.ConnectionClosed: print("Server: connection closed") async def run_server(): async with websockets.serve(server_handler, "localhost", 8080): print("Server listening on ws://localhost:8080") await asyncio.Future() # run forever # Client: propose subprotocols and detect mismatch. async def run_client(): uri = "ws://localhost:8080" subprotocols = ["json.rpc", "chat"] try: async with websockets.connect( uri, subprotocols=subprotocols, max_size=None, ping_interval=None ) as websocket: selected = websocket.subprotocol print(f"Client: connected. Server selected: {selected}") # Validate that server picked one we proposed. if selected and selected not in subprotocols: print(f"Client: ERROR - server selected {selected}, but we only proposed {subprotocols}") await websocket.close(code=1002, reason="Subprotocol mismatch") return # Send and receive. await websocket.send("hello") response = await websocket.recv() print(f"Client: received: {response}") except websockets.exceptions.WebSocketException as e: print(f"Client: WebSocket error: {e}") # Test: run server in background, then client. async def main(): server_task = asyncio.create_task(run_server()) await asyncio.sleep(1) # Let server start. await run_client() server_task.cancel() try: await server_task except asyncio.CancelledError: pass if __name__ == "__main__": asyncio.run(main()) 

package main import ( "fmt" "log" "net/http" "strings" "github.com/gorilla/websocket" ) // DialWithFallback attempts to connect with subprotocols, retrying with fewer options on failure. func DialWithFallback(url string, preferredSubprotocols []string) (*websocket.Conn, string, error) { dialer := websocket.Dialer{} // Try each combination, starting with all, then removing each one. combinations := [][]string{ preferredSubprotocols, } // Generate fallback combinations (remove each subprotocol). for i := 0; i < len(preferredSubprotocols); i++ { fallback := make([]string, 0, len(preferredSubprotocols)-1) for j, sp := range preferredSubprotocols { if i != j { fallback = append(fallback, sp) } } if len(fallback) > 0 { combinations = append(combinations, fallback) } } // Try with no subprotocol. combinations = append(combinations, []string{}) var lastErr error for _, subprocs := range combinations { fmt.Printf("Trying with subprotocols: %v\n", subprocs) header := http.Header{} if len(subprocs) > 0 { header.Add("Sec-WebSocket-Protocol", strings.Join(subprocs, ", ")) } conn, _, err := dialer.Dial(url, header) if err != nil { lastErr = err fmt.Printf("Attempt failed: %v\n", err) continue } selected := conn.Subprotocol() if selected != "" && !contains(subprocs, selected) { fmt.Printf("ERROR: server selected %s, but we proposed %v\n", selected, subprocs) conn.Close() lastErr = fmt.Errorf("subprotocol mismatch: got %s", selected) continue } fmt.Printf("Connected with subprotocol: %s\n", selected) return conn, selected, nil } return nil, "", lastErr } func contains(slice []string, item string) bool { for _, s := range slice { if s == item { return true } } return false } func main() { // Example usage. conn, selected, err := DialWithFallback( "ws://localhost:8080/ws", []string{"json.rpc", "chat", "mqtt"}, ) if err != nil { log.Fatal("Connection failed:", err) } defer conn.Close() fmt.Printf("Final connection: subprotocol=%s\n", selected) }