Skip to content

Commit 53b673e

Browse files
Ayase-252benjamingr
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 <[email protected]> Reviewed-By: Robert Nagy <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]>
1 parent c347f23 commit 53b673e

File tree

1 file changed

+374
-0
lines changed

1 file changed

+374
-0
lines changed

doc/api/http.md

Lines changed: 374 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2233,6 +2233,378 @@ URL {
22332233
}
22342234
```
22352235

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

0 commit comments

Comments
 (0)