Skip to content

Commit

Permalink
doc: add document for http.OutgoingMessage
Browse files Browse the repository at this point in the history
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 <jasnell@gmail.com>
Reviewed-By: Robert Nagy <ronagy@icloud.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
  • Loading branch information
Ayase-252 authored and targos committed Jun 11, 2021
1 parent a6c1233 commit 19e8ae4
Showing 1 changed file with 374 additions and 0 deletions.
374 changes: 374 additions & 0 deletions doc/api/http.md
Original file line number Diff line number Diff line change
Expand Up @@ -2190,6 +2190,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
Expand Down Expand Up @@ -2722,6 +3094,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
Expand All @@ -2731,6 +3104,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
Expand Down

0 comments on commit 19e8ae4

Please sign in to comment.