Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท HTTP, HTTPS, net, TLS, dgram and dns

Node.js http.Agent class

Reference for http.Agent in Node.js: connection pooling, keepAlive, maxSockets, the global agent, agent options, and how to inspect sockets in use.

An http.Agent manages the sockets used by HTTP client requests. When a request is made, the agent either hands it an idle socket to the same host and port or opens a new one, and it can limit how many sockets exist at once. With keep-alive enabled, finished sockets go back into a pool instead of being closed, which saves a TCP (and TLS) handshake per request.

Every http.request() uses the global agent, http.globalAgent, unless you pass agent in the options. Since Node.js 19 the global agent has keep-alive on. For fine control, create your own agent and share it across requests.

NODE
const agent = new http.Agent({ keepAlive: true, maxSockets: 10 });
http.get({ host: '127.0.0.1', port: 3000, agent }, (res) => res.resume());

Try it

Node.js Reusing one socket with keep-alive

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.

Node.js Limiting concurrency with maxSockets

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.

Syntax

NODE
new http.Agent([options])
Option Description
keepAlive Keep sockets open after a request finishes so later requests can reuse them. Default false for a new Agent, but true for http.globalAgent.
keepAliveMsecs Initial delay for TCP keep-alive probes on pooled sockets. Default 1000.
maxSockets Maximum concurrent sockets per host:port (origin). Default Infinity. Excess requests wait in a queue.
maxTotalSockets Maximum sockets across all origins. Default Infinity.
maxFreeSockets Maximum idle sockets kept per origin when keepAlive is on. Default 256.
scheduling 'lifo' (default, reuse the most recently freed socket) or 'fifo'.
timeout Socket timeout in milliseconds for sockets this agent creates.
agentKeepAliveTimeoutBuffer Milliseconds subtracted from the server's Keep-Alive: timeout= hint before an idle socket is dropped.

Properties and methods

Name Description
agent.sockets Object mapping an origin key to the array of sockets in use.
agent.freeSockets Same for idle pooled sockets.
agent.requests Requests waiting for a socket, by origin key.
agent.destroy() Closes all sockets. Do this when you are finished with a custom agent.
agent.getName(options) Returns the key string for an origin (host, port, local address, family).
agent.createConnection(options[, cb]) The function that makes the socket; override it for custom transports.
agent.keepSocketAlive(socket), agent.reuseSocket(socket, req) Hooks that decide what happens when a socket is released and reused.

Errors: a socket that the server closes while idle can raise ECONNRESET on the next request that reuses it; the request fails and you may retry if it is safe to repeat.

Usage notes

  • Pass agent: false to a request to give it a brand-new agent with default settings (no pooling), which sometimes helps when debugging connection reuse problems.
  • Keep-alive only helps if the server cooperates. The server must not close the connection after each response. Connection: close from the server disables reuse for that socket.
  • Always consume responses. A socket returns to the pool only after the response has been fully read (or the request destroyed). A forgotten response leaks a socket and, with maxSockets set, can stall every later request.
  • maxSockets queues, it does not fail. Waiting requests sit in agent.requests until a socket is free; that is a simple way to rate-limit fan-out.
  • Open pooled sockets keep the process alive. Idle keep-alive sockets are unreferenced in current Node versions, but destroy custom agents in tests and scripts anyway.
  • HTTPS has https.Agent, which extends this class with TLS options and also pools TLS sessions.
  • fetch() uses its own pool (undici) and ignores http.Agent; use an undici dispatcher to tune it.