From e3f89067d837e00ad390d4f97f5ababc0df4a768 Mon Sep 17 00:00:00 2001
From: Guy Bedford <gbedford@cloudflare.com>
Date: Tue, 9 Jun 2026 15:33:52 -0700
Subject: [PATCH 1/2] net: support TCP_KEEPINTVL and TCP_KEEPCNT in
 setKeepAlive

Signed-off-by: Guy Bedford <guybedford@gmail.com>
---
 doc/api/net.md                                | 30 ++++++++--
 lib/internal/net.js                           |  2 +
 lib/net.js                                    | 21 +++++--
 src/tcp_wrap.cc                               |  9 ++-
 .../test-net-keepalive-interval-count.js      | 56 +++++++++++++++++++
 5 files changed, 109 insertions(+), 9 deletions(-)
 create mode 100644 test/parallel/test-net-keepalive-interval-count.js

diff --git a/doc/api/net.md b/doc/api/net.md
index e1c77130a26ac6..6e35b33d5e79d3 100644
--- a/doc/api/net.md
+++ b/doc/api/net.md
@@ -1380,11 +1380,15 @@ added: v0.1.90
 Set the encoding for the socket as a [Readable Stream][]. See
 [`readable.setEncoding()`][] for more information.
 
-### `socket.setKeepAlive([enable][, initialDelay])`
+### `socket.setKeepAlive([enable][, initialDelay][, interval][, count])`
 
 <!-- YAML
 added: v0.1.92
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/63825
+    description: Added the `interval` and `count` arguments to configure
+                 `TCP_KEEPINTVL` and `TCP_KEEPCNT`.
   - version:
     - v13.12.0
     - v12.17.0
@@ -1394,6 +1398,8 @@ changes:
 
 * `enable` {boolean} **Default:** `false`
 * `initialDelay` {number} **Default:** `0`
+* `interval` {number} **Default:** `1000`
+* `count` {number} **Default:** `10`
 * Returns: {net.Socket} The socket itself.
 
 Enable/disable keep-alive functionality, and optionally set the initial
@@ -1404,12 +1410,28 @@ data packet received and the first keepalive probe. Setting `0` for
 `initialDelay` will leave the value unchanged from the default
 (or previous) setting.
 
+Set `interval` (in milliseconds) to set the delay between successive
+keepalive probes once they begin (`TCP_KEEPINTVL`). Set `count` to the
+number of unacknowledged probes sent before the connection is dropped
+(`TCP_KEEPCNT`). Both are only applied when keep-alive is enabled.
+Omitting `interval` or `count` uses the defaults of `1000` ms and `10`.
+As with `initialDelay`, a non-positive `interval` or `count` leaves the
+corresponding system default unchanged.
+
+`initialDelay` and `interval` are specified in milliseconds but the
+underlying socket options are configured in whole seconds; the values are
+divided by `1000` and rounded down before being applied.
+
 Enabling the keep-alive functionality will set the following socket options:
 
 * `SO_KEEPALIVE=1`
-* `TCP_KEEPIDLE=initialDelay`
-* `TCP_KEEPCNT=10`
-* `TCP_KEEPINTVL=1`
+* `TCP_KEEPIDLE=initialDelay / 1000`
+* `TCP_KEEPCNT=count`
+* `TCP_KEEPINTVL=interval / 1000`
+
+On Windows versions older than build 1709, keep-alive is configured through
+`SIO_KEEPALIVE_VALS`, which has no probe-count field, so `count` is ignored on
+those platforms.
 
 ### `socket.setNoDelay([noDelay])`
 
diff --git a/lib/internal/net.js b/lib/internal/net.js
index 80de67791512e4..cea3dda23d6176 100644
--- a/lib/internal/net.js
+++ b/lib/internal/net.js
@@ -103,6 +103,8 @@ module.exports = {
   kSetNoDelay: Symbol('kSetNoDelay'),
   kSetKeepAlive: Symbol('kSetKeepAlive'),
   kSetKeepAliveInitialDelay: Symbol('kSetKeepAliveInitialDelay'),
+  kSetKeepAliveInterval: Symbol('kSetKeepAliveInterval'),
+  kSetKeepAliveCount: Symbol('kSetKeepAliveCount'),
   isIP,
   isIPv4,
   isIPv6,
diff --git a/lib/net.js b/lib/net.js
index efd2029fb67ddd..cb484ae7d4a854 100644
--- a/lib/net.js
+++ b/lib/net.js
@@ -51,6 +51,8 @@ const {
   kSetNoDelay,
   kSetKeepAlive,
   kSetKeepAliveInitialDelay,
+  kSetKeepAliveInterval,
+  kSetKeepAliveCount,
   isIP,
   isIPv4,
   isIPv6,
@@ -629,13 +631,18 @@ Socket.prototype.setNoDelay = function(enable) {
 };
 
 
-Socket.prototype.setKeepAlive = function(enable, initialDelayMsecs) {
+Socket.prototype.setKeepAlive = function(enable, initialDelayMsecs,
+                                         intervalMsecs, count) {
   enable = Boolean(enable);
   const initialDelay = ~~(initialDelayMsecs / 1000);
+  const interval = intervalMsecs === undefined ?
+    undefined : ~~(intervalMsecs / 1000);
 
   if (!this._handle) {
     this[kSetKeepAlive] = enable;
     this[kSetKeepAliveInitialDelay] = initialDelay;
+    this[kSetKeepAliveInterval] = interval;
+    this[kSetKeepAliveCount] = count;
     return this;
   }
 
@@ -646,12 +653,16 @@ Socket.prototype.setKeepAlive = function(enable, initialDelayMsecs) {
   if (enable !== this[kSetKeepAlive] ||
       (
         enable &&
-        this[kSetKeepAliveInitialDelay] !== initialDelay
+        (this[kSetKeepAliveInitialDelay] !== initialDelay ||
+         this[kSetKeepAliveInterval] !== interval ||
+         this[kSetKeepAliveCount] !== count)
       )
   ) {
     this[kSetKeepAlive] = enable;
     this[kSetKeepAliveInitialDelay] = initialDelay;
-    this._handle.setKeepAlive(enable, initialDelay);
+    this[kSetKeepAliveInterval] = interval;
+    this[kSetKeepAliveCount] = count;
+    this._handle.setKeepAlive(enable, initialDelay, interval, count);
   }
 
   return this;
@@ -1675,7 +1686,9 @@ function afterConnect(status, handle, req, readable, writable) {
     }
 
     if (self[kSetKeepAlive] && self._handle.setKeepAlive) {
-      self._handle.setKeepAlive(true, self[kSetKeepAliveInitialDelay]);
+      self._handle.setKeepAlive(true, self[kSetKeepAliveInitialDelay],
+                                self[kSetKeepAliveInterval],
+                                self[kSetKeepAliveCount]);
     }
 
     if (self[kSetTOS] !== undefined && self._handle.setTypeOfService) {
diff --git a/src/tcp_wrap.cc b/src/tcp_wrap.cc
index 466b0f8938c699..1abf0d6d83e349 100644
--- a/src/tcp_wrap.cc
+++ b/src/tcp_wrap.cc
@@ -209,7 +209,14 @@ void TCPWrap::SetKeepAlive(const FunctionCallbackInfo<Value>& args) {
   int enable;
   if (!args[0]->Int32Value(env->context()).To(&enable)) return;
   unsigned int delay = static_cast<unsigned int>(args[1].As<Uint32>()->Value());
-  int err = uv_tcp_keepalive(&wrap->handle_, enable, delay);
+  // interval and count are optional. Fall back to the libuv defaults
+  // (1 second, 10 probes) when they are not provided so that callers using
+  // the legacy two-argument form of this handle method keep working.
+  unsigned int interval = 1;
+  unsigned int count = 10;
+  if (args[2]->IsUint32()) interval = args[2].As<Uint32>()->Value();
+  if (args[3]->IsUint32()) count = args[3].As<Uint32>()->Value();
+  int err = uv_tcp_keepalive_ex(&wrap->handle_, enable, delay, interval, count);
   args.GetReturnValue().Set(err);
 }
 
diff --git a/test/parallel/test-net-keepalive-interval-count.js b/test/parallel/test-net-keepalive-interval-count.js
new file mode 100644
index 00000000000000..bd4b7f7af06112
--- /dev/null
+++ b/test/parallel/test-net-keepalive-interval-count.js
@@ -0,0 +1,56 @@
+'use strict';
+
+const common = require('../common');
+const assert = require('assert');
+const net = require('net');
+
+// Verifies that setKeepAlive() forwards the keepalive probe interval
+// (TCP_KEEPINTVL) and probe count (TCP_KEEPCNT) to the handle. The interval is
+// converted from milliseconds to whole seconds, mirroring the initialDelay
+// handling and uv_tcp_keepalive_ex().
+
+// Explicit setKeepAlive(enable, initialDelay, interval, count) forwards all
+// four values, converting milliseconds to seconds for the delays.
+{
+  const server = net.createServer();
+  server.listen(0, common.mustCall(() => {
+    const client = net.connect(
+      { port: server.address().port },
+      common.mustCall(() => {
+        client._handle.setKeepAlive = common.mustCall(
+          (enable, delay, interval, count) => {
+            assert.strictEqual(enable, true);
+            assert.strictEqual(delay, 5);
+            assert.strictEqual(interval, 10);
+            assert.strictEqual(count, 9);
+          });
+        client.setKeepAlive(true, 5000, 10000, 9);
+        client.end();
+      }));
+
+    client.on('end', common.mustCall(() => server.close()));
+  }));
+}
+
+// Omitting interval/count passes undefined through; the handle applies the
+// libuv defaults (1s interval, 10 probes).
+{
+  const server = net.createServer();
+  server.listen(0, common.mustCall(() => {
+    const client = net.connect(
+      { port: server.address().port },
+      common.mustCall(() => {
+        client._handle.setKeepAlive = common.mustCall(
+          (enable, delay, interval, count) => {
+            assert.strictEqual(enable, true);
+            assert.strictEqual(delay, 5);
+            assert.strictEqual(interval, undefined);
+            assert.strictEqual(count, undefined);
+          });
+        client.setKeepAlive(true, 5000);
+        client.end();
+      }));
+
+    client.on('end', common.mustCall(() => server.close()));
+  }));
+}

From 2f3323944e40760f8e96117960d39c44b80e0322 Mon Sep 17 00:00:00 2001
From: Guy Bedford <gbedford@cloudflare.com>
Date: Fri, 12 Jun 2026 14:58:47 -0700
Subject: [PATCH 2/2] add options bag variant

---
 doc/api/http.md                               |  4 +-
 doc/api/net.md                                | 79 +++++++++++++------
 lib/net.js                                    |  7 ++
 .../test-net-keepalive-interval-count.js      | 50 ++++++++++++
 4 files changed, 116 insertions(+), 24 deletions(-)

diff --git a/doc/api/http.md b/doc/api/http.md
index e7aaa04d79e299..76950b95f8c5de 100644
--- a/doc/api/http.md
+++ b/doc/api/http.md
@@ -3763,7 +3763,7 @@ changes:
     **Default:** `false`.
   * `keepAlive` {boolean} If set to `true`, it enables keep-alive functionality
     on the socket immediately after a new incoming connection is received,
-    similarly on what is done in \[`socket.setKeepAlive([enable][, initialDelay])`]\[`socket.setKeepAlive(enable, initialDelay)`].
+    similarly on what is done in [`socket.setKeepAlive()`][].
     **Default:** `false`.
   * `keepAliveInitialDelay` {number} If set to a positive number, it sets the
     initial delay before the first keepalive probe is sent on an idle socket.
@@ -4779,7 +4779,7 @@ const agent2 = new http.Agent({ proxyEnv: process.env });
 [`server.timeout`]: #servertimeout
 [`setHeader(name, value)`]: #requestsetheadername-value
 [`socket.connect()`]: net.md#socketconnectoptions-connectlistener
-[`socket.setKeepAlive()`]: net.md#socketsetkeepaliveenable-initialdelay
+[`socket.setKeepAlive()`]: net.md#socketsetkeepalive
 [`socket.setNoDelay()`]: net.md#socketsetnodelaynodelay
 [`socket.setTimeout()`]: net.md#socketsettimeouttimeout-callback
 [`socket.unref()`]: net.md#socketunref
diff --git a/doc/api/net.md b/doc/api/net.md
index 6e35b33d5e79d3..9ee3c1497397da 100644
--- a/doc/api/net.md
+++ b/doc/api/net.md
@@ -1380,30 +1380,18 @@ added: v0.1.90
 Set the encoding for the socket as a [Readable Stream][]. See
 [`readable.setEncoding()`][] for more information.
 
-### `socket.setKeepAlive([enable][, initialDelay][, interval][, count])`
+### `socket.setKeepAlive()`
 
-<!-- YAML
-added: v0.1.92
-changes:
-  - version: REPLACEME
-    pr-url: https://github.com/nodejs/node/pull/63825
-    description: Added the `interval` and `count` arguments to configure
-                 `TCP_KEEPINTVL` and `TCP_KEEPCNT`.
-  - version:
-    - v13.12.0
-    - v12.17.0
-    pr-url: https://github.com/nodejs/node/pull/32204
-    description: New defaults for `TCP_KEEPCNT` and `TCP_KEEPINTVL` socket options were added.
--->
+Enable/disable keep-alive functionality, and optionally configure the
+keepalive probe timing. Returns the socket itself.
 
-* `enable` {boolean} **Default:** `false`
-* `initialDelay` {number} **Default:** `0`
-* `interval` {number} **Default:** `1000`
-* `count` {number} **Default:** `10`
-* Returns: {net.Socket} The socket itself.
+Possible signatures:
+
+* [`socket.setKeepAlive([options])`][`socket.setKeepAlive(options)`]
+* [`socket.setKeepAlive([enable][, initialDelay][, interval][, count])`][`socket.setKeepAlive(enable)`]
 
-Enable/disable keep-alive functionality, and optionally set the initial
-delay before the first keepalive probe is sent on an idle socket.
+Enabling keep-alive sets the initial delay before the first keepalive probe is
+sent on an idle socket.
 
 Set `initialDelay` (in milliseconds) to set the delay between the last
 data packet received and the first keepalive probe. Setting `0` for
@@ -1433,6 +1421,51 @@ On Windows versions older than build 1709, keep-alive is configured through
 `SIO_KEEPALIVE_VALS`, which has no probe-count field, so `count` is ignored on
 those platforms.
 
+#### `socket.setKeepAlive([options])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `options` {Object}
+  * `enable` {boolean} **Default:** `false`
+  * `initialDelay` {number} **Default:** `0`
+  * `interval` {number} **Default:** `1000`
+  * `count` {number} **Default:** `10`
+* Returns: {net.Socket} The socket itself.
+
+Configure keep-alive using an options object. See [`socket.setKeepAlive()`][]
+for a description of each property.
+
+```js
+socket.setKeepAlive({ enable: true, initialDelay: 1000, interval: 1000, count: 10 });
+```
+
+#### `socket.setKeepAlive([enable][, initialDelay][, interval][, count])`
+
+<!-- YAML
+added: v0.1.92
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/63825
+    description: Added the `interval` and `count` arguments to configure
+                 `TCP_KEEPINTVL` and `TCP_KEEPCNT`.
+  - version:
+    - v13.12.0
+    - v12.17.0
+    pr-url: https://github.com/nodejs/node/pull/32204
+    description: New defaults for `TCP_KEEPCNT` and `TCP_KEEPINTVL` socket options were added.
+-->
+
+* `enable` {boolean} **Default:** `false`
+* `initialDelay` {number} **Default:** `0`
+* `interval` {number} **Default:** `1000`
+* `count` {number} **Default:** `10`
+* Returns: {net.Socket} The socket itself.
+
+Configure keep-alive using positional arguments. See
+[`socket.setKeepAlive()`][] for a description of each argument.
+
 ### `socket.setNoDelay([noDelay])`
 
 <!-- YAML
@@ -2102,7 +2135,9 @@ net.isIPv6('fhqwhgads'); // returns false
 [`socket.pause()`]: #socketpause
 [`socket.resume()`]: #socketresume
 [`socket.setEncoding()`]: #socketsetencodingencoding
-[`socket.setKeepAlive()`]: #socketsetkeepaliveenable-initialdelay
+[`socket.setKeepAlive()`]: #socketsetkeepalive
+[`socket.setKeepAlive(enable)`]: #socketsetkeepaliveenable-initialdelay-interval-count
+[`socket.setKeepAlive(options)`]: #socketsetkeepaliveoptions
 [`socket.setTimeout()`]: #socketsettimeouttimeout-callback
 [`socket.setTimeout(timeout)`]: #socketsettimeouttimeout-callback
 [`stream.getDefaultHighWaterMark()`]: stream.md#streamgetdefaulthighwatermarkobjectmode
diff --git a/lib/net.js b/lib/net.js
index cb484ae7d4a854..ee4bc9943e4d52 100644
--- a/lib/net.js
+++ b/lib/net.js
@@ -633,6 +633,13 @@ Socket.prototype.setNoDelay = function(enable) {
 
 Socket.prototype.setKeepAlive = function(enable, initialDelayMsecs,
                                          intervalMsecs, count) {
+  if (enable !== null && typeof enable === 'object') {
+    const options = enable;
+    enable = options.enable;
+    initialDelayMsecs = options.initialDelay;
+    intervalMsecs = options.interval;
+    count = options.count;
+  }
   enable = Boolean(enable);
   const initialDelay = ~~(initialDelayMsecs / 1000);
   const interval = intervalMsecs === undefined ?
diff --git a/test/parallel/test-net-keepalive-interval-count.js b/test/parallel/test-net-keepalive-interval-count.js
index bd4b7f7af06112..eda3fe6dd51117 100644
--- a/test/parallel/test-net-keepalive-interval-count.js
+++ b/test/parallel/test-net-keepalive-interval-count.js
@@ -54,3 +54,53 @@ const net = require('net');
     client.on('end', common.mustCall(() => server.close()));
   }));
 }
+
+// An options object as the first argument is equivalent to the positional
+// form, forwarding enable/initialDelay/interval/count to the handle.
+{
+  const server = net.createServer();
+  server.listen(0, common.mustCall(() => {
+    const client = net.connect(
+      { port: server.address().port },
+      common.mustCall(() => {
+        client._handle.setKeepAlive = common.mustCall(
+          (enable, delay, interval, count) => {
+            assert.strictEqual(enable, true);
+            assert.strictEqual(delay, 5);
+            assert.strictEqual(interval, 10);
+            assert.strictEqual(count, 9);
+          });
+        client.setKeepAlive({
+          enable: true,
+          initialDelay: 5000,
+          interval: 10000,
+          count: 9,
+        });
+        client.end();
+      }));
+
+    client.on('end', common.mustCall(() => server.close()));
+  }));
+}
+
+// Omitted options properties behave like omitted positional arguments.
+{
+  const server = net.createServer();
+  server.listen(0, common.mustCall(() => {
+    const client = net.connect(
+      { port: server.address().port },
+      common.mustCall(() => {
+        client._handle.setKeepAlive = common.mustCall(
+          (enable, delay, interval, count) => {
+            assert.strictEqual(enable, true);
+            assert.strictEqual(delay, 5);
+            assert.strictEqual(interval, undefined);
+            assert.strictEqual(count, undefined);
+          });
+        client.setKeepAlive({ enable: true, initialDelay: 5000 });
+        client.end();
+      }));
+
+    client.on('end', common.mustCall(() => server.close()));
+  }));
+}