From 915fa1e44fac1c7c367d6c43b33439f8352d63cd Mon Sep 17 00:00:00 2001 From: Mikeal Rogers Date: Tue, 26 Jul 2011 00:13:24 +0200 Subject: [PATCH] doc: http2 documentation --- doc/api/http.markdown | 150 +++++++++++++++++++++++++------------------------- 1 file changed, 74 insertions(+), 76 deletions(-) diff --git a/doc/api/http.markdown b/doc/api/http.markdown index cb57135..497adba 100644 --- a/doc/api/http.markdown +++ b/doc/api/http.markdown @@ -394,10 +394,10 @@ Options: - `path`: Request path. Should include query string and fragments if any. E.G. `'/index.html?page=12'` - `headers`: An object containing request headers. -- `agent`: Controls `Agent` behavior. Possible values: +- `agent`: Controls `Agent` behavior. When an Agent is used request will default to Connection:keep-alive. Possible values: - `undefined` (default): use default `Agent` for this host and port. - `Agent` object: explicitly use the passed in `Agent`. - - `false`: explicitly generate a new `Agent` for this host and port. `Agent` will not be re-used. + - `false`: opts out of connection pooling with an Agent, defaults request to Connection:close. `http.request()` returns an instance of the `http.ClientRequest` class. The `ClientRequest` instance is a writable stream. If one needs to @@ -472,12 +472,71 @@ Example: ## http.Agent -## http.getAgent(options) -`http.request()` uses a special `Agent` for managing multiple connections to -an HTTP server. Normally `Agent` instances should not be exposed to user -code, however in certain situations it's useful to check the status of the -agent. The `http.getAgent()` function allows you to access the agents. +## http.globalAgent + +Global instance of Agent which is used as the default for all http client requests. + +### agent.maxSockets + +By default set to 5. Determines how many concurrent sockets the agent can have open per host. + +### agent.sockets + +An object which contains arrays of sockets currently in use by the Agent. Do not modify. + +### agent.requests + +An object which contains queues of requests that have not yet been assigned to sockets. Do not modify. + + +## http.ClientRequest + +This object is created internally and returned from `http.request()`. It +represents an _in-progress_ request whose header has already been queued. The +header is still mutable using the `setHeader(name, value)`, `getHeader(name)`, +`removeHeader(name)` API. The actual header will be sent along with the first +data chunk or when closing the connection. + +To get the response, add a listener for `'response'` to the request object. +`'response'` will be emitted from the request object when the response +headers have been received. The `'response'` event is executed with one +argument which is an instance of `http.ClientResponse`. + +During the `'response'` event, one can add listeners to the +response object; particularly to listen for the `'data'` event. Note that +the `'response'` event is called before any part of the response body is received, +so there is no need to worry about racing to catch the first part of the +body. As long as a listener for `'data'` is added during the `'response'` +event, the entire body will be caught. + + + // Good + request.on('response', function (response) { + response.on('data', function (chunk) { + console.log('BODY: ' + chunk); + }); + }); + + // Bad - misses all or part of the body + request.on('response', function (response) { + setTimeout(function () { + response.on('data', function (chunk) { + console.log('BODY: ' + chunk); + }); + }, 10); + }); + +This is a `Writable Stream`. + +This is an `EventEmitter` with the following events: + +### Event 'response' + +`function (response) { }` + +Emitted when a response is received to this request. This event is emitted only once. The +`response` argument will be an instance of `http.ClientResponse`. Options: @@ -485,6 +544,12 @@ Options: - `port`: Port of remote server. - `socketPath`: Unix Domain Socket (use one of host:port or socketPath) +### Event: 'socket' + +`function (socket) { }` + +Emitted after a socket is assigned to this request. + ### Event: 'upgrade' `function (response, socket, head) { }` @@ -518,10 +583,7 @@ A client server pair that show you how to listen for the `upgrade` event using ` srv.listen(1337, '127.0.0.1', function() { // make a request - var agent = http.getAgent('127.0.0.1', 1337); - var options = { - agent: agent, port: 1337, host: '127.0.0.1', headers: { @@ -533,85 +595,21 @@ A client server pair that show you how to listen for the `upgrade` event using ` var req = http.request(options); req.end(); - agent.on('upgrade', function(res, socket, upgradeHead) { + req.on('upgrade', function(res, socket, upgradeHead) { console.log('got upgraded!'); socket.end(); process.exit(0); }); }); - -### agent.maxSockets - -By default set to 5. Determines how many concurrent sockets the agent can have open. - -### agent.sockets - -An array of sockets currently in use by the Agent. Do not modify. - -### agent.queue - -A queue of requests waiting to be sent to sockets. - - - -## http.ClientRequest - -This object is created internally and returned from `http.request()`. It -represents an _in-progress_ request whose header has already been queued. The -header is still mutable using the `setHeader(name, value)`, `getHeader(name)`, -`removeHeader(name)` API. The actual header will be sent along with the first -data chunk or when closing the connection. - -To get the response, add a listener for `'response'` to the request object. -`'response'` will be emitted from the request object when the response -headers have been received. The `'response'` event is executed with one -argument which is an instance of `http.ClientResponse`. - -During the `'response'` event, one can add listeners to the -response object; particularly to listen for the `'data'` event. Note that -the `'response'` event is called before any part of the response body is received, -so there is no need to worry about racing to catch the first part of the -body. As long as a listener for `'data'` is added during the `'response'` -event, the entire body will be caught. - - - // Good - request.on('response', function (response) { - response.on('data', function (chunk) { - console.log('BODY: ' + chunk); - }); - }); - - // Bad - misses all or part of the body - request.on('response', function (response) { - setTimeout(function () { - response.on('data', function (chunk) { - console.log('BODY: ' + chunk); - }); - }, 10); - }); - -This is a `Writable Stream`. - -This is an `EventEmitter` with the following events: - ### Event: 'continue' -`function () { }` +`function ()` Emitted when the server sends a '100 Continue' HTTP response, usually because the request contained 'Expect: 100-continue'. This is an instruction that the client should send the request body. -### Event 'response' - -`function (response) { }` - -Emitted when a response is received to this request. This event is emitted only once. The -`response` argument will be an instance of `http.ClientResponse`. - - ### request.write(chunk, encoding='utf8') Sends a chunk of the body. By calling this method -- 2.7.4