Event ID & Retry Mechanism Design #Permalink to this section

Part of SSE Protocol Fundamentals & Architecture.

Without explicit event IDs and a deliberate retry policy, a dropped TCP connection silently discards every event transmitted since the last full page load. The browser reconnects, the server starts a fresh stream, and the client has no idea what it missed. This guide covers the two SSE primitives that fix that: the id field, which gives every event a cursor the browser remembers and replays on reconnect, and the retry directive, which controls how long the browser waits before attempting that reconnect. Together they form a resumption contract — the backbone of at-least-once delivery over a fundamentally unreliable transport.

How the Mechanism Works #Permalink to this section

The WHATWG HTML specification defines id and retry as optional event-stream fields alongside data and event. Their interaction is precise and worth reading at the wire level.

The id field #Permalink to this section

When a client’s EventSource parser encounters an id: line, it stores the value in its last event ID buffer. That buffer persists across reconnections for the lifetime of the EventSource object. On every reconnect, the browser sends the buffer’s contents as the Last-Event-ID HTTP request header.

One special case: an id: line with an empty value (id: followed immediately by a newline) clears the buffer. The next reconnect will not send the header at all. Use this deliberately when you want to signal “start fresh” — for example, after a client-initiated full resync.

The retry field #Permalink to this section

retry: takes a decimal integer in milliseconds. The spec requires the value consist only of ASCII digits; any non-digit character causes the directive to be ignored. The browser replaces its internal reconnect timer on the first retry: it sees and keeps the new value for all subsequent reconnects unless overwritten.

Key behaviors to internalize:

• retry: updates the timer globally for the connection, not per-event. Send it once at stream open, then only when you want to change it.
• The browser does not apply exponential backoff automatically. Whatever you send is what it uses. Implement progressive backoff server-side by updating the retry value over time, or use a fetch-based polyfill for full backoff control.
• If retry: is never sent, browsers default to approximately 3000 ms (Chrome, Firefox) — but this is implementation-defined, not specified.

Wire-level annotated example #Permalink to this section

HTTP/1.1 200 OK
Content-Type: text/event-stream
Cache-Control: no-cache
X-Accel-Buffering: no

retry: 2000
id: evt-001
event: order_update
data: {"orderId":"ORD-9182","status":"confirmed","ts":1748736000}

id: evt-002
event: order_update
data: {"orderId":"ORD-9183","status":"shipped","ts":1748736005}

: heartbeat

id: evt-003
event: order_update
data: {"orderId":"ORD-9182","status":"delivered","ts":1748736060}

Notes on the above:

• retry: is sent once, before the first id:. The browser stores 2000 ms.
• Each event has its own id:. The browser’s last-event-ID buffer is updated to evt-003 after the third event.
• The comment line (: heartbeat) is a keepalive. It has no id: and does not affect the buffer.
• The blank line after each event block is mandatory — it dispatches the event.

The Last-Event-ID header sent on reconnect looks like:

GET /stream HTTP/1.1
Accept: text/event-stream
Last-Event-ID: evt-003
Cache-Control: no-cache

Server-Side Implementation: Cursor-Based Resumption #Permalink to this section

The server’s job on reconnect is to read Last-Event-ID, look up what events the client missed, and replay them in order before resuming the live stream. The cursor store must support range queries by event ID.

Node.js with Redis sorted set #Permalink to this section

import { createClient } from 'redis';
import http from 'http';

const redis = createClient({ url: process.env.REDIS_URL });
await redis.connect();

const STREAM_KEY = 'sse:events';
const RETENTION_MS = 24 * 60 * 60 * 1000; // 24 hours

http.createServer(async (req, res) => {
  if (req.url !== '/stream') { res.end(); return; }

  res.writeHead(200, {
    'Content-Type': 'text/event-stream',
    'Cache-Control': 'no-cache',
    'X-Accel-Buffering': 'no',   // disable nginx buffering
    'Connection': 'keep-alive',
  });

  // Send initial retry directive — clients will wait 3 s before reconnecting
  res.write('retry: 3000\n\n');

  const lastId = req.headers['last-event-id'];

  // Replay missed events if client provides a cursor
  if (lastId) {
    // Events stored as JSON strings in a sorted set, score = numeric sequence
    const cursor = parseInt(lastId.split('-')[1], 10); // extract sequence from "evt-NNN"
    const missed = await redis.zRangeByScore(
      STREAM_KEY,
      cursor + 1,           // exclusive: everything after the last seen ID
      '+inf',
      { LIMIT: { offset: 0, count: 200 } }  // cap replay to 200 events
    );

    for (const raw of missed) {
      const evt = JSON.parse(raw);
      // Re-emit with original id so the client's buffer stays accurate
      res.write(`id: ${evt.id}\ndata: ${JSON.stringify(evt.payload)}\n\n`);
    }
  }

  // Subscribe to new events via Redis pub/sub
  const sub = redis.duplicate();
  await sub.connect();

  sub.subscribe('sse:live', (message) => {
    const evt = JSON.parse(message);
    res.write(`id: ${evt.id}\ndata: ${JSON.stringify(evt.payload)}\n\n`);
  });

  // Clean up on client disconnect
  req.on('close', async () => {
    await sub.unsubscribe('sse:live');
    await sub.quit();
  });
}).listen(3000);

Publishing events (in another service or route):

async function publishEvent(payload) {
  const seq = await redis.incr('sse:seq');  // atomic monotonic counter
  const id = `evt-${seq}`;
  const evt = { id, payload, ts: Date.now() };

  // Store in sorted set with score = sequence number for range queries
  await redis.zAdd(STREAM_KEY, { score: seq, value: JSON.stringify(evt) });

  // Expire old events — keep only last 24 h worth
  const cutoff = Date.now() - RETENTION_MS;
  await redis.zRemRangeByScore(STREAM_KEY, '-inf', cutoff);  // trim by time if score = ts

  // Fan out to all connected stream nodes
  await redis.publish('sse:live', JSON.stringify(evt));
}

For a deeper treatment of distributed fan-out across multiple stream nodes, see Redis Pub/Sub Fan-Out for SSE.

Python / FastAPI with sse-starlette #Permalink to this section

from fastapi import FastAPI, Request
from sse_starlette.sse import EventSourceResponse
import asyncio, redis.asyncio as aioredis

app = FastAPI()
pool = aioredis.ConnectionPool.from_url("redis://localhost")

STREAM_KEY = "sse:events"
RETRY_MS = 3000

async def event_generator(request: Request, last_id: str | None):
    r = aioredis.Redis(connection_pool=pool)

    # Send initial retry directive once
    yield {"retry": RETRY_MS}

    if last_id:
        cursor = int(last_id.split("-")[1])
        missed = await r.zrangebyscore(STREAM_KEY, cursor + 1, "+inf", start=0, num=200)
        for raw in missed:
            evt = json.loads(raw)
            yield {"id": evt["id"], "data": json.dumps(evt["payload"])}

    pubsub = r.pubsub()
    await pubsub.subscribe("sse:live")

    async for msg in pubsub.listen():
        if await request.is_disconnected():
            await pubsub.unsubscribe("sse:live")
            break
        if msg["type"] == "message":
            evt = json.loads(msg["data"])
            yield {"id": evt["id"], "data": json.dumps(evt["payload"])}

@app.get("/stream")
async def stream(request: Request):
    last_id = request.headers.get("last-event-id")
    return EventSourceResponse(event_generator(request, last_id))

See the Python FastAPI SSE Implementation Guide for full middleware and deployment configuration.

Client-Side Consumption with EventSource #Permalink to this section

The native EventSource API handles id and retry automatically, but you need to understand what it actually does — and what it does not do.

const es = new EventSource('/stream', { withCredentials: true });

es.addEventListener('order_update', (e) => {
  // e.lastEventId is the most recently seen id: value
  // The browser will send this as Last-Event-ID on reconnect automatically
  console.log('last cursor:', e.lastEventId);
  processOrder(JSON.parse(e.data));
});

es.addEventListener('error', (e) => {
  // readyState 0 = CONNECTING (auto-reconnecting), 2 = CLOSED (permanent failure)
  if (es.readyState === EventSource.CLOSED) {
    // Server sent HTTP error or called es.close() — will NOT auto-reconnect
    scheduleManualReconnect();
  }
  // readyState === CONNECTING: browser is already waiting the retry interval
});

What the browser does automatically:

1. Receives retry: 3000 → stores 3000 ms as the reconnect delay.
2. Receives id: evt-042 → stores "evt-042" in the last-event-ID buffer.
3. On TCP drop → waits 3000 ms → sends GET /stream with Last-Event-ID: evt-042.
4. On id: (empty) → clears buffer → next reconnect sends no Last-Event-ID.

What the browser does not do: exponential backoff, jitter, max retry attempts, or custom headers beyond Last-Event-ID. For those capabilities, use a fetch-based implementation instead — covered in Browser Support & Polyfill Strategies.

Fetch-based client with exponential backoff #Permalink to this section

async function* streamEvents(url, options = {}) {
  let lastId = null;
  let delay = options.initialDelay ?? 1000;
  const maxDelay = options.maxDelay ?? 30000;
  const factor = options.factor ?? 2;

  while (true) {
    const headers = { Accept: 'text/event-stream' };
    if (lastId) headers['Last-Event-ID'] = lastId;
    if (options.token) headers['Authorization'] = `Bearer ${options.token}`;

    try {
      const res = await fetch(url, { headers, signal: options.signal });
      if (!res.ok) throw new Error(`HTTP ${res.status}`);

      delay = options.initialDelay ?? 1000; // reset on successful connect

      const reader = res.body.getReader();
      const decoder = new TextDecoder();
      let buf = '';

      while (true) {
        const { done, value } = await reader.read();
        if (done) break;
        buf += decoder.decode(value, { stream: true });

        const blocks = buf.split('\n\n');
        buf = blocks.pop(); // incomplete trailing block

        for (const block of blocks) {
          const lines = block.split('\n');
          let id = null, data = null, event = 'message';
          for (const line of lines) {
            if (line.startsWith('id:')) id = line.slice(3).trim();
            else if (line.startsWith('data:')) data = line.slice(5).trim();
            else if (line.startsWith('event:')) event = line.slice(6).trim();
          }
          if (id) lastId = id;           // keep cursor updated
          if (data !== null) yield { id: lastId, event, data };
        }
      }
    } catch (err) {
      if (options.signal?.aborted) return;
      // Exponential backoff with full jitter
      const jitter = Math.random() * delay * 0.2;
      await new Promise(r => setTimeout(r, delay + jitter));
      delay = Math.min(delay * factor, maxDelay);
    }
  }
}

// Usage
const ctrl = new AbortController();
for await (const evt of streamEvents('/stream', { token: getToken(), signal: ctrl.signal })) {
  dispatch({ type: evt.event, payload: JSON.parse(evt.data) });
}

This pattern is also useful for authenticated streams — see Authenticating SSE Streams with Tokens & Cookies.

Designing the retry Value #Permalink to this section

The retry value is a lever with real production consequences. Set it by profiling your failure modes:

Update the retry directive dynamically as conditions change. A server under memory pressure should lengthen retry before it starts dropping connections:

// Increase retry interval as connection count climbs
function adaptiveRetry(connectionCount) {
  if (connectionCount < 10_000) return 2000;
  if (connectionCount < 50_000) return 5000;
  return 10000; // slow reconnects under pressure
}

// Re-emit retry directive every 60 s so reconnecting clients pick it up
setInterval(() => {
  const ms = adaptiveRetry(getConnectionCount());
  broadcastToAll(`retry: ${ms}\n\n`);
}, 60_000);

For the full specification of retry semantics and advanced interval tuning, see Setting the retry Interval in SSE Streams.

Edge Cases and Network Interference #Permalink to this section

SSE streams traverse HTTP infrastructure that was not designed for long-lived responses. Each hop can corrupt or destroy the id/retry mechanism.

Proxy and CDN buffering #Permalink to this section

The most common failure: an intermediate proxy accumulates your events before forwarding them. The client sees no data for seconds, then a burst, then a disconnect — and its Last-Event-ID may be several events behind the actual last delivered event.

The X-Accel-Buffering: no header is the single most important header to set on SSE responses. Without it, nginx silently defeats the entire streaming mechanism.

ID field stripping #Permalink to this section

Some reverse proxies and WAFs normalize or strip unrecognized HTTP headers on the request path. If Last-Event-ID is stripped from the reconnect request, the server has no cursor and replays from the beginning (or not at all). Test this explicitly:

curl -v -N \
  -H "Last-Event-ID: evt-042" \
  -H "Accept: text/event-stream" \
  https://api.example.com/stream 2>&1 | head -40

Check the > Last-Event-ID: line in curl’s verbose output. If it disappears from the server-side access log, a proxy is stripping it. Allowlist the header in your WAF or proxy config.

Firewall idle-connection resets #Permalink to this section

Many corporate firewalls and NAT devices reset TCP connections idle for 60–90 seconds. Your keepalive comment must arrive before that threshold:

// Send a keepalive comment every 25 seconds
const keepalive = setInterval(() => {
  if (!res.writableEnded) res.write(': keepalive\n\n');
}, 25_000);
req.on('close', () => clearInterval(keepalive));

The comment line (: keepalive\n\n) does not update the id buffer and does not trigger a message event on the client.

Stale cursor / cursor expiry #Permalink to this section

If a client reconnects with a cursor that has been evicted from your store (e.g., after a 24-hour TTL), replaying from that cursor is impossible. Options:

1. Return a sync-required event with a full state snapshot and a fresh id.
2. Respond with HTTP 204 No Content to signal “no events since cursor” (browser does not reconnect on 204).
3. Use HTTP 410 Gone to permanently close the stream — but note the browser will stop auto-reconnecting.

Do not silently drop the cursor and start from the head of the stream. That causes silent duplication for the client.

Distributed ID collisions #Permalink to this section

Auto-increment counters are safe on a single node. Across multiple stream nodes they produce collisions. Use one of:

For production systems, Redis INCR on a single Redis instance (or cluster with slot affinity) gives strict monotonicity with no collision risk. See Idempotent Event ID Generation for implementation details and Generating Monotonic Event IDs for SSE for code examples.

Performance and Scale Considerations #Permalink to this section

Memory: the cursor store cost #Permalink to this section

At 1000 events/second with a 24-hour retention window, your sorted set holds up to 86.4 million entries. At ~200 bytes per entry (ID + JSON payload), that is roughly 17 GB — likely too large for RAM.

Mitigation strategies:

• Store only event IDs in the sorted set; keep payloads in a separate key-value store with per-key TTL.
• Use a stream-native data structure: Redis Streams (XADD / XRANGE) are purpose-built for this and are more memory-efficient than sorted sets.
• Tier cold events to disk or an object store; serve hot events (last N minutes) from memory.

CPU: replay fan-out cost #Permalink to this section

A mass reconnect event (deploy, network partition recovery) can trigger thousands of concurrent cursor lookups. Each lookup is a ZRANGEBYSCORE or XRANGE call. Protect Redis with:

• A per-client replay cap (e.g., 200 events maximum).
• A reconnect queue or token bucket to stagger replay requests. See Rate Limiting & Backpressure Handling for token-bucket patterns.
• Redis cluster read replicas for replay queries (replicas handle reads; primary handles writes).

Connection overhead #Permalink to this section

Each SSE connection holds an open TCP socket and a server-side goroutine/thread/async task. At 50k connections:

• File descriptors: set ulimit -n 100000 and configure OS-level net.core.somaxconn.
• Memory per connection: ~10–20 KB goroutine stack (Go), ~100 KB V8 async context (Node.js default).
• Heartbeat timer: one setInterval per connection; consolidate into a single broadcast interval.

Validation and Debugging #Permalink to this section

Verify Last-Event-ID survives your proxy chain #Permalink to this section

# 1. Connect to the raw origin (bypass CDN)
curl -N -H "Last-Event-ID: test-42" -H "Accept: text/event-stream" \
  http://origin-host:3000/stream

# 2. Connect through the full proxy chain
curl -N -H "Last-Event-ID: test-42" -H "Accept: text/event-stream" \
  https://api.example.com/stream

# Compare: does the server log show the header in both cases?
# In Node.js: console.log(req.headers['last-event-id'])

Chrome DevTools inspection #Permalink to this section

1. Open Network tab → filter by EventStream (or text/event-stream).
2. Click the /stream request → EventStream sub-tab: shows each dispatched event with its id.
3. Headers tab of the reconnect request: verify Last-Event-ID is present.
4. Simulate disconnect: kill the server process; watch the browser reconnect and the new request’s headers.

Structured logging #Permalink to this section

// Log every reconnect attempt server-side
const lastId = req.headers['last-event-id'];
logger.info({
  event: 'sse_connect',
  clientIp: req.socket.remoteAddress,
  lastEventId: lastId ?? null,
  resuming: !!lastId,
  userAgent: req.headers['user-agent'],
});

Alert on: resuming: true with lastEventId absent from your cursor store (stale cursor); high reconnect rate per IP (client-side loop bug or very short retry); resuming: false rate spike (mass disconnect without prior id delivery — possible proxy stripping).

Replay correctness test #Permalink to this section

# Publish 10 events via your normal publish path, then kill the stream.
# Reconnect with the id of event 5 and assert events 6-10 are replayed.
# Verify no event is duplicated and sequence is intact.
for i in $(seq 1 10); do
  curl -s -X POST http://localhost:3000/publish \
    -H "Content-Type: application/json" \
    -d "{\"msg\": \"event-$i\"}"
done

Production Checklist #Permalink to this section

• Content-Type: text/event-stream set on all SSE responses
• X-Accel-Buffering: no set (nginx / proxy environments)
• Cache-Control: no-cache set to prevent intermediary caching
• retry: directive emitted within the first event block at stream open
• Event IDs generated by an atomic, globally unique strategy (Redis INCR / ULID / Snowflake)
• Server reads Last-Event-ID header and resumes from cursor on reconnect
• Replay is capped (event count and/or time window)
• Stale cursor case handled: returns sync snapshot + fresh ID rather than silent skip
• Keepalive comment sent every ≤25 s to prevent firewall idle-resets
• proxy_read_timeout (nginx) or equivalent exceeds retry interval by at least 2x
• Last-Event-ID header verified to survive the full proxy/CDN chain
• File-descriptor limit set to ≥2× expected peak connection count

Frequently Asked Questions #Permalink to this section

Related #Permalink to this section

• SSE Protocol Fundamentals & Architecture
• Setting the retry Interval in SSE Streams
• Understanding the Event Stream Format
• Idempotent Event ID Generation
• Browser Support & Polyfill Strategies