· By John Kavanagh

Streaming Node.js Fetch Responses Without Leaving Connections Busy

Black-and-white photograph of inverted U-shaped industrial pipes.
Image by Tim Mossholder, licensed from Unsplash.

A call to fetch() can finish awaiting its response whilst the connection still has plenty of work left to do. The status and headers have arrived. The body may be arriving slowly, may be much larger than expected, or may be waiting for somebody to read it.

That matters when the caller only wanted to inspect the status. Returning early without dealing with the body can leave transport capacity occupied. Under a deliberately small connection pool, the next request makes the omission rather obvious by going nowhere.

My Fetch API guide covers the basic response checks. Here, I'm using Node 22.4.1 and a separately installed Undici 6.19.2 to make the connection policy explicit and inspect what happens after those checks.


Headers are One Stage of the Request

await fetch(url) doesn't mean the response body has finished. A later await response.json() consumes that body and then parses it. My guide to async and await explains the sequencing; the important detail here is which asynchronous operation each await actually represents.

An HTTP error status doesn't remove the body either. A 503 response may contain a short explanation, a substantial generated error page, or a stream which hasn't finished. Checking response.ok and immediately throwing leaves that separate lifecycle unresolved.

Choose who owns the body before returning from the request function. That owner can consume it, stream it to a destination, or cancel it. Hoping that garbage collection gets around to the decision is a fairly relaxed approach to managing a limited resource.

Undici's own guidance on garbage collection specifically recommends consuming or cancelling response bodies in Node. The distinction matters even when a quick local request appears to work without either.


Make the Pool Small Enough to Inspect

I use an explicit dispatcher for this experiment:

import { Pool, fetch } from 'undici';

const pool = new Pool('http://localhost:3000', {
  connections: 1,
  pipelining: 1,
  keepAliveTimeout: 10000,
});

try {
  const response = await fetch('http://localhost:3000/catalogue', {
    dispatcher: pool,
  });

  if (!response.ok) {
    await response.body?.cancel();
    throw new Error(`Catalogue request failed: ${response.status}`);
  }

  console.log(await response.text());
} finally {
  await pool.close();
}

This example owns its pool for the duration of one small command. A long‑lived service would normally reuse its dispatcher across requests and close it during shutdown. It should not destroy a shared pool merely because one caller has finished.

The Pool options define the connection cap. A pipelining depth of one keeps this comparison to one active request per connection. These are chosen test conditions, not a description of whatever global dispatcher happens to be installed elsewhere.

Start one request whose body is large enough to encounter backpressure, retain its response without reading it, then start another request. Record when the server sees each request and whether the pool reports pending work. Finally, cancel the first body and observe whether the second request can proceed.

Keep the first response referenced during the negative test. Otherwise, the experiment starts depending on when the runtime happens to collect it.


Stream Without Collecting the Whole Payload

Reading everything into text() is convenient for a known small response. It isn't an attractive default for a large export which will immediately be written somewhere else.

A reader lets the caller forward chunks and enforce its own byte limit:

async function streamBody(response, write, maxBytes) {
  if (!response.body) return;

  const reader = response.body.getReader();
  let complete = false;
  let bytes = 0;

  try {
    for (;;) {
      const { done, value } = await reader.read();
      if (done) {
        complete = true;
        return;
      }

      bytes += value.byteLength;
      if (bytes > maxBytes) throw new RangeError('Response too large');
      await write(value);
    }
  } finally {
    try {
      if (!complete) await reader.cancel();
    } finally {
      reader.releaseLock();
    }
  }
}

The destination's write function must resolve when it is ready for more work. Merely returning from a call to a Node writable's write() does not establish that condition when it has signalled backpressure. Use an adapter which waits for drain, or an appropriate stream pipeline.

The byte limit counts received chunks before forwarding them. It doesn't bound every buffer inside the transport. The useful property is that the application isn't assembling another complete copy of the response, and a rejected size or failed destination exits through the reader's cleanup.

Once a reader locks the body, cancel through that reader. Calling response.body.cancel() whilst the reader still owns the lock is the wrong level of the API. The unlocked‑body cancellation in the earlier example is a different case.


Disposal and Reuse are Different Outcomes

Consuming a response fully can make its connection available for reuse, subject to the server, protocol, and pool settings. Cancelling early may instead close the connection. Both can release capacity for later requests; they needn't preserve the same socket.

Record socket identity at the local server when testing reuse. Two successful requests don't prove they used one connection. Equally, seeing another connection after cancellation doesn't prove that disposal failed.

For a controlled comparison, run two fully consumed requests with keep‑alive enabled, then repeat with Undici's pipelining: 0 setting, which disables keep‑alive. Keep the request and response bodies identical. That separates the connection policy from the body‑processing policy.

I wouldn't turn the resulting timings into a general performance recommendation. Request‑to‑headers time includes queueing and upstream work. Local socket reuse doesn't model TLS negotiation, proxy buffering, network delay, or a different server's behaviour.


Keep the Awkward Response Cases

A useful test set includes more than a successful JSON document:

  • A non‑success response still carrying a body, which the caller cancels deliberately.
  • A 204 response with no body, which needs no reader.
  • Invalid JSON whose body was consumed successfully before parsing failed.
  • A response exceeding the chosen streaming limit.
  • A destination which rejects part‑way through writing.
  • A deliberately unread response which holds up a capped pool until it is disposed of.
  • Several streamed requests which all finish through a two‑connection limit.

Check progress after each failure. A rejected promise alone doesn't show whether the next request can run. Check that pending and running counts return to zero, that the server stops producing an abandoned response, and that the fixture shuts down its sockets and processes.

The server needs to respect backpressure too. Continually writing chunks after its own write() returns false simply moves the growing queue into the server and makes the experiment harder to interpret.


Wrapping Up

For each response, I want an obvious answer to who consumes or cancels the body, including the branches which only inspect its status. That decision belongs alongside the request's error handling.

Then test the next request. It is a useful witness to whether the previous one actually released what it was using.

Postscript

November 2026: My shared HTTP transport lab now includes a separate connection‑pool chapter alongside its cancellation walkthrough. The current download uses Undici 7.30.2 and is tested on Node 22.23.5 and 24.14.0. I also checked the pool scenarios with Node 22.4.1 and Undici 6.19.2 for the article's historical setting. These are November 2026 verification runs. The tests distinguish releasing pool capacity from preserving the same socket, and deliberately retain an unread body to make the blocked‑request case observable.

Downloadable Resource

  • Node.js HTTP Transport Lab

    Inspect response‑body disposal, request cancellation, and React upload progress with a supervised local service, controlled processing, and independently checked receipts.

    Download ZIP

Need a senior engineer involved?

I can work directly in the codebase, review the architecture, or support the team through delivery when the work needs more than extra hands.