1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: update http.md for consistency and clarity

Browse Source 
The HTTP Keep-Alive text was inconsistent. These changes follow the
following rules

* When referring to flag used in code, it should always be written using
  backticks and in camel case. E.g. `keepAlive`.
* When referring to the mechanism Keep-Alive functionality as described
  in the HTTP 1.1 RFC, it is written as 'HTTP Keep-Alive', without the
  use of backticks.
* When referring to the request header, it should always use backticks
  and be written as `Connection: keep-alive`.

This commit also includes some changes to how `http.Agent` is
referenced. When `Agent` is used as a reference to an object or
instance, backticks should always be used.

And lastly, the documentation about `Agent` behavior around HTTP
Keep-Alive has been clarified and improved.

Fixes: https://github.com/nodejs/node/issues/10567
PR-URL: https://github.com/nodejs/node/pull/10715

Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
This commit is contained in:
Lance Ball 2017-01-09 12:45:46 -05:00
parent 58cb9cde91
commit 3b9e8adad4
No known key found for this signature in database
GPG Key ID: A36D601AFAF00813
1 changed files with 49 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

87
doc/api/http.md
View File

@ -48,26 +48,32 @@ list like the following:
added: v0.3.4 added: v0.3.4
--> -->
The HTTP Agent is used for pooling sockets used in HTTP client An `Agent` is responsible for managing connection persistence
requests. and reuse for HTTP clients. It maintains a queue of pending requests
for a given host and port, reusing a single socket connection for each
until the queue is empty, at which time the socket is either destroyed
or put into a pool where it is kept to be used again for requests to the
same host and port. Whether it is destroyed or pooled depends on the
`keepAlive` [option](#http_new_agent_options).
The HTTP Agent also defaults client requests to using Pooled connections have TCP Keep-Alive enabled for them, but servers may
`Connection: keep-alive`. If no pending HTTP requests are waiting on a still close idle connections, in which case they will be removed from the
socket to become free the socket is closed. This means that Node.js's pool and a new connection will be made when a new HTTP request is made for
pool has the benefit of keep-alive when under load but still does not that host and port. Servers may also refuse to allow multiple requests
require developers to manually close the HTTP clients using over the same connection, in which case the connection will have to be
KeepAlive. remade for every request and cannot be pooled. The `Agent` will still make
the requests to that server, but each one will occur over a new connection.
If you opt into using HTTP KeepAlive, you can create an Agent object When a connection is closed by the client or the server, it is removed
with that flag set to `true`. (See the [constructor options][].) from the pool. Any unused sockets in the pool will be unrefed so as not
Then, the Agent will keep unused sockets in a pool for later use. They to keep the Node.js process running when there are no outstanding requests.
will be explicitly marked so as to not keep the Node.js process running. (see [socket.unref()]).
However, it is still a good idea to explicitly [`destroy()`][] KeepAlive
agents when they are no longer in use, so that the Sockets will be shut
down.
Sockets are removed from the agent's pool when the socket emits either It is good practice, to [`destroy()`][] an `Agent` instance when it is no
a `'close'` event or a special `'agentRemove'` event. This means that if longer in use, because unused sockets consume OS resources.
Sockets are removed from an agent's pool when the socket emits either
a `'close'` event or an `'agentRemove'` event. This means that if
you intend to keep one HTTP request open for a long time and don't you intend to keep one HTTP request open for a long time and don't
want it to stay in the pool you can do something along the lines of: want it to stay in the pool you can do something along the lines of:
@ -79,7 +85,11 @@ http.get(options, (res) => {
}); });
``` ```
Alternatively, you could just opt out of pooling entirely using You may also use an agent for an individual request. By providing
`{agent: false}` as an option to the `http.get()` or `http.request()`
functions, a one-time use `Agent` with default options will be used
for the client connection.
`agent:false`: `agent:false`:
```js ```js
@ -100,11 +110,13 @@ added: v0.3.4
* `options` {Object} Set of configurable options to set on the agent. * `options` {Object} Set of configurable options to set on the agent.
Can have the following fields: Can have the following fields:
* `keepAlive` {Boolean} Keep sockets around in a pool to be used by * `keepAlive` {Boolean} Keep sockets around even when there are no
other requests in the future. Default = `false` outstanding requests, so they can be used for future requests without
* `keepAliveMsecs` {Integer} When using HTTP KeepAlive, how often having to reestablish a TCP connection. Default = `false`
to send TCP KeepAlive packets over sockets being kept alive. * `keepAliveMsecs` {Integer} When using the `keepAlive` option, specifies
Default = `1000`. Only relevant if `keepAlive` is set to `true`. the [initial delay](#net_socket_setkeepalive_enable_initialdelay)
for TCP Keep-Alive packets. Ignored when the
`keepAlive` option is `false` or `undefined`. Default = `1000`.
* `maxSockets` {Number} Maximum number of sockets to allow per * `maxSockets` {Number} Maximum number of sockets to allow per
host. Default = `Infinity`. host. Default = `Infinity`.
* `maxFreeSockets` {Number} Maximum number of sockets to leave open * `maxFreeSockets` {Number} Maximum number of sockets to leave open
@ -114,7 +126,7 @@ added: v0.3.4
The default [`http.globalAgent`][] that is used by [`http.request()`][] has all The default [`http.globalAgent`][] that is used by [`http.request()`][] has all
of these values set to their respective defaults. of these values set to their respective defaults.
To configure any of them, you must create your own [`http.Agent`][] object. To configure any of them, you must create your own [`http.Agent`][] instance.
```js ```js
const http = require('http'); const http = require('http');
@ -136,7 +148,7 @@ added: v0.11.4
Produces a socket/stream to be used for HTTP requests. Produces a socket/stream to be used for HTTP requests.
By default, this function is the same as [`net.createConnection()`][]. However, By default, this function is the same as [`net.createConnection()`][]. However,
custom Agents may override this method in case greater flexibility is desired. 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 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`. socket/stream from this function, or by passing the socket/stream to `callback`.
@ -151,7 +163,7 @@ added: v0.11.4
Destroy any sockets that are currently in use by the agent. Destroy any sockets that are currently in use by the agent.
It is usually not necessary to do this. However, if you are using an It is usually not necessary to do this. However, if you are using an
agent with KeepAlive enabled, then it is best to explicitly shut down agent with `keepAlive` enabled, then it is best to explicitly shut down
the agent when you know that it will no longer be used. Otherwise, the agent when you know that it will no longer be used. Otherwise,
sockets may hang open for quite a long time before the server sockets may hang open for quite a long time before the server
terminates them. terminates them.
@ -164,7 +176,7 @@ added: v0.11.4
* {Object} * {Object}
An object which contains arrays of sockets currently awaiting use by An object which contains arrays of sockets currently awaiting use by
the Agent when HTTP KeepAlive is used. Do not modify. the agent when `keepAlive` is enabled. Do not modify.
### agent.getName(options) ### agent.getName(options)
<!-- YAML <!-- YAML
@ -179,8 +191,8 @@ added: v0.11.4
* Returns: {String} * Returns: {String}
Get a unique name for a set of request options, to determine whether a Get a unique name for a set of request options, to determine whether a
connection can be reused. In the http agent, this returns connection can be reused. For an HTTP agent, this returns
`host:port:localAddress`. In the https agent, the name includes the `host:port:localAddress`. For an HTTPS agent, the name includes the
CA, cert, ciphers, and other HTTPS/TLS-specific options that determine CA, cert, ciphers, and other HTTPS/TLS-specific options that determine
socket reusability. socket reusability.
@ -191,7 +203,7 @@ added: v0.11.7
* {Number} * {Number}
By default set to 256. For Agents supporting HTTP KeepAlive, this By default set to 256. For agents with `keepAlive` enabled, this
sets the maximum number of sockets that will be left open in the free sets the maximum number of sockets that will be left open in the free
state. state.
@ -224,7 +236,7 @@ added: v0.3.6
* {Object} * {Object}
An object which contains arrays of sockets currently in use by the An object which contains arrays of sockets currently in use by the
Agent. Do not modify. agent. Do not modify.
## Class: http.ClientRequest ## Class: http.ClientRequest
<!-- YAML <!-- YAML
@ -652,7 +664,7 @@ added: v0.1.0
* `response` {http.ServerResponse} * `response` {http.ServerResponse}
Emitted each time there is a request. Note that there may be multiple requests Emitted each time there is a request. Note that there may be multiple requests
per connection (in the case of keep-alive connections). per connection (in the case of HTTP Keep-Alive connections).
### Event: 'upgrade' ### Event: 'upgrade'
<!-- YAML <!-- YAML
@ -1489,7 +1501,7 @@ added: v0.5.9
* {http.Agent} * {http.Agent}
Global instance of Agent which is used as the default for all HTTP client Global instance of `Agent` which is used as the default for all HTTP client
requests. requests.
## http.request(options[, callback]) ## http.request(options[, callback])
@ -1519,15 +1531,13 @@ added: v0.3.6
* `headers` {Object} An object containing request headers. * `headers` {Object} An object containing request headers.
* `auth` {String} Basic authentication i.e. `'user:password'` to compute an * `auth` {String} Basic authentication i.e. `'user:password'` to compute an
Authorization header. Authorization header.
* `agent` {http.Agent|Boolean} Controls [`Agent`][] behavior. When an Agent * `agent` {http.Agent|Boolean} Controls [`Agent`][] behavior. Possible values:
is used request will default to `Connection: keep-alive`. Possible values:
* `undefined` (default): use [`http.globalAgent`][] for this host and port. * `undefined` (default): use [`http.globalAgent`][] for this host and port.
* `Agent` object: explicitly use the passed in `Agent`. * `Agent` object: explicitly use the passed in `Agent`.
* `false`: opts out of connection pooling with an Agent, defaults request to * `false`: causes a new `Agent` with default values to be used.
`Connection: close`.
* `createConnection` {Function} A function that produces a socket/stream to * `createConnection` {Function} A function that produces a socket/stream to
use for the request when the `agent` option is not used. This can be used to use for the request when the `agent` option is not used. This can be used to
avoid creating a custom Agent class just to override the default avoid creating a custom `Agent` class just to override the default
`createConnection` function. See [`agent.createConnection()`][] for more `createConnection` function. See [`agent.createConnection()`][] for more
details. details.
* `timeout` {Integer}: A number specifying the socket timeout in milliseconds. * `timeout` {Integer}: A number specifying the socket timeout in milliseconds.
@ -1648,3 +1658,4 @@ There are a few special headers that should be noted.
[constructor options]: #http_new_agent_options [constructor options]: #http_new_agent_options
[Readable Stream]: stream.html#stream_class_stream_readable [Readable Stream]: stream.html#stream_class_stream_readable
[Writable Stream]: stream.html#stream_class_stream_writable [Writable Stream]: stream.html#stream_class_stream_writable
[socket.unref()]: net.html#net_socket_unref