skip to content

Calling HTTP Services

Calling other services with fetch or http.request, and the agent settings that decide whether connections are reused. Asked what an unread response body costs and how to bound a hung call.

on this pageshow

explore

questions

6

In Node.js, what do http.Agent's keepAlive and maxSockets options control, and what does http.globalAgent use by default?

level: middleimportance: must knowfreq 60%

answer

  1. pool idle sockets or close them
  2. per-origin cap, then a queue
  3. plain Agent versus the global one
  4. changed in v19

basics

~20 s

keepAlive decides whether an http.Agent pools idle sockets for reuse; maxSockets caps concurrent sockets per origin and queues the rest. new http.Agent() defaults to keepAlive false and maxSockets Infinity; http.globalAgent enables keep-alive with a 5-second timeout.

solid answer

~40 s

An `http.Agent` owns the sockets for `http.request()`. With `keepAlive: true`, a socket whose request finished goes into `agent.freeSockets` for the next request to that origin, up to `maxFreeSockets` (default 256); with the default `false` it is destroyed, and because `maxSockets` is also at its default `Infinity`, the agent sends `Connection: close`. `maxSockets` caps active sockets per origin (the `agent.getName()` key); extra requests wait in the agent's pending queue rather than failing, and `maxTotalSockets` caps all origins together. `http.globalAgent`, used when you pass no `agent`, differs from a plain agent: since v19 it has `keepAlive: true` and a 5-second socket `timeout`, with the usual `'lifo'` scheduling. Since v24.7.0 an agent also closes a pooled socket `agentKeepAliveTimeoutBuffer` (1000 ms) before the server's `Keep-Alive: timeout` hint expires.

go deeper

for a junior

Recall that an http.Agent decides socket reuse, that keepAlive turns pooling on, and that maxSockets is a per-origin limit.

for a middle

Explain the queue behind maxSockets, the free-socket pool behind keepAlive, and how http.globalAgent's v19 defaults differ from a plain new http.Agent().

for a senior

Diagnose reuse races with reusedSocket and ECONNRESET, size maxSockets against an upstream, and spot a custom agent that quietly disabled keep-alive.

for a principal

Decide whether services share one agent per upstream or the global one, and who owns the caps that protect a fragile dependency.

## What an http.Agent is In `node:http`, an **agent** is the object that decides which TCP socket a client request travels on. Every `http.request()` either names one with the `agent` option, uses `http.globalAgent` when the option is absent, or gets a one-off agent with `agent: false`. The agent keys its sockets by **origin**: the string `agent.getName()` builds from host, port and local address (and, for `node:https`, the TLS options that affect reuse). ## keepAlive: pool or destroy - **`keepAlive: false`** (the constructor default): when the agent has no more queued requests for that origin, the socket is destroyed. Because the default `maxSockets` is `Infinity`, this combination also makes the agent send a `Connection: close` header, so the server closes its side too. - **`keepAlive: true`**: the finished socket goes into `agent.freeSockets` and the next request to that origin reuses it, skipping the TCP and TLS handshakes. Pooled sockets get TCP keepalive probes (initial delay `keepAliveMsecs`, default 1000 ms) and are **unref'd**, so idle pooled sockets do not keep the process alive. - **`maxFreeSockets`** (default 256) caps idle sockets kept per origin; extras are closed. - **`scheduling`** picks which idle socket to reuse: `'lifo'` (the default since v15.6.0) takes the most recently used one, which keeps the pool small at low request rates and lowers the risk of picking a socket the server is about to close; `'fifo'` spreads load across more sockets. The option is easy to confuse with two other things. It is not the `Connection: keep-alive` header, and it is not TCP keepalive alone; it is the agent's decision to **reuse** sockets. ## maxSockets: a cap with a queue - **`maxSockets`** (default `Infinity`) is the most sockets the agent opens to **one origin** at once. - When a request arrives and the cap is reached, the request waits in the agent's pending queue (visible as `agent.requests`) until a socket frees up. Nothing fails; latency grows instead. - **`maxTotalSockets`** (default `Infinity`) applies the same idea across all origins. So an agent with `maxSockets: 10` and 50 concurrent calls to one inventory host runs 10 at a time and queues 40. Nothing in the agent limits how long a request waits there, so the cap protects the upstream but needs a per-call deadline beside it, or queued calls can wait indefinitely. ## What http.globalAgent changes | Setting | `new http.Agent()` | `http.globalAgent` | |---|---|---| | `keepAlive` | `false` | `true` | | `timeout` | none | 5000 ms | | `scheduling` | `'lifo'` | `'lifo'` | | `maxSockets` | `Infinity` | `Infinity` | | `maxFreeSockets` | 256 | 256 | The global agent switched to keep-alive with a 5-second timeout in **v19**. A team that copied `new http.Agent()` into a service to "tune" it can therefore silently turn keep-alive **off** compared with the default it replaced. ## Sizing and observing an agent A cap only means something at the scope where it applies: - `maxSockets` is **per agent and per origin**. Two agents pointed at the same host each get the full cap, and every Node process (each cluster worker or replica) has its own agents, so the upstream sees the per-process cap multiplied by the number of processes. - An agent exposes its state as plain objects keyed by origin name: `agent.sockets` (in use), `agent.freeSockets` (idle, keep-alive only) and `agent.requests` (waiting for a socket). Sampling their sizes shows whether calls are queueing behind the cap or the pool is simply busy. - A long `agent.requests` queue with a healthy upstream means the cap is too low for the traffic; a short queue with slow responses means the upstream is the bottleneck and raising the cap would only add load. ## Living with server idle timeouts A pooled socket can be closed by the server at the moment the client reuses it, and the request then fails with `ECONNRESET`. Node gives you three tools: 1. The agent reads the server's `Keep-Alive: timeout=N` hint and expires the socket early by `agentKeepAliveTimeoutBuffer` (default 1000 ms, an option added in v24.7.0). If the hint minus the buffer is zero or less, the socket is not reused at all. 2. `request.reusedSocket` tells you whether a failed request went out on a reused socket, which is what decides whether a safe retry is reasonable. 3. `agent.destroy()` closes every socket when an agent is no longer needed, so a keep-alive pool does not hold connections open until the server times them out. ## Common misreadings - "maxSockets rejects requests over the limit": it queues them. - "The global agent caps hosts at a handful of sockets, like a browser": its default is unlimited. - "Setting keepAlive on http.globalAgent affects fetch()": fetch uses undici's own pool.

  • An agent has maxSockets: 10 and 50 requests to one host start at once. What happens, and what is the risk?
    Ten requests take sockets and forty wait in the agent's pending queue, `agent.requests`, each starting as a socket frees. Nothing errors, so the visible symptom is latency. The agent sets no wait limit on that queue, so pair the cap with a per-call deadline such as `AbortSignal.timeout()` passed as the `signal` option.
  • Why can a keep-alive agent see ECONNRESET on a request that should have worked, and what does Node do about it?
    The server may close an idle pooled socket just as the client reuses it. Node 24's agent expires sockets `agentKeepAliveTimeoutBuffer` (1000 ms by default) before the server's `Keep-Alive: timeout` hint, and `req.reusedSocket` lets code tell this race from a real failure before deciding to retry an idempotent request.

An http.Agent with maxSockets is a bank branch with a fixed number of tellers per queue: when every teller is busy, new customers wait in line rather than being turned away, and with keepAlive on, a teller who finishes stays at the desk for the next customer instead of going home.

  • new http.Agent() keeps connections alive by default.
  • maxSockets makes extra requests fail once the limit is reached.
  • http.globalAgent limits each host to about six sockets, like a browser.
  • The agent's keepAlive option is just the Connection: keep-alive header.
  • Idle pooled sockets keep the Node process from exiting.

Assumes Node 24: http.globalAgent has used keep-alive with a 5-second timeout since v19, scheduling has defaulted to 'lifo' since v15.6.0, and agentKeepAliveTimeoutBuffer arrived in v24.7.0.

open as a page

In Node.js 24, how does the global fetch() differ from http.request() in its implementation, connection pooling and configuration?

level: middleimportance: must knowfreq 65%

basics

~20 s

Node 24's global fetch() runs on the bundled undici client, not on node:http, so it pools connections in undici's global dispatcher and ignores http.Agent and http.globalAgent; http.request() is the lower-level, stream-based client those agents configure.

open as a page

A Node 24 service's calls to a slow payment API sometimes hang for minutes; what does each built-in client timeout bound, and how do you cap the whole call?

level: seniorimportance: must knowfreq 55%

basics

~20 s

Node's built-in client timeouts are idle timers: http.request's timeout only emits 'timeout', and fetch's undici defaults allow 300 seconds for headers and between body chunks. Cap the whole call with signal: AbortSignal.timeout(ms), which covers connect, headers and body.

open as a page

How do you make a Node 24 service send its fetch() and http.request() calls through the proxy named in HTTP_PROXY and HTTPS_PROXY?

level: middleimportance: should knowfreq 30%

basics

~20 s

Node ignores HTTP_PROXY and HTTPS_PROXY unless you opt in with NODE_USE_ENV_PROXY=1 or --use-env-proxy. Node 24 then routes fetch() and the global http and https agents through the proxy, honouring NO_PROXY; custom agents need a proxyEnv option.

open as a page

A Node 24 service calls an inventory API with fetch(), checks res.ok and never reads error bodies; sockets climb and calls slow down. Why, and what fixes it?

level: seniorimportance: should knowfreq 45%

basics

~20 s

An unread fetch() body can keep its connection busy until the Response is garbage-collected, so new calls open extra sockets or queue behind a cap. Consume every body or call res.body.cancel(); with http.request(), call res.resume().

open as a page

As the lead for Node 24 services that call payment and inventory APIs, which outbound HTTP client defaults would you standardise, and which built-in defaults would you refuse to inherit?

level: principalimportance: should knowfreq 25%

basics

~10 s

Standardise one client, explicit per-upstream connection caps, a mandatory per-call AbortSignal.timeout, a settle-every-body rule and environment-driven proxying. Refuse Node 24's unlimited per-origin pools and undici's 300-second header and body timers.

open as a page