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

• I have looked for issues that already exist before submitting this
• 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