FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

doc: update http.md mention of socket · nodejs/node@b775753 · GitHub

/ node Public

Commit b775753

Browse files
jessekoconnor
authored and
MylesBorins
committed
doc: update http.md mention of socket
This commit is addressing the problem in issue #29948. Fixes: #29948 PR-URL: #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 parent 21dd601 commit b775753

1 file changed

Lines changed: 64 additions & 16 deletions

File tree

‎doc/api/http.md‎

Lines changed: 64 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -157,7 +157,7 @@ added: v0.11.4
157157
* `options` {Object} Options containing connection details. Check
158158
[`net.createConnection()`][] for the format of the options
159159
* `callback` {Function} Callback function that receives the created socket
160-
* Returns: {net.Socket}
160+
* Returns: {stream.Duplex}
161161

162162
Produces a socket/stream to be used for HTTP requests.
163163

@@ -167,14 +167,18 @@ custom agents may override this method in case greater flexibility is desired.
167167
A socket/stream can be supplied in one of two ways: by returning the
168168
socket/stream from this function, or by passing the socket/stream to `callback`.
169169

170+
This method is guaranteed to return an instance of the {net.Socket} class,
171+
a subclass of {stream.Duplex}, unless the user specifies a socket
172+
type other than {net.Socket}.
173+
170174
`callback` has a signature of `(err, stream)`.
171175

172176
### agent.keepSocketAlive(socket)
173177
<!-- YAML
174178
added: v8.1.0
175179
-->
176180

177-
* `socket` {net.Socket}
181+
* `socket` {stream.Duplex}
178182

179183
Called when `socket` is detached from a request and could be persisted by the
180184
`Agent`. Default behavior is to:
@@ -189,12 +193,15 @@ This method can be overridden by a particular `Agent` subclass. If this
189193
method returns a falsy value, the socket will be destroyed instead of persisting
190194
it for use with the next request.
191195

196+
The `socket` argument can be an instance of {net.Socket}, a subclass of
197+
{stream.Duplex}.
198+
192199
### agent.reuseSocket(socket, request)
193200
<!-- YAML
194201
added: v8.1.0
195202
-->
196203

197-
* `socket` {net.Socket}
204+
* `socket` {stream.Duplex}
198205
* `request` {http.ClientRequest}
199206

200207
Called when `socket` is attached to `request` after being persisted because of
@@ -206,6 +213,9 @@ socket.ref();
206213

207214
This method can be overridden by a particular `Agent` subclass.
208215

216+
The `socket` argument can be an instance of {net.Socket}, a subclass of
217+
{stream.Duplex}.
218+
209219
### agent.destroy()
210220
<!-- YAML
211221
added: v0.11.4
@@ -341,13 +351,17 @@ added: v0.7.0
341351
-->
342352

343353
* `response` {http.IncomingMessage}
344-
* `socket` {net.Socket}
354+
* `socket` {stream.Duplex}
345355
* `head` {Buffer}
346356

347357
Emitted each time a server responds to a request with a `CONNECT` method. If
348358
this event is not being listened for, clients receiving a `CONNECT` method will
349359
have their connections closed.
350360

361+
This event is guaranteed to be passed an instance of the {net.Socket} class,
362+
a subclass of {stream.Duplex}, unless the user specifies a socket
363+
type other than {net.Socket}.
364+
351365
A client and server pair demonstrating how to listen for the `'connect'` event:
352366

353367
```js
@@ -471,9 +485,11 @@ once.
471485
added: v0.5.3
472486
-->
473487

474-
* `socket` {net.Socket}
488+
* `socket` {stream.Duplex}
475489

476-
Emitted after a socket is assigned to this request.
490+
This event is guaranteed to be passed an instance of the {net.Socket} class,
491+
a subclass of {stream.Duplex}, unless the user specifies a socket
492+
type other than {net.Socket}.
477493

478494
### Event: 'timeout'
479495
<!-- YAML
@@ -491,14 +507,18 @@ added: v0.1.94
491507
-->
492508

493509
* `response` {http.IncomingMessage}
494-
* `socket` {net.Socket}
510+
* `socket` {stream.Duplex}
495511
* `head` {Buffer}
496512

497513
Emitted each time a server responds to a request with an upgrade. If this
498514
event is not being listened for and the response status code is 101 Switching
499515
Protocols, clients receiving an upgrade header will have their connections
500516
closed.
501517

518+
This event is guaranteed to be passed an instance of the {net.Socket} class,
519+
a subclass of {stream.Duplex}, unless the user specifies a socket
520+
type other than {net.Socket}.
521+
502522
A client server pair demonstrating how to listen for the `'upgrade'` event.
503523

504524
```js
@@ -572,7 +592,7 @@ deprecated: v13.0.0
572592

573593
> Stability: 0 - Deprecated. Use [`request.socket`][].
574594
575-
* {net.Socket}
595+
* {stream.Duplex}
576596

577597
See [`request.socket`][].
578598

@@ -800,7 +820,7 @@ Once a socket is assigned to this request and is connected
800820
added: v0.3.0
801821
-->
802822

803-
* {net.Socket}
823+
* {stream.Duplex}
804824

805825
Reference to the underlying socket. Usually users will not want to access
806826
this property. In particular, the socket will not emit `'readable'` events
@@ -822,6 +842,10 @@ req.once('response', (res) => {
822842
});
823843
```
824844

845+
This property is guaranteed to be an instance of the {net.Socket} class,
846+
a subclass of {stream.Duplex}, unless the user specified a socket
847+
type other than {net.Socket}.
848+
825849
### request.writableEnded
826850
<!-- YAML
827851
added: v12.9.0
@@ -935,13 +959,17 @@ changes:
935959
-->
936960

937961
* `exception` {Error}
938-
* `socket` {net.Socket}
962+
* `socket` {stream.Duplex}
939963

940964
If a client connection emits an `'error'` event, it will be forwarded here.
941965
Listener of this event is responsible for closing/destroying the underlying
942966
socket. For example, one may wish to more gracefully close the socket with a
943967
custom HTTP response instead of abruptly severing the connection.
944968

969+
This event is guaranteed to be passed an instance of the {net.Socket} class,
970+
a subclass of {stream.Duplex}, unless the user specifies a socket
971+
type other than {net.Socket}.
972+
945973
Default behavior is to try close the socket with a HTTP '400 Bad Request',
946974
or a HTTP '431 Request Header Fields Too Large' in the case of a
947975
[`HPE_HEADER_OVERFLOW`][] error. If the socket is not writable it is
@@ -986,13 +1014,17 @@ added: v0.7.0
9861014

9871015
* `request` {http.IncomingMessage} Arguments for the HTTP request, as it is in
9881016
the [`'request'`][] event
989-
* `socket` {net.Socket} Network socket between the server and client
1017+
* `socket` {stream.Duplex} Network socket between the server and client
9901018
* `head` {Buffer} The first packet of the tunneling stream (may be empty)
9911019

9921020
Emitted each time a client requests an HTTP `CONNECT` method. If this event is
9931021
not listened for, then clients requesting a `CONNECT` method will have their
9941022
connections closed.
9951023

1024+
This event is guaranteed to be passed an instance of the {net.Socket} class,
1025+
a subclass of {stream.Duplex}, unless the user specifies a socket
1026+
type other than {net.Socket}.
1027+
9961028
After this event is emitted, the request's socket will not have a `'data'`
9971029
event listener, meaning it will need to be bound in order to handle data
9981030
sent to the server on that socket.
@@ -1002,7 +1034,7 @@ sent to the server on that socket.
10021034
added: v0.1.0
10031035
-->
10041036

1005-
* `socket` {net.Socket}
1037+
* `socket` {stream.Duplex}
10061038

10071039
This event is emitted when a new TCP stream is established. `socket` is
10081040
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
10171049
`server.keepAliveTimeout` when the socket has served a request (if
10181050
`server.keepAliveTimeout` is non-zero).
10191051

1052+
This event is guaranteed to be passed an instance of the {net.Socket} class,
1053+
a subclass of {stream.Duplex}, unless the user specifies a socket
1054+
type other than {net.Socket}.
1055+
10201056
### Event: 'request'
10211057
<!-- YAML
10221058
added: v0.1.0
@@ -1040,7 +1076,7 @@ changes:
10401076

10411077
* `request` {http.IncomingMessage} Arguments for the HTTP request, as it is in
10421078
the [`'request'`][] event
1043-
* `socket` {net.Socket} Network socket between the server and client
1079+
* `socket` {stream.Duplex} Network socket between the server and client
10441080
* `head` {Buffer} The first packet of the upgraded stream (may be empty)
10451081

10461082
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'`
10501086
event listener, meaning it will need to be bound in order to handle data
10511087
sent to the server on that socket.
10521088

1089+
This event is guaranteed to be passed an instance of the {net.Socket} class,
1090+
a subclass of {stream.Duplex}, unless the user specifies a socket
1091+
type other than {net.Socket}.
1092+
10531093
### server.close(\[callback\])
10541094
<!-- YAML
10551095
added: v0.1.90
@@ -1227,7 +1267,7 @@ deprecated: v13.0.0
12271267

12281268
> Stability: 0 - Deprecated. Use [`response.socket`][].
12291269
1230-
* {net.Socket}
1270+
* {stream.Duplex}
12311271

12321272
See [`response.socket`][].
12331273

@@ -1469,7 +1509,7 @@ timed out sockets must be handled explicitly.
14691509
added: v0.3.0
14701510
-->
14711511

1472-
* {net.Socket}
1512+
* {stream.Duplex}
14731513

14741514
Reference to the underlying socket. Usually users will not want to access
14751515
this property. In particular, the socket will not emit `'readable'` events
@@ -1486,6 +1526,10 @@ const server = http.createServer((req, res) => {
14861526
}).listen(3000);
14871527
```
14881528

1529+
This property is guaranteed to be an instance of the {net.Socket} class,
1530+
a subclass of {stream.Duplex}, unless the user specified a socket
1531+
type other than {net.Socket}.
1532+
14891533
### response.statusCode
14901534
<!-- YAML
14911535
added: v0.4.0
@@ -1868,13 +1912,17 @@ Calls `message.connection.setTimeout(msecs, callback)`.
18681912
added: v0.3.0
18691913
-->
18701914

1871-
* {net.Socket}
1915+
* {stream.Duplex}
18721916

18731917
The [`net.Socket`][] object associated with the connection.
18741918

18751919
With HTTPS support, use [`request.socket.getPeerCertificate()`][] to obtain the
18761920
client's authentication details.
18771921

1922+
This property is guaranteed to be an instance of the {net.Socket} class,
1923+
a subclass of {stream.Duplex}, unless the user specified a socket
1924+
type other than {net.Socket}.
1925+
18781926
### message.statusCode
18791927
<!-- YAML
18801928
added: v0.1.1

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL