Resumable Server-Sent Events design

Choose an identifier the server can order for that stream: a per-subscriber sequence, a log offset, or another monotonic position. A random id proves uniqueness and does not define what to replay.

• Set the id field on every event that must survive reconnect.
• End each event with a blank line.
• Keep data as UTF-8 text, often one JSON object.
• Use the retry field only with a deliberate backoff policy.

Persist events, or the ability to recompute them, for longer than a realistic disconnect. Define the response when Last-Event-ID is unknown, expired, or ahead of the log. Catch-up from empty and a full snapshot are different products; pick one and document it.

Authorize the stream and the replay on every request. An unguessable URL is not a substitute for authentication, because reconnects and logs copy that URL.

The client can apply an event and then disconnect before it has a newer id to resume from. The server will send that event again. Handlers should treat the id as an idempotency key.

Ignore comments and unknown event names without closing the stream. Surface application error events differently from an HTTP failure so reconnect logic stays intact.

Send text/event-stream and headers that tell proxies not to buffer. Confirm idle timeouts are longer than your heartbeat, and send a comment heartbeat if the platform closes quiet connections.

Compression and intermediate caches can hold bytes until a buffer fills. Test the deployed path, not only a direct socket to the origin.

Use Flashman's JSON formatter for event data, the timestamp converter for heartbeat intervals, the UUID generator when fixtures need synthetic ids, the URL parser for the stream request, and the Markdown editor for the replay contract.

Test a drop after a stored id, an event with no id, an expired window, a duplicate delivery, proxy buffering, an idle timeout, an unauthorized reconnect, and a client that retries faster than the server allows.