Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: update http.md mention of socket #30155

Closed
wants to merge 25 commits into from
Closed
Changes from 11 commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
55e6663
doc: update http.md mention of socket
jessekoconnor Oct 28, 2019
9eb3fac
docs: correct line spacing
jessekoconnor Oct 28, 2019
8572afb
doc: update stream obj to duplex obj
jessekoconnor Oct 30, 2019
863f6f4
doc: reword socket documentation wording
jessekoconnor Oct 30, 2019
d49e4dd
doc: Capitalize Duplex when referring to class
jessekoconnor Oct 30, 2019
38171e9
doc: update request.keepAlive(duplex)
jessekoconnor Oct 30, 2019
094d513
doc: update the events on Agent first
jessekoconnor Oct 31, 2019
e54b9e9
fix: update rest of events
jessekoconnor Oct 31, 2019
2eec64c
fix: forgot one explanation
jessekoconnor Oct 31, 2019
5b827a3
doc: suggest doc for methods
jessekoconnor Oct 31, 2019
fce5f9c
doc: address rest of relevant methods
jessekoconnor Oct 31, 2019
7cf2e18
doc: suggestion from tniessen
jessekoconnor Nov 1, 2019
da4eec8
Update doc/api/http.md
jessekoconnor Nov 1, 2019
d08c71e
Update doc/api/http.md
jessekoconnor Nov 1, 2019
352fce8
Update doc/api/http.md
jessekoconnor Nov 1, 2019
916b271
Update doc/api/http.md
jessekoconnor Nov 1, 2019
8f39b79
Update doc/api/http.md
jessekoconnor Nov 1, 2019
f1419f3
Update doc/api/http.md
jessekoconnor Nov 1, 2019
92bbaec
Update doc/api/http.md
jessekoconnor Nov 1, 2019
b545157
doc: wording suggestion from tniessen
jessekoconnor Nov 1, 2019
220cecb
doc: more tidying up
jessekoconnor Nov 1, 2019
92fbdef
doc: even more tidying up
jessekoconnor Nov 1, 2019
6809c26
fix: update further
jessekoconnor Nov 1, 2019
14cf7aa
Update doc/api/http.md
jessekoconnor Nov 3, 2019
1fc5adf
doc: Updates based on feedback from tniesson
jessekoconnor Nov 4, 2019
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 46 additions & 8 deletions doc/api/http.md
Original file line number Diff line number Diff line change
Expand Up @@ -189,6 +189,9 @@ 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.

`socket` argument can be an instance of {stream.Duplex}, a superclass of
tniessen marked this conversation as resolved.
Show resolved Hide resolved
Socket.
jessekoconnor marked this conversation as resolved.
Show resolved Hide resolved

### agent.reuseSocket(socket, request)
<!-- YAML
added: v8.1.0
Expand All @@ -206,6 +209,9 @@ socket.ref();

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

`socket` argument can be an instance of {stream.Duplex}, a superclass of
tniessen marked this conversation as resolved.
Show resolved Hide resolved
Socket.
jessekoconnor marked this conversation as resolved.
Show resolved Hide resolved

### agent.destroy()
<!-- YAML
added: v0.11.4
Expand Down Expand Up @@ -341,13 +347,17 @@ added: v0.7.0
-->

* `response` {http.IncomingMessage}
* `socket` {net.Socket}
* `duplex` {stream.Duplex}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would prefer not to rename any arguments, it should be enough to change the type.

* `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
jessekoconnor marked this conversation as resolved.
Show resolved Hide resolved
type other than {net.Socket}.

A client and server pair demonstrating how to listen for the `'connect'` event:

```js
Expand Down Expand Up @@ -471,9 +481,11 @@ once.
added: v0.5.3
-->

* `socket` {net.Socket}
* `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, instead of Duplex unless the user specifies a socket
jessekoconnor marked this conversation as resolved.
Show resolved Hide resolved
type other than {net.Socket}.

### Event: 'timeout'
<!-- YAML
Expand All @@ -491,14 +503,18 @@ added: v0.1.94
-->

* `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
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 Duplex, instead of Duplex unless the user specifies a socket
jessekoconnor marked this conversation as resolved.
Show resolved Hide resolved
type other than {net.Socket}.

A client server pair demonstrating how to listen for the `'upgrade'` event.

```js
Expand Down Expand Up @@ -822,6 +838,8 @@ req.once('response', (res) => {
});
```

Can be passed an instance of {stream.Duplex}, a superclass of Socket.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shouldn't the type of the property be changed to {stream.Duplex}?

Also, "Can be passed" doesn't sound right for a property that is not a function.


### request.writableEnded
<!-- YAML
added: v12.9.0
Expand Down Expand Up @@ -935,13 +953,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
jessekoconnor marked this conversation as resolved.
Show resolved Hide resolved
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This line should be changed, see my previous comments.

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
Expand Down Expand Up @@ -986,13 +1008,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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would prefer not to change the name of the argument.

* `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
jessekoconnor marked this conversation as resolved.
Show resolved Hide resolved
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.
Expand All @@ -1002,7 +1028,7 @@ sent to the server on that socket.
added: v0.1.0
-->

* `socket` {net.Socket}
* `duplex` {stream.Duplex}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ditto.


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
Expand All @@ -1017,6 +1043,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
jessekoconnor marked this conversation as resolved.
Show resolved Hide resolved
type other than {net.Socket}.

### Event: 'request'
<!-- YAML
added: v0.1.0
Expand All @@ -1040,7 +1070,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
* `duplex` {stream.Duplex} Network socket between the server and client
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ditto.

* `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
Expand All @@ -1050,6 +1080,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 Duplex, instead of Duplex unless the user specifies a socket
jessekoconnor marked this conversation as resolved.
Show resolved Hide resolved
type other than {net.Socket}.

### server.close(\[callback\])
<!-- YAML
added: v0.1.90
Expand Down Expand Up @@ -1479,6 +1513,8 @@ const server = http.createServer((req, res) => {
}).listen(3000);
```

Can be passsed an instance of {stream.Duplex}, a superclass of Socket.
tniessen marked this conversation as resolved.
Show resolved Hide resolved

### response.statusCode
<!-- YAML
added: v0.4.0
Expand Down Expand Up @@ -1857,6 +1893,8 @@ The [`net.Socket`][] object associated with the connection.
With HTTPS support, use [`request.socket.getPeerCertificate()`][] to obtain the
client's authentication details.

Can be passed an instance of {stream.Duplex}, a superclass of Socket.
tniessen marked this conversation as resolved.
Show resolved Hide resolved

### message.statusCode
<!-- YAML
added: v0.1.1
Expand Down