WebSocket Builder

---
name: websocket-builder
description: |
  Trigger when the user asks to add realtime features, build a WebSocket
  server, or set up persistent connections. Phrases: "WebSocket",
  "realtime", "live updates", "push notifications", "pub/sub", "socket.io".
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash(pnpm add *)
---

# WebSocket Builder

Build realtime features without the foot-guns. Covers connection
lifecycle, auth, heartbeats, reconnection, backpressure, and when to
reach for a hosted service instead of rolling your own.

## Prerequisites

- Transport decided: raw WebSocket, socket.io, Pusher, Ably, Supabase
  Realtime, or server-sent events (SSE)
- Hosting that supports long-lived connections (not Lambda, not serverless
  edge with short timeouts)

## Steps

1. **Choose the cheapest option that fits.** If you only need server to
   client, use SSE. If you need bidirectional but low volume, use raw
   WebSocket. If you need presence, rooms, or horizontal scale from day
   one, use a hosted service (Pusher, Ably, Supabase Realtime) and skip
   the ops burden.

2. **Authenticate on connect, not per message.** Pass a short-lived token
   as a query param or subprotocol. Validate on `connection`. Close
   4401 if invalid. Rotate tokens on refresh.

3. **Define a small message schema.** Every message has `type`,
   `payload`, and optionally `id`. Validate with Zod on both ends.
   ```ts
   const Msg = z.discriminatedUnion('type', [
     z.object({ type: z.literal('ping') }),
     z.object({ type: z.literal('chat'), payload: z.object({ text: z.string() }) }),
   ]);
   ```

4. **Heartbeat every 30 seconds.** Proxies and load balancers kill idle
   connections. Client sends `ping`, server replies `pong`. If no
   pong in 60s, reconnect.

5. **Reconnect with backoff and resume.** Exponential backoff capped at
   30 seconds, full jitter. On reconnect, send the last seen message ID
   so the server can replay missed events from a short buffer (Redis
   stream, in-memory ring).

6. **Backpressure.** If the client cannot keep up, drop or coalesce
   messages on the server side. Never let the outgoing buffer grow
   unbounded (that is how you OOM).

7. **Horizontal scale.** Multiple Node instances cannot broadcast to each
   other directly. Use Redis pub/sub, NATS, or the adapter built into
   socket.io. Without this, "send to room X" only reaches the instance
   the sender is on.

8. **Graceful shutdown.** On SIGTERM, stop accepting new connections,
   send a `server_shutdown` message to all clients so they reconnect to
   a healthy instance, then wait up to 30 seconds before killing sockets.

## Patterns that work

- One WebSocket per tab, multiplexed by channel/topic
- Server-authoritative state; clients send intents, server broadcasts
  results
- Idempotent messages with client-generated IDs so retries are safe
- Separate fan-out (pub/sub) from delivery (socket write)

## Anti-patterns

- Putting WebSockets behind a serverless function (connections die)
- No heartbeat, then debugging "why does it disconnect after 60s?"
- Broadcasting large payloads to every connected client (send deltas)
- Trusting client-sent state without server validation

## Output

- WebSocket server module with auth, heartbeat, and message validation
- Client wrapper with reconnect + resume
- Redis (or equivalent) adapter for multi-instance broadcast
- Load test showing behavior at target concurrency