From 5ab2a5ffdab1d6700505dc43a2d373241ca7f5fe Mon Sep 17 00:00:00 2001
From: jiho <jiho30125@gmail.com>
Date: Tue, 5 Aug 2025 04:20:19 +0900
Subject: [PATCH] http: add agent.keepAliveTimeoutBuffer option

---
 doc/api/http.md                               | 14 ++++++++++
 lib/_http_agent.js                            | 14 +++++++---
 ...est-http-agent-keepalive-timeout-buffer.js | 26 +++++++++++++++++++
 3 files changed, 50 insertions(+), 4 deletions(-)
 create mode 100644 test/parallel/test-http-agent-keepalive-timeout-buffer.js

diff --git a/doc/api/http.md b/doc/api/http.md
index 8aa2e45c8f1bb7..d8a51f69181bf3 100644
--- a/doc/api/http.md
+++ b/doc/api/http.md
@@ -414,6 +414,20 @@ changes:
 An object which contains arrays of sockets currently in use by the
 agent. Do not modify.
 
+### `agent.keepAliveTimeoutBuffer`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {number} Timeout in milliseconds. **Default:** `1000` (1 second).
+
+The buffer time that is subtracted from the server's keep-alive timeout value to reduce the likelihood of
+ECONNRESET errors. When a server sends a 'keep-alive' timeout hint in its response headers,
+the agent will subtract this buffer value from the hint to determine the actual socket timeout.
+
+This option only affects sockets that receive a keep-alive timeout hint from the server.
+
 ## Class: `http.ClientRequest`
 
 <!-- YAML
diff --git a/lib/_http_agent.js b/lib/_http_agent.js
index ddb6cd7d9a4c03..0c9f7ba8e8f7e3 100644
--- a/lib/_http_agent.js
+++ b/lib/_http_agent.js
@@ -50,6 +50,7 @@ const {
 } = require('internal/util');
 const {
   validateNumber,
+  validateInteger,
   validateOneOf,
   validateString,
 } = require('internal/validators');
@@ -60,8 +61,6 @@ const kOnKeylog = Symbol('onkeylog');
 const kRequestOptions = Symbol('requestOptions');
 const kRequestAsyncResource = Symbol('requestAsyncResource');
 
-// TODO(jazelly): make this configurable
-const HTTP_AGENT_KEEP_ALIVE_TIMEOUT_BUFFER = 1000;
 // New Agent code.
 
 // The largest departure from the previous implementation is that
@@ -114,6 +113,7 @@ function Agent(options) {
   this.scheduling = this.options.scheduling || 'lifo';
   this.maxTotalSockets = this.options.maxTotalSockets;
   this.totalSocketCount = 0;
+  this.keepAliveTimeoutBuffer = this.options.keepAliveTimeoutBuffer;
   const proxyEnv = this.options.proxyEnv;
   if (typeof proxyEnv === 'object' && proxyEnv !== null) {
     this[kProxyConfig] = parseProxyConfigFromEnv(proxyEnv, this.protocol, this.keepAlive);
@@ -128,6 +128,12 @@ function Agent(options) {
     this.maxTotalSockets = Infinity;
   }
 
+  if (this.keepAliveTimeoutBuffer !== undefined) {
+    validateInteger(this.keepAliveTimeoutBuffer, 'keepAliveTimeoutBuffer', 0);
+  } else {
+    this.keepAliveTimeoutBuffer = 1000;
+  }
+
   this.on('free', (socket, options) => {
     const name = this.getName(options);
     debug('agent.on(free)', name);
@@ -557,9 +563,9 @@ Agent.prototype.keepSocketAlive = function keepSocketAlive(socket) {
       const hint = /^timeout=(\d+)/.exec(keepAliveHint)?.[1];
 
       if (hint) {
-        // Let the timer expire before the announced timeout to reduce
+        // Let the timer expire before the announced timeout by the configured buffer to reduce
         // the likelihood of ECONNRESET errors
-        let serverHintTimeout = (NumberParseInt(hint) * 1000) - HTTP_AGENT_KEEP_ALIVE_TIMEOUT_BUFFER;
+        let serverHintTimeout = (NumberParseInt(hint) * 1000) - this.keepAliveTimeoutBuffer;
         serverHintTimeout = serverHintTimeout > 0 ? serverHintTimeout : 0;
         if (serverHintTimeout === 0) {
           // Cannot safely reuse the socket because the server timeout is
diff --git a/test/parallel/test-http-agent-keepalive-timeout-buffer.js b/test/parallel/test-http-agent-keepalive-timeout-buffer.js
new file mode 100644
index 00000000000000..68bfbeec263f82
--- /dev/null
+++ b/test/parallel/test-http-agent-keepalive-timeout-buffer.js
@@ -0,0 +1,26 @@
+'use strict';
+
+require('../common');
+const assert = require('assert');
+const { Agent } = require('http');
+
+{
+  const agent = new Agent({});
+  assert.strictEqual(agent.keepAliveTimeoutBuffer, 1000);
+}
+
+{
+  const buffer = 2500;
+  const agent = new Agent({ keepAliveTimeoutBuffer: buffer });
+  assert.strictEqual(agent.keepAliveTimeoutBuffer, buffer);
+}
+
+{
+  assert.throws(() => {
+    new Agent({ keepAliveTimeoutBuffer: -1 });
+  }, { code: 'ERR_OUT_OF_RANGE' });
+
+  assert.throws(() => {
+    new Agent({ keepAliveTimeoutBuffer: 'foo' });
+  }, { code: 'ERR_INVALID_ARG_TYPE' });
+}