diff --git a/doc/api/http.markdown b/doc/api/http.markdown index 8ac89b1f388..2e4775398c6 100644 --- a/doc/api/http.markdown +++ b/doc/api/http.markdown @@ -43,63 +43,365 @@ list like the following: 'Host', 'mysite.com', 'accepT', '*/*' ] -## http.METHODS +## Class: http.Agent -* {Array} +The HTTP Agent is used for pooling sockets used in HTTP client +requests. -A list of the HTTP methods that are supported by the parser. +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. -## http.STATUS_CODES +If you opt into using HTTP KeepAlive, you can create an Agent object +with that flag set to `true`. (See the [constructor +options](#http_new_agent_options) below.) 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()`](#http_agent_destroy) +KeepAlive agents when they are no longer in use, so that the Sockets +will be shut down. -* {Object} +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 +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: -A collection of all the standard HTTP response status codes, and the -short description of each. For example, `http.STATUS_CODES[404] === 'Not -Found'`. + http.get(options, function(res) { + // Do stuff + }).on("socket", function (socket) { + socket.emit("agentRemove"); + }); -## http.createServer([requestListener]) +Alternatively, you could just opt out of pooling entirely using +`agent:false`: -Returns a new instance of [http.Server](#http_class_http_server). + http.get({ + hostname: 'localhost', + port: 80, + path: '/', + agent: false // create a new agent just for this one request + }, function (res) { + // Do stuff with response + }) -The `requestListener` is a function which is automatically -added to the `'request'` event. +### new Agent([options]) -## http.createClient([port][, host]) +* `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`. + * `maxSockets` {Number} Maximum number of sockets to allow per + host. Default = `Infinity`. + * `maxFreeSockets` {Number} Maximum number of sockets to leave open + in a free state. Only relevant if `keepAlive` is set to `true`. + Default = `256`. - Stability: 0 - Deprecated: Use [http.request][] instead. +The default `http.globalAgent` that is used by `http.request` has all +of these values set to their respective defaults. -Constructs a new HTTP client. `port` and `host` refer to the server to be -connected to. +To configure any of them, you must create your own `Agent` object. + +```javascript +var http = require('http'); +var keepAliveAgent = new http.Agent({ keepAlive: true }); +options.agent = keepAliveAgent; +http.request(options, onResponseCallback); +``` + +### agent.destroy() + +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 +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. + +### agent.freeSockets + +An object which contains arrays of sockets currently awaiting use by +the Agent when HTTP KeepAlive is used. Do not modify. + +### agent.getName(options) + +Get a unique name for a set of request options, to determine whether a +connection can be reused. In the http agent, this returns +`host:port:localAddress`. In the https agent, the name includes the +CA, cert, ciphers, and other HTTPS/TLS-specific options that determine +socket reusability. + +### agent.maxFreeSockets + +By default set to 256. For Agents supporting HTTP KeepAlive, this +sets the maximum number of sockets that will be left open in the free +state. + +### agent.maxSockets + +By default set to Infinity. Determines how many concurrent sockets the agent +can have open per origin. Origin is either a 'host:port' or +'host:port:localAddress' combination. + +### agent.requests + +An object which contains queues of requests that have not yet been assigned to +sockets. Do not modify. + +### agent.sockets + +An object which contains arrays of sockets currently in use by the +Agent. Do not modify. + +## Class: 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.IncomingMessage][]. + +During the `'response'` event, one can add listeners to the +response object; particularly to listen for the `'data'` event. + +If no `'response'` handler is added, then the response will be +entirely discarded. However, if you add a `'response'` event handler, +then you **must** consume the data from the response object, either by +calling `response.read()` whenever there is a `'readable'` event, or +by adding a `'data'` handler, or by calling the `.resume()` method. +Until the data is consumed, the `'end'` event will not fire. Also, until +the data is read it will consume memory that can eventually lead to a +'process out of memory' error. + +Note: Node.js does not check whether Content-Length and the length of the body +which has been transmitted are equal or not. + +The request implements the [Writable Stream][] interface. This is an +[EventEmitter][] with the following events: + +### Event: 'abort' + +`function () { }` + +Emitted when the request has been aborted by the client. This event is only +emitted on the first call to `abort()`. + +### Event: 'connect' + +`function (response, socket, head) { }` + +Emitted each time a server responds to a request with a CONNECT method. If this +event isn't being listened for, clients receiving a CONNECT method will have +their connections closed. + +A client server pair that show you how to listen for the `connect` event. + + var http = require('http'); + var net = require('net'); + var url = require('url'); + + // Create an HTTP tunneling proxy + var proxy = http.createServer(function (req, res) { + res.writeHead(200, {'Content-Type': 'text/plain'}); + res.end('okay'); + }); + proxy.on('connect', function(req, cltSocket, head) { + // connect to an origin server + var srvUrl = url.parse('http://' + req.url); + var srvSocket = net.connect(srvUrl.port, srvUrl.hostname, function() { + cltSocket.write('HTTP/1.1 200 Connection Established\r\n' + + 'Proxy-agent: Node.js-Proxy\r\n' + + '\r\n'); + srvSocket.write(head); + srvSocket.pipe(cltSocket); + cltSocket.pipe(srvSocket); + }); + }); + + // now that proxy is running + proxy.listen(1337, '127.0.0.1', function() { + + // make a request to a tunneling proxy + var options = { + port: 1337, + hostname: '127.0.0.1', + method: 'CONNECT', + path: 'www.google.com:80' + }; + + var req = http.request(options); + req.end(); + + req.on('connect', function(res, socket, head) { + console.log('got connected!'); + + // make a request over an HTTP tunnel + socket.write('GET / HTTP/1.1\r\n' + + 'Host: www.google.com:80\r\n' + + 'Connection: close\r\n' + + '\r\n'); + socket.on('data', function(chunk) { + console.log(chunk.toString()); + }); + socket.on('end', function() { + proxy.close(); + }); + }); + }); + +### 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. + +### 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.IncomingMessage][]. + +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. + + var http = require('http'); + + // 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, head) { + socket.write('HTTP/1.1 101 Web Socket Protocol Handshake\r\n' + + 'Upgrade: WebSocket\r\n' + + 'Connection: Upgrade\r\n' + + '\r\n'); + + socket.pipe(socket); // echo back + }); + + // now that server is running + srv.listen(1337, '127.0.0.1', function() { + + // make a request + var options = { + port: 1337, + hostname: '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); + }); + }); + +### request.abort() + +Marks the request as aborting. Calling this will cause remaining data +in the response to be dropped and the socket to be destroyed. + +### request.end([data][, encoding][, callback]) + +Finishes sending the request. If any parts of the body are +unsent, it will flush them to the stream. If the request is +chunked, this will send the terminating `'0\r\n\r\n'`. + +If `data` is specified, it is equivalent to calling +`request.write(data, encoding)` followed by `request.end(callback)`. + +If `callback` is specified, it will be called when the request stream +is finished. + +### request.flushHeaders() + +Flush the request headers. + +For efficiency reasons, Node.js normally buffers the request headers until you +call `request.end()` or write the first chunk of request data. It then tries +hard to pack the request headers and data into a single TCP packet. + +That's usually what you want (it saves a TCP round-trip) but not when the first +data isn't sent until possibly much later. `request.flushHeaders()` lets you bypass +the optimization and kickstart the request. + +### request.setNoDelay([noDelay]) + +Once a socket is assigned to this request and is connected +[socket.setNoDelay()][] will be called. + +### request.setSocketKeepAlive([enable][, initialDelay]) + +Once a socket is assigned to this request and is connected +[socket.setKeepAlive()][] will be called. + +### request.setTimeout(timeout[, callback]) + +Once a socket is assigned to this request and is connected +[socket.setTimeout()][] will be called. + +### request.write(chunk[, encoding][, callback]) + +Sends a chunk of the body. By calling this method +many times, the user can stream a request body to a +server--in that case it is suggested to use the +`['Transfer-Encoding', 'chunked']` header line when +creating the request. + +The `chunk` argument should be a [Buffer][] or a string. + +The `encoding` argument is optional and only applies when `chunk` is a string. +Defaults to `'utf8'`. + +The `callback` argument is optional and will be called when this chunk of data +is flushed. + +Returns `request`. ## Class: http.Server This is an [EventEmitter][] with the following events: -### Event: 'request' - -`function (request, response) { }` - -Emitted each time there is a request. Note that there may be multiple requests -per connection (in the case of keep-alive connections). - `request` is an instance of [http.IncomingMessage][] and `response` is -an instance of [http.ServerResponse][]. - -### Event: 'connection' - -`function (socket) { }` - -When a new TCP stream is established. `socket` is an object of type -`net.Socket`. Usually users will not want to access this event. In -particular, the socket will not emit `readable` events because of how -the protocol parser attaches to the socket. The `socket` can also be -accessed at `request.connection`. - -### Event: 'close' - -`function () { }` - -Emitted when the server closes. - ### Event: 'checkContinue' `function (request, response) { }` @@ -116,6 +418,20 @@ request body. Note that when this event is emitted and handled, the `request` event will not be emitted. +### Event: 'clientError' + +`function (exception, socket) { }` + +If a client connection emits an 'error' event, it will be forwarded here. + +`socket` is the `net.Socket` object that the error originated from. + +### Event: 'close' + +`function () { }` + +Emitted when the server closes. + ### Event: 'connect' `function (request, socket, head) { }` @@ -134,6 +450,25 @@ After this event is emitted, the request's socket will not have a `data` event listener, meaning you will need to bind to it in order to handle data sent to the server on that socket. +### Event: 'connection' + +`function (socket) { }` + +When a new TCP stream is established. `socket` is an object of type +`net.Socket`. Usually users will not want to access this event. In +particular, the socket will not emit `readable` events because of how +the protocol parser attaches to the socket. The `socket` can also be +accessed at `request.connection`. + +### Event: 'request' + +`function (request, response) { }` + +Emitted each time there is a request. Note that there may be multiple requests +per connection (in the case of keep-alive connections). + `request` is an instance of [http.IncomingMessage][] and `response` is +an instance of [http.ServerResponse][]. + ### Event: 'upgrade' `function (request, socket, head) { }` @@ -152,40 +487,9 @@ After this event is emitted, the request's socket will not have a `data` event listener, meaning you will need to bind to it in order to handle data sent to the server on that socket. -### Event: 'clientError' - -`function (exception, socket) { }` - -If a client connection emits an 'error' event, it will be forwarded here. - -`socket` is the `net.Socket` object that the error originated from. - - -### server.listen(port[, hostname][, backlog][, callback]) - -Begin accepting connections on the specified `port` and `hostname`. If the -`hostname` is omitted, the server will accept connections on any IPv6 address -(`::`) when IPv6 is available, or any IPv4 address (`0.0.0.0`) otherwise. A -port value of zero will assign a random port. - -To listen to a unix socket, supply a filename instead of port and hostname. - -Backlog is the maximum length of the queue of pending connections. -The actual length will be determined by your OS through sysctl settings such as -`tcp_max_syn_backlog` and `somaxconn` on linux. The default value of this -parameter is 511 (not 512). - -This function is asynchronous. The last parameter `callback` will be added as -a listener for the ['listening'][] event. See also [net.Server.listen(port)][]. - - -### server.listen(path[, callback]) - -Start a UNIX socket server listening for connections on the given `path`. - -This function is asynchronous. The last parameter `callback` will be added as -a listener for the ['listening'][] event. See also [net.Server.listen(path)][]. +### server.close([callback]) +Stops the server from accepting new connections. See [net.Server.close()][]. ### server.listen(handle[, callback]) @@ -205,10 +509,29 @@ This function is asynchronous. The last parameter `callback` will be added as a listener for the ['listening'](net.html#net_event_listening) event. See also [net.Server.listen()](net.html#net_server_listen_handle_callback). -### server.close([callback]) +### server.listen(path[, callback]) -Stops the server from accepting new connections. See [net.Server.close()][]. +Start a UNIX socket server listening for connections on the given `path`. +This function is asynchronous. The last parameter `callback` will be added as +a listener for the ['listening'][] event. See also [net.Server.listen(path)][]. + +### server.listen(port[, hostname][, backlog][, callback]) + +Begin accepting connections on the specified `port` and `hostname`. If the +`hostname` is omitted, the server will accept connections on any IPv6 address +(`::`) when IPv6 is available, or any IPv4 address (`0.0.0.0`) otherwise. A +port value of zero will assign a random port. + +To listen to a unix socket, supply a filename instead of port and hostname. + +Backlog is the maximum length of the queue of pending connections. +The actual length will be determined by your OS through sysctl settings such as +`tcp_max_syn_backlog` and `somaxconn` on linux. The default value of this +parameter is 511 (not 512). + +This function is asynchronous. The last parameter `callback` will be added as +a listener for the ['listening'][] event. See also [net.Server.listen(port)][]. ### server.maxHeadersCount @@ -274,37 +597,91 @@ does not imply that the client has received anything yet. After this event, no more events will be emitted on the response object. -### response.writeContinue() +### response.addTrailers(headers) -Sends a HTTP/1.1 100 Continue message to the client, indicating that -the request body should be sent. See the ['checkContinue'][] event on `Server`. +This method adds HTTP trailing headers (a header but at the end of the +message) to the response. -### response.writeHead(statusCode[, statusMessage][, headers]) +Trailers will **only** be emitted if chunked encoding is used for the +response; if it is not (e.g., if the request was HTTP/1.0), they will +be silently discarded. -Sends a response header to the request. The status code is a 3-digit HTTP -status code, like `404`. The last argument, `headers`, are the response headers. -Optionally one can give a human-readable `statusMessage` as the second -argument. +Note that HTTP requires the `Trailer` header to be sent if you intend to +emit trailers, with a list of the header fields in its value. E.g., + + response.writeHead(200, { 'Content-Type': 'text/plain', + 'Trailer': 'Content-MD5' }); + response.write(fileData); + response.addTrailers({'Content-MD5': "7895bf4b8828b55ceaf47747b4bca667"}); + response.end(); + +Attempting to set a trailer field name that contains invalid characters will +result in a `TypeError` being thrown. + +### response.end([data][, encoding][, callback]) + +This method signals to the server that all of the response headers and body +have been sent; that server should consider this message complete. +The method, `response.end()`, MUST be called on each +response. + +If `data` is specified, it is equivalent to calling +`response.write(data, encoding)` followed by `response.end(callback)`. + +If `callback` is specified, it will be called when the response stream +is finished. + +### response.finished + +Boolean value that indicates whether the response has completed. Starts +as `false`. After `response.end()` executes, the value will be `true`. + +### response.getHeader(name) + +Reads out a header that's already been queued but not sent to the client. Note +that the name is case insensitive. This can only be called before headers get +implicitly flushed. Example: - var body = 'hello world'; - response.writeHead(200, { - 'Content-Length': body.length, - 'Content-Type': 'text/plain' }); + var contentType = response.getHeader('content-type'); -This method must only be called once on a message and it must -be called before [response.end()][] is called. +### response.headersSent -If you call [response.write()][] or [response.end()][] before calling this, the -implicit/mutable headers will be calculated and call this function for you. +Boolean (read-only). True if headers were sent, false otherwise. -Note that Content-Length is given in bytes not characters. The above example -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.js does not check whether Content-Length and the length of the body -which has been transmitted are equal or not. +### response.removeHeader(name) + +Removes a header that's queued for implicit sending. + +Example: + + response.removeHeader("Content-Encoding"); + +### response.sendDate + +When true, the Date header will be automatically generated and sent in +the response if it is not already present in the headers. Defaults to true. + +This should only be disabled for testing; HTTP requires the Date header +in responses. + +### response.setHeader(name, value) + +Sets a single header value for implicit headers. If this header already exists +in the to-be-sent headers, its value will be replaced. Use an array of strings +here if you need to send multiple headers with the same name. + +Example: + + response.setHeader("Content-Type", "text/html"); + +or + + response.setHeader("Set-Cookie", ["type=ninja", "language=javascript"]); + +Attempting to set a header field name that contains invalid characters will +result in a `TypeError` being thrown. ### response.setTimeout(msecs, callback) @@ -350,54 +727,6 @@ Example: After response header was sent to the client, this property indicates the status message which was sent out. -### response.setHeader(name, value) - -Sets a single header value for implicit headers. If this header already exists -in the to-be-sent headers, its value will be replaced. Use an array of strings -here if you need to send multiple headers with the same name. - -Example: - - response.setHeader("Content-Type", "text/html"); - -or - - response.setHeader("Set-Cookie", ["type=ninja", "language=javascript"]); - -Attempting to set a header field name that contains invalid characters will -result in a `TypeError` being thrown. - -### response.headersSent - -Boolean (read-only). True if headers were sent, false otherwise. - -### response.sendDate - -When true, the Date header will be automatically generated and sent in -the response if it is not already present in the headers. Defaults to true. - -This should only be disabled for testing; HTTP requires the Date header -in responses. - -### response.getHeader(name) - -Reads out a header that's already been queued but not sent to the client. Note -that the name is case insensitive. This can only be called before headers get -implicitly flushed. - -Example: - - var contentType = response.getHeader('content-type'); - -### response.removeHeader(name) - -Removes a header that's queued for implicit sending. - -Example: - - response.removeHeader("Content-Encoding"); - - ### response.write(chunk[, encoding][, callback]) If this method is called and [response.writeHead()][] has not been called, @@ -424,44 +753,224 @@ Returns `true` if the entire data was flushed successfully to the kernel buffer. Returns `false` if all or part of the data was queued in user memory. `'drain'` will be emitted when the buffer is free again. -### response.addTrailers(headers) +### response.writeContinue() -This method adds HTTP trailing headers (a header but at the end of the -message) to the response. +Sends a HTTP/1.1 100 Continue message to the client, indicating that +the request body should be sent. See the ['checkContinue'][] event on `Server`. -Trailers will **only** be emitted if chunked encoding is used for the -response; if it is not (e.g., if the request was HTTP/1.0), they will -be silently discarded. +### response.writeHead(statusCode[, statusMessage][, headers]) -Note that HTTP requires the `Trailer` header to be sent if you intend to -emit trailers, with a list of the header fields in its value. E.g., +Sends a response header to the request. The status code is a 3-digit HTTP +status code, like `404`. The last argument, `headers`, are the response headers. +Optionally one can give a human-readable `statusMessage` as the second +argument. - response.writeHead(200, { 'Content-Type': 'text/plain', - 'Trailer': 'Content-MD5' }); - response.write(fileData); - response.addTrailers({'Content-MD5': "7895bf4b8828b55ceaf47747b4bca667"}); - response.end(); +Example: -Attempting to set a trailer field name that contains invalid characters will -result in a `TypeError` being thrown. + var body = 'hello world'; + response.writeHead(200, { + 'Content-Length': body.length, + 'Content-Type': 'text/plain' }); -### response.end([data][, encoding][, callback]) +This method must only be called once on a message and it must +be called before [response.end()][] is called. -This method signals to the server that all of the response headers and body -have been sent; that server should consider this message complete. -The method, `response.end()`, MUST be called on each -response. +If you call [response.write()][] or [response.end()][] before calling this, the +implicit/mutable headers will be calculated and call this function for you. -If `data` is specified, it is equivalent to calling -`response.write(data, encoding)` followed by `response.end(callback)`. +Note that Content-Length is given in bytes not characters. The above example +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.js does not check whether Content-Length and the length of the body +which has been transmitted are equal or not. -If `callback` is specified, it will be called when the response stream -is finished. +## http.IncomingMessage -### response.finished +An `IncomingMessage` object is created by [http.Server][] or +[http.ClientRequest][] and passed as the first argument to the `'request'` +and `'response'` event respectively. It may be used to access response status, +headers and data. -Boolean value that indicates whether the response has completed. Starts -as `false`. After `response.end()` executes, the value will be `true`. +It implements the [Readable Stream][] interface, as well as the +following additional events, methods, and properties. + +### Event: 'close' + +`function () { }` + +Indicates that the underlying connection was closed. +Just like `'end'`, this event occurs only once per response. + +### message.headers + +The request/response headers object. + +Read only map of header names and values. Header names are lower-cased. +Example: + + // Prints something like: + // + // { 'user-agent': 'curl/7.22.0', + // host: '127.0.0.1:8000', + // accept: '*/*' } + console.log(request.headers); + +### message.httpVersion + +In case of server request, the HTTP version sent by the client. In the case of +client response, the HTTP version of the connected-to server. +Probably either `'1.1'` or `'1.0'`. + +Also `response.httpVersionMajor` is the first integer and +`response.httpVersionMinor` is the second. + +### message.method + +**Only valid for request obtained from [http.Server][].** + +The request method as a string. Read only. Example: +`'GET'`, `'DELETE'`. + +### message.rawHeaders + +The raw request/response headers list exactly as they were received. + +Note that the keys and values are in the same list. It is *not* a +list of tuples. So, the even-numbered offsets are key values, and the +odd-numbered offsets are the associated values. + +Header names are not lowercased, and duplicates are not merged. + + // Prints something like: + // + // [ 'user-agent', + // 'this is invalid because there can be only one', + // 'User-Agent', + // 'curl/7.22.0', + // 'Host', + // '127.0.0.1:8000', + // 'ACCEPT', + // '*/*' ] + console.log(request.rawHeaders); + +### message.rawTrailers + +The raw request/response trailer keys and values exactly as they were +received. Only populated at the 'end' event. + +### message.setTimeout(msecs, callback) + +* `msecs` {Number} +* `callback` {Function} + +Calls `message.connection.setTimeout(msecs, callback)`. + +Returns `message`. + +### message.statusCode + +**Only valid for response obtained from `http.ClientRequest`.** + +The 3-digit HTTP response status code. E.G. `404`. + +### message.statusMessage + +**Only valid for response obtained from `http.ClientRequest`.** + +### message.socket + +The `net.Socket` object associated with the connection. + +With HTTPS support, use [request.socket.getPeerCertificate()][] to obtain the +client's authentication details. + +The HTTP response status message (reason phrase). E.G. `OK` or `Internal Server Error`. + +### message.trailers + +The request/response trailers object. Only populated at the 'end' event. + +### message.url + +**Only valid for request obtained from [http.Server][].** + +Request URL string. This contains only the URL that is +present in the actual HTTP request. If the request is: + + GET /status?name=ryan HTTP/1.1\r\n + Accept: text/plain\r\n + \r\n + +Then `request.url` will be: + + '/status?name=ryan' + +If you would like to parse the URL into its parts, you can use +`require('url').parse(request.url)`. Example: + + node> require('url').parse('/status?name=ryan') + { href: '/status?name=ryan', + search: '?name=ryan', + query: 'name=ryan', + pathname: '/status' } + +If you would like to extract the params from the query string, +you can use the `require('querystring').parse` function, or pass +`true` as the second argument to `require('url').parse`. Example: + + node> require('url').parse('/status?name=ryan', true) + { href: '/status?name=ryan', + search: '?name=ryan', + query: { name: 'ryan' }, + pathname: '/status' } + +## http.METHODS + +* {Array} + +A list of the HTTP methods that are supported by the parser. + +## http.STATUS_CODES + +* {Object} + +A collection of all the standard HTTP response status codes, and the +short description of each. For example, `http.STATUS_CODES[404] === 'Not +Found'`. + +## http.createClient([port][, host]) + + Stability: 0 - Deprecated: Use [http.request][] instead. + +Constructs a new HTTP client. `port` and `host` refer to the server to be +connected to. + +## http.createServer([requestListener]) + +Returns a new instance of [http.Server](#http_class_http_server). + +The `requestListener` is a function which is automatically +added to the `'request'` event. + +## http.get(options[, callback]) + +Since most requests are GET requests without bodies, Node.js provides this +convenience method. The only difference between this method and `http.request()` +is that it sets the method to GET and calls `req.end()` automatically. + +Example: + + http.get("http://www.google.com/index.html", function(res) { + console.log("Got response: " + res.statusCode); + }).on('error', function(e) { + console.log("Got error: " + e.message); + }); + +## http.globalAgent + +Global instance of Agent which is used as the default for all http client +requests. ## http.request(options[, callback]) @@ -566,525 +1075,6 @@ There are a few special headers that should be noted. * Sending an Authorization header will override using the `auth` option to compute basic authentication. -## http.get(options[, callback]) - -Since most requests are GET requests without bodies, Node.js provides this -convenience method. The only difference between this method and `http.request()` -is that it sets the method to GET and calls `req.end()` automatically. - -Example: - - http.get("http://www.google.com/index.html", function(res) { - console.log("Got response: " + res.statusCode); - }).on('error', function(e) { - console.log("Got error: " + e.message); - }); - - -## Class: http.Agent - -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](#http_new_agent_options) below.) 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()`](#http_agent_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 -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: - - http.get(options, function(res) { - // Do stuff - }).on("socket", function (socket) { - socket.emit("agentRemove"); - }); - -Alternatively, you could just opt out of pooling entirely using -`agent:false`: - - http.get({ - hostname: 'localhost', - port: 80, - path: '/', - agent: false // create a new agent just for this one request - }, function (res) { - // Do stuff with response - }) - -### new Agent([options]) - -* `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`. - * `maxSockets` {Number} Maximum number of sockets to allow per - host. Default = `Infinity`. - * `maxFreeSockets` {Number} Maximum number of sockets to leave open - in a free state. Only relevant if `keepAlive` is set to `true`. - Default = `256`. - -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 `Agent` object. - -```javascript -var http = require('http'); -var keepAliveAgent = new http.Agent({ keepAlive: true }); -options.agent = keepAliveAgent; -http.request(options, onResponseCallback); -``` - -### agent.maxSockets - -By default set to Infinity. Determines how many concurrent sockets the agent -can have open per origin. Origin is either a 'host:port' or -'host:port:localAddress' combination. - -### agent.maxFreeSockets - -By default set to 256. For Agents supporting HTTP KeepAlive, this -sets the maximum number of sockets that will be left open in the free -state. - -### agent.sockets - -An object which contains arrays of sockets currently in use by the -Agent. Do not modify. - -### agent.freeSockets - -An object which contains arrays of sockets currently awaiting use by -the Agent when HTTP KeepAlive is used. Do not modify. - -### agent.requests - -An object which contains queues of requests that have not yet been assigned to -sockets. Do not modify. - -### agent.destroy() - -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 -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. - -### agent.getName(options) - -Get a unique name for a set of request options, to determine whether a -connection can be reused. In the http agent, this returns -`host:port:localAddress`. In the https agent, the name includes the -CA, cert, ciphers, and other HTTPS/TLS-specific options that determine -socket reusability. - - -## http.globalAgent - -Global instance of Agent which is used as the default for all http client -requests. - - -## Class: 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.IncomingMessage][]. - -During the `'response'` event, one can add listeners to the -response object; particularly to listen for the `'data'` event. - -If no `'response'` handler is added, then the response will be -entirely discarded. However, if you add a `'response'` event handler, -then you **must** consume the data from the response object, either by -calling `response.read()` whenever there is a `'readable'` event, or -by adding a `'data'` handler, or by calling the `.resume()` method. -Until the data is consumed, the `'end'` event will not fire. Also, until -the data is read it will consume memory that can eventually lead to a -'process out of memory' error. - -Note: Node.js does not check whether Content-Length and the length of the body -which has been transmitted are equal or not. - -The request implements the [Writable Stream][] interface. 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.IncomingMessage][]. - -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: 'connect' - -`function (response, socket, head) { }` - -Emitted each time a server responds to a request with a CONNECT method. If this -event isn't being listened for, clients receiving a CONNECT method will have -their connections closed. - -A client server pair that show you how to listen for the `connect` event. - - var http = require('http'); - var net = require('net'); - var url = require('url'); - - // Create an HTTP tunneling proxy - var proxy = http.createServer(function (req, res) { - res.writeHead(200, {'Content-Type': 'text/plain'}); - res.end('okay'); - }); - proxy.on('connect', function(req, cltSocket, head) { - // connect to an origin server - var srvUrl = url.parse('http://' + req.url); - var srvSocket = net.connect(srvUrl.port, srvUrl.hostname, function() { - cltSocket.write('HTTP/1.1 200 Connection Established\r\n' + - 'Proxy-agent: Node.js-Proxy\r\n' + - '\r\n'); - srvSocket.write(head); - srvSocket.pipe(cltSocket); - cltSocket.pipe(srvSocket); - }); - }); - - // now that proxy is running - proxy.listen(1337, '127.0.0.1', function() { - - // make a request to a tunneling proxy - var options = { - port: 1337, - hostname: '127.0.0.1', - method: 'CONNECT', - path: 'www.google.com:80' - }; - - var req = http.request(options); - req.end(); - - req.on('connect', function(res, socket, head) { - console.log('got connected!'); - - // make a request over an HTTP tunnel - socket.write('GET / HTTP/1.1\r\n' + - 'Host: www.google.com:80\r\n' + - 'Connection: close\r\n' + - '\r\n'); - socket.on('data', function(chunk) { - console.log(chunk.toString()); - }); - socket.on('end', function() { - proxy.close(); - }); - }); - }); - -### 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. - - var http = require('http'); - - // 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, head) { - socket.write('HTTP/1.1 101 Web Socket Protocol Handshake\r\n' + - 'Upgrade: WebSocket\r\n' + - 'Connection: Upgrade\r\n' + - '\r\n'); - - socket.pipe(socket); // echo back - }); - - // now that server is running - srv.listen(1337, '127.0.0.1', function() { - - // make a request - var options = { - port: 1337, - hostname: '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. - -### Event: 'abort' - -`function () { }` - -Emitted when the request has been aborted by the client. This event is only -emitted on the first call to `abort()`. - -### request.flushHeaders() - -Flush the request headers. - -For efficiency reasons, Node.js normally buffers the request headers until you -call `request.end()` or write the first chunk of request data. It then tries -hard to pack the request headers and data into a single TCP packet. - -That's usually what you want (it saves a TCP round-trip) but not when the first -data isn't sent until possibly much later. `request.flushHeaders()` lets you bypass -the optimization and kickstart the request. - -### request.write(chunk[, encoding][, callback]) - -Sends a chunk of the body. By calling this method -many times, the user can stream a request body to a -server--in that case it is suggested to use the -`['Transfer-Encoding', 'chunked']` header line when -creating the request. - -The `chunk` argument should be a [Buffer][] or a string. - -The `encoding` argument is optional and only applies when `chunk` is a string. -Defaults to `'utf8'`. - -The `callback` argument is optional and will be called when this chunk of data -is flushed. - -### request.end([data][, encoding][, callback]) - -Finishes sending the request. If any parts of the body are -unsent, it will flush them to the stream. If the request is -chunked, this will send the terminating `'0\r\n\r\n'`. - -If `data` is specified, it is equivalent to calling -`request.write(data, encoding)` followed by `request.end(callback)`. - -If `callback` is specified, it will be called when the request stream -is finished. - -### request.abort() - -Marks the request as aborting. Calling this will cause remaining data -in the response to be dropped and the socket to be destroyed. - -### request.setTimeout(timeout[, callback]) - -Once a socket is assigned to this request and is connected -[socket.setTimeout()][] will be called. - -Returns `request`. - -### request.setNoDelay([noDelay]) - -Once a socket is assigned to this request and is connected -[socket.setNoDelay()][] will be called. - -### request.setSocketKeepAlive([enable][, initialDelay]) - -Once a socket is assigned to this request and is connected -[socket.setKeepAlive()][] will be called. - - -## http.IncomingMessage - -An `IncomingMessage` object is created by [http.Server][] or -[http.ClientRequest][] and passed as the first argument to the `'request'` -and `'response'` event respectively. It may be used to access response status, -headers and data. - -It implements the [Readable Stream][] interface, as well as the -following additional events, methods, and properties. - -### Event: 'close' - -`function () { }` - -Indicates that the underlying connection was closed. -Just like `'end'`, this event occurs only once per response. - -### message.httpVersion - -In case of server request, the HTTP version sent by the client. In the case of -client response, the HTTP version of the connected-to server. -Probably either `'1.1'` or `'1.0'`. - -Also `response.httpVersionMajor` is the first integer and -`response.httpVersionMinor` is the second. - -### message.headers - -The request/response headers object. - -Read only map of header names and values. Header names are lower-cased. -Example: - - // Prints something like: - // - // { 'user-agent': 'curl/7.22.0', - // host: '127.0.0.1:8000', - // accept: '*/*' } - console.log(request.headers); - -### message.rawHeaders - -The raw request/response headers list exactly as they were received. - -Note that the keys and values are in the same list. It is *not* a -list of tuples. So, the even-numbered offsets are key values, and the -odd-numbered offsets are the associated values. - -Header names are not lowercased, and duplicates are not merged. - - // Prints something like: - // - // [ 'user-agent', - // 'this is invalid because there can be only one', - // 'User-Agent', - // 'curl/7.22.0', - // 'Host', - // '127.0.0.1:8000', - // 'ACCEPT', - // '*/*' ] - console.log(request.rawHeaders); - -### message.trailers - -The request/response trailers object. Only populated at the 'end' event. - -### message.rawTrailers - -The raw request/response trailer keys and values exactly as they were -received. Only populated at the 'end' event. - -### message.setTimeout(msecs, callback) - -* `msecs` {Number} -* `callback` {Function} - -Calls `message.connection.setTimeout(msecs, callback)`. - -Returns `message`. - -### message.method - -**Only valid for request obtained from [http.Server][].** - -The request method as a string. Read only. Example: -`'GET'`, `'DELETE'`. - -### message.url - -**Only valid for request obtained from [http.Server][].** - -Request URL string. This contains only the URL that is -present in the actual HTTP request. If the request is: - - GET /status?name=ryan HTTP/1.1\r\n - Accept: text/plain\r\n - \r\n - -Then `request.url` will be: - - '/status?name=ryan' - -If you would like to parse the URL into its parts, you can use -`require('url').parse(request.url)`. Example: - - node> require('url').parse('/status?name=ryan') - { href: '/status?name=ryan', - search: '?name=ryan', - query: 'name=ryan', - pathname: '/status' } - -If you would like to extract the params from the query string, -you can use the `require('querystring').parse` function, or pass -`true` as the second argument to `require('url').parse`. Example: - - node> require('url').parse('/status?name=ryan', true) - { href: '/status?name=ryan', - search: '?name=ryan', - query: { name: 'ryan' }, - pathname: '/status' } - -### message.statusCode - -**Only valid for response obtained from `http.ClientRequest`.** - -The 3-digit HTTP response status code. E.G. `404`. - -### message.statusMessage - -**Only valid for response obtained from `http.ClientRequest`.** - -The HTTP response status message (reason phrase). E.G. `OK` or `Internal Server Error`. - -### message.socket - -The `net.Socket` object associated with the connection. - -With HTTPS support, use [request.socket.getPeerCertificate()][] to obtain the -client's authentication details. - - ['checkContinue']: #http_event_checkcontinue ['listening']: net.html#net_event_listening ['response']: #http_event_response