doc: update http.md mention of socket

This commit is addressing the problem in issue #29948.

Fixes: https://github.com/nodejs/node/issues/29948
PR-URL: https://github.com/nodejs/node/pull/30155
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Tobias Nießen <tniessen@tnie.de>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
Reviewed-By: James M Snell <jasnell@gmail.com>

1 files changed, 64 insertions, 16 deletions

diff --git a/doc/api/http.md b/doc/api/http.md
index cab01f3e30..c3ba806def 100644
--- a/doc/api/http.md
+++ b/doc/api/http.md
@@ -157,7 +157,7 @@ added: v0.11.4
 * `options` {Object} Options containing connection details. Check
   [`net.createConnection()`][] for the format of the options
 * `callback` {Function} Callback function that receives the created socket
-* Returns: {net.Socket}
+* Returns: {stream.Duplex}
 
 Produces a socket/stream to be used for HTTP requests.
 
@@ -167,6 +167,10 @@ custom agents may override this method in case greater flexibility is desired.
 A socket/stream can be supplied in one of two ways: by returning the
 socket/stream from this function, or by passing the socket/stream to `callback`.
 
+This method is guaranteed to return an instance of the {net.Socket} class,
+a subclass of {stream.Duplex}, unless the user specifies a socket
+type other than {net.Socket}.
+
 `callback` has a signature of `(err, stream)`.
 
 ### agent.keepSocketAlive(socket)
@@ -174,7 +178,7 @@ socket/stream from this function, or by passing the socket/stream to `callback`.
 added: v8.1.0
 -->
 
-* `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,12 +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 {net.Socket}, a subclass of
+{stream.Duplex}.
+
 ### agent.reuseSocket(socket, request)
 <!-- YAML
 added: v8.1.0
 -->
 
-* `socket` {net.Socket}
+* `socket` {stream.Duplex}
 * `request` {http.ClientRequest}
 
 Called when `socket` is attached to `request` after being persisted because of
@@ -206,6 +213,9 @@ socket.ref();
 
 This method can be overridden by a particular `Agent` subclass.
 
+The `socket` argument can be an instance of {net.Socket}, a subclass of
+{stream.Duplex}.
+
 ### agent.destroy()
 <!-- YAML
 added: v0.11.4
@@ -341,13 +351,17 @@ added: v0.7.0
 -->
 
 * `response` {http.IncomingMessage}
-* `socket` {net.Socket}
+* `socket` {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 {stream.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
@@ -471,9 +485,11 @@ once.
 added: v0.5.3
 -->
 
-* `socket` {net.Socket}
+* `socket` {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 {stream.Duplex}, unless the user specifies a socket
+type other than {net.Socket}.
 
 ### Event: 'timeout'
 <!-- YAML
@@ -491,7 +507,7 @@ added: v0.1.94
 -->
 
 * `response` {http.IncomingMessage}
-* `socket` {net.Socket}
+* `socket` {stream.Duplex}
 * `head` {Buffer}
 
 Emitted each time a server responds to a request with an upgrade. If this
@@ -499,6 +515,10 @@ event is not being listened for and the response status code is 101 Switching
 Protocols, clients receiving an upgrade header will have their connections
 closed.
 
+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
+type other than {net.Socket}.
+
 A client server pair demonstrating how to listen for the `'upgrade'` event.
 
 ```js
@@ -572,7 +592,7 @@ deprecated: v13.0.0
 
 > Stability: 0 - Deprecated. Use [`request.socket`][].
 
-* {net.Socket}
+* {stream.Duplex}
 
 See [`request.socket`][].
 
@@ -800,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
@@ -822,6 +842,10 @@ req.once('response', (res) => {
 });
 ```
 
+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
 <!-- YAML
 added: v12.9.0
@@ -935,13 +959,17 @@ changes:
 -->
 
 * `exception` {Error}
-* `socket` {net.Socket}
+* `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
 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 {stream.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
@@ -986,13 +1014,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
+* `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
 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 {stream.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.
@@ -1002,7 +1034,7 @@ sent to the server on that socket.
 added: v0.1.0
 -->
 
-* `socket` {net.Socket}
+* `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
@@ -1017,6 +1049,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 {stream.Duplex}, unless the user specifies a socket
+type other than {net.Socket}.
+
 ### Event: 'request'
 <!-- YAML
 added: v0.1.0
@@ -1040,7 +1076,7 @@ changes:
 
 * `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
+* `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
@@ -1050,6 +1086,10 @@ 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.
 
+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
+type other than {net.Socket}.
+
 ### server.close(\[callback\])
 <!-- YAML
 added: v0.1.90
@@ -1227,7 +1267,7 @@ deprecated: v13.0.0
 
 > Stability: 0 - Deprecated. Use [`response.socket`][].
 
-* {net.Socket}
+* {stream.Duplex}
 
 See [`response.socket`][].
 
@@ -1469,7 +1509,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
@@ -1486,6 +1526,10 @@ const server = http.createServer((req, res) => {
 }).listen(3000);
 ```
 
+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
 <!-- YAML
 added: v0.4.0
@@ -1868,13 +1912,17 @@ Calls `message.connection.setTimeout(msecs, callback)`.
 added: v0.3.0
 -->
 
-* {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.
 
+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
 <!-- YAML
 added: v0.1.1