From 55e6663d933607910edcf8d4363604e2e6d1c867 Mon Sep 17 00:00:00 2001 From: Jesse O'Connor Date: Mon, 28 Oct 2019 16:47:07 +0100 Subject: [PATCH 01/25] doc: update http.md mention of socket This commit is addressing the problem in issue #29948 --- doc/api/http.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/api/http.md b/doc/api/http.md index 0807cc09d08b58..22d10ff25200f2 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -473,7 +473,9 @@ added: v0.5.3 * `socket` {net.Socket} -Emitted after a socket is assigned to this request. +Emitted after a socket is assigned to this request. This event is sometimes passed +a `duplex` {stream.Duplex} which `socket` {net.Socket} extends rather than being +passed a socket. ### Event: 'timeout' -* `socket` {net.Socket} +* `duplex` {stream.Duplex} -Emitted after a socket is assigned to this request. This event is sometimes -passed a `duplex` {stream.Duplex} which `socket` {net.Socket} extends rather -than being passed a socket. +Emitted after a socket is assigned to this request. This event may be passed +a socket {net.Socket} object, an extendion the duplex object, however this +behavior is not guaranteed. ### Event: 'timeout' -* `socket` {net.Socket} +* `duplex` {stream.Duplex} -Called when `socket` is detached from a request and could be persisted by the +Called when socket is detached from a request and could be persisted by the `Agent`. Default behavior is to: ```js @@ -185,6 +185,10 @@ socket.unref(); return true; ``` +This event is guaranteed to be passed an instance of the {net.Socket} class, +a subclass of Duplex, unless the user specifies a socket type other than +{net.Socket}. + This method can be overridden by a particular `Agent` subclass. If this method returns a falsy value, the socket will be destroyed instead of persisting it for use with the next request. From 094d513da8e997f84012f94e8253ace9271b2c19 Mon Sep 17 00:00:00 2001 From: Jesse O'Connor macPro2019 Date: Thu, 31 Oct 2019 01:19:54 +0100 Subject: [PATCH 07/25] doc: update the events on Agent first --- doc/api/http.md | 30 +++++++++++++++++------------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/doc/api/http.md b/doc/api/http.md index 31db19074be3ba..c6df23c3bf5965 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -169,14 +169,14 @@ socket/stream from this function, or by passing the socket/stream to `callback`. `callback` has a signature of `(err, stream)`. -### agent.keepSocketAlive(duplex) +### agent.keepSocketAlive(socket) -* `duplex` {stream.Duplex} +* `socket` {net.Socket} -Called when socket is detached from a request and could be persisted by the +Called when `socket` is detached from a request and could be persisted by the `Agent`. Default behavior is to: ```js @@ -185,10 +185,6 @@ socket.unref(); return true; ``` -This event is guaranteed to be passed an instance of the {net.Socket} class, -a subclass of Duplex, unless the user specifies a socket type other than -{net.Socket}. - This method can be overridden by a particular `Agent` subclass. If this method returns a falsy value, the socket will be destroyed instead of persisting it for use with the next request. @@ -345,13 +341,17 @@ added: v0.7.0 --> * `response` {http.IncomingMessage} -* `socket` {net.Socket} +* `duplex` {stream.Duplex} * `head` {Buffer} Emitted each time a server responds to a request with a `CONNECT` method. If this event is not being listened for, clients receiving a `CONNECT` method will have their connections closed. +This event is guaranteed to be passed an instance of the {net.Socket} class, +a subclass of Duplex, instead of Duplex unless the user specifies a socket +type other than {net.Socket}. + A client and server pair demonstrating how to listen for the `'connect'` event: ```js @@ -477,9 +477,9 @@ added: v0.5.3 * `duplex` {stream.Duplex} -Emitted after a socket is assigned to this request. This event is guaranteed to -be passed an instance of the {net.Socket} class, a subclass of Duplex, unless -the user specifies a socket type other than {net.Socket}. +This event is guaranteed to be passed an instance of the {net.Socket} class, +a subclass of Duplex, instead of Duplex unless the user specifies a socket +type other than {net.Socket}. ### Event: 'timeout' * `response` {http.IncomingMessage} -* `socket` {net.Socket} +* `duplex` {stream.Duplex} * `head` {Buffer} Emitted each time a server responds to a request with an upgrade. If this @@ -941,13 +941,17 @@ changes: --> * `exception` {Error} -* `socket` {net.Socket} +* `duplex` {stream.Duplex} If a client connection emits an `'error'` event, it will be forwarded here. Listener of this event is responsible for closing/destroying the underlying socket. For example, one may wish to more gracefully close the socket with a custom HTTP response instead of abruptly severing the connection. +This event is guaranteed to be passed an instance of the {net.Socket} class, +a subclass of Duplex, instead of Duplex unless the user specifies a socket +type other than {net.Socket}. + Default behavior is to try close the socket with a HTTP '400 Bad Request', or a HTTP '431 Request Header Fields Too Large' in the case of a [`HPE_HEADER_OVERFLOW`][] error. If the socket is not writable it is From e54b9e9a2949efba4323b500423d9a69e8fd6dc7 Mon Sep 17 00:00:00 2001 From: Jesse O'Connor macPro2019 Date: Thu, 31 Oct 2019 01:33:41 +0100 Subject: [PATCH 08/25] fix: update rest of events --- doc/api/http.md | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/doc/api/http.md b/doc/api/http.md index c6df23c3bf5965..4f41070580d60c 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -996,13 +996,17 @@ added: v0.7.0 * `request` {http.IncomingMessage} Arguments for the HTTP request, as it is in the [`'request'`][] event -* `socket` {net.Socket} Network socket between the server and client +* `duplex` {stream.Duplex} Network socket between the server and client * `head` {Buffer} The first packet of the tunneling stream (may be empty) Emitted each time a client requests an HTTP `CONNECT` method. If this event is not listened for, then clients requesting a `CONNECT` method will have their connections closed. +This event is guaranteed to be passed an instance of the {net.Socket} class, +a subclass of Duplex, instead of Duplex unless the user specifies a socket +type other than {net.Socket}. + After this event is emitted, the request's socket will not have a `'data'` event listener, meaning it will need to be bound in order to handle data sent to the server on that socket. @@ -1012,7 +1016,7 @@ sent to the server on that socket. added: v0.1.0 --> -* `socket` {net.Socket} +* `duplex` {stream.Duplex} This event is emitted when a new TCP stream is established. `socket` is typically an object of type [`net.Socket`][]. Usually users will not want to @@ -1027,6 +1031,10 @@ If `socket.setTimeout()` is called here, the timeout will be replaced with `server.keepAliveTimeout` when the socket has served a request (if `server.keepAliveTimeout` is non-zero). +This event is guaranteed to be passed an instance of the {net.Socket} class, +a subclass of Duplex, instead of Duplex unless the user specifies a socket +type other than {net.Socket}. + ### Event: 'request' -* `socket` {net.Socket} +* `socket` {stream.Duplex} Called when `socket` is detached from a request and could be persisted by the `Agent`. Default behavior is to: @@ -189,15 +193,15 @@ This method can be overridden by a particular `Agent` subclass. If this method returns a falsy value, the socket will be destroyed instead of persisting it for use with the next request. -The `socket` argument can be an instance of {stream.Duplex}, a superclass of -Socket. +The `socket` argument can be an instance of {net.Socket}, a subclass of +{stream.Duplex}. ### agent.reuseSocket(socket, request) -* `socket` {net.Socket} +* `socket` {stream.Duplex} * `request` {http.ClientRequest} Called when `socket` is attached to `request` after being persisted because of @@ -209,8 +213,8 @@ socket.ref(); This method can be overridden by a particular `Agent` subclass. -The `socket` argument can be an instance of {stream.Duplex}, a superclass of -Socket. +The `socket` argument can be an instance of {net.Socket}, a subclass of +{stream.Duplex}. ### agent.destroy() * `response` {http.IncomingMessage} -* `duplex` {stream.Duplex} +* `socket` {stream.Duplex} * `head` {Buffer} Emitted each time a server responds to a request with a `CONNECT` method. If @@ -481,7 +485,7 @@ once. added: v0.5.3 --> -* `duplex` {stream.Duplex} +* `socket` {stream.Duplex} This event is guaranteed to be passed an instance of the {net.Socket} class, a subclass of {stream.Duplex}, unless the user specifies a socket @@ -503,7 +507,7 @@ added: v0.1.94 --> * `response` {http.IncomingMessage} -* `duplex` {stream.Duplex} +* `socket` {stream.Duplex} * `head` {Buffer} Emitted each time a server responds to a request with an upgrade. If this @@ -588,7 +592,7 @@ deprecated: v13.0.0 > Stability: 0 - Deprecated. Use [`request.socket`][]. -* {net.Socket} +* {stream.Duplex} See [`request.socket`][]. @@ -816,7 +820,7 @@ Once a socket is assigned to this request and is connected added: v0.3.0 --> -* {net.Socket} +* {stream.Duplex} Reference to the underlying socket. Usually users will not want to access this property. In particular, the socket will not emit `'readable'` events @@ -838,7 +842,9 @@ req.once('response', (res) => { }); ``` -Socket argument can be an instance of {stream.Duplex}, a superclass of Socket. +This property is guaranteed to be an instance of the {net.Socket} class, +a subclass of {stream.Duplex}, unless the user specified a socket +type other than {net.Socket}. ### request.writableEnded * `exception` {Error} -* `duplex` {stream.Duplex} +* `socket` {stream.Duplex} If a client connection emits an `'error'` event, it will be forwarded here. Listener of this event is responsible for closing/destroying the underlying @@ -1008,7 +1014,7 @@ added: v0.7.0 * `request` {http.IncomingMessage} Arguments for the HTTP request, as it is in the [`'request'`][] event -* `duplex` {stream.Duplex} Network socket between the server and client +* `socket` {stream.Duplex} Network socket between the server and client * `head` {Buffer} The first packet of the tunneling stream (may be empty) Emitted each time a client requests an HTTP `CONNECT` method. If this event is @@ -1028,7 +1034,7 @@ sent to the server on that socket. added: v0.1.0 --> -* `duplex` {stream.Duplex} +* `socket` {stream.Duplex} This event is emitted when a new TCP stream is established. `socket` is typically an object of type [`net.Socket`][]. Usually users will not want to @@ -1070,7 +1076,7 @@ changes: * `request` {http.IncomingMessage} Arguments for the HTTP request, as it is in the [`'request'`][] event -* `duplex` {stream.Duplex} Network socket between the server and client +* `socket` {stream.Duplex} Network socket between the server and client * `head` {Buffer} The first packet of the upgraded stream (may be empty) Emitted each time a client requests an HTTP upgrade. Listening to this event @@ -1261,7 +1267,7 @@ deprecated: v13.0.0 > Stability: 0 - Deprecated. Use [`response.socket`][]. -* {net.Socket} +* {stream.Duplex} See [`response.socket`][]. @@ -1496,7 +1502,7 @@ timed out sockets must be handled explicitly. added: v0.3.0 --> -* {net.Socket} +* {stream.Duplex} Reference to the underlying socket. Usually users will not want to access this property. In particular, the socket will not emit `'readable'` events @@ -1513,7 +1519,9 @@ const server = http.createServer((req, res) => { }).listen(3000); ``` -Socket argument can be an instance of {stream.Duplex}, a superclass of Socket. +This property is guaranteed to be an instance of the {net.Socket} class, +a subclass of {stream.Duplex}, unless the user specified a socket +type other than {net.Socket}. ### response.statusCode -* {net.Socket} +* {stream.Duplex} The [`net.Socket`][] object associated with the connection. With HTTPS support, use [`request.socket.getPeerCertificate()`][] to obtain the client's authentication details. -Socket argument can be an instance of {stream.Duplex}, a superclass of Socket. +This property is guaranteed to be an instance of the {net.Socket} class, +a subclass of {stream.Duplex}, unless the user specified a socket +type other than {net.Socket}. ### message.statusCode