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: #33847

PR-URL: #37265
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Robert Nagy <[email protected]>
Reviewed-By: Benjamin Gruenbaum <[email protected]>

doc/api/http.md

@@ -2209,6 +2209,378 @@ URL {
 }
 ```
 
+## Class: `http.OutgoingMessage`
+<!-- YAML
+added: v0.1.17
+-->
+
+* 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`
+<!-- YAML
+added: v0.3.6
+-->
+
+Emitted when the buffer of the message is free again.
+
+### Event: `finish`
+<!-- YAML
+added: v0.1.17
+-->
+
+Emitted when transmission is finished successfully.
+
+### Event: `prefinish`
+<!-- YAML
+added: v0.11.6
+-->
+
+Emitted when `outgoingMessage.end` was called.
+When the event is emitted, all data has been processed but not necessarily
+completely flushed.
+
+### `outgoingMessage.addTrailers(headers)`
+<!-- YAML
+added: v0.3.0
+-->
+
+* `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`
+<!-- YAML
+added: v0.3.0
+deprecated: REPLACEME
+-->
+
+> Stability: 0 - Deprecated: Use [`outgoingMessage.socket`][] instead.
+
+Aliases of `outgoingMessage.socket`
+### `outgoingMessage.cork()`
+<!-- YAML
+added: v14.0.0
+-->
+
+See [`writable.cork()`][].
+
+### `outgoingMessage.destroy([error])`
+<!-- YAML
+added: v0.3.0
+-->
+
+* `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])`
+<!-- YAML
+added: v0.1.90
+changes:
+  - version: v0.11.6
+    description: add `callback` argument.
+-->
+
+* `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()`
+<!-- YAML
+added: v1.6.0
+-->
+
+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)`
+<!-- YAML
+added: v0.4.0
+-->
+
+* `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()`
+<!-- YAML
+added: v8.0.0
+-->
+
+* Returns {string[]}
+
+Returns an array of names of headers of the outgoing outgoingMessage. All
+names are lowercase.
+
+### `outgoingMessage.getHeaders()`
+<!-- YAML
+added:  v8.0.0
+-->
+
+* 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)`
+<!-- YAML
+added:  v8.0.0
+-->
+
+* `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`
+<!-- YAML
+added: v0.9.3
+-->
+
+* {boolean}
+
+Read-only. `true` if the headers were sent, otherwise `false`.
+
+### `outgoingMessage.pipe()`
+<!-- YAML
+added: v9.0.0
+-->
+
+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()`
+<!-- YAML
+added:  v0.4.0
+-->
+
+Removes a header that is queued for implicit sending.
+
+```js
+outgoingMessage.removeHeader('Content-Encoding');
+```
+
+### `outgoingMessage.setHeader(name, value)`
+<!-- YAML
+added: v0.4.0
+-->
+
+* `name` {string} Header name
+* `value` {string} Header value
+* Returns: {this}
+
+Sets a single header value for header object.
+
+### `outgoingMessage.setTimeout(msesc[, callback])`
+<!-- YAML
+added: v0.9.12
+-->
+
+* `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`
+<!-- YAML
+added: v0.3.0
+-->
+
+* {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()`
+<!-- YAML
+added: v14.0.0
+-->
+
+See [`writable.uncork()`][]
+
+### `outgoingMessage.writableCorked`
+<!-- YAML
+added: v14.0.0
+-->
+
+* {number}
+
+This `outgoingMessage.writableCorked` will return the time how many
+`outgoingMessage.cork()` have been called.
+
+### `outgoingMessage.writableEnded`
+<!-- YAML
+added: v13.0.0
+-->
+
+* {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`
+<!-- YAML
+added: v13.0.0
+-->
+
+* {boolean}
+
+Readonly. `true` if all data has been flushed to the underlying system.
+
+### `outgoingMessage.writableHighWaterMark`
+<!-- YAML
+added: v13.0.0
+-->
+
+* {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`
+<!-- YAML
+added: v13.0.0
+-->
+
+* {number}
+
+Readonly, This `outgoingMessage.writableLength` contains the number of
+bytes (or objects) in the buffer ready to send.
+
+### `outgoingMessage.writableObjectMode`
+<!-- YAML
+added: v13.0.0
+-->
+
+* {boolean}
+
+Readonly, always returns `false`.
+
+### `outgoingMessage.write(chunk[, encoding][, callback])`
+<!-- YAML
+added: v0.1.29
+changes:
+  - version: v0.11.6
+    description: add `callback` argument.
+-->
+
+* `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`
 <!-- YAML
 added: v0.11.8
@@ -2734,6 +3106,7 @@ try {
 [`http.ClientRequest`]: #http_class_http_clientrequest
 [`http.IncomingMessage`]: #http_class_http_incomingmessage
 [`http.Server`]: #http_class_http_server
+[`http.ServerResponse`]: #http_class_http_serverresponse
 [`http.get()`]: #http_http_get_options_callback
 [`http.globalAgent`]: #http_http_globalagent
 [`http.request()`]: #http_http_request_options_callback
@@ -2743,6 +3116,7 @@ try {
 [`net.Socket`]: net.md#net_class_net_socket
 [`net.createConnection()`]: net.md#net_net_createconnection_options_connectlistener
 [`new URL()`]: url.md#url_new_url_input_base
+[`outgoingMessage.socket`]: #http_outgoingMessage.socket
 [`removeHeader(name)`]: #http_request_removeheader_name
 [`request.end()`]: #http_request_end_data_encoding_callback
 [`request.destroy()`]: #http_request_destroy_error