Where each of those four branches physically lives

The tree mixes four different kinds of thing, and they sit in four different places in the object graph. That matters the moment you start reasoning about inheritance, because only one of the four is copied per instance.

So "shape" is not one flat record. It's own state on the instance plus behaviour reached by walking the prototype chain. The next question in this sequence is entirely about that distinction.

The events branch is not a fixed list either

The four names shown are the ones a consumer subscribes to, but a Readable also emits 'close', 'pause' and 'resume'. Of the four listed, 'readable' is the one that carries the most weight later on: it is the event the async-iterator interface is built on, and it is the only one of the four that never appears again in the rest of this material.

What each of the three layers actually owns

The three-word stack is worth expanding, because each layer owns something the layer above it cannot see.

"The stream is richer than that iterator" is precisely this: the iterator protocol has exactly two verbs, next() and (optionally) return(). The stream underneath has a buffer with a size, a watermark that governs whether to keep reading from the resource, three flow states, and a destroy path. None of that is expressible in { value, done }.

What that upward arrow is made of

"Backpressure" is drawn as an arrow pointing back at the producer, which is the right direction but leaves out every link in the chain. On an incoming HTTP request, no message travels upward. What happens is a sequence of things that stop.

The consequence worth holding on to: backpressure on a read path is the absence of recv() calls, not a signal. It is enforced by TCP itself, several layers below JavaScript. That is also why it only works if your consumer genuinely stops asking — which the two consumption interfaces do not handle the same way, as the last stage of this page shows.

The state, with its real field names

Every flag in the "state" branch is a property on one object. Reading it in a debugger is the fastest way to make all of this concrete.

flowing has three values, and the third one is the default

The tree shows "flowing / paused", which reads as a boolean. It is not.

The null state is why a request whose body you never consume simply sits there rather than filling memory, and it is why an unconsumed request can hold a connection open until it times out.

The search, stated exactly

The engine performs [[Get]] on req with the key "read":

1. Look for an own property named read on req. Not found.
2. Follow req.[[Prototype]] and repeat. Not found on IncomingMessage.prototype.
3. Follow again. Found on Readable.prototype. Return that function object.
4. The call then runs with this bound to req — because this is decided by the call site, not by where the method was found. This is the mechanism by which one shared function operates on per-instance state.

That last point is the whole reason the design works. There is exactly one read function in the process, and it reaches this._readableState to find which stream it is reading.

Where each property on a request actually resolves

When the metadata is populated

"Request-specific state" arrives at a specific moment, and it is earlier than the body. Node's HTTP parser signals headers-complete first; only then is your createServer callback invoked. So on the very first line of your handler:

• req.method, req.url and req.headers are already final.
• The body has generally not arrived. Zero, one or several chunks may be sitting in the socket, but the stream has not been consumed.
• req.trailers is an empty object and stays that way until 'end' — trailers are sent after the body, which is the entire reason they exist.

That split — metadata ready synchronously, body available only over time — is what forces the object to be both a record and a stream at once.

"Happens to expose" is doing real work in that sentence

Being iterable is a property the object acquired by inheritance, not something the HTTP layer arranged. IncomingMessage contains no iteration code whatsoever. The method is defined once, on Readable.prototype, keyed by Symbol.asyncIterator, and every readable stream in the process picks it up for free — file reads, sockets, decompression streams, request bodies.

The practical test of whether you have internalised this: req and a fs read stream are iterated by the exact same function. Nothing in that function knows about HTTP.

Why the split is guaranteed, not merely possible

"Maybe it arrives" understates it. TCP offers a byte stream with no message boundaries. There is no framing in the protocol that would let the kernel hand your process a complete HTTP body as a unit, and several independent mechanisms actively chop it up:

• Path MTU. A segment carries roughly 1460 bytes of payload on a standard Ethernet path. A 10 MB body is thousands of segments before it ever reaches the receiver.
• Kernel receive buffer. Bytes accumulate in the socket's receive queue. Your process gets whatever has arrived at the instant it calls recv() — a partial segment, several segments coalesced, anything.
• Congestion and flow control. The sender's window opens and closes over the life of the transfer, so arrival is bursty by design.
• The HTTP parser. Even a single recv() may contain the tail of the headers plus the head of the body, so what reaches the stream is a slice of a slice.

The consequence for your code: a chunk boundary carries no meaning. A multi-byte UTF-8 character can be split across two chunks; a JSON document certainly can. Any code that calls chunk.toString() per chunk and concatenates the strings is already broken for non-ASCII input, and the bug only shows up under a particular chunking.

There is less machinery here than the name suggests

An EventEmitter is a map from event name to a function or an array of functions, plus a loop. Stripped to essentials:

on(name, fn) {
  (this._events[name] ??= []).push(fn);
  return this;
}

emit(name, ...args) {
  const list = this._events[name];
  if (!list) return false;
  for (const fn of [...list]) fn.apply(this, args);
  return true;
}

Four properties follow directly from that loop, and all four surprise people:

• emit is fully synchronous. It is a for loop. By the time emit returns, every listener has already run to completion. Nothing is queued, and there is no event loop involvement at all.
• The list is copied before iterating. A listener that removes itself, or adds another, does not disturb the pass in progress.
• Order is registration order. No priorities.
• A throw from any listener propagates out of emit and skips the remaining listeners.

The one event with special semantics

'error' is not an ordinary name. If an 'error' event is emitted and there is no listener for it, EventEmitter throws the error object, which on an unhandled path takes down the process. Every other event with no listeners is a silent no-op. On a request this matters: a client that disconnects mid-upload produces an error on the request, and the handler you did not attach is the difference between a logged warning and a crash.

The desugaring with the exit path restored

The while (true) version is right about the happy path and silent about every other way out of a loop. The full shape:

const it = req[Symbol.asyncIterator]();
try {
  while (true) {
    const r = await it.next();
    if (r.done) break;
    body(r.value);            // break / return / throw all land below
  }
} finally {
  if (!completedNormally) await it.return?.();
}

On a Readable, it.return() calls destroy(). The behaviours that fall out of it:

This is one of the strongest practical arguments for the iterator form: cleanup on the abnormal path is automatic.

What "the stream machinery knows" is, concretely

It is a saved function reference. When read() comes back empty, the iterator stores the promise's own resolve in a field on itself and returns the pending promise. Nothing else happens — no timer, no polling, no loop.

The chain that eventually fires it is entirely event-driven, and each link is code that already exists for other reasons:

1. The event loop is blocked in the OS event-polling mechanism (epoll_wait on Linux) with the socket's descriptor in the watch set.
2. Bytes land in the kernel receive queue; the descriptor becomes readable; the poll call returns.
3. libuv invokes the read callback, which calls recv() and hands the bytes to the HTTP parser.
4. The parser calls push() on the request, which appends to the buffer and — because a consumer is waiting — emits 'readable'.
5. The iterator's 'readable' handler retries read(), gets a chunk, and calls the stored resolve.
6. Resolving schedules the continuation of your async function as a microtask. It runs after the current synchronous work finishes, before the loop moves on.

The suspended async function, throughout, is not on the call stack. Its execution context was captured when it hit await, so the stack was free to unwind all the way back to the event loop. That is precisely what makes "JavaScript continues" true.

Even the already-buffered case yields

When read() succeeds immediately, next() returns an already-resolved promise. await still suspends — it always queues a microtask before resuming. So the loop body never runs synchronously with the next() call, in either case. This is worth knowing because it means a for await loop always gives the microtask queue a turn between chunks, whereas a tight on('data') handler does not.

The asymmetry the push/pull labels don't capture

Both interfaces deliver the same bytes. They differ in what happens when your handling of a chunk takes longer than the next chunk takes to arrive.

The fourth row is where real programs break. This is a memory leak waiting to happen:

req.on('data', async chunk => {
  await writeToDatabase(chunk);   // 500ms — but nothing waits for it
});

The emitter calls the listener, the listener returns a promise at its first await, and emit discards it. Chunks keep arriving at network speed while completions happen at database speed, and the unfinished operations pile up in memory. The for await version of the same code is correct without any extra thought, because the loop cannot issue the next next() until the body's promise settles.

The layers under the stream, with their real names

The bottom stack is drawn in the direction data flows, but the labels compress several distinct components. Named precisely, bottom-up:

Two things are worth extracting from that table. First, the parser sits between the socket and the request stream, which is why req yields body bytes only — the headers were consumed a layer below. Second, one socket can feed several IncomingMessage objects in sequence under keep-alive, which is why req.socket is shared state and not a per-request resource.

Notification versus consumption, made precise

The two labels are the sharpest sentences in this section, and they hold up under pressure. Sharpening them one more turn:

• Notification answers "has something happened?" — a fact, broadcast to every subscriber, with no return channel. emit ignores what listeners return, so a listener cannot say "not yet, hold on."
• Consumption answers "give me the next item" — a request from exactly one caller, with a return channel. The promise the consumer awaits is the return channel, and its timing is what regulates the producer.

Every difference in the comparison table above is downstream of that one structural fact: one interface has a way to say "not yet" and the other does not.

The HTTP interface is a different kind of thing from the other two

The three-way split is useful, but the first branch is not a peer of the other two:

Metadata is state you query. The other two are a sequence you consume. That is why "read the body twice" is not a thing you can do without buffering it yourself, while "read the method twice" is trivial.

The full descent, one link per step

Each arrow in that stack is a real handoff with a name. Following bytes down from the wire:

Worth noticing where the boundary between "someone else's schedule" and "your schedule" falls. Everything above the parser happens whether or not your code is ready. Everything from push() down is governed by whether a consumer is asking.

The buffer is a linked list, and that is not an implementation detail

The picture shows fixed cells side by side. In reality _readableState.buffer is a BufferList — a singly linked list of Buffer objects — and the reason matters:

• Appending is O(1) with no copying. Chunks arrive at network rate, so this is the hot path.
• Chunks are never merged on arrival. A read() for a specific byte count may have to concatenate across nodes, but the default read() with no argument just shifts the head off.
• The chunk you receive in the loop is the chunk the parser produced. Node does not re-slice to any size, which is why chunk boundaries look arbitrary and why they shift between runs.

A detail specific to the first call

The first next() is not quite like the rest, because up to that point readableFlowing has been null and nobody has read the socket for body bytes. So the first call typically does three things the later ones do not: it puts the stream into paused mode, triggers _read() for the first time, and finds an empty buffer. In other words the first iteration almost always takes the pending path even when the client sent everything at once — the bytes exist in the kernel, but nobody had asked Node to fetch them yet.

The two cases side by side

They differ in one step, and it is not the step most people expect. Case A does not skip the suspension — it skips only the waiting.

That last row is the one with practical weight. A body that is entirely buffered will drain through your loop without the event loop ever advancing a phase, because microtasks run to exhaustion. A slow upload gives the loop a turn between every chunk.

Where the suspended function is kept

At await, the async function's execution context — its environment record, the position to resume from, its live temporaries — is preserved off the call stack, and the stack unwinds back to whatever called it. This is why "nothing blocks the JavaScript thread" is literally true rather than a figure of speech: after suspension there is no frame for that function on the stack at all. When the promise settles, the context is restored and execution continues at the statement after the await.

The while (!data) wait() version, by contrast, would keep its frame on the stack and keep the thread executing. With one thread running the event loop, that loop would also prevent the very poll call that would let the data arrive — it would not merely be wasteful, it would deadlock.

"While our async function is suspended" — what the thread is doing

Nothing, in the strict sense. When there is no runnable JavaScript, the event loop reaches its poll phase and blocks in the OS event-polling mechanism (epoll_wait on Linux, kqueue on macOS, an IOCP wait on Windows). The thread is descheduled by the operating system until a descriptor it is watching becomes ready or a timeout expires. It consumes no CPU while waiting.

That is the payoff of the whole arrangement. One thread can hold thousands of suspended request handlers, because each one costs a heap-allocated context and a socket in the poll set rather than a stack and a thread.

One detail worth keeping straight: the line above says chunk = "hello", but the awaited value is the result object. await iterator.next() produces { value, done }; it is the for await loop that unwraps .value into your binding. In the desugared form the two steps are visible separately.

Different consumption interfaces, one at a time

"Two different consumption interfaces" is exact. The word doing the work is consumption: each chunk leaves the buffer when it is delivered, so the two branches divide the data rather than duplicating it. Choose per stream, and choose once.

If you genuinely need two consumers, the stream layer gives you a way to say so:

Where push turns into pull

The boundary is a single object: the buffer. Above it everything is scheduled by the producer; below it everything is scheduled by the consumer.

This reframes the earlier question of whether Readable "is" push or pull. It is the adapter between the two, and it needs a buffer for exactly the reason any adapter between mismatched rates does.

Following the 500 ms case through, link by link

1. The loop body awaits, so no further next() is issued for 500 ms.
2. Chunks keep arriving and are appended to the buffer. _readableState.length climbs.
3. It passes highWaterMark (64 KiB by default). Node stops calling _read(), so it stops asking the socket for more.
4. Nothing drains the kernel receive queue for this connection, so it fills.
5. The receive window advertised in ACKs shrinks toward zero.
6. The sender's TCP stack stops transmitting. If the client is a browser uploading a file, its own write calls start blocking.

The whole chain works only because step 1 is true. That is the practical difference from the emitter version, where emit ignores the promise your listener returns and step 1 never happens.

The equivalent code with the emitter, written correctly

req.on('data', chunk => {
  req.pause();                          // stop the flow yourself
  expensiveDatabaseOperation(chunk)
    .then(() => req.resume())       // and restart it yourself
    .catch(err => req.destroy(err));
});

Correct, and it makes the point: everything the for await version gets from the shape of the language, the emitter version needs you to write and to not forget. The advisory word in the docs — the watermark is a threshold Node consults, not a hard cap it enforces — describes this precisely. Nothing prevents a producer from pushing past it. What the machinery does is stop asking, and only a consumer that also stops asking makes that effective.

Iterable, iterator, generator — three words that are not synonyms

Against that vocabulary the three objects in play sort cleanly:

The row that settles the original question is the second one. req is not an async iterator — it has no next(). It is async iterable, and calling its symbol method mints an iterator that reads from it.

The bridge in the other direction

Since a generator is one way to make an async iterator, and a Readable can be built from any async iterable, you can convert between them:

const stream = Readable.from(chunks());   // generator → real stream

What that gives you is the thing the generator lacked: a buffer, a watermark, pipe, the event interface, and a destroy path. Which is the clearest possible statement of the difference — the generator supplies the sequence, and the Readable wraps it in the machinery.

Two suspension points, not one

The upload generator has two different kinds of pause in it, and they suspend for different reasons. Separating them is what makes the state-machine picture click.

The second row is the generator's own backpressure, and it is total: between one yield and the next next(), no code in that function body runs at all. It cannot read ahead, cannot buffer, cannot pre-fetch.

Which is precisely what a Readable adds. A stream keeps reading from its resource while nobody is asking, up to the watermark, and holds the result. The generator's laziness is stricter; the stream's eagerness is bounded. That is the real content of "a Readable isn't doing exactly that."

Where step 3 actually sits in time

The eleven steps read as a straight sequence, but steps 1–3 happen once per request and steps 7–11 repeat per chunk. Worth marking the boundary, and worth noting what falls between step 2 and step 3:

The one genuinely important addition: your handler is called after the headers are parsed, not after the request has arrived. Everything about the body is still in the future when your first line runs. That is why the metadata reads synchronously and the body does not.

Splitting the call from the await changes nothing here — but it can elsewhere

This version separates iterator.next() from await promise, which is a useful thing to notice: the call and the wait are two different acts. On a Readable's iterator it makes no difference, because a second next() before the first settles is queued rather than run concurrently.

But the separation is exactly what you would exploit to pipeline a slow consumer — start the next request before processing the current value:

let pending = it.next();
while (true) {
  const r = await pending;
  if (r.done) break;
  pending = it.next();        // ask early…
  await process(r.value);       // …then work
}

That reintroduces exactly one chunk of read-ahead, and with it exactly one chunk of lost backpressure. Sometimes that trade is worth making. The point is that it is a trade you now have the vocabulary to make deliberately.

How the stream learns there is nothing more

"The Readable knows" is the end of a chain that starts at the parser, and how it knows depends on the framing:

• Content-Length — the parser has counted down to zero.
• chunked — the parser read a zero-length chunk header.
• Either way it calls req.push(null). A null push is the end-of-stream signal, which sets ended, and once the buffer has drained, emits 'end'.

Two things share a name here and should not be confused. done: true is a value the iterator returns to your loop; 'end' is an event the stream emits. Under iteration the event still fires — it is what the iterator was waiting on — you just never see it.

The endings that aren't 'end'

A request body does not always finish. Three other terminations exist and only one of them looks like the diagram:

The second row is the one worth internalising: an aborted upload is an exception inside your for await loop, catchable with an ordinary try/catch around it. In the emitter version the same event arrives on a separate channel, and if you never attached an 'error' listener it can take the process down.

The fourth row is the quiet one. If you return a response without reading the body, the stream never ends, the socket stays unread, and the connection is held until a timeout fires. Consuming or explicitly destroying the request is not optional bookkeeping.

The same sentence, with the four refinements folded in

The summary holds. Four clauses can be tightened using what the expansions established:

• "an HTTP-specific Readable" — reached through four prototype links, not three: IncomingMessage → Readable → Stream → EventEmitter. Metadata is own state; everything else is found by lookup.
• "exposes multiple consumption mechanisms" — they are alternatives over one buffer, not simultaneous views of one sequence. Committing to one for a given stream is part of the design.
• "for await uses that iterator interface" — and that interface is built on 'readable' and read(), which keeps the stream paused. That is why iteration backpressures and 'data' does not.
• "eventually resolves" — via a parked resolve function, woken by an event, delivered as a microtask. No polling anywhere in the chain, and the suspended function is off the call stack the entire time.

The four objects, finally distinguished

If one line survives from all of this: req is not an iterator, and it is not a generator. It is a stream, and a stream is the machinery that makes a pull interface possible over a producer that pushes.

The same four kinds of thing, in the same four places

write() and _write() are the pair to keep straight

The read side had read() for consumers and push() for implementers. The write side has the same split with the roles swapped, and the naming convention makes it visible: the underscore prefix marks the implementer's half.

The state, with its real field names

'drain' fires on empty, not on "below the mark"

The natural assumption is that 'drain' fires as soon as the queue drops back under the watermark. It does not. Node emits it when the queue reaches zero, and only if a previous write had returned false:

if (state.length === 0 && state.needDrain) {
  state.needDrain = false;
  stream.emit('drain');
}

Two consequences. A stream that is being written to continuously may never emit 'drain', because the queue never quite empties. And 'drain' is not emitted at all unless a write previously returned false — waiting for one you were never promised is a common way to hang a program.

What the language gives each side

The last row is the practical answer to the missing AsyncIterable branch. Since no syntax runs the write loop for you, the standard library supplies a function that does. That is what the second production interface is.

The prototype chain, drawn out

The response metadata surface

writeHead and setHeader are not two ways of doing one thing. setHeader writes into a map that is serialised later; writeHead takes an object that is merged over that map at serialisation time. Where they disagree, writeHead wins, and headers set with setHeader but overwritten by writeHead are silently discarded.

What pipeline does that pipe does not

Both honour backpressure. They differ entirely on the failure paths, which is where streams actually go wrong.

The leak in row two is the classic one. A read stream that errors mid-transfer leaves the response open with headers already sent, and the client waits for a body that will never arrive until a timeout closes it. This is the single strongest reason to prefer pipeline for anything writing to a socket.

finish and close are not the same moment

Neither event tells you the client got the bytes. 'finish' on a response means the data reached the kernel send buffer. TCP acknowledgement is invisible from JavaScript, and a client that disconnects after 'finish' but before the segments are delivered leaves no trace in your process.

Where the header lock actually happens

The lock is not a timer or a phase — it is a side effect of the first call that produces output. Any of these trip it:

• res.write(chunk) — headers are serialised and prepended to that first chunk
• res.end() — even with no body, a complete response must be sent
• res.writeHead(...) — marks them ready, though the bytes may still be buffered
• res.flushHeaders() — sends them deliberately, ahead of any body

After any of those, res.headersSent is true and mutating a header throws. The practical consequence for the example above: once pipeline has moved a single chunk, you can no longer change the status code. A read error on the file at that point cannot be turned into a 500 — the client has already been told 200. All you can do is destroy the response, which surfaces at the client as a truncated body rather than an error status.

That asymmetry is worth designing around. If you need the option of failing cleanly, open the file and stat it before writing anything, so the failure happens while the headers are still mutable.

Setting Content-Length changes more than the header

The nine handoffs, named

Two things to extract. First, res has no watermark of its own — res.writableLength and res.writableHighWaterMark are getters that read the socket's state. The boolean you get back from res.write is the socket's opinion, relayed. Second, the cork window is why a small response usually leaves as a single packet: Node corks the socket for the duration of the tick and uncorks at the end of it, so the headers and the first body chunk coalesce.

The four endings, and how each one reaches you

Rows two and three are both handled by pipeline, which is the practical argument for it in one line. Row four is the exact mirror of the read side's quiet failure, where never consuming the request body holds the connection open. On both ends of the stream, the way to leak a connection is to stop halfway and say nothing.

A detail on keep-alive

'close' on a response does not imply the socket closed. Under HTTP/1.1 keep-alive the same connection serves the next request, which is why req.socket and res.socket are the same object and why that object outlives both. If you attach listeners to the socket from inside a handler, they accumulate across requests on that connection.

The mirror, side by side

Read down the last two columns and the asymmetry is the finding. The read side is forgiving because the pressure is held by a layer you do not control and cannot break. The write side is not, because the queue is yours.

Inherited versus copied, and what the difference costs

The row that occasionally bites people is the third. Monkey-patching Writable.prototype.write changes nothing for sockets, HTTP responses or any Duplex, because those methods were copied before your patch ran. Patching Readable.prototype does reach them.

The full table

Two entries that deserve a footnote

• crypto hashes and ciphers. These are built on a lazily-materialised transform: _writableState is a getter that constructs the underlying stream the first time anything reads it. So asking hash instanceof Writable is not a passive question — it is what forces the stream into existence. This is also why the membership test checks the prototype chain first, since routing the constructor's own check through the loose test would recurse forever.
• process.stdout. Its concrete type depends on what the process's file descriptor 1 is attached to — a terminal, a pipe, or a file — and the three cases are three different classes. All of them are real streams, but code that assumes a specific one is making an assumption about how the process was launched. It is also the reason process.stdout is synchronous in some of those cases and not in others.

What breaks when the wrong test is used

The public getters in the right-hand column exist precisely because the internals in the left-hand column are missing on these objects. They are the supported way to ask, and they work uniformly across real streams and façades.

Where this bites in practice

• Metrics and tracing wrappers that measure queue depth by reaching into _writableState. They work in tests against a PassThrough and throw in production against a response.
• Libraries that branch on stream type to decide between piping and buffering. A response takes the buffering path, and the backpressure benefit is lost without any error to notice.
• Type definitions. TypeScript models ServerResponse as extending OutgoingMessage, which is declared as a Writable for practical reasons. So the compiler will happily let you reach for members that do not exist at runtime — the type system agrees with the duck typing, not with instanceof.

Three sides, one finding

The three together make one point about the whole design: in Node's streams, the interface and the type are separable, and almost everything is built against the interface. That is why the façades work at all, and why the type check is the one place they show through.