### 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
- `host`: A domain name or IP address of the server to issue the request to.
- `port`: Port of remote server.
+- `socketPath`: Unix Domain Socket (use one of host:port or socketPath)
- `method`: A string specifying the HTTP request method. Possible values:
`'GET'` (default), `'POST'`, `'PUT'`, and `'DELETE'`.
- `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(host, port)
-
-`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.
-
-### Event: 'upgrade'
-
-`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
-their connections closed.
-
-A client server pair that show you how to listen for the `upgrade` event using `http.getAgent`:
-
- var http = require('http');
- var net = require('net');
-
- // Create an HTTP server
- var srv = http.createServer(function (req, res) {
- res.writeHead(200, {'Content-Type': 'text/plain'});
- res.end('okay');
- });
- srv.on('upgrade', function(req, socket, upgradeHead) {
- socket.write('HTTP/1.1 101 Web Socket Protocol Handshake\r\n' +
- 'Upgrade: WebSocket\r\n' +
- 'Connection: Upgrade\r\n' +
- '\r\n\r\n');
-
- socket.ondata = function(data, start, end) {
- socket.write(data.toString('utf8', start, end), 'utf8'); // echo back
- };
- });
-
- // now that server is running
- 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: {
- 'Connection': 'Upgrade',
- 'Upgrade': 'websocket'
- }
- };
-
- var req = http.request(options);
- req.end();
-
- agent.on('upgrade', function(res, socket, upgradeHead) {
- console.log('got upgraded!');
- socket.end();
- process.exit(0);
- });
- });
+## http.globalAgent
-
-### Event: 'continue'
-
-`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.
+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.
+By default set to 5. Determines how many concurrent sockets the agent can have open per host.
### agent.sockets
-An array of sockets currently in use by the Agent. Do not modify.
-
-### agent.queue
+An object which contains arrays of sockets currently in use by the Agent. Do not modify.
-A queue of requests waiting to be sent to sockets.
+### agent.requests
+An object which contains queues of requests that have not yet been assigned to sockets. Do not modify.
## http.ClientRequest
});
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:
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:
+
+- `host`: A domain name or IP address of the server to issue the request to.
+- `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) { }`
+
+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
+their connections closed.
+
+A client server pair that show you how to listen for the `upgrade` event using `http.getAgent`:
+
+ var http = require('http');
+ var net = require('net');
+
+ // Create an HTTP server
+ var srv = http.createServer(function (req, res) {
+ res.writeHead(200, {'Content-Type': 'text/plain'});
+ res.end('okay');
+ });
+ srv.on('upgrade', function(req, socket, upgradeHead) {
+ socket.write('HTTP/1.1 101 Web Socket Protocol Handshake\r\n' +
+ 'Upgrade: WebSocket\r\n' +
+ 'Connection: Upgrade\r\n' +
+ '\r\n\r\n');
+
+ socket.ondata = function(data, start, end) {
+ socket.write(data.toString('utf8', start, end), 'utf8'); // echo back
+ };
+ });
+
+ // now that server is running
+ srv.listen(1337, '127.0.0.1', function() {
+
+ // make a request
+ var options = {
+ port: 1337,
+ host: '127.0.0.1',
+ headers: {
+ 'Connection': 'Upgrade',
+ 'Upgrade': 'websocket'
+ }
+ };
+
+ var req = http.request(options);
+ req.end();
+
+ req.on('upgrade', function(res, socket, upgradeHead) {
+ console.log('got upgraded!');
+ socket.end();
+ process.exit(0);
+ });
+ });
+
+### Event: 'continue'
+
+`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.
### request.write(chunk, encoding='utf8')
### 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