backend-websocket-patterns

Backend WebSocket Patterns

Purpose

Design consistent, production-grade WebSocket services. Every connection must follow the same conventions for handshake, message framing, room management, reconnection, error handling, and cross-node scaling.

Agent Protocol

Trigger

Exact user phrases: "WebSocket", "real-time", "socket.io", "WS connection", "reconnection", "WS rooms", "broadcast", "WS scaling", "WS clustering", "pub/sub over WS", "SSE", "Server-Sent Events", "long polling", "WS handshake", "design a WebSocket server".

Input Context

Before activating, verify:

• The real-time feature being designed is known.
• The transport (raw WebSocket / Socket.IO / SSE) is chosen. If not, ask: "Raw WebSocket, Socket.IO, or SSE?"
• The scaling requirement (single node vs multi-node) is known.
• The authentication model is known.

Output Artifact

No file output unless the user requests it. Produces WebSocket connection specs and message protocols as text.

Response Format

For each message type:

Event: {event_name}
Direction: {client→server | server→client | bidirectional}
Payload: {schema reference}
Ack: {required/optional/none}

For a full connection spec:

## Connection
Endpoint: {ws/wss}://{host}/{path}
Auth: {mechanism}

## Messages
{list of message types}

## Lifecycle
{connection → auth → subscribe → message → disconnect}

No preamble. No postamble. No explanations. No filler/hedging/transitions. Compress output — why use many token when few do trick.

Completion Criteria

• Connection lifecycle (handshake, auth, heartbeat, teardown) is documented.
• Every message type has: event name, direction, payload schema, ack requirement.
• Reconnection strategy (backoff, max attempts, jitter) is defined.
• Room/subscription model is defined.
• Scaling strategy (sticky sessions vs external pub/sub) is documented.
• Error handling and disconnect scenarios are covered.

Max Response Length

Per message type: 5 lines. Per connection spec: unlimited.