SSE Protocol & Wire Format

Technical Deep Dive & Specifications

The Four Standard Protocol Fields

The WHATWG specification defines four valid field names in the text/event-stream wire format. Any unrecognized field name is silently ignored.

+-----------------------------------------------------------------------------------------------+
|                                    SSE WIRE FORMAT FIELDS                                     |
+-----------------------------------------------------------------------------------------------+
|  Field Name  | Example                     | Description                                      |
+--------------+-----------------------------+--------------------------------------------------+
|  data        | data: {"status": "ok"}      | The payload data. Multiple lines are joined by \n |
|  event       | event: user_joined          | Custom event type (dispatched via addEventListener) |
|  id          | id: evt-98234               | Event ID. Updates the client's lastEventId       |
|  retry       | retry: 5000                 | Reconnection backoff interval in milliseconds    |
|  : (Comment) | : heartbeat ping            | Ignored by parser; keeps idle sockets alive      |
+-----------------------------------------------------------------------------------------------+

1. The data: Field & Multi-Line Concatenation

The data: field carries the actual message payload string. If your payload contains newlines (such as multiline text, formatted JSON, or Markdown), each line is prefixed with data: :

data: Line 1 of message
data: Line 2 of message
data: Line 3 of message

Parser Resulting event.data:

"Line 1 of message\nLine 2 of message\nLine 3 of message"

2. The event: Field (Custom Event Types)

Sets the event name. If omitted, the browser defaults to dispatching a generic message event (which triggers eventSource.onmessage). If specified, it must be listened to using addEventListener:

event: alert
data: Warning: High temperature!

eventSource.addEventListener('alert', (e) => {
  console.log(e.data); // "Warning: High temperature!"
});

3. The id: Field (Event Resumption Identifier)

Sets the internal lastEventId property of the EventSource object. If the network connection drops, the browser sends this value in the Last-Event-ID request header upon reconnecting:

id: 42
data: Transaction #42 committed

4. The retry: Field (Client Backoff Directive)

Instructs the browser how many milliseconds to wait before attempting to reconnect if the connection drops:

retry: 10000
data: Reconnection wait time set to 10 seconds

5. Comments (:) & Proxy Heartbeats

Any line starting with a colon character (:) is treated as a comment and ignored by the browser. This is essential for sending periodic keep-alive pings (every 15–30 seconds) to prevent firewalls and Nginx proxies from closing idle connections:

: ping heartbeat 2026-08-21T02:30:00Z

Strict Delimiter Rules: Single vs. Double Newlines

+-------------------------------------------------------------+
|  data: Hello                                                |
|  data: World                                                |
|  \n                                                         | <-- Single newline continues message
|  id: 1                                                      |
|  \n\n                                                       | <-- DOUBLE NEWLINE TRIGGERS DISPATCH!
+-------------------------------------------------------------+

💻 Interactive Code Playground

Below is a live, interactive SSE Wire-Format Parser and Simulator. You can type or modify raw wire-format text in real time and observe how the parser state machine tokenizes and emits structured events.

Starter Code

Line-by-Line Code Breakdown

• Lines 105–109: Normalizes all CRLF (\r\n) and CR (\r) line breaks to standard LF (\n) for cross-platform parser consistency.
• Lines 118–137 (dispatch()): Glues all lines in dataBuffer together with \n and creates a visual event card. If event: was omitted, currentEvent.type defaults to "message".
• Lines 144–147: When a blank line (line === '') is encountered, the frame is complete and dispatch() is immediately executed.
• Lines 150–156: Lines beginning with : are identified as keep-alive comments. They are filtered out and not sent to onmessage.
• Lines 163–170: Strict WHATWG spec rule: if the character immediately following the colon is a space (U+0020), exactly one space is stripped.
• Lines 172–180: Distributes parsed fields to data, event, id, or retry.

Expected Browser Render Output

🔬 Live SSE Wire Format Parser
Dispatched Event Output:

[Comment/Heartbeat] ping keepalive 10:00:00

[message] ID: 101  Retry: 5000ms
{"user": "Alice", "status": "online"}

[trade] ID: 102
{
  "symbol": "BTC/USD",
  "price": 64250.00
}

[Comment/Heartbeat] another comment

[system_alert] ID: 103
Emergency maintenance scheduled at midnight.