From 20b99ac51e337ddcf3338839cf59a8c60316641a Mon Sep 17 00:00:00 2001 From: ankitsyadav Date: Thu, 19 Feb 2026 11:53:08 +0530 Subject: [PATCH] doc: clarify keepAlive and keepAliveTimeout semantics Clarify that the keepAlive option enables TCP keepalive and does not control HTTP persistent connections. Also clarify that keepAliveTimeout = 0 disables the timeout rather than HTTP keep-alive itself. Fixes: #61850 --- doc/api/http.md | 10 ++++++---- doc/api/net.md | 7 ++++--- 2 files changed, 10 insertions(+), 7 deletions(-) diff --git a/doc/api/http.md b/doc/api/http.md index d9fcd80215703e..4b0e8ff20d9ac2 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -2013,10 +2013,12 @@ socketTimeout = keepAliveTimeout + keepAliveTimeoutBuffer If the server receives new data before the keep-alive timeout has fired, it will reset the regular inactivity timeout, i.e., [`server.timeout`][]. -A value of `0` will disable the keep-alive timeout behavior on incoming -connections. -A value of `0` makes the HTTP server behave similarly to Node.js versions prior -to 8.0.0, which did not have a keep-alive timeout. +A value of `0` disables the keep-alive timeout. HTTP persistent +connections remain enabled and will stay open until closed by the +client or the server. + +Disabling the timeout may increase resource usage, as idle connections +can remain open indefinitely. The socket timeout logic is set up on connection, so changing this value only affects new connections to the server, not any existing connections. diff --git a/doc/api/net.md b/doc/api/net.md index f8cd3ccf8d3c40..ffef235343a1f4 100644 --- a/doc/api/net.md +++ b/doc/api/net.md @@ -767,9 +767,10 @@ changes: access to specific IP addresses, IP ranges, or IP subnets. * `fd` {number} If specified, wrap around an existing socket with the given file descriptor, otherwise a new socket will be created. - * `keepAlive` {boolean} If set to `true`, it enables keep-alive functionality on - the socket immediately after the connection is established, similarly on what - is done in [`socket.setKeepAlive()`][]. **Default:** `false`. + * `keepAlive` {boolean} If set to `true`, TCP keepalive is enabled on the + socket immediately after the connection is established, equivalent to + calling [`socket.setKeepAlive()`][]. If set to `false`, TCP keepalive is + not enabled automatically. **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. **Default:** `0`. * `noDelay` {boolean} If set to `true`, it disables the use of Nagle's algorithm