http: add agent.keepAliveTimeoutBuffer option

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

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

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' });
+}