From d432386f837751c36e34cdf8a62121c8c392cbe0 Mon Sep 17 00:00:00 2001 From: Luigi Pinca Date: Thu, 22 Apr 2021 19:13:08 +0200 Subject: [PATCH] doc: do not mention TCP in the allowHalfOpen option description The `allowHalfOpen` option works in the same way for both TCP and IPC connections. PR-URL: https://github.com/nodejs/node/pull/38360 Fixes: https://github.com/nodejs/node/issues/38307 Reviewed-By: Anna Henningsen Reviewed-By: James M Snell Reviewed-By: Rich Trott --- doc/api/net.md | 36 ++++++++++++++++++++---------------- doc/api/tls.md | 8 ++++---- 2 files changed, 24 insertions(+), 20 deletions(-) diff --git a/doc/api/net.md b/doc/api/net.md index 699b1ba4d573b8..e8c68c53477b27 100644 --- a/doc/api/net.md +++ b/doc/api/net.md @@ -551,9 +551,10 @@ changes: * `options` {Object} Available options are: * `fd` {number} If specified, wrap around an existing socket with the given file descriptor, otherwise a new socket will be created. - * `allowHalfOpen` {boolean} Indicates whether half-opened TCP connections - are allowed. See [`net.createServer()`][] and the [`'end'`][] event - for details. **Default:** `false`. + * `allowHalfOpen` {boolean} If set to `false`, then the socket will + automatically end the writable side when the readable side ends. See + [`net.createServer()`][] and the [`'end'`][] event for details. **Default:** + `false`. * `readable` {boolean} Allow reads on the socket when an `fd` is passed, otherwise ignored. **Default:** `false`. * `writable` {boolean} Allow writes on the socket when an `fd` is passed, @@ -612,14 +613,14 @@ See also: the return values of `socket.write()`. added: v0.1.90 --> -Emitted when the other end of the socket sends a FIN packet, thus ending the -readable side of the socket. +Emitted when the other end of the socket signals the end of transmission, thus +ending the readable side of the socket. -By default (`allowHalfOpen` is `false`) the socket will send a FIN packet -back and destroy its file descriptor once it has written out its pending -write queue. However, if `allowHalfOpen` is set to `true`, the socket will -not automatically [`end()`][`socket.end()`] its writable side, allowing the -user to write arbitrary amounts of data. The user must call +By default (`allowHalfOpen` is `false`) the socket will send an end of +transmission packet back and destroy its file descriptor once it has written out +its pending write queue. However, if `allowHalfOpen` is set to `true`, the +socket will not automatically [`end()`][`socket.end()`] its writable side, +allowing the user to write arbitrary amounts of data. The user must call [`end()`][`socket.end()`] explicitly to close the connection (i.e. sending a FIN packet back). @@ -1295,8 +1296,9 @@ added: v0.5.0 --> * `options` {Object} - * `allowHalfOpen` {boolean} Indicates whether half-opened TCP - connections are allowed. **Default:** `false`. + * `allowHalfOpen` {boolean} If set to `false`, then the socket will + automatically end the writable side when the readable side ends. + **Default:** `false`. * `pauseOnConnect` {boolean} Indicates whether the socket should be paused on incoming connections. **Default:** `false`. * `connectionListener` {Function} Automatically set as a listener for the @@ -1306,10 +1308,12 @@ added: v0.5.0 Creates a new TCP or [IPC][] server. If `allowHalfOpen` is set to `true`, when the other end of the socket -sends a FIN packet, the server will only send a FIN packet back when -[`socket.end()`][] is explicitly called, until then the connection is -half-closed (non-readable but still writable). See [`'end'`][] event -and [RFC 1122][half-closed] (section 4.2.2.13) for more information. +signals the end of transmission, the server will only send back the end of +transmission when [`socket.end()`][] is explicitly called. For example, in the +context of TCP, when a FIN packed is received, a FIN packed is sent +back only when [`socket.end()`][] is explicitly called. Until then the +connection is half-closed (non-readable but still writable). See [`'end'`][] +event and [RFC 1122][half-closed] (section 4.2.2.13) for more information. If `pauseOnConnect` is set to `true`, then the socket associated with each incoming connection will be paused, and no data will be read from its handle. diff --git a/doc/api/tls.md b/doc/api/tls.md index 432ffff8675c8e..d82ecf733d209d 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -1473,10 +1473,10 @@ changes: Connection/disconnection/destruction of `socket` is the user's responsibility; calling `tls.connect()` will not cause `net.connect()` to be called. - * `allowHalfOpen` {boolean} If the `socket` option is missing, indicates - whether or not to allow the internally created socket to be half-open, - otherwise the option is ignored. See the `allowHalfOpen` option of - [`net.Socket`][] for details. **Default:** `false`. + * `allowHalfOpen` {boolean} If set to `false`, then the socket will + automatically end the writable side when the readable side ends. If the + `socket` option is set, this option has no effect. See the `allowHalfOpen` + option of [`net.Socket`][] for details. **Default:** `false`. * `rejectUnauthorized` {boolean} If not `false`, the server certificate is verified against the list of supplied CAs. An `'error'` event is emitted if verification fails; `err.code` contains the OpenSSL error code. **Default:**