Server-Sent Events: Streaming

The text format most providers stream with, why network chunks never line up with events, and the parser traps.

Most providers stream over HTTP using Server-Sent Events (SSE). It is a plain-text format where each event is one or more data: lines ended by a blank line:

data: {"delta": "Hel"}

data: {"delta": "lo"}

data: [DONE]

The [DONE] line is a convention some providers use to mark the end. Others send a typed final event instead, so check yours.

Your HTTP library hands you chunks of bytes, and chunks do not line up with events. A chunk can end in the middle of a line, or contain three events and half of a fourth.

Real output of the example parser on that stream cut into 14-character chunks. Only a blank line completes an event.

The SSEParser keeps a buffer. Append each chunk, split off the complete events at blank lines, and keep the remainder for next time. Its tests cover these traps:

Events split at every chunk size from 1 to 50 characters give the same result.
Comment lines (starting with :) and keep-alives produce no events.
Line endings can be \n, \r\n or a lone \r, and a chunk can end between the \r and the \n.
An incomplete event waits for more data instead of raising an error.
A data: payload spread over several lines is joined with newlines.
Only one space after data: is part of the format. Any further spaces belong to the data.

For the curious A bug the first version had

The first version of this parser converted \r\n to \n chunk by chunk. When a chunk ended exactly between the \r and the \n, the pair was never joined. With 1-character chunks it returned no events at all, and with 3-character chunks it silently lost the last event. The old tests only used \n in the chunked case and only tried four chunk sizes, so nothing caught it. The fix is to normalise the whole buffer and hold back a trailing \r until the next chunk shows what follows it. The price is that, for a stream using lone \r endings, the last event waits for one more byte.

For the curious A known limit

If one event contains invalid JSON, json.loads raises, and other events found in the same feed call are lost with it. A production client would catch the error per event, log the bad payload and carry on. Exercise Medium 3 asks you to do this.

In practice your SDK or HTTP library usually hides this layer. You need it when you build a proxy, a test double or a browser client, and it is a classic interview exercise. One browser detail: the built-in EventSource can only make GET requests without a body, so chat applications usually send a normal fetch request and read the response stream themselves.