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.