System Design Cases
Server-Sent Events (SSE)
Server-Sent Events (SSE) — concept page. One-way server -> client streaming over plain HTTP using text/event-stream format. EventSource browser API with built-in auto-reconnect and Last-Event-ID resume. Three scenarios: (1) basic SSE setup and steady event delivery from a Redis Stream, (2) connection drop with auto-reconnect and Last-Event-ID replay of missed events, (3) LLM token streaming OpenAI/Anthropic-style with data: [DONE] terminator. Three ADRs covering SSE vs WebSocket vs long-poll choice, Redis Stream resume buffer strategy, and disabling proxy buffering plus compression on SSE endpoints.
Server-Sent Events: one-way HTTP stream with resumable application state
Server-Sent Events is a browser API and UTF-8 event-stream format over HTTP. It is server-to-client only. The user agent handles reconnection and Last-Event-ID, while authentication, authorization, durable replay, deduplication, backpressure, and retention remain application responsibilities.
Mental model
- An EventSource request expects status 200 with text/event-stream and parses fields line by line; a blank line dispatches a complete event.
- data lines are joined, event chooses the event type, id updates the last event ID buffer, and a numeric retry field changes reconnection time.
- After reconnect, Last-Event-ID reports client protocol state. It is a cursor hint, not a guarantee that the server retained the corresponding event.
- HTTP 204 stops automatic reconnect. Other errors can fail or reestablish according to the processing model.
Гарантии и границы
- The wire format is UTF-8 and one-way from server to browser over the open response.
- EventSource automatic reconnect does not make delivery exactly once.
- The browser does not acknowledge business processing; application state needs its own cursor or idempotency rule.
- Proxy buffering and idle timeouts can change latency or terminate an otherwise correct stream.
Сценарии диаграммы
Open and dispatch an event stream. EventSource fetches a 200 text/event-stream response and dispatches complete UTF-8 events separated by blank lines.
Reconnect with Last-Event-ID. The browser reconnects after a broken stream and reports its last event ID; the server chooses replay semantics.
Producer commit and subscriber delivery. Publishing and browser delivery are separate phases; an append can succeed while a subscriber is disconnected.
Slow clients, heartbeat comments, and deliberate stop. Streaming services need bounded buffers; HTTP 204 tells EventSource not to reconnect.
Архитектурные решения
- Choose SSE for browser-facing server push when client-to-server messages can use ordinary HTTP requests.
- Use durable event identity and bounded retention only when replay is a product requirement.
- Define slow-consumer and reconnect-storm policies before setting connection targets.
Сбои и неоднозначные исходы
- An incomplete final event is not dispatched when the stream ends before its blank-line terminator.
- A retention gap requires snapshot or reset semantics; silently resuming from current head loses state.
- Auth expiry, tenant changes, and revocation require reconnect or server-side termination policy.
Операционный checklist
- Set content type, no-transform/buffering behavior as needed, cancellation propagation, and keepalive policy.
- Authorize filters and reauthorize reconnects.
- Bound connections, per-client buffers, event size, write time, retry rate, and log lag.
- Test 204 stop, proxy timeout, partial event, duplicate replay, retention gap, and rolling deploy.