From 3c8b4277f566b289fe74e9e0569b3fe8759591e0 Mon Sep 17 00:00:00 2001 From: Lance Ball Date: Mon, 9 Jan 2017 12:45:46 -0500 Subject: [PATCH] doc: update http.md for consistency and clarity 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 Reviewed-By: Luigi Pinca --- doc/api/http.md | 93 +++++++++++++++++++++++++++---------------------- 1 file changed, 52 insertions(+), 41 deletions(-) diff --git a/doc/api/http.md b/doc/api/http.md index ea23dad33a8bd8..9f0fca7b52d16a 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -48,26 +48,32 @@ list like the following: added: v0.3.4 --> -The HTTP Agent is used for pooling sockets used in HTTP client -requests. - -The HTTP Agent also defaults client requests to using -`Connection: keep-alive`. If no pending HTTP requests are waiting on a -socket to become free the socket is closed. This means that Node.js's -pool has the benefit of keep-alive when under load but still does not -require developers to manually close the HTTP clients using -KeepAlive. - -If you opt into using HTTP KeepAlive, you can create an Agent object -with that flag set to `true`. (See the [constructor options][].) -Then, the Agent will keep unused sockets in a pool for later use. They -will be explicitly marked so as to not keep the Node.js process running. -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 -a `'close'` event or a special `'agentRemove'` event. This means that if +An `Agent` is responsible for managing connection persistence +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). + +Pooled connections have TCP Keep-Alive enabled for them, but servers may +still close idle connections, in which case they will be removed from the +pool and a new connection will be made when a new HTTP request is made for +that host and port. Servers may also refuse to allow multiple requests +over the same connection, in which case the connection will have to be +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. + +When a connection is closed by the client or the server, it is removed +from the pool. Any unused sockets in the pool will be unrefed so as not +to keep the Node.js process running when there are no outstanding requests. +(see [socket.unref()]). + +It is good practice, to [`destroy()`][] an `Agent` instance when it is no +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 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`: ```js @@ -100,11 +110,13 @@ added: v0.3.4 * `options` {Object} Set of configurable options to set on the agent. Can have the following fields: - * `keepAlive` {Boolean} Keep sockets around in a pool to be used by - other requests in the future. Default = `false` - * `keepAliveMsecs` {Integer} When using HTTP KeepAlive, how often - to send TCP KeepAlive packets over sockets being kept alive. - Default = `1000`. Only relevant if `keepAlive` is set to `true`. + * `keepAlive` {Boolean} Keep sockets around even when there are no + outstanding requests, so they can be used for future requests without + having to reestablish a TCP connection. Default = `false` + * `keepAliveMsecs` {Integer} When using the `keepAlive` option, specifies + 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 host. Default = `Infinity`. * `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 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 const http = require('http'); @@ -136,7 +148,7 @@ added: v0.11.4 Produces a socket/stream to be used for HTTP requests. 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 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. 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, sockets may hang open for quite a long time before the server terminates them. @@ -164,7 +176,7 @@ added: v0.11.4 * {Object} 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)