Skip to content

Commit e5f7179

Browse files
Ayase-252danielleadams
authored andcommitted
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 <jasnell@gmail.com> Reviewed-By: Robert Nagy <ronagy@icloud.com> Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
1 parent 7c0ce17 commit e5f7179

File tree

1 file changed

+374
-0
lines changed

1 file changed

+374
-0
lines changed

doc/api/http.md

+374
Original file line numberDiff line numberDiff line change
@@ -2209,6 +2209,378 @@ URL {
22092209
}
22102210
```
22112211

2212+
## Class: `http.OutgoingMessage`
2213+
<!-- YAML
2214+
added: v0.1.17
2215+
-->
2216+
2217+
* Extends: {Stream}
2218+
2219+
This class serves as the parent class of [`http.ClientRequest`][]
2220+
and [`http.ServerResponse`][]. It is an abstract of outgoing message from
2221+
the perspective of the participants of HTTP transaction.
2222+
2223+
### Event: `drain`
2224+
<!-- YAML
2225+
added: v0.3.6
2226+
-->
2227+
2228+
Emitted when the buffer of the message is free again.
2229+
2230+
### Event: `finish`
2231+
<!-- YAML
2232+
added: v0.1.17
2233+
-->
2234+
2235+
Emitted when transmission is finished successfully.
2236+
2237+
### Event: `prefinish`
2238+
<!-- YAML
2239+
added: v0.11.6
2240+
-->
2241+
2242+
Emitted when `outgoingMessage.end` was called.
2243+
When the event is emitted, all data has been processed but not necessarily
2244+
completely flushed.
2245+
2246+
### `outgoingMessage.addTrailers(headers)`
2247+
<!-- YAML
2248+
added: v0.3.0
2249+
-->
2250+
2251+
* `headers` {Object}
2252+
2253+
Adds HTTP trailers (headers but at the end of the message) to the message.
2254+
2255+
Trailers are **only** be emitted if the message is chunked encoded. If not,
2256+
trailer will be silently discarded.
2257+
2258+
HTTP requires the `Trailer` header to be sent in order to emit trailers,
2259+
with a list of header fields in its value, e.g.
2260+
2261+
```js
2262+
message.writeHead(200, { 'Content-Type': 'text/plain',
2263+
'Trailer': 'Content-MD5' });
2264+
message.write(fileData);
2265+
message.addTrailers({ 'Content-MD5': '7895bf4b8828b55ceaf47747b4bca667' });
2266+
message.end();
2267+
```
2268+
2269+
Attempting to set a header field name or value that contains invalid characters
2270+
will result in a `TypeError` being thrown.
2271+
2272+
### `outgoingMessage.connection`
2273+
<!-- YAML
2274+
added: v0.3.0
2275+
deprecated: REPLACEME
2276+
-->
2277+
2278+
> Stability: 0 - Deprecated: Use [`outgoingMessage.socket`][] instead.
2279+
2280+
Aliases of `outgoingMessage.socket`
2281+
### `outgoingMessage.cork()`
2282+
<!-- YAML
2283+
added: v14.0.0
2284+
-->
2285+
2286+
See [`writable.cork()`][].
2287+
2288+
### `outgoingMessage.destroy([error])`
2289+
<!-- YAML
2290+
added: v0.3.0
2291+
-->
2292+
2293+
* `error` {Error} Optional, an error to emit with `error` event
2294+
* Returns: {this}
2295+
2296+
Destroys the message. Once a socket is associated with the message
2297+
and is connected, that socket will be destroyed as well.
2298+
2299+
### `outgoingMessage.end(chunk[, encoding][, callback])`
2300+
<!-- YAML
2301+
added: v0.1.90
2302+
changes:
2303+
- version: v0.11.6
2304+
description: add `callback` argument.
2305+
-->
2306+
2307+
* `chunk` {string | Buffer}
2308+
* `encoding` {string} Optional, **Default**: `utf-8`
2309+
* `callback` {Function} Optional
2310+
* Returns: {this}
2311+
2312+
Finishes the outgoing message. If any parts of the body are unsent, it will
2313+
flush them to the underlying system. If the message is chunked, it will
2314+
send the terminating chunk `0\r\n\r\n`, and send the trailer (if any).
2315+
2316+
If `chunk` is specified, it is equivalent to call
2317+
`outgoingMessage.write(chunk, encoding)`, followed by
2318+
`outgoingMessage.end(callback)`.
2319+
2320+
If `callback` is provided, it will be called when the message is finished.
2321+
(equivalent to the callback to event `finish`)
2322+
2323+
### `outgoingMessage.flushHeaders()`
2324+
<!-- YAML
2325+
added: v1.6.0
2326+
-->
2327+
2328+
Compulsorily flushes the message headers
2329+
2330+
For efficiency reason, Node.js normally buffers the message headers
2331+
until `outgoingMessage.end()` is called or the first chunk of message data
2332+
is written. It then tries to pack the headers and data into a single TCP
2333+
packet.
2334+
2335+
It is usually desired (it saves a TCP round-trip), but not when the first
2336+
data is not sent until possibly much later. `outgoingMessage.flushHeaders()`
2337+
bypasses the optimization and kickstarts the request.
2338+
2339+
### `outgoingMessage.getHeader(name)`
2340+
<!-- YAML
2341+
added: v0.4.0
2342+
-->
2343+
2344+
* `name` {string} Name of header
2345+
* Returns {string | undefined}
2346+
2347+
Gets value of HTTP header with given name. If such name doesn't exist in
2348+
message, it will be `undefined`.
2349+
2350+
### `outgoingMessage.getHeaderNames()`
2351+
<!-- YAML
2352+
added: v8.0.0
2353+
-->
2354+
2355+
* Returns {string[]}
2356+
2357+
Returns an array of names of headers of the outgoing outgoingMessage. All
2358+
names are lowercase.
2359+
2360+
### `outgoingMessage.getHeaders()`
2361+
<!-- YAML
2362+
added: v8.0.0
2363+
-->
2364+
2365+
* Returns: {Object}
2366+
2367+
Returns a shallow copy of the current outgoing headers. Since a shallow
2368+
copy is used, array values may be mutated without additional calls to
2369+
various header-related http module methods. The keys of the returned
2370+
object are the header names and the values are the respective header
2371+
values. All header names are lowercase.
2372+
2373+
The object returned by the `outgoingMessage.getHeaders()` method does
2374+
not prototypically inherit from the JavaScript Object. This means that
2375+
typical Object methods such as `obj.toString()`, `obj.hasOwnProperty()`,
2376+
and others are not defined and will not work.
2377+
2378+
```js
2379+
outgoingMessage.setHeader('Foo', 'bar');
2380+
outgoingMessage.setHeader('Set-Cookie', ['foo=bar', 'bar=baz']);
2381+
2382+
const headers = outgoingMessage.getHeaders();
2383+
// headers === { foo: 'bar', 'set-cookie': ['foo=bar', 'bar=baz'] }
2384+
```
2385+
2386+
### `outgoingMessage.hasHeader(name)`
2387+
<!-- YAML
2388+
added: v8.0.0
2389+
-->
2390+
2391+
* `name` {string}
2392+
* Returns {boolean}
2393+
2394+
Returns `true` if the header identified by `name` is currently set in the
2395+
outgoing headers. The header name is case-insensitive.
2396+
2397+
```js
2398+
const hasContentType = outgoingMessage.hasHeader('content-type');
2399+
```
2400+
2401+
### `outgoingMessage.headersSent`
2402+
<!-- YAML
2403+
added: v0.9.3
2404+
-->
2405+
2406+
* {boolean}
2407+
2408+
Read-only. `true` if the headers were sent, otherwise `false`.
2409+
2410+
### `outgoingMessage.pipe()`
2411+
<!-- YAML
2412+
added: v9.0.0
2413+
-->
2414+
2415+
Overrides the pipe method of legacy `Stream` which is the parent class of
2416+
`http.outgoingMessage`.
2417+
2418+
Since `OutgoingMessage` should be a write-only stream,
2419+
call this function will throw an `Error`. Thus, it disabled the pipe method
2420+
it inherits from `Stream`.
2421+
2422+
User should not call this function directly.
2423+
2424+
### `outgoingMessage.removeHeader()`
2425+
<!-- YAML
2426+
added: v0.4.0
2427+
-->
2428+
2429+
Removes a header that is queued for implicit sending.
2430+
2431+
```js
2432+
outgoingMessage.removeHeader('Content-Encoding');
2433+
```
2434+
2435+
### `outgoingMessage.setHeader(name, value)`
2436+
<!-- YAML
2437+
added: v0.4.0
2438+
-->
2439+
2440+
* `name` {string} Header name
2441+
* `value` {string} Header value
2442+
* Returns: {this}
2443+
2444+
Sets a single header value for header object.
2445+
2446+
### `outgoingMessage.setTimeout(msesc[, callback])`
2447+
<!-- YAML
2448+
added: v0.9.12
2449+
-->
2450+
2451+
* `msesc` {number}
2452+
* `callback` {Function} Optional function to be called when a timeout
2453+
occurs, Same as binding to the `timeout` event.
2454+
* Returns: {this}
2455+
2456+
Once a socket is associated with the message and is connected,
2457+
[`socket.setTimeout()`][] will be called with `msecs` as the first parameter.
2458+
2459+
### `outgoingMessage.socket`
2460+
<!-- YAML
2461+
added: v0.3.0
2462+
-->
2463+
2464+
* {stream.Duplex}
2465+
2466+
Reference to the underlying socket. Usually users will not want to access
2467+
this property.
2468+
2469+
After calling `outgoingMessage.end()`, this property will be nulled.
2470+
2471+
### `outgoingMessage.uncork()`
2472+
<!-- YAML
2473+
added: v14.0.0
2474+
-->
2475+
2476+
See [`writable.uncork()`][]
2477+
2478+
### `outgoingMessage.writableCorked`
2479+
<!-- YAML
2480+
added: v14.0.0
2481+
-->
2482+
2483+
* {number}
2484+
2485+
This `outgoingMessage.writableCorked` will return the time how many
2486+
`outgoingMessage.cork()` have been called.
2487+
2488+
### `outgoingMessage.writableEnded`
2489+
<!-- YAML
2490+
added: v13.0.0
2491+
-->
2492+
2493+
* {boolean}
2494+
2495+
Readonly, `true` if `outgoingMessage.end()` has been called. Noted that
2496+
this property does not reflect whether the data has been flush. For that
2497+
purpose, use `message.writableFinished` instead.
2498+
2499+
### `outgoingMessage.writableFinished`
2500+
<!-- YAML
2501+
added: v13.0.0
2502+
-->
2503+
2504+
* {boolean}
2505+
2506+
Readonly. `true` if all data has been flushed to the underlying system.
2507+
2508+
### `outgoingMessage.writableHighWaterMark`
2509+
<!-- YAML
2510+
added: v13.0.0
2511+
-->
2512+
2513+
* {number}
2514+
2515+
This `outgoingMessage.writableHighWaterMark` will be the `highWaterMark` of
2516+
underlying socket if socket exists. Else, it would be the default
2517+
`highWaterMark`.
2518+
2519+
`highWaterMark` is the maximum amount of data which can be potentially
2520+
buffered by socket.
2521+
2522+
### `outgoingMessage.writableLength`
2523+
<!-- YAML
2524+
added: v13.0.0
2525+
-->
2526+
2527+
* {number}
2528+
2529+
Readonly, This `outgoingMessage.writableLength` contains the number of
2530+
bytes (or objects) in the buffer ready to send.
2531+
2532+
### `outgoingMessage.writableObjectMode`
2533+
<!-- YAML
2534+
added: v13.0.0
2535+
-->
2536+
2537+
* {boolean}
2538+
2539+
Readonly, always returns `false`.
2540+
2541+
### `outgoingMessage.write(chunk[, encoding][, callback])`
2542+
<!-- YAML
2543+
added: v0.1.29
2544+
changes:
2545+
- version: v0.11.6
2546+
description: add `callback` argument.
2547+
-->
2548+
2549+
* `chunk` {string | Buffer}
2550+
* `encoding` {string} **Default**: `utf-8`
2551+
* `callback` {Function}
2552+
* Returns {boolean}
2553+
2554+
If this method is called and header is not sent, it will call
2555+
`this._implicitHeader` to flush implicit header.
2556+
If the message should not have a body (indicated by `this._hasBody`),
2557+
the call is ignored and `chunk` will not be sent. It could be useful
2558+
when handling particular message which must not include a body.
2559+
e.g. response to `HEAD` request, `204` and `304` response.
2560+
2561+
`chunk` can be a string or a buffer. When `chunk` is a string, the
2562+
`encoding` parameter specifies how to encode `chunk` into a byte stream.
2563+
`callback` will be called when the `chunk` is flushed.
2564+
2565+
If the message is transferred in chucked encoding
2566+
(indicated by `this.chunkedEncoding`), `chunk` will be flushed as
2567+
one chunk among a stream of chunks. Otherwise, it will be flushed as body
2568+
of message.
2569+
2570+
This method handles the raw body of HTTP message and has nothing to do with
2571+
higher-level multi-part body encodings that may be used.
2572+
2573+
If it is the first call to this method of a message, it will send the
2574+
buffered header first, then flush the the `chunk` as described above.
2575+
2576+
The second and successive calls to this method, it will assume the data
2577+
will streamed and send the new data separately. It means that the response
2578+
is buffered up to the first chunk of the body.
2579+
2580+
Returns `true` if the entire data was flushed successfully to the kernel
2581+
buffer. Returns `false` if all or part of the data was queued in user
2582+
memory. Event `drain` will be emitted when the buffer is free again.
2583+
22122584
## `http.METHODS`
22132585
<!-- YAML
22142586
added: v0.11.8
@@ -2734,6 +3106,7 @@ try {
27343106
[`http.ClientRequest`]: #http_class_http_clientrequest
27353107
[`http.IncomingMessage`]: #http_class_http_incomingmessage
27363108
[`http.Server`]: #http_class_http_server
3109+
[`http.ServerResponse`]: #http_class_http_serverresponse
27373110
[`http.get()`]: #http_http_get_options_callback
27383111
[`http.globalAgent`]: #http_http_globalagent
27393112
[`http.request()`]: #http_http_request_options_callback
@@ -2743,6 +3116,7 @@ try {
27433116
[`net.Socket`]: net.md#net_class_net_socket
27443117
[`net.createConnection()`]: net.md#net_net_createconnection_options_connectlistener
27453118
[`new URL()`]: url.md#url_new_url_input_base
3119+
[`outgoingMessage.socket`]: #http_outgoingMessage.socket
27463120
[`removeHeader(name)`]: #http_request_removeheader_name
27473121
[`request.end()`]: #http_request_end_data_encoding_callback
27483122
[`request.destroy()`]: #http_request_destroy_error

0 commit comments

Comments
 (0)