From 1c7b622cfc1e0108f16e703ae20945a9587ba540 Mon Sep 17 00:00:00 2001 From: Anna Henningsen Date: Thu, 23 Jun 2016 21:50:36 +0200 Subject: [PATCH] doc: add `added:` information for http Ref: https://github.com/nodejs/node/issues/6578 PR-URL: https://github.com/nodejs/node/pull/7392 Reviewed-By: James M Snell --- doc/api/http.md | 244 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 244 insertions(+) diff --git a/doc/api/http.md b/doc/api/http.md index 493e66b7e7..35eb23193d 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -44,6 +44,9 @@ list like the following: ``` ## Class: http.Agent + The HTTP Agent is used for pooling sockets used in HTTP client requests. @@ -91,6 +94,9 @@ http.get({ ``` ### new Agent([options]) + * `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]) + 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() + 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 + 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 @@ -160,28 +178,43 @@ Options: the request. ### 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 @@ -213,6 +246,9 @@ The request implements the [Writable Stream][] interface. This is an [`EventEmitter`][] with the following events: ### Event: 'abort' + `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' + `function () { }` @@ -227,6 +266,9 @@ Emitted when the request has been aborted by the server and the network socket has closed. ### Event: 'checkExpectation' + `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' + `function (response, socket, head) { }` @@ -303,6 +348,9 @@ proxy.listen(1337, '127.0.0.1', () => { ``` ### Event: 'continue' + `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' + `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' + `function (socket) { }` Emitted after a socket is assigned to this request. ### Event: 'upgrade' + `function (response, socket, head) { }` @@ -375,11 +432,17 @@ srv.listen(1337, '127.0.0.1', () => { ``` ### 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 @@ -392,6 +455,9 @@ If `callback` is specified, it will be called when the request stream is finished. ### request.flushHeaders() + 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]) + 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. @@ -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]) + 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 + This class inherits from [`net.Server`][] and has the following additional events: ### Event: 'checkContinue' + `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' + `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' + `function () { }` Emitted when the server closes. ### Event: 'connect' + `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' + `function (socket) { }` @@ -524,6 +620,9 @@ the protocol parser attaches to the socket. The `socket` can also be accessed at `request.connection`. ### Event: 'request' + `function (request, response) { }` @@ -533,6 +632,9 @@ per connection (in the case of keep-alive connections). an instance of [`http.ServerResponse`][]. ### Event: 'upgrade' + `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]) + Stops the server from accepting new connections. See [`net.Server.close()`][]. ### server.listen(handle[, callback]) + * `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]) + 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]) + 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 + A Boolean indicating whether or not the server is listening for connections. ### server.maxHeadersCount + Limits maximum incoming headers count, equal to 1000 by default. If set to 0 - no limit will be applied. ### server.setTimeout(msecs, callback) + * `msecs` {Number} * `callback` {Function} @@ -627,6 +750,9 @@ for handling socket timeouts. Returns `server`. ### server.timeout + * {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 + 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' + `function () { }` @@ -656,6 +788,9 @@ Indicates that the underlying connection was terminated before [`response.end()`][] was called or able to flush. ### Event: 'finish' + `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) + 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]) + 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 + 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 @@ -719,10 +866,16 @@ var contentType = response.getHeader('content-type'); ``` ### response.headersSent + Boolean (read-only). True if headers were sent, false otherwise. ### response.removeHeader(name) + Removes a header that's queued for implicit sending. @@ -733,6 +886,9 @@ 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. @@ -741,6 +897,9 @@ 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 @@ -776,6 +935,9 @@ const server = http.createServer((req,res) => { ``` ### response.setTimeout(msecs, callback) + * `msecs` {Number} * `callback` {Function} @@ -793,6 +955,9 @@ sockets. Returns `response`. ### response.statusCode + 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 + 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]) + 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() + 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]) + 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 + 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' + `function () { }` @@ -918,6 +1101,9 @@ Emitted when the request has been aborted by the client and the network socket has closed. ### Event: 'close' + `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]) + * `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 + The request/response headers object. @@ -959,6 +1151,9 @@ header name: * For all other headers, the values are joined together with ', '. ### 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. @@ -968,6 +1163,9 @@ Also `message.httpVersionMajor` is the first integer and `message.httpVersionMinor` is the second. ### message.method + **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 + The raw request/response headers list exactly as they were received. @@ -999,11 +1200,17 @@ 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} @@ -1013,18 +1220,27 @@ 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`][].** The HTTP response status message (reason phrase). E.G. `OK` or `Internal Server Error`. ### message.socket + 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 + The request/response trailers object. Only populated at the `'end'` event. ### message.url + **Only valid for request obtained from [`http.Server`][].** @@ -1084,12 +1306,18 @@ $ node ``` ## http.METHODS + * {Array} A list of the HTTP methods that are supported by the parser. ## http.STATUS_CODES + * {Object} @@ -1098,6 +1326,10 @@ short description of each. For example, `http.STATUS_CODES[404] === 'Not Found'`. ## http.createClient([port][, host]) + 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]) + 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]) + 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 + Global instance of Agent which is used as the default for all http client requests. ## http.request(options[, callback]) + Node.js maintains several connections per server to make HTTP requests. This function allows one to transparently issue requests.