Understanding http Agent timeout

[meghamishra]

Node.js Version

v20.19.0

NPM Version

v10.8.2

Operating System

Darwin kernel version 24.5.0

Subsystem

tls, https, Other

Description

I’m building a Node.js HTTP client that needs to:

• Use mutual TLS (mTLS)
• Enable keep-alive, so sockets are reused across requests.
• Set a keep-alive idle timeout to automatically close unused sockets after a period of inactivity

I'd like to configure this once using a single shared https.Agent instance and pass it to the global HTTP module (e.g., via Axios or NestJS HttpModule) so that all outbound requests automatically use this agent

While reviewing the Node.js documentation, I came across this line for the timeout option:

"Socket timeout in milliseconds. This will set the timeout when the socket is created." This is not clear to me.

I’m confused on a few things and would appreciate any guidance or clarification on this setup :

• What does it mean by Socket timeout and why does it say "when the socket is created" specifically?
• Also Is this the right way if I want to set it once and share across requests/modules?

Code Snippet for reference:

import { Agent } from 'https';
import * as fs from 'fs';

const httpsAgent = new Agent({
  keepAlive: true,
  key: fs.readFileSync('client.key'),
  cert: fs.readFileSync('client.crt'),
  passphrase: 'passphrase',
  timeout: 5000
});

HttpModule.register({
  httpsAgent,
});

Minimal Reproduction

No response

Output

No response

Before You Submit

• [x] I have looked for issues that already exist before submitting this
• [x] My issue follows the guidelines in the README file, and follows the 'How to ask a good question' guide at https://stackoverflow.com/help/how-to-ask

[nam-nguyen-clv]

I have the same question as @meghamishra, especially in agent.freeSockets section a few rows below, it mentions timeout as:

Sockets in the freeSockets list will be automatically destroyed and removed from the array on 'timeout'.

So, is this agent.freeSockets timeout the same as new Agent({timeout: xxx}) 🤔 ???

[sidneip]

I understood that

new Agent({timeout: xxx})

is the same thing that, executed after created, it means each connection opened by agent is monitored by ticker if nothing traffic during the interval the socket will emit 'timeout' event.

socket.setTimeout(timeout

When you enable ⁠keepAlive, sockets that finish a request aren’t closed immediately—they move into ⁠agent.freeSockets so future requests can reuse them.
 • Those sockets keep the very same timeout you set earlier. The timer doesn’t reset just because the socket became “free”.

If the timeout elapses while a socket is idle in ⁠freeSockets, it still emits ⁠'timeout', and the agent automatically destroys and removes it from the pool.
 • So there’s no extra configuration needed: the single ⁠timeout you pass to the agent governs both active sockets and idle sockets waiting to be reused.