The Event Stream Protocol

A response that never finishes

Server-Sent Events is a response that never finishes.

Your client opens an ordinary request and your server answers with a success and a content type saying this is an event stream. Then it keeps the body open indefinitely, writing events down it as they happen.

Read the wire format and you will find nothing to it. Lines beginning with data carry the payload. An optional line names the event type, another tags it so a client can resume, and a blank line ends each event.

Write three lines in the browser and you are done: construct an EventSource, handle the messages, finish. No library at all. It also handles reconnecting for you, which the next lesson covers, and that is why these clients end up dramatically shorter than a hand-rolled polling loop.

Buffering, the classic saboteur

Watch out for buffering, the classic saboteur here, even though most infrastructure passes a plain HTTP response straight through.

Nginx buffers proxied responses by default, which turns your real-time stream into bursts arriving whenever a buffer happens to fill. Turn buffering off, or send the header that asks it not to. Some older corporate proxies and a few CDN setups do the same, so test through your real production path.

Know three limits before you commit. The stream runs one way, server to client, and your client talks back over ordinary separate requests. The payloads are text, so binary data needs encoding or a different transport.

And on HTTP/1.1 browsers allow only six connections per domain, so a user with seven tabs open starves. HTTP/2 carries many streams over one connection and removes that entirely, so serve these endpoints over it.

Add one housekeeping habit. Send a comment line every 15 to 30 seconds so anything along the path that kills idle connections keeps seeing traffic.

// Server: a response that never finishes.
res.setHeader("Content-Type", "text/event-stream");
res.setHeader("Cache-Control", "no-cache");
res.setHeader("X-Accel-Buffering", "no");   // or a proxy buffers your stream

for (Event e : stream) {
  res.write("id: " + e.id() + "\n");        // lets the client resume
  res.write("event: " + e.type() + "\n");
  res.write("data: " + e.json() + "\n\n");  // blank line ends the event
  res.flush();
}

// Client: three lines, and reconnection is already handled.
const es = new EventSource("/stream");
es.onmessage = (e) => render(JSON.parse(e.data));
// On a drop the browser reconnects and sends Last-Event-ID by itself.

Worked example

Dev replaces a 10 second poll on a sports score widget with SSE. Locally it is perfect; in staging, scores arrive in clumps of five with 20 second silences. Nothing is wrong with his Go code, which writes and flushes each event immediately. The culprit is the Nginx layer in front, buffering the proxied response 4 KB at a time, so events queue until the buffer fills. One header from the app, X-Accel-Buffering: no, and events flow the instant they are written. He then finds mobile users on one carrier disconnecting every 60 seconds and adds a ': ping' comment every 20 seconds to look alive to the carrier's idle timeout. Total client code in the browser: four lines, versus the 40-line polling loop with backoff that it replaced.