diff --git a/doc/api/http.md b/doc/api/http.md index a02b1d6a08f80e..cfe26a812927e7 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -47,7 +47,7 @@ list like the following: 'accepT', '*/*' ] ``` -## Class: http.Agent +## Class: `http.Agent` @@ -107,7 +107,7 @@ http.get({ }); ``` -### new Agent(\[options\]) +### `new Agent([options])` @@ -149,7 +149,7 @@ options.agent = keepAliveAgent; http.request(options, onResponseCallback); ``` -### agent.createConnection(options\[, callback\]) +### `agent.createConnection(options[, callback])` @@ -169,7 +169,7 @@ socket/stream from this function, or by passing the socket/stream to `callback`. `callback` has a signature of `(err, stream)`. -### agent.keepSocketAlive(socket) +### `agent.keepSocketAlive(socket)` @@ -189,7 +189,7 @@ This method can be overridden by a particular `Agent` subclass. If this method returns a falsy value, the socket will be destroyed instead of persisting it for use with the next request. -### agent.reuseSocket(socket, request) +### `agent.reuseSocket(socket, request)` @@ -206,7 +206,7 @@ socket.ref(); This method can be overridden by a particular `Agent` subclass. -### agent.destroy() +### `agent.destroy()` @@ -219,7 +219,7 @@ the agent when it will no longer be used. Otherwise, sockets may hang open for quite a long time before the server terminates them. -### agent.freeSockets +### `agent.freeSockets` @@ -229,7 +229,7 @@ added: v0.11.4 An object which contains arrays of sockets currently awaiting use by the agent when `keepAlive` is enabled. Do not modify. -### agent.getName(options) +### `agent.getName(options)` @@ -249,7 +249,7 @@ connection can be reused. For an HTTP agent, this returns the name includes the CA, cert, ciphers, and other HTTPS/TLS-specific options that determine socket reusability. -### agent.maxFreeSockets +### `agent.maxFreeSockets` @@ -260,7 +260,7 @@ By default set to 256. For agents with `keepAlive` enabled, this sets the maximum number of sockets that will be left open in the free state. -### agent.maxSockets +### `agent.maxSockets` @@ -270,7 +270,7 @@ added: v0.3.6 By default set to `Infinity`. Determines how many concurrent sockets the agent can have open per origin. Origin is the returned value of [`agent.getName()`][]. -### agent.requests +### `agent.requests` @@ -280,7 +280,7 @@ added: v0.5.9 An object which contains queues of requests that have not yet been assigned to sockets. Do not modify. -### agent.sockets +### `agent.sockets` @@ -290,7 +290,7 @@ added: v0.3.6 An object which contains arrays of sockets currently in use by the agent. Do not modify. -## Class: http.ClientRequest +## Class: `http.ClientRequest` @@ -327,7 +327,7 @@ Unlike the `request` object, if the response closes prematurely, the Node.js does not check whether Content-Length and the length of the body which has been transmitted are equal or not. -### Event: 'abort' +### Event: `'abort'` @@ -335,7 +335,7 @@ added: v1.4.1 Emitted when the request has been aborted by the client. This event is only emitted on the first call to `abort()`. -### Event: 'connect' +### Event: `'connect'` @@ -405,7 +405,7 @@ proxy.listen(1337, '127.0.0.1', () => { }); ``` -### Event: 'continue' +### Event: `'continue'` @@ -414,7 +414,7 @@ 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: 'information' +### Event: `'information'` @@ -456,7 +456,7 @@ traditional HTTP request/response chain, such as web sockets, in-place TLS upgrades, or HTTP 2.0. To be notified of 101 Upgrade notices, listen for the [`'upgrade'`][] event instead. -### Event: 'response' +### Event: `'response'` @@ -466,7 +466,7 @@ added: v0.1.0 Emitted when a response is received to this request. This event is emitted only once. -### Event: 'socket' +### Event: `'socket'` @@ -475,7 +475,7 @@ added: v0.5.3 Emitted after a socket is assigned to this request. -### Event: 'timeout' +### Event: `'timeout'` @@ -485,7 +485,7 @@ that the socket has been idle. The request must be aborted manually. See also: [`request.setTimeout()`][]. -### Event: 'upgrade' +### Event: `'upgrade'` @@ -542,7 +542,7 @@ srv.listen(1337, '127.0.0.1', () => { }); ``` -### request.abort() +### `request.abort()` @@ -550,7 +550,7 @@ 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.aborted +### `request.aborted` @@ -573,7 +573,7 @@ added: v0.3.0 See [`request.socket`][]. -### request.end(\[data\[, encoding\]\]\[, callback\]) +### `request.end([data[, encoding]][, callback])` @@ -608,7 +608,7 @@ The `request.finished` property will be `true` if [`request.end()`][] has been called. `request.end()` will automatically be called if the request was initiated via [`http.get()`][]. -### request.flushHeaders() +### `request.flushHeaders()` @@ -623,7 +623,7 @@ That's usually desired (it saves a TCP round-trip), but not when the first data is not sent until possibly much later. `request.flushHeaders()` bypasses the optimization and kickstarts the request. -### request.getHeader(name) +### `request.getHeader(name)` @@ -647,20 +647,20 @@ const cookie = request.getHeader('Cookie'); // 'cookie' is of type string[] ``` -### request.maxHeadersCount +### `request.maxHeadersCount` * {number} **Default:** `2000` Limits maximum response headers count. If set to 0, no limit will be applied. -### request.path +### `request.path` * {string} The request path. -### request.removeHeader(name) +### `request.removeHeader(name)` @@ -673,7 +673,7 @@ Removes a header that's already defined into headers object. request.removeHeader('Content-Type'); ``` -### request.setHeader(name, value) +### `request.setHeader(name, value)` @@ -698,7 +698,7 @@ or request.setHeader('Cookie', ['type=ninja', 'language=javascript']); ``` -### request.setNoDelay(\[noDelay\]) +### `request.setNoDelay([noDelay])` @@ -708,7 +708,7 @@ added: v0.5.9 Once a socket is assigned to this request and is connected [`socket.setNoDelay()`][] will be called. -### request.setSocketKeepAlive(\[enable\]\[, initialDelay\]) +### `request.setSocketKeepAlive([enable][, initialDelay])` @@ -719,7 +719,7 @@ added: v0.5.9 Once a socket is assigned to this request and is connected [`socket.setKeepAlive()`][] will be called. -### request.setTimeout(timeout\[, callback\]) +### `request.setTimeout(timeout[, callback])` @@ -763,7 +763,7 @@ req.once('response', (res) => { }); ``` -### request.writableEnded +### `request.writableEnded` @@ -774,7 +774,7 @@ Is `true` after [`request.end()`][] has been called. This property does not indicate whether the data has been flushed, for this use [`request.writableFinished`][] instead. -### request.writableFinished +### `request.writableFinished` @@ -784,7 +784,7 @@ added: v12.7.0 Is `true` if all data has been flushed to the underlying system, immediately before the [`'finish'`][] event is emitted. -### request.write(chunk\[, encoding\]\[, callback\]) +### `request.write(chunk[, encoding][, callback])` @@ -813,14 +813,14 @@ buffer. Returns `false` if all or part of the data was queued in user memory. When `write` function is called with empty string or buffer, it does nothing and waits for more input. -## Class: http.Server +## Class: `http.Server` * Extends: {net.Server} -### Event: 'checkContinue' +### Event: `'checkContinue'` @@ -840,7 +840,7 @@ the request body. When this event is emitted and handled, the [`'request'`][] event will not be emitted. -### Event: 'checkExpectation' +### Event: `'checkExpectation'` @@ -855,7 +855,7 @@ automatically respond with a `417 Expectation Failed` as appropriate. When this event is emitted and handled, the [`'request'`][] event will not be emitted. -### Event: 'clientError' +### Event: `'clientError'` Emitted when the server closes. -### Event: 'connect' +### Event: `'connect'` @@ -938,7 +938,7 @@ After this event is emitted, the request's socket will not have a `'data'` event listener, meaning it will need to be bound in order to handle data sent to the server on that socket. -### Event: 'connection' +### Event: `'connection'` @@ -958,7 +958,7 @@ If `socket.setTimeout()` is called here, the timeout will be replaced with `server.keepAliveTimeout` when the socket has served a request (if `server.keepAliveTimeout` is non-zero). -### Event: 'request' +### Event: `'request'` @@ -969,7 +969,7 @@ added: v0.1.0 Emitted each time there is a request. There may be multiple requests per connection (in the case of HTTP Keep-Alive connections). -### Event: 'upgrade' +### Event: `'upgrade'` @@ -1000,7 +1000,7 @@ added: v0.1.90 Stops the server from accepting new connections. See [`net.Server.close()`][]. -### server.headersTimeout +### `server.headersTimeout` @@ -1020,19 +1020,19 @@ event is emitted on the server object, and (by default) the socket is destroyed. See [`server.timeout`][] for more information on how timeout behavior can be customized. -### server.listen() +### `server.listen()` Starts the HTTP server listening for connections. This method is identical to [`server.listen()`][] from [`net.Server`][]. -### server.listening +### `server.listening` * {boolean} Indicates whether or not the server is listening for connections. -### server.maxHeadersCount +### `server.maxHeadersCount` @@ -1041,7 +1041,7 @@ added: v0.7.0 Limits maximum incoming headers count. If set to 0, no limit will be applied. -### server.setTimeout(\[msecs\]\[, callback\]) +### `server.setTimeout([msecs][, callback])` @@ -1064,7 +1064,7 @@ to the Server's `'timeout'` event, timeouts must be handled explicitly. To change the default timeout use the [`--http-server-default-timeout`][] flag. -### server.timeout +### `server.timeout` @@ -1082,7 +1082,7 @@ value only affects new connections to the server, not any existing connections. To change the default timeout use the [`--http-server-default-timeout`][] flag. -### server.keepAliveTimeout +### `server.keepAliveTimeout` @@ -1103,7 +1103,7 @@ to 8.0.0, which did not have a keep-alive timeout. The socket timeout logic is set up on connection, so changing this value only affects new connections to the server, not any existing connections. -## Class: http.ServerResponse +## Class: `http.ServerResponse` @@ -1113,14 +1113,14 @@ added: v0.1.17 This object is created internally by an HTTP server — not by the user. It is passed as the second parameter to the [`'request'`][] event. -### Event: 'close' +### Event: `'close'` Indicates that the underlying connection was terminated. -### Event: 'finish' +### Event: `'finish'` @@ -1130,7 +1130,7 @@ emitted when the last segment of the response headers and body have been handed off to the operating system for transmission over the network. It does not imply that the client has received anything yet. -### response.addTrailers(headers) +### `response.addTrailers(headers)` @@ -1158,7 +1158,7 @@ response.end(); Attempting to set a header field name or value that contains invalid characters will result in a [`TypeError`][] being thrown. -### response.connection +### `response.connection` @@ -1167,7 +1167,7 @@ added: v0.3.0 See [`response.socket`][]. -### response.end(\[data\[, encoding\]\]\[, callback\]) +### `response.end([data[, encoding]][, callback])` @@ -1201,14 +1201,14 @@ added: v0.0.2 The `response.finished` property will be `true` if [`response.end()`][] has been called. -### response.flushHeaders() +### `response.flushHeaders()` Flushes the response headers. See also: [`request.flushHeaders()`][]. -### response.getHeader(name) +### `response.getHeader(name)` @@ -1232,7 +1232,7 @@ const setCookie = response.getHeader('set-cookie'); // setCookie is of type string[] ``` -### response.getHeaderNames() +### `response.getHeaderNames()` @@ -1250,7 +1250,7 @@ const headerNames = response.getHeaderNames(); // headerNames === ['foo', 'set-cookie'] ``` -### response.getHeaders() +### `response.getHeaders()` @@ -1276,7 +1276,7 @@ const headers = response.getHeaders(); // headers === { foo: 'bar', 'set-cookie': ['foo=bar', 'bar=baz'] } ``` -### response.hasHeader(name) +### `response.hasHeader(name)` @@ -1291,7 +1291,7 @@ outgoing headers. The header name matching is case-insensitive. const hasContentType = response.hasHeader('content-type'); ``` -### response.headersSent +### `response.headersSent` @@ -1300,7 +1300,7 @@ added: v0.9.3 Boolean (read-only). True if headers were sent, false otherwise. -### response.removeHeader(name) +### `response.removeHeader(name)` @@ -1313,7 +1313,7 @@ Removes a header that's queued for implicit sending. response.removeHeader('Content-Encoding'); ``` -### response.sendDate +### `response.sendDate` @@ -1326,7 +1326,7 @@ 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) +### `response.setHeader(name, value)` @@ -1375,7 +1375,7 @@ header will not yield the expected result. If progressive population of headers is desired with potential future retrieval and modification, use [`response.setHeader()`][] instead of [`response.writeHead()`][]. -### response.setTimeout(msecs\[, callback\]) +### `response.setTimeout(msecs[, callback])` @@ -1393,7 +1393,7 @@ the server, then sockets are destroyed when they time out. If a handler is assigned to the request, the response, or the server's `'timeout'` events, timed out sockets must be handled explicitly. -### response.socket +### `response.socket` @@ -1415,7 +1415,7 @@ const server = http.createServer((req, res) => { }).listen(3000); ``` -### response.statusCode +### `response.statusCode` @@ -1433,7 +1433,7 @@ response.statusCode = 404; After response header was sent to the client, this property indicates the status code which was sent out. -### response.statusMessage +### `response.statusMessage` @@ -1452,7 +1452,7 @@ response.statusMessage = 'Not found'; After response header was sent to the client, this property indicates the status message which was sent out. -### response.writableEnded +### `response.writableEnded` @@ -1463,7 +1463,7 @@ Is `true` after [`response.end()`][] has been called. This property does not indicate whether the data has been flushed, for this use [`response.writableFinished`][] instead. -### response.writableFinished +### `response.writableFinished` @@ -1473,7 +1473,7 @@ added: v12.7.0 Is `true` if all data has been flushed to the underlying system, immediately before the [`'finish'`][] event is emitted. -### response.write(chunk\[, encoding\]\[, callback\]) +### `response.write(chunk[, encoding][, callback])` @@ -1510,7 +1510,7 @@ 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.writeContinue() +### `response.writeContinue()` @@ -1519,7 +1519,7 @@ 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\]) +### `response.writeHead(statusCode[, statusMessage][, headers])` @@ -1600,7 +1600,7 @@ added: v10.0.0 Sends a HTTP/1.1 102 Processing message to the client, indicating that the request body should be sent. -## Class: http.IncomingMessage +## Class: `http.IncomingMessage` @@ -1612,21 +1612,21 @@ An `IncomingMessage` object is created by [`http.Server`][] or and [`'response'`][] event respectively. It may be used to access response status, headers and data. -### Event: 'aborted' +### Event: `'aborted'` Emitted when the request has been aborted. -### Event: 'close' +### Event: `'close'` Indicates that the underlying connection was closed. -### message.aborted +### `message.aborted` @@ -1636,7 +1636,7 @@ added: v10.1.0 The `message.aborted` property will be `true` if the request has been aborted. -### message.complete +### `message.complete` @@ -1664,7 +1664,7 @@ const req = http.request({ }); ``` -### message.destroy(\[error\]) +### `message.destroy([error])` @@ -1675,7 +1675,7 @@ Calls `destroy()` on the socket that received the `IncomingMessage`. If `error` is provided, an `'error'` event is emitted on the socket and `error` is passed as an argument to any listeners on the event. -### message.headers +### `message.headers` @@ -1706,7 +1706,7 @@ header name: * For duplicate `cookie` headers, the values are joined together with '; '. * For all other headers, the values are joined together with ', '. -### message.httpVersion +### `message.httpVersion` @@ -1720,7 +1720,7 @@ Probably either `'1.1'` or `'1.0'`. Also `message.httpVersionMajor` is the first integer and `message.httpVersionMinor` is the second. -### message.method +### `message.method` @@ -1731,7 +1731,7 @@ added: v0.1.1 The request method as a string. Read only. Examples: `'GET'`, `'DELETE'`. -### message.rawHeaders +### `message.rawHeaders` @@ -1760,7 +1760,7 @@ Header names are not lowercased, and duplicates are not merged. console.log(request.rawHeaders); ``` -### message.rawTrailers +### `message.rawTrailers` @@ -1770,7 +1770,7 @@ 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\]) +### `message.setTimeout(msecs[, callback])` @@ -1781,7 +1781,7 @@ added: v0.5.9 Calls `message.connection.setTimeout(msecs, callback)`. -### message.socket +### `message.socket` @@ -1793,7 +1793,7 @@ The [`net.Socket`][] object associated with the connection. With HTTPS support, use [`request.socket.getPeerCertificate()`][] to obtain the client's authentication details. -### message.statusCode +### `message.statusCode` @@ -1804,7 +1804,7 @@ added: v0.1.1 The 3-digit HTTP response status code. E.G. `404`. -### message.statusMessage +### `message.statusMessage` @@ -1816,7 +1816,7 @@ added: v0.11.10 The HTTP response status message (reason phrase). E.G. `OK` or `Internal Server Error`. -### message.trailers +### `message.trailers` @@ -1825,7 +1825,7 @@ added: v0.3.0 The request/response trailers object. Only populated at the `'end'` event. -### message.url +### `message.url` @@ -1893,7 +1893,7 @@ Url { href: '/status?name=ryan' } ``` -## http.METHODS +## `http.METHODS` @@ -1902,7 +1902,7 @@ added: v0.11.8 A list of the HTTP methods that are supported by the parser. -## http.STATUS_CODES +## `http.STATUS_CODES` @@ -1913,7 +1913,7 @@ 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.createServer(\[options\]\[, requestListener\]) +## `http.createServer([options][, requestListener])` @@ -2023,7 +2023,7 @@ added: v0.5.9 Global instance of `Agent` which is used as the default for all HTTP client requests. -## http.maxHeaderSize +## `http.maxHeaderSize` @@ -2033,8 +2033,8 @@ added: v11.6.0 Read-only property specifying the maximum allowed size of HTTP headers in bytes. Defaults to 8KB. Configurable using the [`--max-http-header-size`][] CLI option. -## http.request(options\[, callback\]) -## http.request(url\[, options\]\[, callback\]) +## `http.request(options[, callback])` +## `http.request(url[, options][, callback])`