WebSockets, a two-way
pipe the server can push down.

Plain HTTP has one shape: the client asks, the server answers (the HTTP chapter's request– response model). The server can never speak first — it has no way to push data to a client that hasn't just asked for it. That's fine for fetching a page or calling an API, but it breaks down the moment you need the server to notify the client as things happen: a new chat message, a live price tick, a notification, a collaborator's cursor moving, a match found. The server has the update; HTTP gives it no channel to deliver it.

Before WebSockets, you faked server push by having the client ask repeatedly — polling. Every few seconds the client sends "anything new?" and usually hears "no." This is wasteful on every axis: a flood of requests that mostly return nothing, the full overhead of HTTP headers and connection setup on each one, and latency bounded by your polling interval (poll every 5s and an event can sit undelivered for nearly 5s). WebSockets exist to replace that hack with a real persistent, two-way connection where either side can send at any time.

WebSockets aren't the only way to get server-to-client updates, and reaching for them reflexively is a common mistake. There's a spectrum of techniques, each a different point on the trade-off between simplicity and capability. Knowing all four lets you pick the simplest thing that meets the need (the full decision guide is §18).

A WebSocket is a persistent, bidirectional, full-duplex communication channel over a single TCP connection, established through an HTTP request and then kept open. Unpack each word: persistent — opened once and held for the session, not per message; bidirectional / full-duplex — both sides can send simultaneously and independently, not taking turns; single TCP connection — one socket carries everything, on the same ports as HTTP (80/443), so it traverses firewalls that allow web traffic.

The clever design choice is that a WebSocket starts life as an HTTP request and then upgrades (§4). This isn't an accident — it's what lets WebSockets reuse the existing web infrastructure (ports, TLS, proxies, the same origin) instead of requiring a new port or protocol that firewalls would block. Once upgraded, the connection stops speaking HTTP and starts speaking the WebSocket framing protocol (§5). The URL scheme reflects this: ws:// (like http://) and wss:// (TLS, like https://).

Every WebSocket begins with a single, special HTTP request — the upgrade handshake (the HTTP chapter's §19, in full). The client sends a normal-looking GET with headers that say "I'd like to switch this connection to the WebSocket protocol." If the server agrees, it replies with status 101 Switching Protocols — not 200 — and from that instant the connection is no longer HTTP; it's a raw WebSocket carrying frames (§5).

GET /ws/chat HTTP/1.1
Host: api.example.com
Upgrade: websocket                              ← "switch this connection"
Connection: Upgrade                             ← the Upgrade header is meaningful
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==     ← a random client nonce (base64)
Sec-WebSocket-Version: 13                        ← the protocol version
Sec-WebSocket-Protocol: chat.v1                  ← optional subprotocol(s) offered
Origin: https://app.example.com                  ← the browser sends this; SERVER must check (§14)

HTTP/1.1 101 Switching Protocols                ← NOT 200 — the upgrade succeeded
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=  ← proves the server spoke WebSocket
Sec-WebSocket-Protocol: chat.v1                  ← the subprotocol the server picked

# After 101, both sides stop speaking HTTP and start exchanging WebSocket frames.

What Sec-WebSocket-Accept proves

The server computes Accept by concatenating the client's Sec-WebSocket-Key with a fixed, magic GUID defined by the spec, SHA-1 hashing it, and base64-encoding the result. This isn't security — the GUID is public — it's a proof of protocol understanding: it confirms the responder is a genuine WebSocket server and not some cache or proxy blindly echoing a 101. The client verifies the value matches before treating the connection as a working WebSocket. Libraries do this for you; you almost never compute it by hand.

After the handshake, data doesn't flow as a raw byte stream — it's chopped into frames, small structured units with a compact header. Framing is what lets one connection carry discrete messages (so the receiver knows where one ends and the next begins), distinguish text from binary, send control signals like close and ping, and split a large message across multiple frames. You rarely touch frames directly — libraries expose "send message / receive message" — but understanding the structure explains masking, message types, and control frames.

Text vs binary, and why client frames are masked

• Two data types. A frame is either text (UTF-8 — JSON usually rides here) or binary (raw bytes — Protobuf, images, custom formats). The library hands you a string or bytes accordingly.
• Masking is mandatory client→server, forbidden server→client. Browsers XOR-mask every frame they send with a random key. This isn't encryption (use wss:// for that — §14); it's a security mitigation so a malicious page can't craft bytes that confuse old intermediary proxies into mis-parsing the stream as something else (cache poisoning). Server frames are never masked. Libraries handle this automatically.
• Fragmentation. A large message can be split into a sequence of frames (FIN=0 on all but the last, opcode 0x0 continuation on the middle ones), letting senders stream without buffering the whole thing first.

A WebSocket has a clear life: open → exchange messages → close, with events at each stage your code hooks into. The open completes after the handshake (§4). Then messages flow freely. Closing is itself a small handshake: one side sends a close frame (opcode 0x8) carrying a status code and optional reason, the other echoes a close frame, and both then shut the TCP connection. A clean close lets each side know why the connection ended.

Because a dead connection often looks identical to an idle one (no bytes either way), you need an active way to tell "still alive" from "silently gone." The protocol provides ping and pong control frames for exactly this: one side sends a ping, the other must answer with a pong. A heartbeat is the pattern of sending pings on a timer and treating a missed pong (within a deadline) as a dead connection to be closed and cleaned up. This is the same liveness problem as Kubernetes probes (containerization §17) and Kafka consumer keepalive, solved with the same idea: don't assume health, verify it.

A server endpoint does three things: accept the upgrade (§4), then run a loop reading messages and a way to write them. In Go the standard library doesn't ship a WebSocket implementation, so you use a library — gorilla/websocket (the long-time standard) or coder/websocket (nhooyr). In Python, frameworks like FastAPI/Starlette expose WebSockets directly, and the websockets library is the standalone standard. Here is a minimal echo server — the "hello world" of WebSockets.

// github.com/gorilla/websocket
var upgrader = websocket.Upgrader{
    // CheckOrigin guards against cross-site hijacking — DO NOT leave it open (§14).
    CheckOrigin: func(r *http.Request) bool {
        return r.Header.Get("Origin") == "https://app.example.com"
    },
}

func wsHandler(w http.ResponseWriter, r *http.Request) {
    conn, err := upgrader.Upgrade(w, r, nil) // performs the 101 handshake (§4)
    if err != nil {
        return // upgrader already wrote an HTTP error
    }
    defer conn.Close() // always close → frees the socket (§19)

    for { // the READ LOOP — one per connection
        mt, msg, err := conn.ReadMessage()
        if err != nil {
            break // client closed or connection died (§6) → exit, cleanup via defer
        }
        // echo it straight back
        if err := conn.WriteMessage(mt, msg); err != nil {
            break
        }
    }
}

func main() {
    http.HandleFunc("/ws", wsHandler) // a normal HTTP route that upgrades
    http.ListenAndServe(":8080", nil)
}

# FastAPI / Starlette expose WebSockets natively (the `websockets` lib is an alternative).
from fastapi import FastAPI, WebSocket, WebSocketDisconnect

app = FastAPI()

@app.websocket("/ws")
async def ws_handler(ws: WebSocket):
    # Validate origin yourself before accepting (§14); then complete the handshake.
    await ws.accept()                      # performs the 101 handshake (§4)
    try:
        while True:                        # the READ LOOP — one coroutine per connection
            msg = await ws.receive_text()  # awaits the next message
            await ws.send_text(msg)        # echo it straight back
    except WebSocketDisconnect:
        pass                               # client closed or connection died (§6)
    # FastAPI cleans up the connection when the coroutine returns

# uvicorn app:app  — uvicorn speaks the WebSocket protocol for you

Go gives each connection a goroutine running a blocking read loop; Python gives each connection an async coroutine awaiting messages. Same structure — accept, loop reading, write — expressed in each language's concurrency model.

A backend is often a WebSocket client too — consuming a real-time feed from another service, bridging systems, or in tests. The client side: dial the ws:///wss:// URL (which does the handshake), then read and write messages. The shape mirrors the server.

// github.com/gorilla/websocket
func runClient() {
    // Dial performs the upgrade handshake; header carries auth where allowed (§13).
    h := http.Header{"Authorization": {"Bearer " + token}}
    conn, _, err := websocket.DefaultDialer.Dial("wss://api.example.com/ws", h)
    if err != nil {
        log.Fatal(err)
    }
    defer conn.Close()

    // reader goroutine
    go func() {
        for {
            _, msg, err := conn.ReadMessage()
            if err != nil {
                return
            }
            log.Printf("recv: %s", msg)
        }
    }()

    // send a message
    conn.WriteMessage(websocket.TextMessage, []byte(`{"type":"hello"}`))

    // graceful close: send a close frame, then the socket shuts (§6)
    conn.WriteMessage(websocket.CloseMessage,
        websocket.FormatCloseMessage(websocket.CloseNormalClosure, "bye"))
}

# `websockets` library — clean async client
import asyncio, websockets

async def run_client():
    # extra_headers carries auth where the runtime allows it (§13);
    # browsers can't set headers, but a backend client can.
    async with websockets.connect(
        "wss://api.example.com/ws",
        extra_headers={"Authorization": f"Bearer {token}"},
    ) as ws:                                 # context manager → handshake + clean close
        await ws.send('{"type":"hello"}')    # send a message

        async for msg in ws:                 # iterate incoming messages
            print("recv:", msg)
    # leaving the `async with` block sends a close frame and shuts down (§6)

asyncio.run(run_client())

One connection is trivial; the real work is managing many. A server holding thousands of live connections needs a central place that tracks who's connected so it can route and broadcast messages. The canonical solution is the hub (or "connection manager"): a single owner of the set of active connections, with channels/locks to register, unregister, and send — sidestepping the concurrent-write hazard from §8 by funneling everything through one coordinator.

type Hub struct {
    clients    map[*Client]bool
    register   chan *Client
    unregister chan *Client
    broadcast  chan []byte
}

// One goroutine owns the map → all mutation is serialized here (no locks needed).
func (h *Hub) Run() {
    for {
        select {
        case c := <-h.register:
            h.clients[c] = true
        case c := <-h.unregister:
            if _, ok := h.clients[c]; ok {
                delete(h.clients, c)
                close(c.send) // tell the client's writer goroutine to stop
            }
        case msg := <-h.broadcast:
            for c := range h.clients {
                select {
                case c.send <- msg:        // queue into the client's buffered channel
                default:                   // buffer full → slow client; drop it (§12)
                    delete(h.clients, c)
                    close(c.send)
                }
            }
        }
    }
}

import asyncio

class Hub:
    def __init__(self):
        self.clients: set[WebSocket] = set()   # the active connection set

    async def register(self, ws: WebSocket):
        await ws.accept()
        self.clients.add(ws)

    def unregister(self, ws: WebSocket):
        self.clients.discard(ws)               # idempotent removal

    async def broadcast(self, message: str):
        dead = []
        for ws in self.clients:
            try:
                await ws.send_text(message)     # fan out to everyone
            except Exception:
                dead.append(ws)                 # send failed → connection is gone
        for ws in dead:
            self.unregister(ws)                 # clean up on the way out

hub = Hub()
# (asyncio is single-threaded, so the set needs no lock; just don't mutate
#  it while iterating — collect dead ones, remove after.)

Real apps rarely send to everyone — they send to a relevant subset: the members of one chat room, the subscribers to one stock symbol, the players in one game. The pattern is rooms (a.k.a. channels or topics): connections subscribe to named groups, and you broadcast to a group rather than the whole server. Concretely, the hub holds a map from room name to the set of connections in it.

A failure mode unique to push systems: what happens when you produce messages faster than a client can receive them? A phone on a weak connection, a browser tab throttled in the background — the client drains slowly while the server keeps generating data for it. Without a plan, that data piles up in a per-client buffer that grows without bound, and one slow client can exhaust the server's memory. This is backpressure, and you must decide a policy.

The standard implementation (visible in the hub of §10): give each client a bounded send queue. When you try to enqueue and it's full, you don't block the broadcaster (that would let one slow client stall everyone) — instead you apply a policy:

• Drop messages — for lossy data where only the latest matters (a live position, a ticker), discard the overflow or keep only the newest. The slow client misses some updates but the server stays healthy.
• Disconnect the client — for data where gaps are unacceptable, close the slow connection and let it reconnect and re-sync (§17). Better to drop one client than degrade all.
• Conflate / batch — collapse multiple pending updates into one (send the latest snapshot rather than every intermediate step).

Authenticating a WebSocket is trickier than a normal request because of a browser limitation from §4: the JavaScript WebSocket constructor can't set custom headers, so the usual Authorization: Bearer isn't available from a browser. You authenticate at the handshake (it's still an HTTP request — the server can read cookies, the URL, and the subprotocol) and you do it before calling Upgrade/accept. The principle from the auth chapter holds: verify identity at the door; an unauthenticated socket should never be upgraded.

func wsHandler(w http.ResponseWriter, r *http.Request) {
    // AUTHENTICATE FIRST — before upgrading. Reject with a normal HTTP error.
    token := r.URL.Query().Get("token")          // or read a cookie / subprotocol
    user, err := verifyJWT(token)                 // your auth logic (auth chapter)
    if err != nil {
        http.Error(w, "unauthorized", http.StatusUnauthorized) // 401, no upgrade
        return
    }
    // Only now perform the upgrade; attach the identity to the connection.
    conn, err := upgrader.Upgrade(w, r, nil)
    if err != nil {
        return
    }
    serve(conn, user) // every message from this conn is now tied to `user`
}

@app.websocket("/ws")
async def ws_handler(ws: WebSocket):
    # AUTHENTICATE FIRST — before accept(). Close with a policy code if it fails.
    token = ws.query_params.get("token")          # or a cookie / subprotocol
    user = verify_jwt(token)                       # your auth logic (auth chapter)
    if user is None:
        await ws.close(code=1008)                  # 1008 = policy violation; no accept
        return
    await ws.accept()                              # only now complete the handshake
    await serve(ws, user)                          # messages are tied to `user`

WebSockets inherit the web's threat model plus a few of their own. The security chapter's principles apply directly; these are the WebSocket-specific essentials.

This is the defining hard problem of WebSockets, and the reason they complicate architecture far more than stateless HTTP. A WebSocket connection is stateful and pinned to one server: the socket lives in the memory of the specific instance the client connected to. The moment you run more than one instance — which you must, for capacity and availability — a painful question appears: if user A is connected to server 1 and user B (in the same chat room) is connected to server 2, how does A's message reach B? Server 1 has no access to server 2's connections.

The solution is a backplane (a.k.a. pub/sub adapter): an external message system that all server instances connect to. When a server needs to deliver a message to a client that may be on any instance, it publishes the message to the backplane; every instance is subscribed, receives it, and forwards it to whichever of its local connections should get it. The instances no longer need to know about each other's connections — they coordinate through the shared bus. Common backplanes:

• Redis Pub/Sub — the most common choice: simple, fast, low-latency, fire-and-forget. Perfect when you only need live fan-out and don't need history (a disconnected user simply misses messages).
• Kafka — when you also want durability, replay, and the events to feed other systems (the Kafka chapter): publish events to a topic, every WS instance consumes and forwards. Heavier, but the messages become part of your durable event stream.
• NATS / cloud pub/sub — other fast messaging options with similar mechanics.

Putting a load balancer in front of WebSocket servers has its own wrinkles, because the connection is long-lived and stateful rather than a quick request. Three things matter: the LB must support WebSockets, connections usually need affinity, and deploys must drain connections gracefully.

• The LB must speak WebSocket. It has to pass through the Upgrade handshake and then keep the connection open (an L7/HTTP-aware proxy, or L4 TCP pass-through). Most modern LBs (Nginx, HAProxy, cloud ALBs, the Kubernetes Ingress controllers of chapter 21) support this, but you configure longer idle timeouts — a default 60s idle timeout will kill quiet WebSockets, which is another reason for heartbeats (§7).
• Sticky sessions / affinity. Once a client is connected to instance 1, all its frames must keep going to instance 1 (that's where its socket lives). With raw TCP that's automatic (one connection = one backend), but reconnections and any per-message routing want session affinity so a client returns to a consistent instance. With a backplane (§15) affinity matters less for delivery (any instance can publish/receive), but it still affects local state.
• Connection draining on deploy. The big one: deploying a new version (the rolling updates of chapter 21 §18) terminates instances, and every WebSocket on a terminating instance drops. You must drain gracefully — stop accepting new connections, send a close frame (code 1001 "going away") so clients reconnect cleanly to a healthy instance, and allow time before SIGKILL (graceful shutdown chapter). Even so, a deploy causes a reconnection storm — which is why robust client reconnection (§17) is mandatory.

Given everything above — connections drop silently (§6), deploys disconnect everyone (§16), networks are flaky — a real-time client that doesn't automatically reconnect is broken by design. Resilience lives mostly on the client, with server-side support for re-syncing missed state. (Note: SSE gives you reconnection for free — another reason to prefer it when you only need server push, §2.)

The resilience checklist

• Reconnect with exponential backoff + jitter. Don't hammer a struggling server with instant retries; grow the delay (1s, 2s, 4s, … capped) and add randomness so thousands of clients disconnected by a deploy don't all reconnect at the same instant (the thundering-herd / reconnect-storm problem from §16).
• Re-sync after reconnect. A new connection means a possible gap in the stream. On reconnect, the client should reconcile: fetch current state via a normal HTTP call, or tell the server "last event I saw was N, send me everything since" (a resume token / sequence number). This is where a durable backplane like Kafka (§15) shines — the missed messages are still in the log to replay.
• Decide your delivery guarantee. Like Kafka (§9), WebSocket delivery isn't magically exactly-once. For critical data, give messages sequence numbers/IDs so the client can detect gaps and duplicates, and make handling idempotent. For lossy data (live positions), a gap is fine — the next update corrects it.
• Buffer outbound on the client while disconnected (within limits), and flush on reconnect — so a user's action taken during a blip isn't simply lost.

The decision that should come before you build anything real-time. WebSockets are powerful but carry the operational weight of Part IV (stateful connections, backplane, sticky sessions, reconnection), so picking the simplest tool that fits is a real cost saving. Four contenders, drawing together the spectrum (§2) and the gRPC chapter.

The failure modes that bite WebSocket servers in production — most are about resource management for long-lived, stateful connections, a discipline stateless HTTP never demanded.

Pulling the manual into design judgment for anything real-time.

Design principles

• Choose the lightest transport first. Polling → SSE → WebSocket → gRPC streaming, leftmost that fits (§18). Don't pay for WebSocket complexity unless you need bidirectional browser traffic.
• Design the backplane in from day one if you'll ever run more than one instance — which is always, in production (§15). Retrofitting cross-instance delivery into a single-instance design is painful.
• Treat disconnection as normal. Heartbeats to detect it (§7), graceful drain on deploy (§16), client reconnection with backoff + jitter and state re-sync (§17). The connection will churn; build for it.
• Bound everything per connection. Send-buffer size, message size, message rate, connections per user (§12, §14, §19). Unbounded anything is an outage waiting for one bad client.
• Don't assume reliable, ordered, exactly-once delivery. Add sequence numbers/IDs for gap detection and idempotent handling where it matters; accept loss where it doesn't (§17, echoing Kafka §9).
• Authenticate at the handshake, authorize every message, secure the channel. wss://, origin checks, validated inbound messages (§13–14).
• Keep the read loop fast; offload real work to a queue/worker (ch.10), and serialize writes through one writer per connection (§8).

The whole manual compressed to what you reach for under pressure.