diff --git a/doc/api/http.md b/doc/api/http.md index 0c7cfa5a858977..09d1338cbb1029 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -2702,6 +2702,35 @@ been transmitted are equal or not. Attempting to set a header field name or value that contains invalid characters will result in a [`TypeError`][] being thrown. +### `response.writeInformation(statusCode[, headers][, callback])` + + + +* `statusCode` {number} An HTTP 1xx informational status code, between `100` + and `199` inclusive, excluding `101` (Switching Protocols) which is only + available through the [`'upgrade'`][] event. +* `headers` {Object|Array} An optional set of headers to send with the + informational response. Accepts the same shapes as + [`response.writeHead()`][]. +* `callback` {Function} Optional, called once the message has been written + to the socket. + +Sends an arbitrary HTTP/1.1 1xx informational response to the client. This +is a generic equivalent of [`response.writeContinue()`][], +[`response.writeProcessing()`][] and [`response.writeEarlyHints()`][], and +can be called multiple times before the final response. After the final +response headers have been sent (via [`response.writeHead()`][] or an +implicit header), calling this method throws `ERR_HTTP_HEADERS_SENT`. + +Clients receive these responses via the [`'information'`][information event] +event on `http.ClientRequest`. + +```js +response.writeInformation(110, { 'X-Progress': '50%' }); +``` + ### `response.writeProcessing()` + +* `statusCode` {number} An HTTP 1xx informational status code, between `100` + and `199` inclusive, excluding `101` (Switching Protocols) which is not + allowed in HTTP/2. +* `headers` {Object} An optional object of headers to send with the + informational response. + +Sends an arbitrary HTTP 1xx informational response, equivalent in HTTP/2 to a +`HEADERS` frame whose `:status` pseudo-header is a 1xx code. May be called +multiple times before the final response. After the final response headers +have been sent, this method is a no-op and returns `false`. + +This is the generic equivalent of [`response.writeContinue()`][] and +[`response.writeEarlyHints()`][]. + +```js +response.writeInformation(110, { 'X-Progress': '50%' }); +``` + #### `response.writeHead(statusCode[, statusMessage][, headers])`