Skip to main content

ClientRequest

class ClientRequest

Deno compatibility

Constructor option createConnection is not supported.

This object is created internally and returned from request. It represents an in-progress request whose header has already been queued. The header is still mutable using the setHeader(name, value), getHeader(name), removeHeader(name) API. The actual header will be sent along with the first data chunk or when calling request.end().

To get the response, add a listener for 'response' to the request object. 'response' will be emitted from the request object when the response headers have been received. The 'response' event is executed with one argument which is an instance of IncomingMessage.

During the 'response' event, one can add listeners to the response object; particularly to listen for the 'data' event.

If no 'response' handler is added, then the response will be entirely discarded. However, if a 'response' event handler is added, then the data from the response object must be consumed, either by calling response.read() whenever there is a 'readable' event, or by adding a 'data' handler, or by calling the .resume() method. Until the data is consumed, the 'end' event will not fire. Also, until the data is read it will consume memory that can eventually lead to a 'process out of memory' error.

For backward compatibility, res will only emit 'error' if there is an 'error' listener registered.

Set Content-Length header to limit the response body size. If response.strictContentLength is set to true, mismatching the Content-Length header value will result in an Error being thrown, identified by code:``'ERR_HTTP_CONTENT_LENGTH_MISMATCH'.

Content-Length value should be in bytes, not characters. Use Buffer.byteLength() to determine the length of the body in bytes.

Constructors Jump to heading

new
Jump to headingClientRequest(
url:
string
| URL
| ClientRequestArgs
,
cb?: (res: IncomingMessage) => void,
)

Properties Jump to heading

deprecated
Jump to headingaborted: boolean

The request.aborted property will be true if the request has been aborted.

The request host.

Limits maximum response headers count. If set to 0, no limit will be applied.

The request method.

The request path.

The request protocol.

When sending request through a keep-alive enabled agent, the underlying socket might be reused. But if server closes connection at unfortunate time, client may run into a 'ECONNRESET' error.

import http from 'node:http';

// Server has a 5 seconds keep-alive timeout by default
http
  .createServer((req, res) => {
    res.write('hello\n');
    res.end();
  })
  .listen(3000);

setInterval(() => {
  // Adapting a keep-alive agent
  http.get('http://localhost:3000', { agent }, (res) => {
    res.on('data', (data) => {
      // Do nothing
    });
  });
}, 5000); // Sending request on 5s interval so it's easy to hit idle timeout

By marking a request whether it reused socket or not, we can do automatic error retry base on it.

import http from 'node:http';
const agent = new http.Agent({ keepAlive: true });

function retriableRequest() {
  const req = http
    .get('http://localhost:3000', { agent }, (res) => {
      // ...
    })
    .on('error', (err) => {
      // Check if retry is needed
      if (req.reusedSocket && err.code === 'ECONNRESET') {
        retriableRequest();
      }
    });
}

retriableRequest();
deprecated
Jump to headingabort(): void

Marks the request as aborting. Calling this will cause remaining data in the response to be dropped and the socket to be destroyed.

deprecated
Jump to headingaddListener(
event: "abort",
listener: () => void,
): this
Jump to headingaddListener(
event: "connect",
listener: (
response: IncomingMessage,
socket: Socket,
head: Buffer,
) => void,
): this
Jump to headingaddListener(
event: "continue",
listener: () => void,
): this
Jump to headingaddListener(
event: "information",
listener: (info: InformationEvent) => void,
): this
Jump to headingaddListener(
event: "response",
listener: (response: IncomingMessage) => void,
): this
Jump to headingaddListener(
event: "socket",
listener: (socket: Socket) => void,
): this
Jump to headingaddListener(
event: "timeout",
listener: () => void,
): this
Jump to headingaddListener(
event: "upgrade",
listener: (
response: IncomingMessage,
socket: Socket,
head: Buffer,
) => void,
): this
Jump to headingaddListener(
event: "close",
listener: () => void,
): this
Jump to headingaddListener(
event: "drain",
listener: () => void,
): this
Jump to headingaddListener(
event: "error",
listener: (err: Error) => void,
): this
Jump to headingaddListener(
event: "finish",
listener: () => void,
): this
Jump to headingaddListener(
event: "pipe",
listener: (src: stream.Readable) => void,
): this
Jump to headingaddListener(
event: "unpipe",
listener: (src: stream.Readable) => void,
): this
Jump to headingaddListener(
event: string | symbol,
listener: (...args: any[]) => void,
): this

Returns an array containing the unique names of the current outgoing raw headers. Header names are returned with their exact casing being set.

request.setHeader('Foo', 'bar');
request.setHeader('Set-Cookie', ['foo=bar', 'bar=baz']);

const headerNames = request.getRawHeaderNames();
// headerNames === ['Foo', 'Set-Cookie']
deprecated
Jump to headingon(
event: "abort",
listener: () => void,
): this
Jump to headingon(
event: "connect",
listener: (
response: IncomingMessage,
socket: Socket,
head: Buffer,
) => void,
): this
Jump to headingon(
event: "continue",
listener: () => void,
): this
Jump to headingon(
event: "information",
listener: (info: InformationEvent) => void,
): this
Jump to headingon(
event: "response",
listener: (response: IncomingMessage) => void,
): this
Jump to headingon(
event: "socket",
listener: (socket: Socket) => void,
): this
Jump to headingon(
event: "timeout",
listener: () => void,
): this
Jump to headingon(
event: "upgrade",
listener: (
response: IncomingMessage,
socket: Socket,
head: Buffer,
) => void,
): this
Jump to headingon(
event: "close",
listener: () => void,
): this
Jump to headingon(
event: "drain",
listener: () => void,
): this
Jump to headingon(
event: "error",
listener: (err: Error) => void,
): this
Jump to headingon(
event: "finish",
listener: () => void,
): this
Jump to headingon(
event: "pipe",
listener: (src: stream.Readable) => void,
): this
Jump to headingon(
event: "unpipe",
listener: (src: stream.Readable) => void,
): this
Jump to headingon(
event: string | symbol,
listener: (...args: any[]) => void,
): this
deprecated
Jump to headingonce(
event: "abort",
listener: () => void,
): this
Jump to headingonce(
event: "connect",
listener: (
response: IncomingMessage,
socket: Socket,
head: Buffer,
) => void,
): this
Jump to headingonce(
event: "continue",
listener: () => void,
): this
Jump to headingonce(
event: "information",
listener: (info: InformationEvent) => void,
): this
Jump to headingonce(
event: "response",
listener: (response: IncomingMessage) => void,
): this
Jump to headingonce(
event: "socket",
listener: (socket: Socket) => void,
): this
Jump to headingonce(
event: "timeout",
listener: () => void,
): this
Jump to headingonce(
event: "upgrade",
listener: (
response: IncomingMessage,
socket: Socket,
head: Buffer,
) => void,
): this
Jump to headingonce(
event: "close",
listener: () => void,
): this
Jump to headingonce(
event: "drain",
listener: () => void,
): this
Jump to headingonce(
event: "error",
listener: (err: Error) => void,
): this
Jump to headingonce(
event: "finish",
listener: () => void,
): this
Jump to headingonce(
event: "pipe",
listener: (src: stream.Readable) => void,
): this
Jump to headingonce(
event: "unpipe",
listener: (src: stream.Readable) => void,
): this
Jump to headingonce(
event: string | symbol,
listener: (...args: any[]) => void,
): this
deprecated
Jump to headingprependListener(
event: "abort",
listener: () => void,
): this
Jump to headingprependListener(
event: "connect",
listener: (
response: IncomingMessage,
socket: Socket,
head: Buffer,
) => void,
): this
Jump to headingprependListener(
event: "continue",
listener: () => void,
): this
Jump to headingprependListener(
event: "information",
listener: (info: InformationEvent) => void,
): this
Jump to headingprependListener(
event: "response",
listener: (response: IncomingMessage) => void,
): this
Jump to headingprependListener(
event: "socket",
listener: (socket: Socket) => void,
): this
Jump to headingprependListener(
event: "timeout",
listener: () => void,
): this
Jump to headingprependListener(
event: "upgrade",
listener: (
response: IncomingMessage,
socket: Socket,
head: Buffer,
) => void,
): this
Jump to headingprependListener(
event: "close",
listener: () => void,
): this
Jump to headingprependListener(
event: "drain",
listener: () => void,
): this
Jump to headingprependListener(
event: "error",
listener: (err: Error) => void,
): this
Jump to headingprependListener(
event: "finish",
listener: () => void,
): this
Jump to headingprependListener(
event: "pipe",
listener: (src: stream.Readable) => void,
): this
Jump to headingprependListener(
event: "unpipe",
listener: (src: stream.Readable) => void,
): this
Jump to headingprependListener(
event: string | symbol,
listener: (...args: any[]) => void,
): this
deprecated
Jump to headingprependOnceListener(
event: "abort",
listener: () => void,
): this
Jump to headingprependOnceListener(
event: "connect",
listener: (
response: IncomingMessage,
socket: Socket,
head: Buffer,
) => void,
): this
Jump to headingprependOnceListener(
event: "continue",
listener: () => void,
): this
Jump to headingprependOnceListener(
event: "information",
listener: (info: InformationEvent) => void,
): this
Jump to headingprependOnceListener(
event: "response",
listener: (response: IncomingMessage) => void,
): this
Jump to headingprependOnceListener(
event: "socket",
listener: (socket: Socket) => void,
): this
Jump to headingprependOnceListener(
event: "timeout",
listener: () => void,
): this
Jump to headingprependOnceListener(
event: "upgrade",
listener: (
response: IncomingMessage,
socket: Socket,
head: Buffer,
) => void,
): this
Jump to headingprependOnceListener(
event: "close",
listener: () => void,
): this
Jump to headingprependOnceListener(
event: "drain",
listener: () => void,
): this
Jump to headingprependOnceListener(
event: "error",
listener: (err: Error) => void,
): this
Jump to headingprependOnceListener(
event: "finish",
listener: () => void,
): this
Jump to headingprependOnceListener(
event: "pipe",
listener: (src: stream.Readable) => void,
): this
Jump to headingprependOnceListener(
event: "unpipe",
listener: (src: stream.Readable) => void,
): this
Jump to headingprependOnceListener(
event: string | symbol,
listener: (...args: any[]) => void,
): this
Jump to headingsetNoDelay(noDelay?: boolean): void

Once a socket is assigned to this request and is connected socket.setNoDelay() will be called.

Jump to headingsetSocketKeepAlive(
enable?: boolean,
initialDelay?: number,
): void

Once a socket is assigned to this request and is connected socket.setKeepAlive() will be called.

Jump to headingsetTimeout(
timeout: number,
callback?: () => void,
): this

Once a socket is assigned to this request and is connected socket.setTimeout() will be called.

Back to top