Real-Time API Design (SSE, WebSockets, Polling)

## ROLE

You are a real-time systems architect who has designed and operated live communication infrastructure for applications requiring instant data delivery — chat platforms, live dashboards, collaborative editing tools, trading systems, and gaming backends. You have deep expertise in WebSocket protocol internals, Server-Sent Events, long polling optimization, and the infrastructure challenges of maintaining millions of concurrent persistent connections. You understand when each real-time pattern is appropriate and how to combine them for optimal developer and user experience.

## OBJECTIVE

Design a real-time communication layer for [APPLICATION: live dashboard / chat application / collaborative editor / notification system / trading platform / IoT monitoring / gaming backend / live streaming platform / auction system / project management tool] built on [STACK: Node.js + Socket.io / Node.js + ws / Python + FastAPI / Go + Gorilla / Java + Spring WebSocket / Elixir + Phoenix / Rust + Tokio / .NET SignalR]. The system must deliver real-time updates for [USE CASES: list 3-6, e.g., live price feeds, typing indicators, presence updates, notification delivery, cursor positions, chat messages]. Expected concurrent connections: [CONNECTIONS: hundreds / thousands / tens of thousands / hundreds of thousands]. Message volume: [VOLUME: hundreds / thousands / tens of thousands / hundreds of thousands] messages per second. The infrastructure runs on [PLATFORM: single server / horizontally scaled servers / Kubernetes / serverless / edge network].

## TASK: COMPLETE REAL-TIME API DESIGN

### Pattern Selection & Architecture Decision
Evaluate each real-time communication pattern for your specific use cases and make a clear recommendation.

**Long Polling:** The client sends a request, the server holds it open until new data is available or a timeout occurs, responds, and the client immediately sends a new request. Advantages: works everywhere (no special protocol support needed), passes through all proxies and firewalls, simple to implement on both sides. Disadvantages: higher latency (seconds), higher server resource usage (holding open HTTP connections), request overhead on each reconnect. Best for: notification feeds, infrequent updates, environments with restrictive network policies. Provide the complete implementation: server endpoint that holds requests in a pending queue, resolves them when data arrives or after [TIMEOUT: 25-30]s, and handles client disconnection. Provide the client implementation with automatic reconnection and backoff.

**Server-Sent Events (SSE):** The server sends a stream of events over a single long-lived HTTP connection. The client opens the connection with EventSource and receives events as they arrive. Advantages: built on HTTP (works with existing infrastructure), automatic reconnection with Last-Event-ID for resumption, simpler than WebSockets for server-to-client streaming, native browser support. Disadvantages: unidirectional (server to client only), limited concurrent connections per domain in HTTP/1.1 (6 connections), text-only (no binary). Best for: live feeds, dashboards, notifications, activity streams. Provide the complete SSE implementation: server endpoint that sets the correct headers (Content-Type: text/event-stream, Cache-Control: no-cache, Connection: keep-alive), formats events with id, event, data, and retry fields, implements heartbeat pings every [HEARTBEAT: 15-30]s to detect dead connections, and supports Last-Event-ID for missed event recovery. Provide the client implementation with EventSource and custom reconnection logic.

**WebSockets:** Full-duplex bidirectional communication over a single TCP connection after an HTTP upgrade handshake. Advantages: lowest latency, bidirectional, binary and text support, minimal per-message overhead. Disadvantages: requires WebSocket support on all intermediaries (some proxies strip upgrade headers), more complex server implementation, connection state management at scale. Best for: chat, collaborative editing, gaming, live trading, any use case requiring client-to-server real-time communication. Provide the complete WebSocket implementation: server that handles the upgrade handshake, manages connection lifecycle (open, message, close, error events), implements a message protocol (JSON with type, payload, timestamp, and message ID), handles authentication during the handshake (token in query parameter or first message), and implements heartbeat/ping-pong frames every [PING: 20-30]s to detect dead connections. Provide the client implementation with automatic reconnection, exponential backoff, and message buffering during disconnection.

For your [USE CASES], provide a recommendation matrix mapping each use case to the best pattern with rationale. If a hybrid approach is recommended (e.g., SSE for server updates + REST for client actions), document the combined architecture.

### Authentication & Authorization for Persistent Connections
Design the authentication strategy for long-lived connections that cannot send Authorization headers on every message. For WebSockets: authenticate during the connection handshake using a [METHOD: JWT in query parameter / JWT in first message / session cookie / ticket-based auth]. For ticket-based auth: the client first calls a REST endpoint (POST /ws/ticket) with standard Authorization header, receives a short-lived ticket (valid for [TTL: 30-60]s, single-use), and passes the ticket as a query parameter during the WebSocket handshake. The server validates the ticket, associates the connection with the authenticated user, and immediately invalidates the ticket. For SSE: authenticate using [METHOD: cookie-based session / bearer token in EventSource URL / custom middleware]. Address token expiration during long-lived connections: implement a re-authentication protocol where the server sends an auth_required event before closing the connection, and the client transparently reconnects with a fresh token. Implement authorization for channels/rooms: define which users can subscribe to which event streams ([MODEL: user-specific events / role-based channels / resource-level permissions / topic-based subscriptions with ACLs]). Provide the complete auth flow implementation for your [STACK] with [NUMBER: 3-4] code examples covering initial auth, re-auth, and unauthorized access rejection.

### Message Protocol & Event Design
Design the message protocol for real-time communication. Define a standard message envelope: { type: string, payload: object, id: string, timestamp: string, version: number }. Define the event type taxonomy for your [USE CASES]. Categorize events by: data events (carrying business data: order.updated, message.created, price.changed), control events (managing the connection: ping, pong, subscribe, unsubscribe, auth, error), and presence events (tracking online status: user.online, user.offline, user.typing). For each event type, define: the payload schema with typed fields, whether the event is ephemeral (not persisted, e.g., typing indicators) or durable (persisted and replayable, e.g., chat messages), the delivery guarantee (at-most-once for ephemeral, at-least-once for durable), and an example payload with realistic data. Implement message ordering: assign monotonically increasing sequence numbers per channel, and document how clients detect and handle gaps (request missed messages via REST endpoint). Implement message compression for high-volume streams: use [COMPRESSION: per-message deflate for WebSocket / gzip for SSE] and define the minimum message size threshold for compression. Define the maximum message size ([MAX: 32KB-1MB]) and the behavior when a message exceeds it (truncate with reference link, or reject with error). Provide the complete message protocol specification with [NUMBER: 8-12] example messages covering all event categories.

### Scaling & Infrastructure
Design the system to handle [CONNECTIONS] concurrent connections across [SERVER COUNT: multiple] server instances. Address the fundamental challenge: when a client connects to Server A but the event originates on Server B, how does Server B's event reach Server A's client? Implement a pub/sub backbone using [PUBSUB: Redis Pub/Sub / Redis Streams / Kafka / NATS / RabbitMQ / custom]: every server subscribes to relevant channels, when an event is generated it is published to the pub/sub system, and every server forwards matching events to their connected clients. Calculate the capacity per server: each WebSocket connection uses approximately [MEMORY: 2-10] KB of memory and [FD: 1] file descriptor. For [CONNECTIONS] total connections across [SERVERS: N] servers, each server handles approximately [CONNECTIONS/N] connections. Configure the operating system: increase file descriptor limits (ulimit -n [FD LIMIT: 100000-1000000]), tune TCP settings (keepalive, buffer sizes), and configure the event loop to handle the connection count. Implement connection affinity for stateful protocols: sticky sessions at the load balancer (based on cookie or client ID) or handle any-server-any-connection with the shared pub/sub layer. Design horizontal auto-scaling: add server instances when the average connection count per server exceeds [THRESHOLD: 60-80%] of capacity, and drain connections gracefully during scale-down (send reconnect events to clients and wait for them to establish connections to other servers). Provide the complete infrastructure configuration for [PLATFORM] with load balancer, auto-scaling, and pub/sub setup.

### Reliability, Reconnection & Offline Handling
Design the client-side reliability layer. Implement automatic reconnection with [STRATEGY: exponential backoff starting at 1s, maximum 30s, with jitter] on connection loss. During disconnection, buffer outgoing messages (up to [BUFFER: 50-100] messages or [SIZE: 1MB]) and flush them upon reconnection. Implement missed event recovery: the client tracks the last received event ID, sends it during reconnection (SSE: Last-Event-ID header, WebSocket: in the reconnect handshake message), and the server replays events from that point forward using [EVENT STORE: Redis Streams / database event log / Kafka topic]. Define the maximum replay window ([WINDOW: 5 minutes / 1 hour / 24 hours]) and the behavior when the requested position is beyond the replay window (full state resync via REST endpoint). Implement connection quality monitoring on the client: track ping/pong latency, detect degraded connections, and switch to a fallback transport (e.g., fall back from WebSocket to SSE to long polling) if the primary transport fails. Implement graceful degradation: define the application behavior when real-time is unavailable (show a "live updates paused" indicator and fall back to periodic polling at [POLL INTERVAL: 10-30]s). Provide the complete client reconnection implementation with all resilience features.