Server-Sent Events

The Problem

Many applications need to push updates from the server to the client in real time — live dashboards, notification feeds, stock tickers, build logs, and progress indicators. Traditional HTTP request-response requires the client to poll repeatedly, wasting bandwidth and adding latency. Server-Sent Events (SSE) provides a standardized, lightweight mechanism for the server to push a continuous stream of events to the client over a single long-lived HTTP connection.

Architectural Approaches

Architecture

Loading diagram...

Key Components

Data Model

Loading diagram...

SSE Wire Protocol

The SSE protocol is remarkably simple — it’s just a UTF-8 text stream over HTTP with a specific format:

Event format:

• data: <payload>\n\n — the event data (can span multiple lines)
• event: <type>\n — optional named event type (defaults to “message”)
• id: <id>\n — optional event ID for resume
• retry: <ms>\n — optional reconnection interval in milliseconds
• : comment\n — comment line, useful for keep-alive heartbeats

Reconnection: When the connection drops, the browser automatically reconnects and sends Last-Event-ID header. The server can use this to replay missed events — critical for reliability. Store events with sequential IDs and replay from the requested ID on reconnect.

Keep-alive: Send a comment line (: heartbeat\n\n) every 15–30 seconds to prevent proxies and load balancers from closing idle connections.

Scaling SSE Horizontally

A single SSE gateway can hold tens of thousands of connections, but at scale you need multiple instances.

The fan-out problem: When an event occurs, it must reach the correct gateway holding the target user’s connection. Solutions:

1. Pub/Sub fan-out — Every gateway subscribes to a Redis Pub/Sub channel or Kafka topic. Events are broadcast to all gateways, and each gateway filters locally. Simple but wasteful at large scale.
2. Targeted routing — Maintain a connection registry mapping user→gateway. Publish events only to the specific gateway. More efficient but requires registry consistency.
3. Consistent hashing — Route users to gateways deterministically. No registry needed, but rebalancing on scale events causes reconnections.

Memory management: Each SSE connection consumes a file descriptor and a small memory buffer. Monitor open FD counts and set appropriate ulimit values. Use connection pooling for the pub/sub subscriber.

Loading diagram...

Event Ordering and Delivery Guarantees

SSE provides at-most-once delivery by default — if the client misses events during a disconnect, they’re gone unless you implement replay.

At-least-once delivery: Assign monotonically increasing IDs to events. Store recent events in a bounded buffer (e.g., Redis sorted set with TTL). On reconnect, replay from the client’s Last-Event-ID. Accept that clients may receive duplicates and handle idempotently.

Ordering: Events within a single SSE connection are ordered (TCP guarantees this). Across multiple channels or after reconnection, ordering depends on your event store. Use timestamps or sequence numbers for cross-channel ordering.

Backpressure: If events produce faster than the client can consume, the TCP send buffer fills up. Monitor write buffer sizes and drop/batch events for slow clients rather than blocking the event loop.

Real-World Examples

Architectural Tradeoffs

# Learn the System Design of: Server-Sent Events

You are an expert software architect and teacher. I want to understand server-sent events as a practical system design capability. (One-way real-time streaming from server to client over HTTP).

Use the following architectural guide as a learning reference. Avoid one-size-fits-all recommendations. Keep assumptions, costs, and tradeoffs explicit.

---

import { Mermaid, ComponentList, ComponentCard, ApproachList, Approach, Example, Tradeoff } from '@/components/mdx';

## The Problem

Many applications need to push updates from the server to the client in real time — live dashboards, notification feeds, stock tickers, build logs, and progress indicators. Traditional HTTP request-response requires the client to poll repeatedly, wasting bandwidth and adding latency. Server-Sent Events (SSE) provides a standardized, lightweight mechanism for the server to push a continuous stream of events to the client over a single long-lived HTTP connection.

## Architectural Approaches

<ApproachList>
<Approach
  name="Native SSE with EventSource API"
  pros={[
    'Zero client-side dependencies — built into every modern browser',
    'Automatic reconnection with last-event-id resume',
    'Works through HTTP/2 multiplexing without extra connections',
    'Simple text-based protocol easy to debug with curl',
  ]}
  cons={[
    'Unidirectional — server to client only',
    'Limited to ~6 concurrent connections per domain in HTTP/1.1',
    'No binary data support (text only)',
    'Some older proxies/load balancers may buffer or drop the connection',
  ]}
>
Use the browser's built-in **EventSource** API to establish a persistent HTTP connection. The server responds with `Content-Type: text/event-stream` and writes events in the SSE wire format (`data:`, `event:`, `id:`, `retry:` fields). The browser automatically handles reconnection with the `Last-Event-ID` header.
</Approach>
<Approach
  name="Long Polling Fallback"
  pros={[
    'Wor...

[Full prompt copied to clipboard]