method

http.Agent.createConnection

options: ClientRequestArgs,
callback?: (err: null | Error, stream: Duplex) => void
): undefined | null | Duplex;

Produces a socket/stream to be used for HTTP requests.

By default, this function behaves identically to net.createConnection(), synchronously returning the created socket. The optional callback parameter in the signature is not used by this default implementation.

However, custom agents may override this method to provide greater flexibility, for example, to create sockets asynchronously. When overriding createConnection:

  1. Synchronous socket creation: The overriding method can return the socket/stream directly.
  2. Asynchronous socket creation: The overriding method can accept the callback and pass the created socket/stream to it (e.g., callback(null, newSocket)). If an error occurs during socket creation, it should be passed as the first argument to the callback (e.g., callback(err)).

The agent will call the provided createConnection function with options and this internal callback. The callback provided by the agent has a signature of (err, stream).

@param options

Options containing connection details. Check net.createConnection for the format of the options. For custom agents, this object is passed to the custom createConnection function.

@param callback

(Optional, primarily for custom agents) A function to be called by a custom createConnection implementation when the socket is created, especially for asynchronous operations.

@returns

The created socket. This is returned by the default implementation or by a custom synchronous createConnection implementation. If a custom createConnection uses the callback for asynchronous operation, this return value might not be the primary way to obtain the socket.

Referenced types

interface ClientRequestArgs