WebSockets, from Upgrade to close frame

HOW IT FITS TOGETHER

KEY TERMS

Upgrade handshake

A GET with Upgrade: websocket and a random Sec-WebSocket-Key. The server replies 101 with Sec-WebSocket-Accept, the SHA-1 of the key plus a fixed GUID, base64-encoded. This only proves both ends understood the protocol; it is the last point where HTTP auth, cookies and status codes apply.

Frames and opcodes

Messages are split into frames: 0x1 text (must be UTF-8), 0x2 binary, 0x0 continuation, and control frames 0x8 close, 0x9 ping, 0xA pong. Control frames are at most 125 bytes and never fragmented.

Masking

Clients must XOR every frame with a fresh random 4-byte key; servers must not mask. It exists to stop attacker-controlled bytes from looking like HTTP to naive intermediaries (cache poisoning), not for confidentiality. TLS does that.

Close codes

1000 normal, 1001 going away, 1008 policy violation, 1009 message too big, 1011 server error. 1006 means the connection died without a close frame; it is reported locally and must never be sent.

WebSockets over HTTP/2 and HTTP/3

RFC 8441 bootstraps a WebSocket on one HTTP/2 stream via extended CONNECT (:protocol = websocket) once the server sends SETTINGS_ENABLE_CONNECT_PROTOCOL; success is 200, not 101, and Sec-WebSocket-Key/Accept are not used. RFC 9220 applies the same to HTTP/3.

Backpressure

send() usually just queues bytes. If the peer reads slower than you write, the queue grows in process memory (bufferedAmount) until something crashes. The browser WebSocket API has no backpressure at all; servers need per-connection limits and a policy for slow consumers.

WebSocket vs SSE

Server-Sent Events are plain HTTP responses (text/event-stream), server-to-client only, with built-in reconnect and Last-Event-ID resume. They pass through HTTP infrastructure untouched. Use SSE for feeds and notifications; use WebSockets when the client sends frequent low-latency messages.

IN YOUR STACK

const ws = new WebSocket("wss://api.example.com/ws?ticket=" + ticket, ["v1.json"]);

ws.addEventListener("open", () => {
  ws.send(JSON.stringify({ type: "subscribe", topic: "orders", after: lastSeq }));
});

ws.addEventListener("message", (event) => {
  const msg = JSON.parse(event.data);
  if (msg.seq <= lastSeq) return; // replayed or duplicate after reconnect
  lastSeq = msg.seq;
  apply(msg);
});

ws.addEventListener("close", (event) => {
  // 1006: no close frame (network drop, proxy idle timeout, server crash)
  console.warn("closed", event.code, event.reason, event.wasClean);
  scheduleReconnectWithJitter();
});

function sendBounded(data) {
  // No backpressure in this API: check the queue before adding to it.
  if (ws.readyState === WebSocket.OPEN && ws.bufferedAmount < 1_000_000) ws.send(data);
}

import { createServer } from "node:http";
import { WebSocketServer } from "ws";
const server = createServer();
const wss = new WebSocketServer({ noServer: true, maxPayload: 1 << 20 });
server.on("upgrade", (req, socket, head) => {
  const user = authenticate(req); // cookie or ticket; also check req.headers.origin
  if (!user) {
    socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
    return socket.destroy();
  }
  wss.handleUpgrade(req, socket, head, (ws) => wss.emit("connection", ws, req, user));
});
wss.on("connection", (ws, req, user) => {
  let alive = true;
  ws.on("pong", () => { alive = true; });
  const timer = setInterval(() => {
    if (!alive) return ws.terminate(); // no pong since last ping
    alive = false;
    ws.ping();
  }, 30_000);
  ws.on("close", () => clearInterval(timer));
  ws.on("message", (data, isBinary) => {
    if (ws.bufferedAmount > 4 << 20) return ws.close(1008, "slow consumer");
    ws.send(data, { binary: isBinary });
  });
});
server.listen(8080);

// server
import { Server } from "socket.io";
const io = new Server(3000, { cors: { origin: "https://app.example.com" } });

io.use((socket, next) => {
  const user = verifyToken(socket.handshake.auth.token);
  if (!user) return next(new Error("unauthorized")); // client gets connect_error
  socket.data.user = user;
  next();
});

io.on("connection", (socket) => {
  socket.join(`user:${socket.data.user.id}`);
  socket.on("order:place", async (order, ack) => {
    ack({ ok: true, id: await placeOrder(order, socket.data.user) });
  });
});

// client
import { io as connect } from "socket.io-client";
const socket = connect("https://api.example.com", { auth: { token }, ackTimeout: 10_000, retries: 3 });
socket.on("connect_error", (err) => console.warn(err.message));
const res = await socket.emitWithAck("order:place", { sku: "A1", idempotencyKey });

// import "github.com/coder/websocket"
func handleWS(w http.ResponseWriter, r *http.Request) {
	c, err := websocket.Accept(w, r, &websocket.AcceptOptions{
		OriginPatterns: []string{"app.example.com"},
	})
	if err != nil {
		return // Accept has already written the HTTP error
	}
	defer c.CloseNow()
	c.SetReadLimit(1 << 20)

	for {
		typ, msg, err := c.Read(r.Context())
		if err != nil {
			return // inspect websocket.CloseStatus(err) for the peer's code
		}
		ctx, cancel := context.WithTimeout(r.Context(), 5*time.Second)
		err = c.Write(ctx, typ, msg) // the deadline bounds a slow reader
		cancel()
		if err != nil {
			return
		}
	}
}

from typing import Annotated
from fastapi import Depends, FastAPI, Query, WebSocket, WebSocketDisconnect, WebSocketException, status

app = FastAPI()

async def ws_user(websocket: WebSocket, ticket: Annotated[str | None, Query()] = None):
    user = await redeem_ticket(ticket)  # one-time, short-lived
    if user is None:
        raise WebSocketException(code=status.WS_1008_POLICY_VIOLATION)
    return user

@app.websocket("/ws")
async def ws_endpoint(websocket: WebSocket, user: Annotated[User, Depends(ws_user)]):
    await websocket.accept()
    try:
        while True:
            msg = await websocket.receive_json()
            await websocket.send_json({"echo": msg, "user": user.id})
    except WebSocketDisconnect as exc:
        logger.info("client left with code %s", exc.code)

use axum::extract::ws::{Message, WebSocket, WebSocketUpgrade};
use axum::{response::Response, routing::any, Router};

// Extractors (auth, State) run before the upgrade, so a rejection is a normal HTTP error.
async fn ws_handler(ws: WebSocketUpgrade, user: AuthUser) -> Response {
    ws.max_message_size(1 << 20)
        .on_upgrade(move |socket| handle_socket(socket, user))
}

async fn handle_socket(mut socket: WebSocket, user: AuthUser) {
    while let Some(Ok(msg)) = socket.recv().await {
        match msg {
            Message::Text(text) => {
                let reply = format!("{}: {}", user.id, text.as_str());
                if socket.send(Message::text(reply)).await.is_err() {
                    return; // client went away
                }
            }
            Message::Close(_) => return,
            _ => {} // pings are answered automatically
        }
    }
}
pub fn router() -> Router { Router::new().route("/ws", any(ws_handler)) }

# endpoint.ex
socket "/socket", MyAppWeb.UserSocket, websocket: true, longpoll: false, auth_token: true
defmodule MyAppWeb.UserSocket do
  use Phoenix.Socket
  channel "room:*", MyAppWeb.RoomChannel

  def connect(_params, socket, connect_info) do
    case Phoenix.Token.verify(socket, "user socket", connect_info[:auth_token], max_age: 86_400) do
      {:ok, user_id} -> {:ok, assign(socket, :user_id, user_id)}
      {:error, _reason} -> :error
    end
  end

  def id(socket), do: "users_socket:#{socket.assigns.user_id}"
end
defmodule MyAppWeb.RoomChannel do
  use Phoenix.Channel
  def join("room:" <> _room_id, _payload, socket), do: {:ok, socket}

  def handle_in("new_msg", %{"body" => body}, socket) do
    broadcast!(socket, "new_msg", %{body: body, user_id: socket.assigns.user_id})
    {:noreply, socket}
  end
end

var request = URLRequest(url: URL(string: "wss://api.example.com/ws")!)
request.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
let task = URLSession.shared.webSocketTask(with: request)
task.maximumMessageSize = 1 << 20
task.resume()

try await task.send(.string(#"{"type":"subscribe","topic":"orders"}"#))

let heartbeat = Task {
    while !Task.isCancelled {
        try await Task.sleep(for: .seconds(25))
        task.sendPing { error in if let error { print("ping failed:", error) } }
    }
}
defer { heartbeat.cancel() }

while true {
    switch try await task.receive() { // throws once the connection closes
    case .string(let text): handle(text)
    case .data(let data): handle(data)
    @unknown default: break
    }
}

WHERE IT BITES

• Forgetting proxy configuration: Upgrade and Connection are hop-by-hop, so nginx and similar proxies must forward them explicitly, and nginx closes a proxied connection after 60 s with no data unless you send pings or raise proxy_read_timeout.
• Authenticating only at connect time: the socket outlives the token. Re-check on sensitive messages or close with 1008 when the session is revoked or expires.
• Skipping Origin checks. WebSockets are not covered by CORS and browsers can attach cookies to cross-site handshakes, so a cookie-authenticated endpoint without an Origin allowlist is open to cross-site WebSocket hijacking.
• Unbounded send queues: one slow mobile client can grow server memory without limit. Cap bufferedAmount per connection and drop, coalesce or disconnect.
• Treating the stream as the source of truth. Connections end without a close frame (1006); resume from a sequence number or reload an HTTP snapshot after every reconnect.
• Using WebSockets for a one-way feed. SSE gets reconnect, Last-Event-ID resume and normal HTTP caching and auth for free.

WHEN IT BREAKS IN PRODUCTION

• WebSockets disconnect, duplicate, or lose events
• Optimistic UI lies about money

SOURCES

• RFC 6455: The WebSocket Protocol (opens in new tab)Checked 2026-10-07
• RFC 8441: Bootstrapping WebSockets with HTTP/2 (opens in new tab)Checked 2026-10-07
• RFC 9220: Bootstrapping WebSockets with HTTP/3 (opens in new tab)Checked 2026-10-07
• MDN: WebSocket (opens in new tab)Checked 2026-10-07
• NGINX: WebSocket proxying (opens in new tab)Checked 2026-10-07
• MDN: Using server-sent events (opens in new tab)Checked 2026-10-07