diff options
| -rw-r--r-- | doc/api/http.md | 112 |
1 files changed, 44 insertions, 68 deletions
diff --git a/doc/api/http.md b/doc/api/http.md index f8a4bb163f..0174908eb5 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -2455,8 +2455,8 @@ 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. +and [`http.ServerResponse`][]. It is an abstract outgoing message from +the perspective of the participants of an HTTP transaction. ### Event: `'drain'` @@ -2480,7 +2480,7 @@ Emitted when the transmission is finished successfully. added: v0.11.6 --> -Emitted when `outgoingMessage.end` was called. +Emitted after `outgoingMessage.end()` is called. When the event is emitted, all data has been processed but not necessarily completely flushed. @@ -2494,11 +2494,11 @@ added: v0.3.0 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, -the trailer will be silently discarded. +Trailers will **only** be emitted if the message is chunked encoded. If not, +the trailers will be silently discarded. HTTP requires the `Trailer` header to be sent to emit trailers, -with a list of header fields in its value, e.g. +with a list of header field names in its value, e.g. ```js message.writeHead(200, { 'Content-Type': 'text/plain', @@ -2522,7 +2522,7 @@ deprecated: > Stability: 0 - Deprecated: Use [`outgoingMessage.socket`][] instead. -Aliases of `outgoingMessage.socket` +Alias of [`outgoingMessage.socket`][]. ### `outgoingMessage.cork()` @@ -2562,14 +2562,14 @@ changes: 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). +send the terminating chunk `0\r\n\r\n`, and send the trailers (if any). -If `chunk` is specified, it is equivalent to call +If `chunk` is specified, it is equivalent to calling `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`) +If `callback` is provided, it will be called when the message is finished +(equivalent to a listener of the `'finish'` event). ### `outgoingMessage.flushHeaders()` @@ -2577,7 +2577,7 @@ If `callback` is provided, it will be called when the message is finished. added: v1.6.0 --> -Compulsorily flushes the message headers +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 @@ -2586,7 +2586,7 @@ 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. +bypasses the optimization and kickstarts the message. ### `outgoingMessage.getHeader(name)` @@ -2597,8 +2597,8 @@ added: v0.4.0 * `name` {string} Name of header * Returns {string | undefined} -Gets the value of HTTP header with the given name. If such a name doesn't -exist in message, it will be `undefined`. +Gets the value of the HTTP header with the given name. If that header is not +set, the returned value will be `undefined`. ### `outgoingMessage.getHeaderNames()` @@ -2608,8 +2608,8 @@ added: v7.7.0 * Returns {string\[]} -Returns an array of names of headers of the outgoing outgoingMessage. All -names are lowercase. +Returns an array containing the unique names of the current outgoing headers. +All names are lowercase. ### `outgoingMessage.getHeaders()` @@ -2626,8 +2626,8 @@ 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()`, +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 @@ -2670,14 +2670,11 @@ Read-only. `true` if the headers were sent, otherwise `false`. 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`. +Overrides the `stream.pipe()` method inherited from the legacy `Stream` class +which is the parent class of `http.OutgoingMessage`. -The User should not call this function directly. +Calling this method will throw an `Error` because `outgoingMessage` is a +write-only stream. ### `outgoingMessage.removeHeader(name)` @@ -2700,10 +2697,12 @@ added: v0.4.0 --> * `name` {string} Header name -* `value` {string} Header value +* `value` {any} Header value * Returns: {this} -Sets a single header value for the header object. +Sets a single header value. If the header already exists in the to-be-sent +headers, its value will be replaced. Use an array of strings to send multiple +headers with the same name. ### `outgoingMessage.setTimeout(msesc[, callback])` @@ -2752,8 +2751,7 @@ added: * {number} -This `outgoingMessage.writableCorked` will return the time how many -`outgoingMessage.cork()` have been called. +The number of times `outgoingMessage.cork()` has been called. ### `outgoingMessage.writableEnded` @@ -2763,9 +2761,9 @@ added: v12.9.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. +Is `true` if `outgoingMessage.end()` has been called. This property does +not indicate whether the data has been flushed. For that purpose, use +`message.writableFinished` instead. ### `outgoingMessage.writableFinished` @@ -2775,7 +2773,7 @@ added: v12.7.0 * {boolean} -Readonly. `true` if all data has been flushed to the underlying system. +Is `true` if all data has been flushed to the underlying system. ### `outgoingMessage.writableHighWaterMark` @@ -2785,12 +2783,8 @@ added: v12.9.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 that can be potentially -buffered by the socket. +The `highWaterMark` of the underlying socket if assigned. Otherwise, the default +buffer level when [`writable.write()`][] starts returning false (`16384`). ### `outgoingMessage.writableLength` @@ -2800,8 +2794,7 @@ added: v12.9.0 * {number} -Readonly, This `outgoingMessage.writableLength` contains the number of -bytes (or objects) in the buffer ready to send. +The number of buffered bytes. ### `outgoingMessage.writableObjectMode` @@ -2811,7 +2804,7 @@ added: v12.9.0 * {boolean} -Readonly, always returns `false`. +Always `false`. ### `outgoingMessage.write(chunk[, encoding][, callback])` @@ -2819,7 +2812,7 @@ Readonly, always returns `false`. added: v0.1.29 changes: - version: v0.11.6 - description: add `callback` argument. + description: The `callback` argument was added. --> * `chunk` {string | Buffer} @@ -2827,35 +2820,17 @@ changes: * `callback` {Function} * Returns {boolean} -If this method is called and the 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 a particular message which must not include a body. -e.g. response to `HEAD` request, `204` and `304` response. +Sends a chunk of the body. This method can be called multiple times. -`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. +The `encoding` argument is only relevant when `chunk` is a string. Defaults to +`'utf8'`. -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 the -body of message. - -This method handles the raw body of the 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 `chunk` as described above. - -The second and successive calls to this method will assume the data -will be streamed and send the new data separately. It means that the response -is buffered up to the first chunk of the body. +The `callback` argument is optional and will be called when this chunk of data +is flushed. 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 the user -memory. Event `drain` will be emitted when the buffer is free again. +memory. The `'drain'` event will be emitted when the buffer is free again. ## `http.METHODS` @@ -3542,4 +3517,5 @@ try { [`writable.destroy()`]: stream.md#writabledestroyerror [`writable.destroyed`]: stream.md#writabledestroyed [`writable.uncork()`]: stream.md#writableuncork +[`writable.write()`]: stream.md#writablewritechunk-encoding-callback [initial delay]: net.md#socketsetkeepaliveenable-initialdelay |