From 19e8ae44c4c90546e3adcab067a12f710b8197f3 Mon Sep 17 00:00:00 2001 From: Qingyu Deng Date: Thu, 4 Feb 2021 18:53:57 +0800 Subject: [PATCH] doc: add document for http.OutgoingMessage OutgoingMessage is a very old feature which is exported to public in http module dated to v0.1.x. But it is not documented at all. This commit adds document for http.OutgogingMessage. Fixes: https://github.com/nodejs/node/issues/33847 PR-URL: https://github.com/nodejs/node/pull/37265 Reviewed-By: James M Snell Reviewed-By: Robert Nagy Reviewed-By: Benjamin Gruenbaum --- doc/api/http.md | 374 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 374 insertions(+) diff --git a/doc/api/http.md b/doc/api/http.md index 68e2b68ab860e4..4c77e45296a410 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -2190,6 +2190,378 @@ URL { } ``` +## Class: `http.OutgoingMessage` + + +* Extends: {Stream} + +This class serves as the parent class of [`http.ClientRequest`][] +and [`http.ServerResponse`][]. It is an abstract of outgoing message from +the perspective of the participants of HTTP transaction. + +### Event: `drain` + + +Emitted when the buffer of the message is free again. + +### Event: `finish` + + +Emitted when transmission is finished successfully. + +### Event: `prefinish` + + +Emitted when `outgoingMessage.end` was called. +When the event is emitted, all data has been processed but not necessarily +completely flushed. + +### `outgoingMessage.addTrailers(headers)` + + +* `headers` {Object} + +Adds HTTP trailers (headers but at the end of the message) to the message. + +Trailers are **only** be emitted if the message is chunked encoded. If not, +trailer will be silently discarded. + +HTTP requires the `Trailer` header to be sent in order to emit trailers, +with a list of header fields in its value, e.g. + +```js +message.writeHead(200, { 'Content-Type': 'text/plain', + 'Trailer': 'Content-MD5' }); +message.write(fileData); +message.addTrailers({ 'Content-MD5': '7895bf4b8828b55ceaf47747b4bca667' }); +message.end(); +``` + +Attempting to set a header field name or value that contains invalid characters +will result in a `TypeError` being thrown. + +### `outgoingMessage.connection` + + +> Stability: 0 - Deprecated: Use [`outgoingMessage.socket`][] instead. + +Aliases of `outgoingMessage.socket` +### `outgoingMessage.cork()` + + +See [`writable.cork()`][]. + +### `outgoingMessage.destroy([error])` + + +* `error` {Error} Optional, an error to emit with `error` event +* Returns: {this} + +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])` + + +* `chunk` {string | Buffer} +* `encoding` {string} Optional, **Default**: `utf-8` +* `callback` {Function} Optional +* Returns: {this} + +Finishes the outgoing message. If any parts of the body are unsent, it will +flush them to the underlying system. If the message is chunked, it will +send the terminating chunk `0\r\n\r\n`, and send the trailer (if any). + +If `chunk` is specified, it is equivalent to call +`outgoingMessage.write(chunk, encoding)`, followed by +`outgoingMessage.end(callback)`. + +If `callback` is provided, it will be called when the message is finished. +(equivalent to the callback to event `finish`) + +### `outgoingMessage.flushHeaders()` + + +Compulsorily flushes the message headers + +For efficiency reason, Node.js normally buffers the message headers +until `outgoingMessage.end()` is called or the first chunk of message data +is written. It then tries to pack the headers and data into a single TCP +packet. + +It is usually desired (it saves a TCP round-trip), but not when the first +data is not sent until possibly much later. `outgoingMessage.flushHeaders()` +bypasses the optimization and kickstarts the request. + +### `outgoingMessage.getHeader(name)` + + +* `name` {string} Name of header +* Returns {string | undefined} + +Gets value of HTTP header with given name. If such name doesn't exist in +message, it will be `undefined`. + +### `outgoingMessage.getHeaderNames()` + + +* Returns {string[]} + +Returns an array of names of headers of the outgoing outgoingMessage. All +names are lowercase. + +### `outgoingMessage.getHeaders()` + + +* Returns: {Object} + +Returns a shallow copy of the current outgoing headers. Since a shallow +copy is used, array values may be mutated without additional calls to +various header-related http module methods. The keys of the returned +object are the header names and the values are the respective header +values. All header names are lowercase. + +The object returned by the `outgoingMessage.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. + +```js +outgoingMessage.setHeader('Foo', 'bar'); +outgoingMessage.setHeader('Set-Cookie', ['foo=bar', 'bar=baz']); + +const headers = outgoingMessage.getHeaders(); +// headers === { foo: 'bar', 'set-cookie': ['foo=bar', 'bar=baz'] } +``` + +### `outgoingMessage.hasHeader(name)` + + +* `name` {string} +* Returns {boolean} + +Returns `true` if the header identified by `name` is currently set in the +outgoing headers. The header name is case-insensitive. + +```js +const hasContentType = outgoingMessage.hasHeader('content-type'); +``` + +### `outgoingMessage.headersSent` + + +* {boolean} + +Read-only. `true` if the headers were sent, otherwise `false`. + +### `outgoingMessage.pipe()` + + +Overrides the pipe method of legacy `Stream` which is the parent class of +`http.outgoingMessage`. + +Since `OutgoingMessage` should be a write-only stream, +call this function will throw an `Error`. Thus, it disabled the pipe method +it inherits from `Stream`. + +User should not call this function directly. + +### `outgoingMessage.removeHeader()` + + +Removes a header that is queued for implicit sending. + +```js +outgoingMessage.removeHeader('Content-Encoding'); +``` + +### `outgoingMessage.setHeader(name, value)` + + +* `name` {string} Header name +* `value` {string} Header value +* Returns: {this} + +Sets a single header value for header object. + +### `outgoingMessage.setTimeout(msesc[, callback])` + + +* `msesc` {number} +* `callback` {Function} Optional function to be called when a timeout +occurs, Same as binding to the `timeout` event. +* Returns: {this} + +Once a socket is associated with the message and is connected, +[`socket.setTimeout()`][] will be called with `msecs` as the first parameter. + +### `outgoingMessage.socket` + + +* {stream.Duplex} + +Reference to the underlying socket. Usually users will not want to access +this property. + +After calling `outgoingMessage.end()`, this property will be nulled. + +### `outgoingMessage.uncork()` + + +See [`writable.uncork()`][] + +### `outgoingMessage.writableCorked` + + +* {number} + +This `outgoingMessage.writableCorked` will return the time how many +`outgoingMessage.cork()` have been called. + +### `outgoingMessage.writableEnded` + + +* {boolean} + +Readonly, `true` if `outgoingMessage.end()` has been called. Noted that +this property does not reflect whether the data has been flush. For that +purpose, use `message.writableFinished` instead. + +### `outgoingMessage.writableFinished` + + +* {boolean} + +Readonly. `true` if all data has been flushed to the underlying system. + +### `outgoingMessage.writableHighWaterMark` + + +* {number} + +This `outgoingMessage.writableHighWaterMark` will be the `highWaterMark` of +underlying socket if socket exists. Else, it would be the default +`highWaterMark`. + +`highWaterMark` is the maximum amount of data which can be potentially +buffered by socket. + +### `outgoingMessage.writableLength` + + +* {number} + +Readonly, This `outgoingMessage.writableLength` contains the number of +bytes (or objects) in the buffer ready to send. + +### `outgoingMessage.writableObjectMode` + + +* {boolean} + +Readonly, always returns `false`. + +### `outgoingMessage.write(chunk[, encoding][, callback])` + + +* `chunk` {string | Buffer} +* `encoding` {string} **Default**: `utf-8` +* `callback` {Function} +* Returns {boolean} + +If this method is called and header is not sent, it will call +`this._implicitHeader` to flush implicit header. +If the message should not have a body (indicated by `this._hasBody`), +the call is ignored and `chunk` will not be sent. It could be useful +when handling particular message which must not include a body. +e.g. response to `HEAD` request, `204` and `304` response. + +`chunk` can be a string or a buffer. When `chunk` is a string, the +`encoding` parameter specifies how to encode `chunk` into a byte stream. +`callback` will be called when the `chunk` is flushed. + +If the message is transferred in chucked encoding +(indicated by `this.chunkedEncoding`), `chunk` will be flushed as +one chunk among a stream of chunks. Otherwise, it will be flushed as body +of message. + +This method handles the raw body of HTTP message and has nothing to do with +higher-level multi-part body encodings that may be used. + +If it is the first call to this method of a message, it will send the +buffered header first, then flush the the `chunk` as described above. + +The second and successive calls to this method, it will assume the data +will streamed and send the new data separately. It means that the response +is buffered up to the first chunk of the body. + +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. Event `drain` will be emitted when the buffer is free again. + ## `http.METHODS`