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 e1c77130a26ac6..9ee3c1497397da 100644 --- a/doc/api/net.md +++ b/doc/api/net.md @@ -1380,11 +1380,76 @@ 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/disable keep-alive functionality, and optionally configure the +keepalive probe timing. Returns the socket itself. + +Possible signatures: + +* [`socket.setKeepAlive([options])`][`socket.setKeepAlive(options)`] +* [`socket.setKeepAlive([enable][, initialDelay][, interval][, count])`][`socket.setKeepAlive(enable)`] + +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 +`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 / 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.setKeepAlive([options])` + + + +* `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])`