The Wire Protocol¶
SSE's beauty is that the entire spec fits in your head. A stream is a
text/event-stream response body made of events, and an event is a block
of field: value lines ended by a blank line.
┌─ an event ─────────────────┐
id: 42 │ ← optional fields, any order
event: stock │
data: {"symbol":"ACME", │
data: "price":142.50} │
│ ← blank line = "dispatch now"
└─────────────────────────────┘
The four fields¶
| Field | Purpose | Repeatable? |
|---|---|---|
data: |
The payload. Concatenated with \n if repeated. |
✅ yes — that's how multi-line data works |
event: |
Names the event type. Client listens via addEventListener(name). |
no |
id: |
Sets lastEventId. Sent back as Last-Event-ID on reconnect. |
no |
retry: |
Milliseconds the client should wait before reconnecting. | no |
Any other field name is ignored — so you can send comments for debugging or heartbeats.
Field-by-field¶
data: — the payload (required)¶
The second example delivers "line one\nline two" — one event whose data
contains a newline. JSON is the convention for structured data
(data: {"price": 142.5}), but the protocol doesn't care; it's all strings.
No leading/trailing whitespace games
Everything after data: up to the newline is data — a single leading
space after the colon is stripped, but the rest is literal. Just json.dumps
your payload and move on.
event: — naming events¶
On the client:
es.addEventListener("tick", handler); // gets the tick event
es.addEventListener("chat", handler); // gets the chat event
es.onmessage = handler; // only events WITHOUT an event: field
The default type is message. If you never send event:, everything lands
on onmessage.
id: — resumability¶
The browser remembers the last id it saw. On reconnect it sends:
Your server can then replay missed events or resume a cursor. Set ids on every event — it costs nothing and buys exactly-once-ish semantics. (See reliability.)
retry: — reconnect backoff¶
Tells the browser "if we get disconnected, wait 2000ms before retrying." Applies to the whole connection from then on; you can send it once at the top of the stream. Without it, browsers pick their own (usually ~3s).
Comments — lines starting with :¶
Two uses:
- Heartbeat: send
: hbevery N seconds so proxies, load balancers, and NATs don't drop your "idle" connection. Our demo uses 15s. - Human debugging: first line of our stream is a comment describing the
connection — you see it in
curlbut never in JS.
Putting it together — a real stream¶
: new connection | channels=chat,clock,stocks ← comment (JS never sees this)
retry: 2000 ← set reconnect delay
event: welcome ← named event, no id
data: {"msg": "new connection", "channels": ["chat","clock","stocks"]}
id: 1 ← tick event
event: tick
data: {"time": "2026-11-13T10:02:01+05:30"}
id: 2
event: stock
data: {"symbol": "NOVA", "price": 88.4, "change": 0.3}
: hb ← heartbeat after 15s idle
id: 3
event: chat
data: {"name": "ada", "text": "hello", "at": "..."}
The response headers that make it SSE¶
HTTP/1.1 200 OK
Content-Type: text/event-stream ← REQUIRED — this is the switch
Cache-Control: no-cache ← stop caches buffering events
Connection: keep-alive ← the response never ends
Gotchas:
- No
Content-Length— the length is unknowable, that's the point. - Flush every write. If your framework buffers, events arrive in clumps.
X-Accel-Buffering: nofor nginx (details in production).text/event-streammust be exact —text/plainstreams will display in curl butEventSourcerefuses them.
Dispatch rules (the spec in 30 seconds)¶
A client must:
- Buffer
field: valuelines until a blank line, then dispatch. - Strip exactly one leading space after the colon, if present.
- Concatenate multiple
data:fields with\n. - Ignore unknown fields and lines starting with
:. - Fire
onmessageif noevent:field was given; otherwise fire an event of that type. Skip dispatch entirely if there was nodata:at all (that's whyretry:alone doesn't create an event, and comments are free).
Check your understanding¶
What actually dispatches (delivers) an SSE event to JavaScript?
Which field may appear multiple times in a single event?
A block contains only event: hello — no data: line. What happens?
Which of these does JavaScript receive via EventSource? (select all)
Next: the EventSource API — the browser side.