http.OutgoingMessage

class http.OutgoingMessage extends Stream

This class serves as the parent class of http.ClientRequest and http.ServerResponse. It is an abstract outgoing message from the perspective of the participants of an HTTP transaction.

Emitted when the buffer of the message is free again.

Emitted when the transmission is finished successfully.

Emitted after outgoingMessage.end() is called. When the event is emitted, all data has been processed but not necessarily completely flushed.

outgoingMessage.addTrailers(headers): void

Adds HTTP trailers (headers but at the end of the message) to the message.

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 field names in its value, e.g.

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.appendHeader(name, value): this

Append a single header value to the header object.

If the value is an array, this is equivalent to calling this method multiple times.

If there were no previous values for the header, this is equivalent to calling outgoingMessage.setHeader(name, value).

Depending of the value of options.uniqueHeaders when the client request or the server were created, this will end up in the header being sent multiple times or a single time with values joined using ; .

Alias of outgoingMessage.socket.

outgoingMessage.cork(): void

See writable.cork().

outgoingMessage.destroy(error?): 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?): 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 trailers (if any).

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 a listener of the 'finish' event).

outgoingMessage.flushHeaders(): void

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 message.

outgoingMessage.getHeader(name): number | string | string[] | 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(): string[]

Returns an array containing the unique names of the current outgoing headers. All names are lowercase.

outgoingMessage.getHeaders(): 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.

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): boolean

Returns true if the header identified by name is currently set in the outgoing headers. The header name is case-insensitive.

const hasContentType = outgoingMessage.hasHeader('content-type');

Read-only. true if the headers were sent, otherwise false.

outgoingMessage.pipe(): void

Overrides the stream.pipe() method inherited from the legacy Stream class which is the parent class of http.OutgoingMessage.

Calling this method will throw an Error because outgoingMessage is a write-only stream.

outgoingMessage.removeHeader(name): void

Removes a header that is queued for implicit sending.

outgoingMessage.removeHeader('Content-Encoding');

outgoingMessage.setHeader(name, value): this

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.setHeaders(headers): this

Sets multiple header values for implicit headers. headers must be an instance of Headers or Map, if a header already exists in the to-be-sent headers, its value will be replaced.

const headers = new Headers({ foo: 'bar' });
outgoingMessage.setHeaders(headers);

or

const headers = new Map([['foo', 'bar']]);
outgoingMessage.setHeaders(headers);

When headers have been set with outgoingMessage.setHeaders(), they will be merged with any headers passed to response.writeHead(), with the headers passed to response.writeHead() given precedence.

// Returns content-type = text/plain
const server = http.createServer((req, res) => {
  const headers = new Headers({ 'Content-Type': 'text/html' });
  res.setHeaders(headers);
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('ok');
});

outgoingMessage.setTimeout(msecs, callback?): this

Once a socket is associated with the message and is connected, socket.setTimeout() will be called with msecs as the first parameter.

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(): void

See writable.uncork()

The number of times outgoingMessage.cork() has been called.

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.

Is true if all data has been flushed to the underlying system.

The highWaterMark of the underlying socket if assigned. Otherwise, the default buffer level when writable.write() starts returning false (16384).

The number of buffered bytes.

Always false.

outgoingMessage.write(chunk, encoding?, callback?): boolean

Sends a chunk of the body. This method can be called multiple times.

The encoding argument is only relevant when chunk is a string. Defaults to 'utf8'.

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. The 'drain' event will be emitted when the buffer is free again.