@ -25,7 +25,7 @@ HTTP API is very low-level. It deals with stream handling and message
parsing only. It parses a message into headers and body but it does not
parse the actual headers or the body.
See [message.headers][] for details on how duplicate headers are handled.
See [` message.headers` ][] for details on how duplicate headers are handled.
The raw headers as they were received are retained in the `rawHeaders`
property, which is an array of `[key, value, key2, value2, ...]` . For
@ -60,7 +60,7 @@ 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
a `'close'` event or a special `'agentRemove'`
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:
@ -97,10 +97,10 @@ Alternatively, you could just opt out of pooling entirely using
in a free state. Only relevant if `keepAlive` is set to `true` .
Default = `256` .
The default `http.globalAgent` that is used by `http.request`
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`
To configure any of them, you must create your own [`http.Agent`][] object.
```javascript
var http = require('http');
@ -156,7 +156,7 @@ Agent. Do not modify.
## Class: http.ClientRequest
This object is created internally and returned from `http.request()`
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
@ -165,7 +165,7 @@ 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][].
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.
@ -183,7 +183,7 @@ 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:
[` EventEmitter` ][] with the following events:
### Event: 'abort'
@ -196,11 +196,11 @@ emitted on the first call to `abort()`.
`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
Emitted each time a server responds to a request with a ` CONNECT`
event isn't being listened for, clients receiving a ` CONNECT`
their connections closed.
A client server pair that show you how to listen for the `connect` event.
A client server pair that show you how to listen for the `' connect' ` event.
var http = require('http');
var net = require('net');
@ -268,7 +268,7 @@ the client should send the request body.
`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][].
once. The `response` argument will be an instance of [` http.IncomingMessage` ][].
Options:
@ -290,7 +290,7 @@ 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.
A client server pair that show you how to listen for the `' upgrade' ` event.
var http = require('http');
@ -343,7 +343,7 @@ 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)` `request.end(callback)` .
[`response.write(data, encoding)`][] followed by `request.end(callback)` .
If `callback` is specified, it will be called when the request stream
is finished.
@ -363,17 +363,17 @@ 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.
[` 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.
[` 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.
[` socket.setTimeout()` ][] will be called.
### request.write(chunk[, encoding][, callback])
@ -383,7 +383,7 @@ 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 `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'` .
@ -395,7 +395,7 @@ Returns `request`.
## Class: http.Server
This is an [EventEmitter][] with the following events:
This is an [` EventEmitter` ][] with the following events:
### Event: 'checkContinue'
@ -405,21 +405,21 @@ 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
with a 100 Continue as appropriate.
Handling this event involves calling [response.writeContinue()][] if the client
Handling this event involves calling [` response.writeContinue()` ][] if the client
should continue to send the request body, or generating an appropriate HTTP
response (e.g., 400 Bad Request) if the client should not continue to send the
request body.
Note that when this event is emitted and handled, the `request` event will
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.
If a client connection emits an ` 'error'`
`socket` is the `net.Socket`
`socket` is the [`net.Socket`][] object that the error originated from.
### Event: 'close'
@ -431,8 +431,8 @@ Emitted when the server closes.
`function (request, socket, head) { }`
Emitted each time a client requests a http CONNECT method. If this event isn't
listened for, then clients requesting a CONNECT method will have their
Emitted each time a client requests a http ` CONNECT`
listened for, then clients requesting a ` CONNECT`
connections closed.
* `request` is the arguments for the http request, as it is in the request
@ -441,7 +441,7 @@ connections closed.
* `head` is an instance of Buffer, the first packet of the tunneling stream,
this may be empty.
After this event is emitted, the request's socket will not have a `data`
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.
@ -450,8 +450,8 @@ sent to the server on that socket.
`function (socket) { }`
When a new TCP stream is established. `socket` is an object of type
`net.Socket`
particular, the socket will not emit `readable` events because of how
[`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` .
@ -461,8 +461,8 @@ accessed at `request.connection`.
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][].
`request` is an instance of [` http.IncomingMessage` ][] and `response` is
an instance of [` http.ServerResponse` ][].
### Event: 'upgrade'
@ -478,13 +478,13 @@ closed.
* `head` is an instance of Buffer, the first packet of the upgraded stream,
this may be empty.
After this event is emitted, the request's socket will not have a `data`
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.
### server.close([callback])
Stops the server from accepting new connections. See [net.Server.close()][].
Stops the server from accepting new connections. See [` net.Server.close()` ][].
### server.listen(handle[, callback])
@ -501,14 +501,14 @@ already been bound to a port or domain socket.
Listening on a file descriptor is not supported on Windows.
This function is asynchronous. The last parameter `callback` will be added as
a listener for the ['listening'][] event. See also [net.Server.listen() ][].
a listener for the `'listening'` event. See also [`net.Server.listen()`
### 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) ][].
a listener for the `'listening'` event. See also [`net.Server.listen(path)`
### server.listen(port[, hostname][, backlog][, callback])
@ -525,7 +525,7 @@ The actual length will be determined by your OS through sysctl settings such as
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) ][].
a listener for the `'listening'` event. See also [`net.Server.listen(port)`
### server.maxHeadersCount
@ -571,14 +571,14 @@ This object is created internally by a HTTP server--not by the user. It is
passed as the second parameter to the `'request'` event.
The response implements the [Writable Stream][] interface. This is an
[EventEmitter][] with the following events:
[` EventEmitter` ][] with the following events:
### Event: 'close'
`function () { }`
Indicates that the underlying connection was terminated before
[response.end()][] was called or able to flush.
[` response.end()` ][] was called or able to flush.
### Event: 'finish'
@ -610,17 +610,16 @@ emit trailers, with a list of the header fields in its value. E.g.,
response.end();
Attempting to set a trailer field name that contains invalid characters will
result in a `TypeError`
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.
The method, `response.end()` , MUST be called on each response.
If `data` is specified, it is equivalent to calling
`response.write(data, encoding)` `response.end(callback)` .
[`response.write(data, encoding)`][] followed by `response.end(callback)` .
If `callback` is specified, it will be called when the response stream
is finished.
@ -628,7 +627,7 @@ is finished.
### response.finished
Boolean value that indicates whether the response has completed. Starts
as `false` . After `response.end()` `true` .
as `false` . After [`response.end()`][] executes, the value will be `true` .
### response.getHeader(name)
@ -675,7 +674,7 @@ 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`
result in a [`TypeError`][] being thrown.
### response.setTimeout(msecs, callback)
@ -696,7 +695,7 @@ Returns `response`.
### response.statusCode
When using implicit headers (not calling [response.writeHead()][] explicitly),
When using implicit headers (not calling [` response.writeHead()` ][] explicitly),
this property controls the status code that will be sent to the client when
the headers get flushed.
@ -709,7 +708,7 @@ status code which was sent out.
### response.statusMessage
When using implicit headers (not calling `response.writeHead()`
When using implicit headers (not calling [`response.writeHead()`][] explicitly), this property
controls the status message that will be sent to the client when the headers get
flushed. If this is left as `undefined` then the standard message for the status
code will be used.
@ -723,7 +722,7 @@ status message which was sent out.
### response.write(chunk[, encoding][, callback])
If this method is called and [response.writeHead()][] has not been called,
If this method is called and [` response.writeHead()` ][] has not been called,
it will switch to implicit header mode and flush the implicit headers.
This sends a chunk of the response body. This method may
@ -737,9 +736,9 @@ will be called when this chunk of data is flushed.
**Note**: This is the raw HTTP body and has nothing to do with
higher-level multi-part body encodings that may be used.
The first time `response.write()`
The first time [`response.write()`][] is called, it will send the buffered
header information and the first body to the client. The second time
`response.write()`
[`response.write()`][] is called, Node.js assumes you're going to be streaming
data, and sends that separately. That is, the response is buffered up to the
first chunk of body.
@ -750,7 +749,7 @@ buffer. Returns `false` if all or part of the data was queued in user memory.
### response.writeContinue()
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` .
the request body should be sent. See the [` 'checkContinue'` ][] event on `Server` .
### response.writeHead(statusCode[, statusMessage][, headers])
@ -767,9 +766,9 @@ Example:
'Content-Type': 'text/plain' });
This method must only be called once on a message and it must
be called before [response.end()][] is called.
be called before [` response.end()` ][] is called.
If you call [response.write()][] or [response.end()][] before calling this, the
If you call [` response.write()` ][] or [` response.end()` ][] before calling this, the
implicit/mutable headers will be calculated and call this function for you.
Note that Content-Length is given in bytes not characters. The above example
@ -781,8 +780,8 @@ which has been transmitted are equal or not.
## http.IncomingMessage
An `IncomingMessage` object is created by [http.Server][] or
[http.ClientRequest][] and passed as the first argument to the `'request'`
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.
@ -831,7 +830,7 @@ Also `response.httpVersionMajor` is the first integer and
### message.method
**Only valid for request obtained from [http.Server][].**
**Only valid for request obtained from [` http.Server` ][].**
The request method as a string. Read only. Example:
`'GET'` , `'DELETE'` .
@ -861,7 +860,7 @@ Header names are not lowercased, and duplicates are not merged.
### message.rawTrailers
The raw request/response trailer keys and values exactly as they were
received. Only populated at the 'end' event.
received. Only populated at the ` 'end'`
### message.setTimeout(msecs, callback)
@ -874,30 +873,30 @@ Returns `message`.
### message.statusCode
**Only valid for response obtained from `http.ClientRequest`
**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`
**Only valid for response obtained from [`http.ClientRequest`][] .**
### message.socket
The `net.Socket`
The [`net.Socket`][] object associated with the connection.
With HTTPS support, use [request.socket.getPeerCertificate()][] to obtain the
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.
The request/response trailers object. Only populated at the ` 'end'`
### message.url
**Only valid for request obtained from [http.Server][].**
**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:
@ -945,14 +944,14 @@ Found'`.
## http.createClient([port][, host])
Stability: 0 - Deprecated: Use [http.request][] instead.
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][].
Returns a new instance of [` http.Server` ][].
The `requestListener` is a function which is automatically
added to the `'request'` event.
@ -960,7 +959,7 @@ 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()`
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:
@ -982,14 +981,14 @@ Node.js maintains several connections per server to make HTTP requests.
This function allows one to transparently issue requests.
`options` can be an object or a string. If `options` is a string, it is
automatically parsed with [url.parse()][].
automatically parsed with [` url.parse()` ][].
Options:
- `protocol` : Protocol to use. Defaults to `'http'` .
- `host` : A domain name or IP address of the server to issue the request to.
Defaults to `'localhost'` .
- `hostname` : Alias for `host` . To support `url.parse()` `hostname` is
- `hostname` : Alias for `host` . To support [`url.parse()`][] `hostname` is
preferred over `host` .
- `family` : IP address family to use when resolving `host` and `hostname` .
Valid values are `4` or `6` . When unspecified, both IP v4 and v6 will be
@ -1005,17 +1004,17 @@ Options:
- `headers` : An object containing request headers.
- `auth` : Basic authentication i.e. `'user:password'` to compute an
Authorization header.
- `agent` : Controls [Agent][] behavior. When an Agent is used request will
- `agent` : Controls [` Agent` ][] behavior. When an Agent is used request will
default to `Connection: keep-alive` . Possible values:
- `undefined` (default): use [globalAgent][] for this host and port.
- `undefined` (default): use [`http. globalAgent` ][] 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` .
The optional `callback` parameter will be added as a one time listener for
the ['response'][] event.
the `'response'`
`http.request()` returns an instance of the [http.ClientRequest][]
`http.request()` returns an instance of the [` http.ClientRequest` ][]
class. The `ClientRequest` instance is a writable stream. If one needs to
upload a file with a POST request, then write to the `ClientRequest` object.
@ -1073,41 +1072,44 @@ There are a few special headers that should be noted.
* Sending an 'Expect' header will immediately send the request headers.
Usually, when sending 'Expect: 100-continue', you should both set a timeout
and listen for the `continue` event. See RFC2616 Section 8.2.3 for more
and listen for the `' continue' ` event. See RFC2616 Section 8.2.3 for more
information.
* Sending an Authorization header will override using the `auth` option
to compute basic authentication.
[message.headers][]: #http_message_headers
[constructor options]: #http_new_agent_options
[`'checkContinue'`]: #http_event_checkcontinue
[`'listening'`]: net.html#net_event_listening
[`'response'`]: #http_event_response
[`Agent`]: #http_class_http_agent
[`Buffer`]: buffer.html#buffer_buffer
[`destroy()`]: #http_agent_destroy
['checkContinue']: #http_event_checkcontinue
['listening']: net.html#net_event_listening
['response']: #http_event_response
[Agent]: #http_class_http_agent
[Buffer]: buffer.html#buffer_buffer
[EventEmitter]: events.html#events_class_events_eventemitter
[`EventEmitter`]: events.html#events_class_events_eventemitter
[`http.Agent`]: #http_class_http_agent
[`http.ClientRequest`]: #http_class_http_clientrequest
[`http.globalAgent`]: #http_http_globalagent
[`http.IncomingMessage`]: #http_http_incomingmessage
[`http.request()`]: #http_http_request_options_callback
[`http.Server`]: #http_class_http_server
[`http.ServerResponse`]: #http_class_http_serverresponse
[`message.headers`]: #http_message_headers
[`net.Server.close()`]: net.html#net_server_close_callback
[`net.Server.listen()`]: net.html#net_server_listen_handle_callback
[`net.Server.listen(path)`]: net.html#net_server_listen_path_callback
[`net.Server.listen(port)`]: net.html#net_server_listen_port_hostname_backlog_callback
[`net.Socket`]: net.html#net_class_net_socket
[`request.socket.getPeerCertificate()`]: tls.html#tls_tlssocket_getpeercertificate_detailed
[`response.end()`]: #http_response_end_data_encoding_callback
[`response.write()`]: #http_response_write_chunk_encoding_callback
[`response.write(data, encoding)`]: #http_response_write_chunk_encoding_callback
[`response.writeContinue()`]: #http_response_writecontinue
[`response.writeHead()`]: #http_response_writehead_statuscode_statusmessage_headers
[`socket.setKeepAlive()`]: net.html#net_socket_setkeepalive_enable_initialdelay
[`socket.setNoDelay()`]: net.html#net_socket_setnodelay_nodelay
[`socket.setTimeout()`]: net.html#net_socket_settimeout_timeout_callback
[`stream.setEncoding()`]: stream.html#stream_stream_setencoding_encoding
[`TypeError`]: errors.html#errors_class_typeerror
[`url.parse()`]: url.html#url_url_parse_urlstr_parsequerystring_slashesdenotehost
[constructor options]: #http_new_agent_options
[Readable Stream]: stream.html#stream_class_stream_readable
[Writable Stream]: stream.html#stream_class_stream_writable
[globalAgent]: #http_http_globalagent
[http.ClientRequest]: #http_class_http_clientrequest
[http.IncomingMessage]: #http_http_incomingmessage
[http.ServerResponse]: #http_class_http_serverresponse
[http.Server]: #http_class_http_server
[http.request]: #http_http_request_options_callback
[net.Server.close()]: net.html#net_server_close_callback
['listening']: net.html#net_event_listening
[net.Server.listen(path)]: net.html#net_server_listen_path_callback
[net.Server.listen(port)]: net.html#net_server_listen_port_hostname_backlog_callback
[net.Server.listen()]: net.html#net_server_listen_handle_callback
[response.end()]: #http_response_end_data_encoding_callback
[response.write()]: #http_response_write_chunk_encoding_callback
[response.writeContinue()]: #http_response_writecontinue
[response.writeHead()]: #http_response_writehead_statuscode_statusmessage_headers
[socket.setKeepAlive()]: net.html#net_socket_setkeepalive_enable_initialdelay
[socket.setNoDelay()]: net.html#net_socket_setnodelay_nodelay
[socket.setTimeout()]: net.html#net_socket_settimeout_timeout_callback
[request.socket.getPeerCertificate()]: tls.html#tls_tlssocket_getpeercertificate_detailed
[stream.setEncoding()]: stream.html#stream_stream_setencoding_encoding
[url.parse()]: url.html#url_url_parse_urlstr_parsequerystring_slashesdenotehost
jpersson
9 years ago
James M Snell