### Event: 'connection'
-`function (stream) { }`
+`function (socket) { }`
- When a new TCP stream is established. `stream` is an object of type
- `net.Stream`. Usually users will not want to access this event. The
- `stream` can also be accessed at `request.connection`.
+ When a new TCP stream is established. `socket` is an object of type
+ `net.Socket`. Usually users will not want to access this event. The
+ `socket` can also be accessed at `request.connection`.
### Event: 'close'
### Event: 'checkContinue'
-`function (request, response) {}`
+`function (request, response) { }`
Emitted each time a request with an http Expect: 100-continue is received.
If this event isn't listened for, the server will automatically respond
### Event: 'upgrade'
-`function (request, socket, head)`
+`function (request, socket, head) { }`
Emitted each time a client requests a http upgrade. If this event isn't
listened for, then clients requesting an upgrade will have their connections
### Event: 'clientError'
-`function (exception) {}`
+`function (exception) { }`
If a client connection emits an 'error' event - it will forwarded here.
### request.connection
-The `net.Stream` object associated with the connection.
+The `net.Socket` object associated with the connection.
With HTTPS support, use request.connection.verifyPeer() and
works because the string `'hello world'` contains only single byte characters.
If the body contains higher coded characters then `Buffer.byteLength()`
should be used to determine the number of bytes in a given encoding.
+And Node does not check whether Content-Length and the length of the body
+which has been transmitted are equal or not.
### response.statusCode
response.statusCode = 404;
+After response header was sent to the client, this property indicates the
+status code which was sent out.
+
### response.setHeader(name, value)
Sets a single header value for implicit headers. If this header already exists
- `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. 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`: 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
## 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`.
+Note: Node does not check whether Content-Length and the length of the body
+which has been transmitted are equal or not.
+
+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:
- `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)`
+`function (response, socket, head) { }`
Emitted each time a server responds to a request with an upgrade. If this
event isn't being listened for, clients receiving an upgrade header will have
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: {
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);
});
});
-
### Event: 'continue'
`function ()`
the request contained 'Expect: 100-continue'. This is an instruction that
the client should send the request body.
-### 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 '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
### Event: 'data'
-`function (chunk) {}`
+`function (chunk) { }`
Emitted when a piece of the message body is received.
### Event: 'end'
-`function () {}`
+`function () { }`
Emitted exactly once for each message. No arguments. After
emitted no other events will be emitted on the response.
+### Event: 'close'
+
+`function (err) { }`
+
+Indicates that the underlaying connection was terminated before
+`end` event was emitted.
+See [http.ServerRequest](#http.ServerRequest)'s `'close'` event for more
+information.
+
### response.statusCode
The 3-digit HTTP response status code. E.G. `404`.
projects / platform / upstream / nodejs.git / blobdiff