Realtime WebSockets and SSE skill for Claude Code

A realtime system is done when connections are authenticated at the handshake, dead peers are detected within a minute, slow consumers cannot exhaust server memory, any server instance can deliver any message, and clients reconnect and catch up without user action or a thundering herd.

Workflow

- [ ] 1. Pick the transport from the traffic pattern
- [ ] 2. Define the message protocol (envelope, types, versioning, sequence numbers)
- [ ] 3. Authenticate the handshake; authorize every subscription
- [ ] 4. Heartbeats and idle timeouts across every hop
- [ ] 5. Backpressure and per-connection limits
- [ ] 6. Fan-out across instances (pub/sub) and connection state storage
- [ ] 7. Client reconnection with backoff, jitter and resume
- [ ] 8. Deploy draining, metrics, load test

1. Transport choice

Pattern	Use
Server pushes, client rarely sends (feeds, notifications, progress, LLM token streams)	SSE (text/event-stream): plain HTTP, auto-reconnect, Last-Event-ID resume
Bidirectional, low-latency, frequent client messages (chat, games, collaboration, presence)	WebSocket
Updates every 30 s+ or very constrained infra	Polling with ETags
Browser-to-browser media or data	WebRTC (signaling over WS)
Managed option without running sockets	Pusher/Ably/Supabase Realtime/Cloudflare Durable Objects

SSE over HTTP/1.1 is limited to about 6 connections per origin per browser; serve over HTTP/2 or multiplex streams into one connection. Socket.IO is a protocol on top of WS with its own client; only use it when you want its rooms, acks and fallbacks, and then use its Redis adapter for scaling.

2. Protocol

{ "v": 1, "type": "message.created", "id": "evt_01J...", "seq": 1842, "channel": "room:42", "data": { } }

• Every server event carries a monotonically increasing seq per channel (or a global event ID) so clients detect gaps and resume.
• Client commands carry a client-generated id; the server replies with ack or error referencing it. Commands are idempotent by that ID.
• Validate every inbound message against a schema; cap message size (e.g. 64 KB) with the server’s max payload option.
• Version the envelope (v); old clients live for weeks in open tabs.

3. Authentication and authorization

• Browsers cannot set custom headers on new WebSocket(url). Options in order of preference:
  1. Same-site session cookie sent with the handshake, plus a strict Origin header allowlist check on upgrade (prevents cross-site WebSocket hijacking).
  2. Short-lived single-use ticket: client calls POST /realtime/ticket (authenticated), receives a token valid for 30-60 s, connects with wss://.../ws?ticket=...; server redeems and deletes it. Never put long-lived tokens in URLs (they land in logs).
  3. First message {type:"auth", token} with a server timeout of a few seconds before closing.
• Authorize each subscribe: subscribe room:42 checks membership server-side; channel names from clients are untrusted input.
• Re-validate on token expiry: close with code 4001 (app-defined) and let the client reauthenticate, or push a refresh request before expiry.

4. Heartbeats and timeouts

Every hop has an idle timeout that silently kills quiet connections: AWS ALB 60 s default (configurable), nginx proxy_read_timeout 60 s default, Cloudflare about 100 s, mobile NATs often less. Send a ping every 20-30 s from the server (WS ping frames, or an SSE comment line : ping\n\n), and terminate connections that miss two pongs. Server-side dead-peer detection prevents leaked connections from piling up after network drops.

Proxy configuration for upgrades and buffering is in references/infra-config.md; read it when deploying behind nginx, a cloud load balancer, or Kubernetes ingress.

5. Backpressure

import { WebSocketServer, WebSocket } from "ws";

const wss = new WebSocketServer({ noServer: true, maxPayload: 64 * 1024 });
const MAX_BUFFERED = 1 * 1024 * 1024;   // 1 MiB queued per client

function send(ws: WebSocket, msg: object) {
  if (ws.readyState !== WebSocket.OPEN) return;
  if (ws.bufferedAmount > MAX_BUFFERED) {
    ws.close(1013, "slow consumer");    // try again later; client resyncs on reconnect
    return;
  }
  ws.send(JSON.stringify(msg));
}

Policies for slow consumers: drop and resync (above), coalesce (send only the latest state per key), or sample. Never let an unbounded per-connection queue grow. Also cap connections per user and per IP, and inbound message rate per connection.

6. Scaling out

• Each instance holds only its own sockets. Publish events to a broker (Redis pub/sub, Redis Streams, NATS, Postgres LISTEN/NOTIFY for small scale); every instance subscribes and delivers to its local sockets for that channel.
• Redis pub/sub is fire-and-forget: an instance that blips misses messages. For guaranteed catch-up, persist events (Redis Streams with IDs, or a DB table) and let clients resume from seq.
• Sticky sessions are not required for raw WS/SSE once fan-out uses a broker; they are required for Socket.IO’s HTTP long-polling fallback.
• Presence: store per-connection entries with TTL in Redis (refresh on heartbeat), not in instance memory.
• Capacity: plan memory per connection (tens of KB in Node ws plus buffers), raise file descriptor limits (ulimit -n), and load test before launch.

7. Client reconnection

let attempt = 0;
async function connect() {
  const ws = new WebSocket(`wss://api.example.com/ws?ticket=${await getTicket()}`);
  ws.onopen = () => { attempt = 0; ws.send(JSON.stringify({ type: "resume", lastSeq })); };
  ws.onclose = (e) => {
    if (e.code === 4001) return reauthenticate().then(connect);   // app-defined auth failure
    const delay = Math.min(30_000, 1000 * 2 ** attempt++) * Math.random();   // full jitter
    setTimeout(connect, delay);
  };
}

On resume, the server replays events after lastSeq or tells the client to refetch full state if the gap is too old. Also reconnect on online and visibilitychange events. SSE’s EventSource reconnects automatically and sends Last-Event-ID if events carry id: lines; set the retry: field to control delay.

8. Deploys and observability

• On SIGTERM: stop accepting upgrades, send close code 1012 (service restart) or 1001 (going away) to clients in batches spread over 10-30 s, then exit. Clients reconnect to new instances with jitter instead of all at once.
• Metrics: open connections, connects/disconnects per minute by close code, messages in/out per second, send-buffer drops, broker lag, handshake auth failures.

Gotchas

• ws:// from an https:// page is blocked as mixed content; always wss:// in production.
• Compression (permessage-deflate) costs memory per connection; leave it off unless messages are large and repetitive.
• Serverless functions cannot hold WebSockets; use API Gateway WebSocket APIs, Durable Objects, or a dedicated service.
• Broadcasting by looping over all sockets on every event does not scale; index sockets by channel.
• Close codes 4000-4999 are for applications; 1006 means abnormal closure (network drop or no close frame), never sent explicitly.

Verification

1. Integration test: two clients on different server instances; a message published via instance A arrives at a client on instance B.
2. Kill the network (or the server) mid-session: the client reconnects with backoff and receives missed events via resume.
3. Simulate a slow consumer (pause reading): server memory stays bounded and the connection closes with 1013.
4. Leave a connection idle for 5 minutes behind the real proxy: it stays open.
5. Load test (k6 k6/ws or artillery) to target connection count; record memory per connection.