Workspace

Server-Sent Events, byte by byte

3 day streakD

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.

BasicsLesson 2 of 622 min

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.

stream.txtText
: 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
FieldMeaning
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.
: commentAny 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.

Figure 2.1

Feed a stream in random chunks

Network reads (↵ is a newline)
  1. read 1 · 11 B: ping↵↵eve
  2. read 2 · 19 Bnt: delta↵id: 1↵dat
  3. read 3 · 22 Ba: {"text":"Hel"}↵↵eve
  4. read 4 · 36 Bnt: delta↵id: 2↵data: {"text":"lo �
  5. read 5 · 19 B��"}↵↵event: stop↵i
  6. read 6 · 15 Bd: 3↵data: {}↵↵
Buffered text, waiting for a blank lineempty
Events emitted
  • none yet

Press Next step to deliver the first network read.

Step 01 / 7
Step through network reads of the stream above, split at awkward points. A naive parser treats each read as events and corrupts data. A correct parser decodes UTF-8 with { stream: true }, buffers text, and emits only events ended by a blank line.
sse-parse.tsTypeScript
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

Model SDKs

Official SDKs parse SSE exactly like this and expose typed events: message start, content deltas, tool-use deltas and stop.

Progress pages

CI systems and deploy dashboards stream log lines with SSE, using IDs so a refreshed page continues where it left off.

Heartbeats

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.

A good place to start

Explore a pattern

A little guidance

Start with a pattern, read through a problem, and mark it solved when the idea clicks. Save anything you want to revisit.

New tutorials are added one at a time. Your bookmarks and solved checkmarks stay in this browser.

Explore the roadmap