WebSocket Patterns (Deep Workflow)

Realtime connections add stateful complexity: who is connected, what order messages arrive, and what happens when links flap. Design for at-least-once delivery, explicit heartbeats, and horizontal scaling early.

When to Offer This Workflow

Trigger conditions:

Replacing polling with WS or SSE
Auth on connect; token refresh mid-session
Fan-out to many subscribers; presence and typing indicators
Sticky sessions, load balancer timeouts, reconnect storms

Initial offer:

Use six stages: (1) choose transport, (2) connection & auth, (3) protocol & messages, (4) reliability & ordering, (5) scale & ops, (6) security & abuse). Confirm browser vs server clients and proxies (nginx, ALB, Cloudflare).

Stage 1: Choose Transport

Goal: WebSocket vs SSE vs long polling—right tool per direction.

Heuristics

Bidirectional, low latency, binary payloads → WebSocket
Server → client one-way streams, HTTP-friendly infra → SSE
Fire-and-forget notifications with simple infra → consider push services first

Caveats

Corporate proxies historically hurt WS—test environments; WSS mandatory
HTTP/3 QUIC stacks differ—validate intermediaries

Exit condition: Transport choice documented with why not alternatives.

Stage 2: Connection & Auth

Goal: Authenticated sockets without long-lived secrets in query strings when avoidable.

Patterns

JWT in Sec-WebSocket-Protocol or first message after connect—prefer short-lived tokens + refresh flow
Cookie sessions with CSRF considerations on same-site policies
Re-auth before token expiry; graceful close with code and reason

Authorization

Subscribe to topics only after server-side check—never trust client channel names alone

Exit condition: Auth diagram: issue token → connect → authorize subscriptions.

Stage 3: Protocol & Messages

Goal: Versioned message schema; predictable errors.

Design

Envelope: { type, id, ts, payload }; correlation ids for RPC-style
Version negotiation on connect or feature flags in hello message
Binary vs JSON—protobuf/msgpack for bandwidth; JSON for debuggability early

Heartbeats

Ping/pong or application-level heartbeat at interval < proxy timeout (often 30–60s)
Idle detection and clean disconnect

Exit condition: Protocol doc + example session transcript.

Stage 4: Reliability & Ordering

Goal: Define delivery semantics—usually at-least-once over TCP; ordering per channel.

Practices

Idempotent message handlers; dedupe by message id when retries exist
Per-user sequence numbers if strict order matters
Buffer limits: drop, close, or apply backpressure policy

Reconnect

Exponential backoff + jitter to prevent thundering herd
Resume from last seen seq if missed messages are unacceptable—persist or snapshot

Exit condition: Reconnect story documented; storm mitigation tested.

Stage 5: Scale & Operations

Goal: Many connections across many nodes—affinity and pub/sub backbone.

Architecture

Sticky sessions or shared pub/sub (Redis, NATS, Kafka) for cross-node fan-out
Shard connection maps; avoid single giant in-memory map on one box

Observability

Metrics: active connections, msg/sec, queue depth, disconnect reasons
Tracing: connect → subscribe → first message latency

Load shedding

Max connections per IP/user; rate limit connection attempts

Exit condition: Capacity model: connections per node × message fan-out cost.

Stage 6: Security & Abuse

Goal: Minimize attack surface on long-lived pipes.

Controls

WSS everywhere; validate Origin where applicable
Payload size limits; compression bomb awareness
AuthZ on every subscription; audit admin actions

Abuse

Spam detection; kick/ban flows; circuit breakers on misbehaving clients

Final Review Checklist

Transport choice justified (WS/SSE/etc.)
AuthN/Z on connect and per-channel
Heartbeats aligned with proxy/LB timeouts
Delivery/idempotency/reconnect semantics explicit
Horizontal scale path + observability + abuse controls

Tips for Effective Guidance

ALB idle timeout vs heartbeat—classic production bug; call it out.
When user says “real-time,” ask latency target and ordering needs.
SSE is simpler—don’t default to WS for one-way feeds.

Handling Deviations

Edge runtimes (Workers): different connection limits and duration—validate platform.
Mobile: background suspension—push notifications may complement WS.