Skip to content
Tutorials Center
My learning

Topics

Lesson 56 of 133 ยท Networking and HTTP

Server-Sent Events and Streaming Responses

Stream data from a Node.js server with chunked responses and Server-Sent Events - the text/event-stream format, a fetch-based client, reconnection with Last-Event-ID, heartbeats and backpressure.

A normal HTTP response is one message: the server builds the whole answer, sends it, and the exchange is over. But some answers are not ready all at once: a progress report for a long job, live prices, a log being tailed, chat messages, or tokens from an AI model. For these the server needs to keep the response open and send pieces whenever it has something new.

Node.js is very good at this because a ServerResponse is a writable stream. In this lesson you will start with plain chunked responses, then learn Server-Sent Events (SSE): a simple standard format on top of a long-lived response, understood natively by browsers through EventSource. You will write the server, write a client that parses the event stream with fetch, add automatic resume with Last-Event-ID, send heartbeats, and handle slow clients with backpressure. If you are new to req and res, read The http Module: Servers first; streams are explained in Streams Fundamentals.

Chunked responses

If you call res.write() several times before res.end(), and you have not set Content-Length, Node uses Transfer-Encoding: chunked. Each write() can reach the client immediately, so the client can start processing before the server is finished. On the client, response.body is a ReadableStream of Uint8Array pieces, which you can read with for await.

Node.js A response that arrives in pieces

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The client saw Transfer-Encoding: chunked and no Content-Length. Notice decoder.decode(chunk, { stream: true }): a chunk boundary can fall in the middle of a multi-byte character, and the stream option keeps the incomplete bytes for the next call (Text, Encodings and Unicode). How the pieces are grouped on the wire is up to the network; never rely on one write() equalling one received chunk.

Browsers may buffer a plain chunked text/plain response before showing it, and proxies may too. SSE solves that with a defined format and a dedicated media type.

The Server-Sent Events format

An SSE response has Content-Type: text/event-stream. The body is plain UTF-8 text made of events separated by a blank line. Each event is made of lines of the form field: value. There are only four fields:

Field Meaning
data: The payload. Several data: lines in one event are joined with \n.
event: An optional event name (default is message).
id: An identifier; the client remembers the last one and sends it back after a reconnect as Last-Event-ID.
retry: Tells the client how many milliseconds to wait before reconnecting.

A line that starts with a colon is a comment and is ignored by clients, which makes it ideal for keep-alive pings. A complete stream might look like this:

TEXT
: hello, this is a comment

retry: 3000

id: 1
event: price
data: {"symbol":"ACME","value":10.5}

id: 2
data: first line
data: second line

The blank line after an event is what dispatches it; forgetting it is the most common SSE bug. SSE is one-way (server to client) over ordinary HTTP. The client sends nothing after the first request; if it needs to talk back it uses a normal fetch/POST. It works through most proxies and CDNs, supports automatic reconnection, and uses HTTP/2 multiplexing well. For two-way messaging use WebSockets.

Writing an SSE server

The server needs to do four things: send the right headers, flush them immediately, write events in the format above, and notice when the client leaves. A tiny helper to format events keeps the code clean.

Node.js An SSE endpoint and a raw look at the stream

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

res.flushHeaders() matters: without it Node may hold the headers back until the first body write. Setting Cache-Control: no-cache stops intermediaries from storing the stream, and if you run behind nginx you also need X-Accel-Buffering: no (or proxy buffering off) so events are not collected into big blocks. We ended the response after a few events to keep the demo short; a real stream stays open until the client leaves.

Reading events on the client

Browsers have new EventSource(url), which parses the stream, reconnects automatically and fires events. Node 24 does not enable it by default (it is behind an experimental flag), but fetch can do the job, and a hand-written parser is only a few lines. It is also more flexible than EventSource: you can send headers such as Authorization and use POST, which EventSource cannot.

The parser must handle events split across chunks, so it keeps a buffer of text and extracts complete events (ending in a blank line). Because the stream is an async iterable, we write it as an async generator (Async Iterators and Generators).

Node.js An EventSource-like client with fetch

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The server cut the text every 7 characters, yet the parser reassembled it: the same events always come out, whatever the chunk boundaries. That property is exactly what you must test for in any streaming parser. Browsers' EventSource behaves the same, with event.type, event.data and event.lastEventId on each MessageEvent.

In a browser you would write const source = new EventSource('/events'); source.addEventListener('price', (e) => console.log(e.data));. It reconnects on its own and sends Last-Event-ID. It is also limited to six connections per browser per origin on HTTP/1.1, which is a good reason to use HTTP/2 or one shared stream per page.

Reconnecting and resuming with Last-Event-ID

Networks drop connections all the time. EventSource reconnects automatically after retry milliseconds (default a few seconds) and sends a Last-Event-ID header with the id of the last event it received. If your server numbers events and can replay the missed ones, the client never misses anything. If it cannot replay, clients should refetch the current state after reconnecting.

Let us simulate it: the server keeps a history of events, deliberately closes the first connection after three events, and the client reconnects and asks for everything after the last id it saw.

Node.js Resuming a stream after a dropped connection

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The client received all eight messages, in order and without duplicates, although the first connection died after three. The server used the header to skip what the client already had. Your history store can be a bounded ring buffer in memory (the last 1,000 events) or a database table; if a client asks for an id older than you keep, tell it to resynchronise. A server can also set the retry: field to slow down reconnect storms when it is overloaded.

Broadcasting to many clients

Real servers keep a set of open responses and write each new event to all of them. Two details matter: remove a client when its connection closes (otherwise you leak memory and write to dead sockets), and send a periodic heartbeat comment so that proxies and load balancers, which close "idle" connections after 30 to 60 seconds, do not cut the stream. The heartbeat also makes broken connections visible, because writing to a dead socket eventually fails.

Node.js A broadcast hub with cleanup and heartbeats

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Bob stopped receiving after he left, and the set shrank on its own thanks to the 'close' handler. Call .unref() on a heartbeat interval so that it never keeps your process alive by itself. For several Node processes (a cluster, or many containers), each process only knows its own clients, so publish through a shared channel such as Redis pub/sub; see Cluster, Scaling and Load Balancing.

Backpressure to slow clients

A fast producer and a slow consumer is the classic trap. res.write(data) returns false when Node's internal buffer for that socket is full. If you ignore this and keep writing, the data piles up in memory per client, and a few slow phones can bring your server down. The rule: when write() returns false, stop producing and wait for the 'drain' event.

Node.js Honouring write() and drain

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Each event is 256 KB, so a single write() already exceeds the stream's buffer limit and returns false; the server pauses until 'drain'. The number of waits depends on socket buffer sizes and timing, so we print only that it happened. For a general approach, stream.pipeline and Readable handle backpressure for you, as explained in pipeline and Backpressure. A good production policy is: if a client is too slow for too long (for example, no drain within 10 seconds), drop it.

When to use SSE, and when not

Choose SSE for server to client flows: notifications, dashboards, progress bars, log tails, live feeds, streaming AI output. It is plain HTTP, so authentication, logging and CDNs mostly work as usual, and the browser reconnects for you. Choose WebSockets when the client sends frequent messages too (chat, games, collaborative editing) or you need binary frames. Choose simple polling when updates are rare, because it needs no long-lived connections.

Operational advice:

  • Each open stream holds a socket; plan file-descriptor limits and capacity.
  • Disable response buffering in proxies and compression on the stream (or flush after each event).
  • Always handle 'close'/'error' on the response, send heartbeats, and clean up timers.
  • Don't put secrets in the URL, since EventSource cannot set headers: use cookies, or the fetch approach shown here.
  • Graceful shutdown must close the streams, otherwise server.close() waits for them for ever (Graceful Shutdown and Health Checks).

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What ends one event in the text/event-stream format?

    An event is dispatched when the parser reads an empty line. Forgetting the extra newline means the client never sees the event.
  2. 2. How do you send a payload with two lines in one SSE event?

    Every line needs its own data prefix; the client joins them with a newline. A raw newline inside a data line would end the field.
  3. 3. What is the purpose of sending : ping comment lines every few seconds?

    Comments are ignored by clients but count as traffic, so idle timeouts do not fire. A failing write also shows that a client is gone.
  4. 4. After a reconnect, how does the server know which events the client already received?

    The client stores the last id field it saw and sends it back as Last-Event-ID. The server replays everything after that id.
  5. 5. res.write() returned false. What should the producer do?

    false means the internal buffer is full. Continuing to write only piles data up in memory, so you pause until drain says there is room again.

Summary

  • A response can stay open: res.write() sends chunks (Transfer-Encoding: chunked) until res.end().
  • SSE is a simple text format served as text/event-stream: data, event, id and retry fields, comments starting with :, and a blank line after every event.
  • Call res.flushHeaders(), disable caching and proxy buffering, and remove clients on 'close'.
  • Parse the stream with a buffer that tolerates any chunk boundary; fetch plus an async generator makes an EventSource replacement that can send headers.
  • Numbered events and Last-Event-ID let clients resume after a dropped connection.
  • Send heartbeats, bound your history, and honour write() returning false by waiting for 'drain'.
  • Use SSE for one-way updates, WebSockets for two-way traffic.

Next: WebSockets