1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: add added: information for http

Browse Source 
Ref: https://github.com/nodejs/node/issues/6578
PR-URL: https://github.com/nodejs/node/pull/7392
Reviewed-By: James M Snell <jasnell@gmail.com>
This commit is contained in:
Anna Henningsen 2016-06-23 21:50:36 +02:00
parent 21535e851c
commit 72500f942b
No known key found for this signature in database
GPG Key ID: D8B9F5AEAE84E4CF
1 changed files with 244 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

244
doc/api/http.md
View File

@ -44,6 +44,9 @@ list like the following:
```
## Class: http.Agent
<!-- YAML
added: v0.3.4
-->
The HTTP Agent is used for pooling sockets used in HTTP client
requests.
@ -91,6 +94,9 @@ http.get({
```
### new Agent([options])
<!-- YAML
added: v0.3.4
-->
* `options` {Object} Set of configurable options to set on the agent.
Can have the following fields:
@ -118,6 +124,9 @@ http.request(options, onResponseCallback);
```
### agent.createConnection(options[, callback])
<!-- YAML
added: v0.11.4
-->
Produces a socket/stream to be used for HTTP requests.
@ -130,6 +139,9 @@ socket/stream from this function, or by passing the socket/stream to `callback`.
`callback` has a signature of `(err, stream)`.
### agent.destroy()
<!-- YAML
added: v0.11.4
-->
Destroy any sockets that are currently in use by the agent.
@ -140,11 +152,17 @@ sockets may hang open for quite a long time before the server
terminates them.
### agent.freeSockets
<!-- YAML
added: v0.11.4
-->
An object which contains arrays of sockets currently awaiting use by
the Agent when HTTP KeepAlive is used. Do not modify.
### agent.getName(options)
<!-- YAML
added: v0.11.4
-->
Get a unique name for a set of request options, to determine whether a
connection can be reused. In the http agent, this returns
@ -160,28 +178,43 @@ Options:
the request.
### agent.maxFreeSockets
<!-- YAML
added: v0.11.7
-->
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
<!-- YAML
added: v0.3.6
-->
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
<!-- YAML
added: v0.5.9
-->
An object which contains queues of requests that have not yet been assigned to
sockets. Do not modify.
### agent.sockets
<!-- YAML
added: v0.3.6
-->
An object which contains arrays of sockets currently in use by the
Agent. Do not modify.
## Class: http.ClientRequest
<!-- YAML
added: v0.1.17
-->
This object is created internally and returned from [`http.request()`][]. It
represents an _in-progress_ request whose header has already been queued. The
@ -213,6 +246,9 @@ The request implements the [Writable Stream][] interface. This is an
[`EventEmitter`][] with the following events:
### Event: 'abort'
<!-- YAML
added: v1.4.1
-->
`function () { }`
@ -220,6 +256,9 @@ Emitted when the request has been aborted by the client. This event is only
emitted on the first call to `abort()`.
### Event: 'aborted'
<!-- YAML
added: v0.3.8
-->
`function () { }`
@ -227,6 +266,9 @@ Emitted when the request has been aborted by the server and the network
socket has closed.
### Event: 'checkExpectation'
<!-- YAML
added: v5.5.0
-->
`function (request, response) { }`
@ -238,6 +280,9 @@ Note that when this event is emitted and handled, the `request` event will
not be emitted.
### Event: 'connect'
<!-- YAML
added: v0.7.0
-->
`function (response, socket, head) { }`
@ -303,6 +348,9 @@ proxy.listen(1337, '127.0.0.1', () => {
```
### Event: 'continue'
<!-- YAML
added: v0.3.2
-->
`function () { }`
@ -311,6 +359,9 @@ the request contained 'Expect: 100-continue'. This is an instruction that
the client should send the request body.
### Event: 'response'
<!-- YAML
added: v0.1.0
-->
`function (response) { }`
@ -318,12 +369,18 @@ 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`][].
### Event: 'socket'
<!-- YAML
added: v0.5.3
-->
`function (socket) { }`
Emitted after a socket is assigned to this request.
### Event: 'upgrade'
<!-- YAML
added: v0.1.94
-->
`function (response, socket, head) { }`
@ -375,11 +432,17 @@ srv.listen(1337, '127.0.0.1', () => {
```
### request.abort()
<!-- YAML
added: v0.3.8
-->
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])
<!-- YAML
added: v0.1.90
-->
Finishes sending the request. If any parts of the body are
unsent, it will flush them to the stream. If the request is
@ -392,6 +455,9 @@ If `callback` is specified, it will be called when the request stream
is finished.
### request.flushHeaders()
<!-- YAML
added: v1.6.0
-->
Flush the request headers.
@ -404,16 +470,25 @@ data isn't sent until possibly much later. `request.flushHeaders()` lets you by
the optimization and kickstart the request.
### request.setNoDelay([noDelay])
<!-- YAML
added: v0.5.9
-->
Once a socket is assigned to this request and is connected
[`socket.setNoDelay()`][] will be called.
### request.setSocketKeepAlive([enable][, initialDelay])
<!-- YAML
added: v0.5.9
-->
Once a socket is assigned to this request and is connected
[`socket.setKeepAlive()`][] will be called.
### request.setTimeout(timeout[, callback])
<!-- YAML
added: v0.5.9
-->
Once a socket is assigned to this request and is connected
[`socket.setTimeout()`][] will be called.
@ -422,6 +497,9 @@ Once a socket is assigned to this request and is connected
* `callback` {Function} Optional function to be called when a timeout occurs. Same as binding to the `timeout` event.
### request.write(chunk[, encoding][, callback])
<!-- YAML
added: v0.1.29
-->
Sends a chunk of the body. By calling this method
many times, the user can stream a request body to a
@ -440,10 +518,16 @@ is flushed.
Returns `request`.
## Class: http.Server
<!-- YAML
added: v0.1.17
-->
This class inherits from [`net.Server`][] and has the following additional events:
### Event: 'checkContinue'
<!-- YAML
added: v0.3.0
-->
`function (request, response) { }`
@ -460,6 +544,9 @@ Note that when this event is emitted and handled, the `'request'` event will
not be emitted.
### Event: 'clientError'
<!-- YAML
added: v0.1.94
-->
`function (exception, socket) { }`
@ -490,12 +577,18 @@ object, so any HTTP response sent, including response headers and payload,
ensure the response is a properly formatted HTTP response message.
### Event: 'close'
<!-- YAML
added: v0.1.4
-->
`function () { }`
Emitted when the server closes.
### Event: 'connect'
<!-- YAML
added: v0.7.0
-->
`function (request, socket, head) { }`
@ -514,6 +607,9 @@ event listener, meaning you will need to bind to it in order to handle data
sent to the server on that socket.
### Event: 'connection'
<!-- YAML
added: v0.1.0
-->
`function (socket) { }`
@ -524,6 +620,9 @@ the protocol parser attaches to the socket. The `socket` can also be
accessed at `request.connection`.
### Event: 'request'
<!-- YAML
added: v0.1.0
-->
`function (request, response) { }`
@ -533,6 +632,9 @@ per connection (in the case of keep-alive connections).
an instance of [`http.ServerResponse`][].
### Event: 'upgrade'
<!-- YAML
added: v0.1.94
-->
`function (request, socket, head) { }`
@ -551,10 +653,16 @@ 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])
<!-- YAML
added: v0.1.90
-->
Stops the server from accepting new connections. See [`net.Server.close()`][].
### server.listen(handle[, callback])
<!-- YAML
added: v0.5.10
-->
* `handle` {Object}
* `callback` {Function}
@ -574,6 +682,9 @@ a listener for the `'listening'` event. See also [`net.Server.listen()`][].
Returns `server`.
### server.listen(path[, callback])
<!-- YAML
added: v0.1.90
-->
Start a UNIX socket server listening for connections on the given `path`.
@ -581,6 +692,9 @@ 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])
<!-- YAML
added: v0.1.90
-->
Begin accepting connections on the specified `port` and `hostname`. If the
`hostname` is omitted, the server will accept connections on any IPv6 address
@ -598,16 +712,25 @@ 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.listening
<!-- YAML
added: v5.7.0
-->
A Boolean indicating whether or not the server is listening for
connections.
### server.maxHeadersCount
<!-- YAML
added: v0.7.0
-->
Limits maximum incoming headers count, equal to 1000 by default. If set to 0 -
no limit will be applied.
### server.setTimeout(msecs, callback)
<!-- YAML
added: v0.9.12
-->
* `msecs` {Number}
* `callback` {Function}
@ -627,6 +750,9 @@ for handling socket timeouts.
Returns `server`.
### server.timeout
<!-- YAML
added: v0.9.12
-->
* {Number} Default = 120000 (2 minutes)
@ -641,6 +767,9 @@ Set to 0 to disable any kind of automatic timeout behavior on incoming
connections.
## Class: http.ServerResponse
<!-- YAML
added: v0.1.17
-->
This object is created internally by a HTTP server--not by the user. It is
passed as the second parameter to the `'request'` event.
@ -649,6 +778,9 @@ The response implements, but does not inherit from, the [Writable Stream][]
interface. This is an [`EventEmitter`][] with the following events:
### Event: 'close'
<!-- YAML
added: v0.6.7
-->
`function () { }`
@ -656,6 +788,9 @@ Indicates that the underlying connection was terminated before
[`response.end()`][] was called or able to flush.
### Event: 'finish'
<!-- YAML
added: v0.3.6
-->
`function () { }`
@ -667,6 +802,9 @@ does not imply that the client has received anything yet.
After this event, no more events will be emitted on the response object.
### response.addTrailers(headers)
<!-- YAML
added: v0.3.0
-->
This method adds HTTP trailing headers (a header but at the end of the
message) to the response.
@ -690,6 +828,9 @@ Attempting to set a header field name or value that contains invalid characters
will result in a [`TypeError`][] being thrown.
### response.end([data][, encoding][, callback])
<!-- YAML
added: v0.1.90
-->
This method signals to the server that all of the response headers and body
have been sent; that server should consider this message complete.
@ -702,11 +843,17 @@ If `callback` is specified, it will be called when the response stream
is finished.
### response.finished
<!-- YAML
added: v0.0.2
-->
Boolean value that indicates whether the response has completed. Starts
as `false`. After [`response.end()`][] executes, the value will be `true`.
### response.getHeader(name)
<!-- YAML
added: v0.4.0
-->
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
@ -719,10 +866,16 @@ var contentType = response.getHeader('content-type');
```
### response.headersSent
<!-- YAML
added: v0.9.3
-->
Boolean (read-only). True if headers were sent, false otherwise.
### response.removeHeader(name)
<!-- YAML
added: v0.4.0
-->
Removes a header that's queued for implicit sending.
@ -733,6 +886,9 @@ response.removeHeader('Content-Encoding');
```
### response.sendDate
<!-- YAML
added: v0.7.5
-->
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.
@ -741,6 +897,9 @@ This should only be disabled for testing; HTTP requires the Date header
in responses.
### response.setHeader(name, value)
<!-- YAML
added: v0.4.0
-->
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
@ -776,6 +935,9 @@ const server = http.createServer((req,res) => {
```
### response.setTimeout(msecs, callback)
<!-- YAML
added: v0.9.12
-->
* `msecs` {Number}
* `callback` {Function}
@ -793,6 +955,9 @@ sockets.
Returns `response`.
### response.statusCode
<!-- YAML
added: v0.4.0
-->
When using implicit headers (not calling [`response.writeHead()`][] explicitly),
this property controls the status code that will be sent to the client when
@ -808,6 +973,9 @@ After response header was sent to the client, this property indicates the
status code which was sent out.
### response.statusMessage
<!-- YAML
added: v0.11.8
-->
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
@ -824,6 +992,9 @@ After response header was sent to the client, this property indicates the
status message which was sent out.
### response.write(chunk[, encoding][, callback])
<!-- YAML
added: v0.1.29
-->
If this method is called and [`response.writeHead()`][] has not been called,
it will switch to implicit header mode and flush the implicit headers.
@ -850,11 +1021,17 @@ 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.writeContinue()
<!-- YAML
added: v0.3.0
-->
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`.
### response.writeHead(statusCode[, statusMessage][, headers])
<!-- YAML
added: v0.1.30
-->
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.
@ -901,6 +1078,9 @@ Attempting to set a header field name or value that contains invalid characters
will result in a [`TypeError`][] being thrown.
## Class: http.IncomingMessage
<!-- YAML
added: v0.1.17
-->
An `IncomingMessage` object is created by [`http.Server`][] or
[`http.ClientRequest`][] and passed as the first argument to the `'request'`
@ -911,6 +1091,9 @@ It implements the [Readable Stream][] interface, as well as the
following additional events, methods, and properties.
### Event: 'aborted'
<!-- YAML
added: v0.3.8
-->
`function () { }`
@ -918,6 +1101,9 @@ Emitted when the request has been aborted by the client and the network
socket has closed.
### Event: 'close'
<!-- YAML
added: v0.4.2
-->
`function () { }`
@ -925,6 +1111,9 @@ Indicates that the underlying connection was closed.
Just like `'end'`, this event occurs only once per response.
### message.destroy([error])
<!-- YAML
added: v0.3.0
-->
* `error` {Error}
@ -933,6 +1122,9 @@ is provided, an `'error'` event is emitted and `error` is passed as an argument
to any listeners on the event.
### message.headers
<!-- YAML
added: v0.1.5
-->
The request/response headers object.
@ -959,6 +1151,9 @@ header name:
* For all other headers, the values are joined together with ', '.
### message.httpVersion
<!-- YAML
added: v0.1.1
-->
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.
@ -968,6 +1163,9 @@ Also `message.httpVersionMajor` is the first integer and
`message.httpVersionMinor` is the second.
### message.method
<!-- YAML
added: v0.1.1
-->
**Only valid for request obtained from [`http.Server`][].**
@ -975,6 +1173,9 @@ The request method as a string. Read only. Example:
`'GET'`, `'DELETE'`.
### message.rawHeaders
<!-- YAML
added: v0.11.6
-->
The raw request/response headers list exactly as they were received.
@ -999,11 +1200,17 @@ console.log(request.rawHeaders);
```
### message.rawTrailers
<!-- YAML
added: v0.11.6
-->
The raw request/response trailer keys and values exactly as they were
received. Only populated at the `'end'` event.
### message.setTimeout(msecs, callback)
<!-- YAML
added: v0.5.9
-->
* `msecs` {Number}
* `callback` {Function}
@ -1013,18 +1220,27 @@ Calls `message.connection.setTimeout(msecs, callback)`.
Returns `message`.
### message.statusCode
<!-- YAML
added: v0.1.1
-->
**Only valid for response obtained from [`http.ClientRequest`][].**
The 3-digit HTTP response status code. E.G. `404`.
### message.statusMessage
<!-- YAML
added: v0.11.10
-->
**Only valid for response obtained from [`http.ClientRequest`][].**
The HTTP response status message (reason phrase). E.G. `OK` or `Internal Server Error`.
### message.socket
<!-- YAML
added: v0.3.0
-->
The [`net.Socket`][] object associated with the connection.
@ -1032,10 +1248,16 @@ With HTTPS support, use [`request.socket.getPeerCertificate()`][] to obtain the
client's authentication details.
### message.trailers
<!-- YAML
added: v0.3.0
-->
The request/response trailers object. Only populated at the `'end'` event.
### message.url
<!-- YAML
added: v0.1.90
-->
**Only valid for request obtained from [`http.Server`][].**
@ -1084,12 +1306,18 @@ $ node
```
## http.METHODS
<!-- YAML
added: v0.11.8
-->
* {Array}
A list of the HTTP methods that are supported by the parser.
## http.STATUS_CODES
<!-- YAML
added: v0.1.22
-->
* {Object}
@ -1098,6 +1326,10 @@ short description of each. For example, `http.STATUS_CODES[404] === 'Not
Found'`.
## http.createClient([port][, host])
<!-- YAML
added: v0.1.13
deprecated: v0.3.6
-->
Stability: 0 - Deprecated: Use [`http.request()`][] instead.
@ -1105,6 +1337,9 @@ Constructs a new HTTP client. `port` and `host` refer to the server to be
connected to.
## http.createServer([requestListener])
<!-- YAML
added: v0.1.13
-->
Returns a new instance of [`http.Server`][].
@ -1112,6 +1347,9 @@ The `requestListener` is a function which is automatically
added to the `'request'` event.
## http.get(options[, callback])
<!-- YAML
added: v0.3.6
-->
Since most requests are GET requests without bodies, Node.js provides this
convenience method. The only difference between this method and [`http.request()`][]
@ -1130,11 +1368,17 @@ http.get('http://www.google.com/index.html', (res) => {
```
## http.globalAgent
<!-- YAML
added: v0.5.9
-->
Global instance of Agent which is used as the default for all http client
requests.
## http.request(options[, callback])
<!-- YAML
added: v0.3.6
-->
Node.js maintains several connections per server to make HTTP requests.
This function allows one to transparently issue requests.