From d0b58c0287e67a139137aa906819d95f8314b093 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Sun, 10 Oct 2021 21:55:04 -0700 Subject: doc: format doc/api/*.md with markdown formatter MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PR-URL: https://github.com/nodejs/node/pull/40403 Reviewed-By: Benjamin Gruenbaum Reviewed-By: Zijian Liu Reviewed-By: Michaël Zasso Reviewed-By: Antoine du Hamel --- doc/api/http.md | 196 ++++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 176 insertions(+), 20 deletions(-) (limited to 'doc/api/http.md') diff --git a/doc/api/http.md b/doc/api/http.md index 09aa425b0f9..722defc987d 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -17,6 +17,7 @@ user is able to stream data. HTTP message headers are represented by an object like this: + ```js { 'content-length': '123', 'content-type': 'text/plain', @@ -40,6 +41,7 @@ example, the previous message header object might have a `rawHeaders` list like the following: + ```js [ 'ConTent-Length', '123456', 'content-LENGTH', '123', @@ -50,6 +52,7 @@ list like the following: ``` ## Class: `http.Agent` + @@ -110,6 +113,7 @@ http.get({ ``` ### `new Agent([options])` + @@ -215,6 +220,7 @@ type other than {net.Socket}. `callback` has a signature of `(err, stream)`. ### `agent.keepSocketAlive(socket)` + @@ -238,6 +244,7 @@ The `socket` argument can be an instance of {net.Socket}, a subclass of {stream.Duplex}. ### `agent.reuseSocket(socket, request)` + @@ -258,6 +265,7 @@ The `socket` argument can be an instance of {net.Socket}, a subclass of {stream.Duplex}. ### `agent.destroy()` + @@ -271,6 +279,7 @@ sockets might stay open for quite a long time before the server terminates them. ### `agent.freeSockets` + @@ -308,6 +318,7 @@ the name includes the CA, cert, ciphers, and other HTTPS/TLS-specific options that determine socket reusability. ### `agent.maxFreeSockets` + @@ -319,6 +330,7 @@ sets the maximum number of sockets that will be left open in the free state. ### `agent.maxSockets` + @@ -329,6 +341,7 @@ 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.maxTotalSockets` + @@ -378,7 +394,7 @@ 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 header is still mutable using the [`setHeader(name, value)`][], - [`getHeader(name)`][], [`removeHeader(name)`][] API. The actual header will +[`getHeader(name)`][], [`removeHeader(name)`][] API. The actual header will be sent along with the first data chunk or when calling [`request.end()`][]. To get the response, add a listener for [`'response'`][] to the request object. @@ -405,6 +421,7 @@ Node.js does not check whether Content-Length and the length of the body which has been transmitted are equal or not. ### Event: `'abort'` + @@ -490,6 +508,7 @@ proxy.listen(1337, '127.0.0.1', () => { ``` ### Event: `'continue'` + @@ -499,6 +518,7 @@ the request contained 'Expect: 100-continue'. This is an instruction that the client should send the request body. ### Event: `'information'` + @@ -510,7 +530,7 @@ added: v10.0.0 * `statusCode` {integer} * `statusMessage` {string} * `headers` {Object} - * `rawHeaders` {string[]} + * `rawHeaders` {string\[]} Emitted when the server sends a 1xx intermediate response (excluding 101 Upgrade). The listeners of this event will receive an object containing the @@ -541,6 +561,7 @@ upgrades, or HTTP 2.0. To be notified of 101 Upgrade notices, listen for the [`'upgrade'`][] event instead. ### Event: `'response'` + @@ -551,6 +572,7 @@ Emitted when a response is received to this request. This event is emitted only once. ### Event: `'socket'` + @@ -562,6 +584,7 @@ a subclass of {stream.Duplex}, unless the user specifies a socket type other than {net.Socket}. ### Event: `'timeout'` + @@ -572,6 +595,7 @@ that the socket has been idle. The request must be destroyed manually. See also: [`request.setTimeout()`][]. ### Event: `'upgrade'` + @@ -633,6 +657,7 @@ server.listen(1337, '127.0.0.1', () => { ``` ### `request.abort()` + @@ -762,6 +794,7 @@ data is not sent until possibly much later. `request.flushHeaders()` bypasses the optimization and kickstarts the request. ### `request.getHeader(name)` + @@ -786,13 +819,14 @@ const cookie = request.getHeader('Cookie'); ``` ### `request.getRawHeaderNames()` + -* Returns: {string[]} +* Returns: {string\[]} Returns an array containing the unique names of the current outgoing raw headers. Header names are returned with their exact casing being set. @@ -812,6 +846,7 @@ const headerNames = request.getRawHeaderNames(); Limits maximum response headers count. If set to 0, no limit will be applied. ### `request.path` + @@ -819,6 +854,7 @@ added: v0.4.0 * {string} The request path. ### `request.method` + @@ -826,6 +862,7 @@ added: v0.1.97 * {string} The request method. ### `request.host` + @@ -857,6 +896,7 @@ request.removeHeader('Content-Type'); ``` ### `request.reusedSocket` + @@ -939,6 +980,7 @@ request.setHeader('Cookie', ['type=ninja', 'language=javascript']); ``` ### `request.setNoDelay([noDelay])` + @@ -949,6 +991,7 @@ Once a socket is assigned to this request and is connected [`socket.setNoDelay()`][] will be called. ### `request.setSocketKeepAlive([enable][, initialDelay])` + @@ -960,6 +1003,7 @@ Once a socket is assigned to this request and is connected [`socket.setKeepAlive()`][] will be called. ### `request.setTimeout(timeout[, callback])` + @@ -1007,6 +1052,7 @@ a subclass of {stream.Duplex}, unless the user specified a socket type other than {net.Socket}. ### `request.writableEnded` + @@ -1018,6 +1064,7 @@ does not indicate whether the data has been flushed, for this use [`request.writableFinished`][] instead. ### `request.writableFinished` + @@ -1028,6 +1075,7 @@ Is `true` if all data has been flushed to the underlying system, immediately before the [`'finish'`][] event is emitted. ### `request.write(chunk[, encoding][, callback])` + @@ -1057,6 +1105,7 @@ When `write` function is called with empty string or buffer, it does nothing and waits for more input. ## Class: `http.Server` + @@ -1064,6 +1113,7 @@ added: v0.1.17 * Extends: {net.Server} ### Event: `'checkContinue'` + @@ -1084,6 +1134,7 @@ When this event is emitted and handled, the [`'request'`][] event will not be emitted. ### Event: `'checkExpectation'` + @@ -1099,6 +1150,7 @@ When this event is emitted and handled, the [`'request'`][] event will not be emitted. ### Event: `'clientError'` + @@ -1183,6 +1236,7 @@ added: v0.1.4 Emitted when the server closes. ### Event: `'connect'` + @@ -1205,6 +1259,7 @@ event listener, meaning it will need to be bound in order to handle data sent to the server on that socket. ### Event: `'connection'` + @@ -1229,6 +1284,7 @@ a subclass of {stream.Duplex}, unless the user specifies a socket type other than {net.Socket}. ### Event: `'request'` + @@ -1240,6 +1296,7 @@ Emitted each time there is a request. There may be multiple requests per connection (in the case of HTTP Keep-Alive connections). ### Event: `'upgrade'` + @@ -1275,6 +1333,7 @@ added: v0.1.90 Stops the server from accepting new connections. See [`net.Server.close()`][]. ### `server.headersTimeout` + @@ -1309,6 +1369,7 @@ added: v5.7.0 * {boolean} Indicates whether or not the server is listening for connections. ### `server.maxHeadersCount` + @@ -1318,6 +1379,7 @@ added: v0.7.0 Limits maximum incoming headers count. If set to 0, no limit will be applied. ### `server.requestTimeout` + @@ -1335,6 +1397,7 @@ potential Denial-of-Service attacks in case the server is deployed without a reverse proxy in front. ### `server.setTimeout([msecs][, callback])` + @@ -1375,6 +1439,7 @@ but will not actually close the connection, subsequent requests sent after the limit is reached will get `503 Service Unavailable` as a response. ### `server.timeout` + @@ -1415,6 +1481,7 @@ 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` + @@ -1425,6 +1492,7 @@ 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'` + @@ -1433,6 +1501,7 @@ Indicates that the response is completed, or its underlying connection was terminated prematurely (before the response completion). ### Event: `'finish'` + @@ -1443,6 +1512,7 @@ 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)` + @@ -1471,6 +1541,7 @@ Attempting to set a header field name or value that contains invalid characters will result in a [`TypeError`][] being thrown. ### `response.connection` + @@ -1538,6 +1613,7 @@ added: v1.6.0 Flushes the response headers. See also: [`request.flushHeaders()`][]. ### `response.getHeader(name)` + @@ -1562,11 +1638,12 @@ const setCookie = response.getHeader('set-cookie'); ``` ### `response.getHeaderNames()` + -* Returns: {string[]} +* Returns: {string\[]} Returns an array containing the unique names of the current outgoing headers. All header names are lowercase. @@ -1580,6 +1657,7 @@ const headerNames = response.getHeaderNames(); ``` ### `response.getHeaders()` + @@ -1595,7 +1673,7 @@ are lowercase. The object returned by the `response.getHeaders()` method _does not_ prototypically inherit from the JavaScript `Object`. This means that typical `Object` methods such as `obj.toString()`, `obj.hasOwnProperty()`, and others -are not defined and *will not work*. +are not defined and _will not work_. ```js response.setHeader('Foo', 'bar'); @@ -1606,6 +1684,7 @@ const headers = response.getHeaders(); ``` ### `response.hasHeader(name)` + @@ -1621,6 +1700,7 @@ const hasContentType = response.hasHeader('content-type'); ``` ### `response.headersSent` + @@ -1630,6 +1710,7 @@ added: v0.9.3 Boolean (read-only). True if headers were sent, false otherwise. ### `response.removeHeader(name)` + @@ -1643,6 +1724,7 @@ response.removeHeader('Content-Encoding'); ``` ### `response.req` + @@ -1652,6 +1734,7 @@ added: v15.7.0 A reference to the original HTTP `request` object. ### `response.sendDate` + @@ -1665,6 +1748,7 @@ This should only be disabled for testing; HTTP requires the Date header in responses. ### `response.setHeader(name, value)` + @@ -1718,6 +1802,7 @@ is desired with potential future retrieval and modification, use [`response.setHeader()`][] instead of [`response.writeHead()`][]. ### `response.setTimeout(msecs[, callback])` + @@ -1736,6 +1821,7 @@ assigned to the request, the response, or the server's `'timeout'` events, timed out sockets must be handled explicitly. ### `response.socket` + @@ -1761,6 +1847,7 @@ a subclass of {stream.Duplex}, unless the user specified a socket type other than {net.Socket}. ### `response.statusCode` + @@ -1779,6 +1866,7 @@ After response header was sent to the client, this property indicates the status code which was sent out. ### `response.statusMessage` + @@ -1798,6 +1886,7 @@ After response header was sent to the client, this property indicates the status message which was sent out. ### `response.uncork()` + @@ -1818,6 +1908,7 @@ does not indicate whether the data has been flushed, for this use [`response.writableFinished`][] instead. ### `response.writableFinished` + @@ -1828,6 +1919,7 @@ Is `true` if all data has been flushed to the underlying system, immediately before the [`'finish'`][] event is emitted. ### `response.write(chunk[, encoding][, callback])` + @@ -1865,6 +1957,7 @@ 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()` + @@ -1874,6 +1967,7 @@ the request body should be sent. See the [`'checkContinue'`][] event on `Server`. ### `response.writeHead(statusCode[, statusMessage][, headers])` + @@ -1965,6 +2060,7 @@ Sends a HTTP/1.1 102 Processing message to the client, indicating that the request body should be sent. ## Class: `http.IncomingMessage` + @@ -2009,6 +2107,7 @@ added: v0.4.2 Indicates that the underlying connection was closed. ### `message.aborted` + @@ -2050,6 +2150,7 @@ const req = http.request({ ``` ### `message.connection` + @@ -2130,6 +2234,7 @@ Also `message.httpVersionMajor` is the first integer and `message.httpVersionMinor` is the second. ### `message.method` + @@ -2141,15 +2246,16 @@ added: v0.1.1 The request method as a string. Read only. Examples: `'GET'`, `'DELETE'`. ### `message.rawHeaders` + -* {string[]} +* {string\[]} The raw request/response headers list exactly as they were received. -The keys and values are in the same list. It is *not* a +The keys and values are in the same list. It is _not_ a list of tuples. So, the even-numbered offsets are key values, and the odd-numbered offsets are the associated values. @@ -2170,16 +2276,18 @@ console.log(request.rawHeaders); ``` ### `message.rawTrailers` + -* {string[]} +* {string\[]} The raw request/response trailer keys and values exactly as they were received. Only populated at the `'end'` event. ### `message.setTimeout(msecs[, callback])` + @@ -2191,6 +2299,7 @@ added: v0.5.9 Calls `message.socket.setTimeout(msecs, callback)`. ### `message.socket` + @@ -2207,6 +2316,7 @@ a subclass of {stream.Duplex}, unless the user specified a socket type other than {net.Socket}. ### `message.statusCode` + @@ -2218,6 +2328,7 @@ added: v0.1.1 The 3-digit HTTP response status code. E.G. `404`. ### `message.statusMessage` + @@ -2230,6 +2341,7 @@ The HTTP response status message (reason phrase). E.G. `OK` or `Internal Server Error`. ### `message.trailers` + @@ -2239,6 +2351,7 @@ added: v0.3.0 The request/response trailers object. Only populated at the `'end'` event. ### `message.url` + @@ -2284,6 +2397,7 @@ URL { ``` ## Class: `http.OutgoingMessage` + @@ -2295,6 +2409,7 @@ and [`http.ServerResponse`][]. It is an abstract of outgoing message from the perspective of the participants of HTTP transaction. ### Event: `drain` + @@ -2302,6 +2417,7 @@ added: v0.3.6 Emitted when the buffer of the message is free again. ### Event: `finish` + @@ -2309,6 +2425,7 @@ added: v0.1.17 Emitted when the transmission is finished successfully. ### Event: `prefinish` + @@ -2318,6 +2435,7 @@ When the event is emitted, all data has been processed but not necessarily completely flushed. ### `outgoingMessage.addTrailers(headers)` + @@ -2344,6 +2462,7 @@ Attempting to set a header field name or value that contains invalid characters will result in a `TypeError` being thrown. ### `outgoingMessage.connection` + @@ -2362,6 +2483,7 @@ added: v14.0.0 See [`writable.cork()`][]. ### `outgoingMessage.destroy([error])` + @@ -2373,6 +2495,7 @@ Destroys the message. Once a socket is associated with the message and is connected, that socket will be destroyed as well. ### `outgoingMessage.end(chunk[, encoding][, callback])` + @@ -2413,6 +2537,7 @@ data is not sent until possibly much later. `outgoingMessage.flushHeaders()` bypasses the optimization and kickstarts the request. ### `outgoingMessage.getHeader(name)` + @@ -2424,16 +2549,18 @@ Gets the value of HTTP header with the given name. If such a name doesn't exist in message, it will be `undefined`. ### `outgoingMessage.getHeaderNames()` + -* Returns {string[]} +* Returns {string\[]} Returns an array of names of headers of the outgoing outgoingMessage. All names are lowercase. ### `outgoingMessage.getHeaders()` + @@ -2460,6 +2587,7 @@ const headers = outgoingMessage.getHeaders(); ``` ### `outgoingMessage.hasHeader(name)` + @@ -2475,6 +2603,7 @@ const hasContentType = outgoingMessage.hasHeader('content-type'); ``` ### `outgoingMessage.headersSent` + @@ -2484,6 +2613,7 @@ added: v0.9.3 Read-only. `true` if the headers were sent, otherwise `false`. ### `outgoingMessage.pipe()` + @@ -2498,6 +2628,7 @@ it inherits from `Stream`. The User should not call this function directly. ### `outgoingMessage.removeHeader()` + @@ -2509,6 +2640,7 @@ outgoingMessage.removeHeader('Content-Encoding'); ``` ### `outgoingMessage.setHeader(name, value)` + @@ -2520,6 +2652,7 @@ added: v0.4.0 Sets a single header value for the header object. ### `outgoingMessage.setTimeout(msesc[, callback])` + @@ -2533,6 +2666,7 @@ Once a socket is associated with the message and is connected, [`socket.setTimeout()`][] will be called with `msecs` as the first parameter. ### `outgoingMessage.socket` + @@ -2545,6 +2679,7 @@ this property. After calling `outgoingMessage.end()`, this property will be nulled. ### `outgoingMessage.uncork()` + @@ -2552,6 +2687,7 @@ added: v14.0.0 See [`writable.uncork()`][] ### `outgoingMessage.writableCorked` + @@ -2562,6 +2698,7 @@ This `outgoingMessage.writableCorked` will return the time how many `outgoingMessage.cork()` have been called. ### `outgoingMessage.writableEnded` + @@ -2573,6 +2710,7 @@ this property does not reflect whether the data has been flush. For that purpose, use `message.writableFinished` instead. ### `outgoingMessage.writableFinished` + @@ -2582,6 +2720,7 @@ added: v13.0.0 Readonly. `true` if all data has been flushed to the underlying system. ### `outgoingMessage.writableHighWaterMark` + @@ -2596,6 +2735,7 @@ underlying socket if socket exists. Else, it would be the default buffered by the socket. ### `outgoingMessage.writableLength` + @@ -2606,6 +2746,7 @@ Readonly, This `outgoingMessage.writableLength` contains the number of bytes (or objects) in the buffer ready to send. ### `outgoingMessage.writableObjectMode` + @@ -2615,6 +2756,7 @@ added: v13.0.0 Readonly, always returns `false`. ### `outgoingMessage.write(chunk[, encoding][, callback])` + -* {string[]} +* {string\[]} A list of the HTTP methods that are supported by the parser. ## `http.STATUS_CODES` + @@ -2678,6 +2822,7 @@ short description of each. For example, `http.STATUS_CODES[404] === 'Not Found'`. ## `http.createServer([options][, requestListener])` + @@ -2843,6 +2992,7 @@ Global instance of `Agent` which is used as the default for all HTTP client requests. ## `http.maxHeaderSize` + @@ -3162,6 +3315,7 @@ or response. The HTTP module will automatically validate such headers. Examples: Example: + ```js const { validateHeaderName } = require('http'); @@ -3175,6 +3329,7 @@ try { ``` ## `http.validateHeaderValue(name, value)` + @@ -3186,6 +3341,7 @@ Performs the low-level validations on the provided `value` that are done when `res.setHeader(name, value)` is called. Passing illegal value as `value` will result in a [`TypeError`][] being thrown. + * Undefined value error is identified by `code: 'ERR_HTTP_INVALID_HEADER_VALUE'`. * Invalid value character error is identified by `code: 'ERR_INVALID_CHAR'`. -- cgit v1.2.3