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 <jasnell@gmail.com>
9 years ago · 1c7b622cfc
1 changed files with 244 additions and 0 deletions
--- a/doc/api/http.md
+++ b/doc/api/http.md
@ -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.