Server-Sent Events, byte by byte
SSE is a tiny text format inside an HTTP response. Learn every field, how to parse it correctly from arbitrary chunks, and how reconnection with Last-Event-ID works.
An SSE response has Content-Type: text/event-stream and a body made of events. Each event is a group of field: value lines and ends with a blank line. That blank line is the frame delimiter, the Module 4 framing lesson in its simplest form.
: connected, keep this comment as a heartbeat
event: message_start
id: 1
data: {"type":"message_start","model":"…"}
event: content_block_delta
id: 2
data: {"type":"content_block_delta","delta":{"text":"Hel"}}
event: content_block_delta
id: 3
data: {"type":"content_block_delta","delta":{"text":"lo 🙂"}}
retry: 3000
| Field | Meaning |
|---|---|
data: | The payload. Several data: lines in one event are joined with newlines. |
event: | The event's type. Defaults to message. |
id: | The event ID. The client remembers the last one it saw. |
retry: | How long, in milliseconds, the client should wait before reconnecting. |
: comment | Any line starting with a colon is ignored. Perfect for heartbeats. |
Parsing from arbitrary chunks
The body arrives in network reads that split anywhere: in the middle of a line, in the middle of a JSON string, even in the middle of a multi-byte character such as 🙂. A correct parser keeps two buffers: undecoded bytes, handled by a streaming TextDecoder, and decoded text waiting for a complete event.
Feed a stream in random chunks
- read 1 · 11 B
: ping↵↵eve - read 2 · 19 B
nt: delta↵id: 1↵dat - read 3 · 22 B
a: {"text":"Hel"}↵↵eve - read 4 · 36 B
nt: delta↵id: 2↵data: {"text":"lo � - read 5 · 19 B
��"}↵↵event: stop↵i - read 6 · 15 B
d: 3↵data: {}↵↵
empty- none yet
Press Next step to deliver the first network read.
{ stream: true }, buffers text, and emits only events ended by a blank line.export type SSEEvent = { event: string; data: string; id?: string };
export async function* parseSSE(body: ReadableStream<Uint8Array>): AsyncGenerator<SSEEvent> {
const decoder = new TextDecoder(); // keeps partial UTF-8 between chunks
let text = "";
for await (const chunk of body) {
text += decoder.decode(chunk, { stream: true });
text = text.replace(/\r\n?/g, "\n"); // the spec allows CRLF, LF or CR
let end: number;
while ((end = text.indexOf("\n\n")) !== -1) {
const raw = text.slice(0, end);
text = text.slice(end + 2);
const event: SSEEvent = { event: "message", data: "" };
const data: string[] = [];
for (const line of raw.split("\n")) {
if (!line || line.startsWith(":")) continue; // blank or comment
const colon = line.indexOf(":");
const field = colon === -1 ? line : line.slice(0, colon);
let value = colon === -1 ? "" : line.slice(colon + 1);
if (value.startsWith(" ")) value = value.slice(1);
if (field === "data") data.push(value);
else if (field === "event") event.event = value;
else if (field === "id") event.id = value;
}
if (data.length) yield { ...event, data: data.join("\n") };
}
}
}This is the part of a model SDK you can now write yourself. Fuzz it by re-chunking a recorded stream at every possible split point.
Reconnection
The browser's EventSource reconnects automatically after a dropped connection, waiting retry milliseconds, and sends the last seen ID in a Last-Event-ID header. A server that keeps events can resume from there. A server that does not, which is most LLM endpoints, starts over or fails. Reconnection is only as good as the server's memory (the last lesson of this module).
Go deeperThe six-connection limit
Over HTTP/1.1, browsers allow about six connections per origin. Each open SSE stream holds one. Open seven tabs of your chat app and the seventh stream, and every other request to that origin, waits.
Over HTTP/2 or HTTP/3, streams share one connection and the limit becomes the server's concurrent-stream setting, often 100. Serving SSE over HTTP/2 removes the problem; so does multiplexing many logical streams over one SSE connection in the app.
Where you will meet it
Official SDKs parse SSE exactly like this and expose typed events: message start, content deltas, tool-use deltas and stop.
CI systems and deploy dashboards stream log lines with SSE, using IDs so a refreshed page continues where it left off.
Servers send : ping comments every 15 to 30 seconds so proxies and NATs keep the stream alive.
Words to know
- text/event-stream
- The content type of an SSE response.
- Event
- One group of SSE field lines ended by a blank line.
- Last-Event-ID
- Request header carrying the last event ID the client received.
- Heartbeat
- A periodic message, here an SSE comment, that keeps idle connections alive.
Check yourself
Answer out loud before you open each one.
How does an SSE parser know an event is complete?
A blank line ends the event.
Why does an SSE parser need a streaming TextDecoder?
A network read can end in the middle of a multi-byte UTF-8 character; the streaming decoder holds the partial bytes until the next read.
What does Last-Event-ID do?
On reconnect, the client sends the last event ID it saw so the server can resume after it.
Try it
Record a real model stream with curl -N into a file. Feed it to the parser above in random 1-to-20-byte chunks, 1,000 times, and check every run yields identical events.