Server-Sent Events skill for Codex

Done well means: the first event reaches the browser within milliseconds of being written, nothing between server and client buffers the stream, the server notices a closed client and frees its resources, and a reconnecting client resumes from Last-Event-ID without gaps or duplicates.

When SSE fits

Situation	Choice
Server-to-client updates, client actions go over normal HTTP	SSE
Need custom headers or a POST body to start the stream (auth tokens, LLM prompts)	SSE format consumed with fetch + a stream parser, not EventSource
Frequent client-to-server messages, binary frames	WebSocket: use $websockets-realtime
Updates every few minutes, mobile battery matters	Polling with ETag / If-None-Match

Inspect first

• Read AGENTS.md, then find the existing stream code: rg -n "text/event-stream|EventSource|StreamingResponse|streamSSE|Flusher" .
• List every hop: app server, compression middleware, reverse proxy (nginx, Caddy, Traefik), CDN (Cloudflare, CloudFront), platform (Vercel, Cloud Run, Heroku router). Each one can buffer or time out the stream.
• Check the HTTP version clients use. On HTTP/1.1 browsers allow only ~6 connections per origin, so a few open tabs with SSE exhaust it; HTTP/2 multiplexes streams.

Wire format

retry: 5000
id: 4182
event: order.updated
data: {"orderId":"o_19","status":"shipped"}

: heartbeat

• Each event ends with a blank line (\n\n). Without it, nothing dispatches.
• Multi-line payloads use one data: line per line; the client joins them with \n. Simplest rule: send single-line JSON.
• event: sets the type; clients listen with addEventListener("order.updated", ...). Events without it fire onmessage.
• id: becomes lastEventId; the browser sends it back as the Last-Event-ID header on reconnect. Use a monotonic sequence or a stream offset, not a random UUID.
• retry: sets the reconnect delay in milliseconds.
• Lines starting with : are comments. Send one every 15-30 s as a heartbeat to keep proxies and load balancers from closing an idle stream.

Required response headers

HTTP/1.1 200 OK
Content-Type: text/event-stream; charset=utf-8
Cache-Control: no-cache, no-transform
X-Accel-Buffering: no

Do not send Connection: keep-alive on HTTP/2 (it is a forbidden connection-specific header there). X-Accel-Buffering: no disables nginx buffering for this response only.

Server workflow

1. Authenticate before writing headers; return 401/403 as a normal response.
2. Write headers and flush immediately, plus an initial comment or retry: line so proxies see bytes at once.
3. If Last-Event-ID is present, replay events after that id from a bounded history (Redis Stream, DB table). If it is too old, send an event telling the client to refetch full state.
4. Subscribe to the source (pub/sub, queue, generator) and write each event, flushing after each one.
5. Send a heartbeat comment on a timer.
6. On client disconnect, unsubscribe, clear timers, cancel upstream work (DB cursors, LLM calls). Leaks here are the main SSE production incident.
7. To end the stream for good, have the client close it; a server-side close just triggers a reconnect. Responding with 204 tells EventSource to stop reconnecting.

Node / Express

app.get("/events", requireUser, async (req, res) => {
  res.writeHead(200, {
    "Content-Type": "text/event-stream; charset=utf-8",
    "Cache-Control": "no-cache, no-transform",
    "X-Accel-Buffering": "no",
  });
  res.write("retry: 5000\n\n");

  const send = (e: { id: number; type: string; data: unknown }) =>
    res.write(`id: ${e.id}\nevent: ${e.type}\ndata: ${JSON.stringify(e.data)}\n\n`);

  const lastId = Number(req.get("Last-Event-ID") ?? 0);
  for (const e of await history.after(req.user.id, lastId)) send(e);

  const unsubscribe = bus.subscribe(req.user.id, send);
  const hb = setInterval(() => res.write(": hb\n\n"), 20_000);
  req.on("close", () => { clearInterval(hb); unsubscribe(); });
});

If the compression middleware runs on this route, either exclude text/event-stream from it or call res.flush() after each write; otherwise gzip holds events in its buffer.

FastAPI

from fastapi import Request
from fastapi.responses import StreamingResponse

@app.get("/events")
async def events(request: Request, user: CurrentUser):
    async def gen():
        yield "retry: 5000\n\n"
        async for e in bus.subscribe(user.id):
            if await request.is_disconnected():
                break
            yield f"id: {e.id}\nevent: {e.type}\ndata: {e.json}\n\n"
    return StreamingResponse(gen(), media_type="text/event-stream",
                             headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"})

The sse-starlette package adds heartbeats (ping=) and disconnect handling if the project already uses it. Never call blocking I/O inside the generator.

Other servers

• Go: set headers, then rc := http.NewResponseController(w) and rc.Flush() after each write; watch r.Context().Done() for disconnects. Clear the server WriteTimeout for this route with rc.SetWriteDeadline(time.Time{}).
• Hono: streamSSE(c, async (stream) => { await stream.writeSSE({ id, event, data }) }) from hono/streaming; use stream.onAbort for cleanup.
• Django: StreamingHttpResponse with an async generator under ASGI. Under WSGI each stream pins a worker thread for its whole lifetime; do not ship that at scale.

Client

const es = new EventSource("/events", { withCredentials: true });
es.addEventListener("order.updated", (e) => apply(JSON.parse(e.data)));
es.onerror = () => { if (es.readyState === EventSource.CLOSED) showOffline(); };

• EventSource reconnects automatically and sends Last-Event-ID; do not add your own reconnect loop on top.
• It only does GET and cannot set headers, so auth is cookie-based. For bearer tokens or POST bodies, read fetch(...).body with a parser (for example eventsource-parser) and implement reconnect with backoff and Last-Event-ID yourself.
• A non-200 status or wrong Content-Type fails the connection permanently; the browser does not retry. Check readyState in onerror.
• Close the stream when the view unmounts (es.close()), or tabs keep connections open.

Proxies and platforms

location /events {
  proxy_pass http://app;
  proxy_http_version 1.1;
  proxy_set_header Connection "";
  proxy_buffering off;
  proxy_cache off;
  gzip off;
  proxy_read_timeout 1h;
}

• Cloudflare closes responses that send no bytes for about 100 s: heartbeats fix it.
• Serverless functions end the stream at their max duration; design clients to resume.
• Kubernetes ingress-nginx: set nginx.ingress.kubernetes.io/proxy-buffering: "off" and a longer proxy-read-timeout on the ingress.

Verification

Run the bundled probe against a local or staging endpoint (staging needs network access from the sandbox):

python3 scripts/sse_probe.py http://localhost:3000/events --events 5 --timeout 30
python3 scripts/sse_probe.py https://staging.example.com/events \
  --header "Cookie: session=..." --last-event-id 4180

It checks status and headers, parses events exactly as a browser would, prints the delay before each event, and flags bursts after a long wait (buffering), compression, missing heartbeats and wrong content types. Exit 0 means healthy, 1 a protocol or header problem, 2 a connection failure or silence until timeout.

Compare a probe straight to the app port against one through the proxy: if only the proxied run bursts, the proxy is buffering. Also test: kill the client and confirm the server’s subscriber count drops; reconnect with --last-event-id and confirm replay starts at the next id.

Gotchas

• \n inside a data: value breaks framing; JSON-encode or split into multiple data: lines.
• Express res.write returns false under backpressure. For high-volume streams wait for drain or drop/coalesce events for slow clients.
• Each open stream holds a socket and a subscription. Count them in metrics and cap them per user.
• Response timeouts on the app server (Node server.requestTimeout, gunicorn --timeout for sync workers) kill long streams; exempt or raise them for SSE routes.
• Corporate antivirus proxies sometimes buffer whole responses; heartbeats every 15 s and HTTPS make this rarer but not impossible. Polling fallback is the escape hatch.

Output template

## SSE endpoint: <path>
- Auth: <cookie | fetch + bearer>
- Event types: <list with payload shape>
- Ids and resume: <sequence source, history retention>
- Heartbeat: every <N> s
- Disconnect cleanup: <what is released>
- Proxy/CDN changes: <nginx/ingress/CDN settings>
- Probe result: direct <ok>, via proxy <ok>