@types/node 22.15.21 → 24.10.1

node/http.d.ts

@@ -37,9 +37,10 @@
  *   'Host', 'example.com',
  *   'accepT', '*' ]
  * ```
- * @see [source](https://github.com/nodejs/node/blob/v22.x/lib/http.js)
+ * @see [source](https://github.com/nodejs/node/blob/v24.x/lib/http.js)
  */
 declare module "http" {
+    import { NonSharedBuffer } from "node:buffer";
     import * as stream from "node:stream";
     import { URL } from "node:url";
     import { LookupOptions } from "node:dns";
@@ -200,7 +201,7 @@ declare module "http" {
         "x-frame-options"?: string | undefined;
         "x-xss-protection"?: string | undefined;
     }
-    interface ClientRequestArgs {
+    interface ClientRequestArgs extends Pick<LookupOptions, "hints"> {
         _defaultAgent?: Agent | undefined;
         agent?: Agent | boolean | undefined;
         auth?: string | null | undefined;
@@ -213,7 +214,6 @@ declare module "http" {
         defaultPort?: number | string | undefined;
         family?: number | undefined;
         headers?: OutgoingHttpHeaders | readonly string[] | undefined;
-        hints?: LookupOptions["hints"];
         host?: string | null | undefined;
         hostname?: string | null | undefined;
         insecureHTTPParser?: boolean | undefined;
@@ -234,7 +234,7 @@ declare module "http" {
         socketPath?: string | undefined;
         timeout?: number | undefined;
         uniqueHeaders?: Array<string | string[]> | undefined;
-        joinDuplicateHeaders?: boolean;
+        joinDuplicateHeaders?: boolean | undefined;
     }
     interface ServerOptions<
         Request extends typeof IncomingMessage = typeof IncomingMessage,
@@ -260,7 +260,7 @@ declare module "http" {
          * @default false
          * @since v18.14.0
          */
-        joinDuplicateHeaders?: boolean;
+        joinDuplicateHeaders?: boolean | undefined;
         /**
          * The number of milliseconds of inactivity a server needs to wait for additional incoming data,
          * after it has finished writing the last response, before a socket will be destroyed.
@@ -269,6 +269,13 @@ declare module "http" {
          * @since v18.0.0
          */
         keepAliveTimeout?: number | undefined;
+        /**
+         * An additional buffer time added to the
+         * `server.keepAliveTimeout` to extend the internal socket timeout.
+         * @since 24.6.0
+         * @default 1000
+         */
+        keepAliveTimeoutBuffer?: number | undefined;
         /**
          * Sets the interval value in milliseconds to check for request and headers timeout in incomplete requests.
          * @default 30000
@@ -333,6 +340,17 @@ declare module "http" {
          * If the header's value is an array, the items will be joined using `; `.
          */
         uniqueHeaders?: Array<string | string[]> | undefined;
+        /**
+         * A callback which receives an
+         * incoming request and returns a boolean, to control which upgrade attempts
+         * should be accepted. Accepted upgrades will fire an `'upgrade'` event (or
+         * their sockets will be destroyed, if no listener is registered) while
+         * rejected upgrades will fire a `'request'` event like any non-upgrade
+         * request.
+         * @since v24.9.0
+         * @default () => server.listenerCount('upgrade') > 0
+         */
+        shouldUpgradeCallback?: ((request: InstanceType<Request>) => boolean) | undefined;
         /**
          * If set to `true`, an error is thrown when writing to an HTTP response which does not have a body.
          * @default false
@@ -413,12 +431,18 @@ declare module "http" {
         /**
          * The number of milliseconds of inactivity a server needs to wait for additional
          * incoming data, after it has finished writing the last response, before a socket
-         * will be destroyed. If the server receives new data before the keep-alive
-         * timeout has fired, it will reset the regular inactivity timeout, i.e., `server.timeout`.
+         * will be destroyed.
+         *
+         * This timeout value is combined with the
+         * `server.keepAliveTimeoutBuffer` option to determine the actual socket
+         * timeout, calculated as:
+         * socketTimeout = keepAliveTimeout + keepAliveTimeoutBuffer
+         * If the server receives new data before the keep-alive timeout has fired, it
+         * will reset the regular inactivity timeout, i.e., `server.timeout`.
          *
          * A value of `0` will disable the keep-alive timeout behavior on incoming
          * connections.
-         * A value of `0` makes the http server behave similarly to Node.js versions prior
+         * A value of `0` makes the HTTP server behave similarly to Node.js versions prior
          * to 8.0.0, which did not have a keep-alive timeout.
          *
          * The socket timeout logic is set up on connection, so changing this value only
@@ -426,6 +450,18 @@ declare module "http" {
          * @since v8.0.0
          */
         keepAliveTimeout: number;
+        /**
+         * An additional buffer time added to the
+         * `server.keepAliveTimeout` to extend the internal socket timeout.
+         *
+         * This buffer helps reduce connection reset (`ECONNRESET`) errors by increasing
+         * the socket timeout slightly beyond the advertised keep-alive timeout.
+         *
+         * This option applies only to new incoming connections.
+         * @since v24.6.0
+         * @default 1000
+         */
+        keepAliveTimeoutBuffer: number;
         /**
          * Sets the timeout value in milliseconds for receiving the entire request from
          * the client.
@@ -460,13 +496,13 @@ declare module "http" {
         addListener(event: "clientError", listener: (err: Error, socket: stream.Duplex) => void): this;
         addListener(
             event: "connect",
-            listener: (req: InstanceType<Request>, socket: stream.Duplex, head: Buffer) => void,
+            listener: (req: InstanceType<Request>, socket: stream.Duplex, head: NonSharedBuffer) => void,
         ): this;
         addListener(event: "dropRequest", listener: (req: InstanceType<Request>, socket: stream.Duplex) => void): this;
         addListener(event: "request", listener: RequestListener<Request, Response>): this;
         addListener(
             event: "upgrade",
-            listener: (req: InstanceType<Request>, socket: stream.Duplex, head: Buffer) => void,
+            listener: (req: InstanceType<Request>, socket: stream.Duplex, head: NonSharedBuffer) => void,
         ): this;
         emit(event: string, ...args: any[]): boolean;
         emit(event: "close"): boolean;
@@ -484,14 +520,14 @@ declare module "http" {
             res: InstanceType<Response> & { req: InstanceType<Request> },
         ): boolean;
         emit(event: "clientError", err: Error, socket: stream.Duplex): boolean;
-        emit(event: "connect", req: InstanceType<Request>, socket: stream.Duplex, head: Buffer): boolean;
+        emit(event: "connect", req: InstanceType<Request>, socket: stream.Duplex, head: NonSharedBuffer): boolean;
         emit(event: "dropRequest", req: InstanceType<Request>, socket: stream.Duplex): boolean;
         emit(
             event: "request",
             req: InstanceType<Request>,
             res: InstanceType<Response> & { req: InstanceType<Request> },
         ): boolean;
-        emit(event: "upgrade", req: InstanceType<Request>, socket: stream.Duplex, head: Buffer): boolean;
+        emit(event: "upgrade", req: InstanceType<Request>, socket: stream.Duplex, head: NonSharedBuffer): boolean;
         on(event: string, listener: (...args: any[]) => void): this;
         on(event: "close", listener: () => void): this;
         on(event: "connection", listener: (socket: Socket) => void): this;
@@ -500,10 +536,16 @@ declare module "http" {
         on(event: "checkContinue", listener: RequestListener<Request, Response>): this;
         on(event: "checkExpectation", listener: RequestListener<Request, Response>): this;
         on(event: "clientError", listener: (err: Error, socket: stream.Duplex) => void): this;
-        on(event: "connect", listener: (req: InstanceType<Request>, socket: stream.Duplex, head: Buffer) => void): this;
+        on(
+            event: "connect",
+            listener: (req: InstanceType<Request>, socket: stream.Duplex, head: NonSharedBuffer) => void,
+        ): this;
         on(event: "dropRequest", listener: (req: InstanceType<Request>, socket: stream.Duplex) => void): this;
         on(event: "request", listener: RequestListener<Request, Response>): this;
-        on(event: "upgrade", listener: (req: InstanceType<Request>, socket: stream.Duplex, head: Buffer) => void): this;
+        on(
+            event: "upgrade",
+            listener: (req: InstanceType<Request>, socket: stream.Duplex, head: NonSharedBuffer) => void,
+        ): this;
         once(event: string, listener: (...args: any[]) => void): this;
         once(event: "close", listener: () => void): this;
         once(event: "connection", listener: (socket: Socket) => void): this;
@@ -514,13 +556,13 @@ declare module "http" {
         once(event: "clientError", listener: (err: Error, socket: stream.Duplex) => void): this;
         once(
             event: "connect",
-            listener: (req: InstanceType<Request>, socket: stream.Duplex, head: Buffer) => void,
+            listener: (req: InstanceType<Request>, socket: stream.Duplex, head: NonSharedBuffer) => void,
         ): this;
         once(event: "dropRequest", listener: (req: InstanceType<Request>, socket: stream.Duplex) => void): this;
         once(event: "request", listener: RequestListener<Request, Response>): this;
         once(
             event: "upgrade",
-            listener: (req: InstanceType<Request>, socket: stream.Duplex, head: Buffer) => void,
+            listener: (req: InstanceType<Request>, socket: stream.Duplex, head: NonSharedBuffer) => void,
         ): this;
         prependListener(event: string, listener: (...args: any[]) => void): this;
         prependListener(event: "close", listener: () => void): this;
@@ -532,7 +574,7 @@ declare module "http" {
         prependListener(event: "clientError", listener: (err: Error, socket: stream.Duplex) => void): this;
         prependListener(
             event: "connect",
-            listener: (req: InstanceType<Request>, socket: stream.Duplex, head: Buffer) => void,
+            listener: (req: InstanceType<Request>, socket: stream.Duplex, head: NonSharedBuffer) => void,
         ): this;
         prependListener(
             event: "dropRequest",
@@ -541,7 +583,7 @@ declare module "http" {
         prependListener(event: "request", listener: RequestListener<Request, Response>): this;
         prependListener(
             event: "upgrade",
-            listener: (req: InstanceType<Request>, socket: stream.Duplex, head: Buffer) => void,
+            listener: (req: InstanceType<Request>, socket: stream.Duplex, head: NonSharedBuffer) => void,
         ): this;
         prependOnceListener(event: string, listener: (...args: any[]) => void): this;
         prependOnceListener(event: "close", listener: () => void): this;
@@ -553,7 +595,7 @@ declare module "http" {
         prependOnceListener(event: "clientError", listener: (err: Error, socket: stream.Duplex) => void): this;
         prependOnceListener(
             event: "connect",
-            listener: (req: InstanceType<Request>, socket: stream.Duplex, head: Buffer) => void,
+            listener: (req: InstanceType<Request>, socket: stream.Duplex, head: NonSharedBuffer) => void,
         ): this;
         prependOnceListener(
             event: "dropRequest",
@@ -562,7 +604,7 @@ declare module "http" {
         prependOnceListener(event: "request", listener: RequestListener<Request, Response>): this;
         prependOnceListener(
             event: "upgrade",
-            listener: (req: InstanceType<Request>, socket: stream.Duplex, head: Buffer) => void,
+            listener: (req: InstanceType<Request>, socket: stream.Duplex, head: NonSharedBuffer) => void,
         ): this;
     }
     /**
@@ -911,7 +953,7 @@ declare module "http" {
          * the request body should be sent.
          * @since v10.0.0
          */
-        writeProcessing(): void;
+        writeProcessing(callback?: () => void): void;
     }
     interface InformationEvent {
         statusCode: number;
@@ -1082,7 +1124,7 @@ declare module "http" {
         addListener(event: "abort", listener: () => void): this;
         addListener(
             event: "connect",
-            listener: (response: IncomingMessage, socket: Socket, head: Buffer) => void,
+            listener: (response: IncomingMessage, socket: Socket, head: NonSharedBuffer) => void,
         ): this;
         addListener(event: "continue", listener: () => void): this;
         addListener(event: "information", listener: (info: InformationEvent) => void): this;
@@ -1091,7 +1133,7 @@ declare module "http" {
         addListener(event: "timeout", listener: () => void): this;
         addListener(
             event: "upgrade",
-            listener: (response: IncomingMessage, socket: Socket, head: Buffer) => void,
+            listener: (response: IncomingMessage, socket: Socket, head: NonSharedBuffer) => void,
         ): this;
         addListener(event: "close", listener: () => void): this;
         addListener(event: "drain", listener: () => void): this;
@@ -1104,13 +1146,19 @@ declare module "http" {
          * @deprecated
          */
         on(event: "abort", listener: () => void): this;
-        on(event: "connect", listener: (response: IncomingMessage, socket: Socket, head: Buffer) => void): this;
+        on(
+            event: "connect",
+            listener: (response: IncomingMessage, socket: Socket, head: NonSharedBuffer) => void,
+        ): this;
         on(event: "continue", listener: () => void): this;
         on(event: "information", listener: (info: InformationEvent) => void): this;
         on(event: "response", listener: (response: IncomingMessage) => void): this;
         on(event: "socket", listener: (socket: Socket) => void): this;
         on(event: "timeout", listener: () => void): this;
-        on(event: "upgrade", listener: (response: IncomingMessage, socket: Socket, head: Buffer) => void): this;
+        on(
+            event: "upgrade",
+            listener: (response: IncomingMessage, socket: Socket, head: NonSharedBuffer) => void,
+        ): this;
         on(event: "close", listener: () => void): this;
         on(event: "drain", listener: () => void): this;
         on(event: "error", listener: (err: Error) => void): this;
@@ -1122,13 +1170,19 @@ declare module "http" {
          * @deprecated
          */
         once(event: "abort", listener: () => void): this;
-        once(event: "connect", listener: (response: IncomingMessage, socket: Socket, head: Buffer) => void): this;
+        once(
+            event: "connect",
+            listener: (response: IncomingMessage, socket: Socket, head: NonSharedBuffer) => void,
+        ): this;
         once(event: "continue", listener: () => void): this;
         once(event: "information", listener: (info: InformationEvent) => void): this;
         once(event: "response", listener: (response: IncomingMessage) => void): this;
         once(event: "socket", listener: (socket: Socket) => void): this;
         once(event: "timeout", listener: () => void): this;
-        once(event: "upgrade", listener: (response: IncomingMessage, socket: Socket, head: Buffer) => void): this;
+        once(
+            event: "upgrade",
+            listener: (response: IncomingMessage, socket: Socket, head: NonSharedBuffer) => void,
+        ): this;
         once(event: "close", listener: () => void): this;
         once(event: "drain", listener: () => void): this;
         once(event: "error", listener: (err: Error) => void): this;
@@ -1142,7 +1196,7 @@ declare module "http" {
         prependListener(event: "abort", listener: () => void): this;
         prependListener(
             event: "connect",
-            listener: (response: IncomingMessage, socket: Socket, head: Buffer) => void,
+            listener: (response: IncomingMessage, socket: Socket, head: NonSharedBuffer) => void,
         ): this;
         prependListener(event: "continue", listener: () => void): this;
         prependListener(event: "information", listener: (info: InformationEvent) => void): this;
@@ -1151,7 +1205,7 @@ declare module "http" {
         prependListener(event: "timeout", listener: () => void): this;
         prependListener(
             event: "upgrade",
-            listener: (response: IncomingMessage, socket: Socket, head: Buffer) => void,
+            listener: (response: IncomingMessage, socket: Socket, head: NonSharedBuffer) => void,
         ): this;
         prependListener(event: "close", listener: () => void): this;
         prependListener(event: "drain", listener: () => void): this;
@@ -1166,7 +1220,7 @@ declare module "http" {
         prependOnceListener(event: "abort", listener: () => void): this;
         prependOnceListener(
             event: "connect",
-            listener: (response: IncomingMessage, socket: Socket, head: Buffer) => void,
+            listener: (response: IncomingMessage, socket: Socket, head: NonSharedBuffer) => void,
         ): this;
         prependOnceListener(event: "continue", listener: () => void): this;
         prependOnceListener(event: "information", listener: (info: InformationEvent) => void): this;
@@ -1175,7 +1229,7 @@ declare module "http" {
         prependOnceListener(event: "timeout", listener: () => void): this;
         prependOnceListener(
             event: "upgrade",
-            listener: (response: IncomingMessage, socket: Socket, head: Buffer) => void,
+            listener: (response: IncomingMessage, socket: Socket, head: NonSharedBuffer) => void,
         ): this;
         prependOnceListener(event: "close", listener: () => void): this;
         prependOnceListener(event: "drain", listener: () => void): this;
@@ -1419,7 +1473,15 @@ declare module "http" {
          */
         destroy(error?: Error): this;
     }
-    interface AgentOptions extends Partial<TcpSocketConnectOpts> {
+    interface ProxyEnv extends NodeJS.ProcessEnv {
+        HTTP_PROXY?: string | undefined;
+        HTTPS_PROXY?: string | undefined;
+        NO_PROXY?: string | undefined;
+        http_proxy?: string | undefined;
+        https_proxy?: string | undefined;
+        no_proxy?: string | undefined;
+    }
+    interface AgentOptions extends NodeJS.PartialOptions<TcpSocketConnectOpts> {
         /**
          * Keep sockets around in a pool to be used by other requests in the future. Default = false
          */
@@ -1429,6 +1491,16 @@ declare module "http" {
          * Only relevant if keepAlive is set to true.
          */
         keepAliveMsecs?: number | undefined;
+        /**
+         * Milliseconds to subtract from
+         * the server-provided `keep-alive: timeout=...` hint when determining socket
+         * expiration time. This buffer helps ensure the agent closes the socket
+         * slightly before the server does, reducing the chance of sending a request
+         * on a socket that’s about to be closed by the server.
+         * @since v24.7.0
+         * @default 1000
+         */
+        agentKeepAliveTimeoutBuffer?: number | undefined;
         /**
          * Maximum number of sockets to allow per host. Default for Node 0.10 is 5, default for Node 0.12 is Infinity
          */
@@ -1450,6 +1522,22 @@ declare module "http" {
          * @default `lifo`
          */
         scheduling?: "fifo" | "lifo" | undefined;
+        /**
+         * Environment variables for proxy configuration. See
+         * [Built-in Proxy Support](https://nodejs.org/docs/latest-v24.x/api/http.html#built-in-proxy-support) for details.
+         * @since v24.5.0
+         */
+        proxyEnv?: ProxyEnv | undefined;
+        /**
+         * Default port to use when the port is not specified in requests.
+         * @since v24.5.0
+         */
+        defaultPort?: number | undefined;
+        /**
+         * The protocol to use for the agent.
+         * @since v24.5.0
+         */
+        protocol?: string | undefined;
     }
     /**
      * An `Agent` is responsible for managing connection persistence
@@ -1505,7 +1593,7 @@ declare module "http" {
      * });
      * ```
      *
-     * `options` in [`socket.connect()`](https://nodejs.org/docs/latest-v22.x/api/net.html#socketconnectoptions-connectlistener) are also supported.
+     * `options` in [`socket.connect()`](https://nodejs.org/docs/latest-v24.x/api/net.html#socketconnectoptions-connectlistener) are also supported.
      *
      * To configure any of them, a custom {@link Agent} instance must be created.
      *
@@ -1570,6 +1658,68 @@ declare module "http" {
          * @since v0.11.4
          */
         destroy(): void;
+        /**
+         * Produces a socket/stream to be used for HTTP requests.
+         *
+         * By default, this function is the same as `net.createConnection()`. However,
+         * custom agents may override this method in case greater flexibility is desired.
+         *
+         * A socket/stream can be supplied in one of two ways: by returning the
+         * socket/stream from this function, or by passing the socket/stream to `callback`.
+         *
+         * This method is guaranteed to return an instance of the `net.Socket` class,
+         * a subclass of `stream.Duplex`, unless the user specifies a socket
+         * type other than `net.Socket`.
+         *
+         * `callback` has a signature of `(err, stream)`.
+         * @since v0.11.4
+         * @param options Options containing connection details. Check `createConnection` for the format of the options
+         * @param callback Callback function that receives the created socket
+         */
+        createConnection(
+            options: ClientRequestArgs,
+            callback?: (err: Error | null, stream: stream.Duplex) => void,
+        ): stream.Duplex | null | undefined;
+        /**
+         * Called when `socket` is detached from a request and could be persisted by the`Agent`. Default behavior is to:
+         *
+         * ```js
+         * socket.setKeepAlive(true, this.keepAliveMsecs);
+         * socket.unref();
+         * return true;
+         * ```
+         *
+         * This method can be overridden by a particular `Agent` subclass. If this
+         * method returns a falsy value, the socket will be destroyed instead of persisting
+         * it for use with the next request.
+         *
+         * The `socket` argument can be an instance of `net.Socket`, a subclass of `stream.Duplex`.
+         * @since v8.1.0
+         */
+        keepSocketAlive(socket: stream.Duplex): void;
+        /**
+         * Called when `socket` is attached to `request` after being persisted because of
+         * the keep-alive options. Default behavior is to:
+         *
+         * ```js
+         * socket.ref();
+         * ```
+         *
+         * This method can be overridden by a particular `Agent` subclass.
+         *
+         * The `socket` argument can be an instance of `net.Socket`, a subclass of `stream.Duplex`.
+         * @since v8.1.0
+         */
+        reuseSocket(socket: stream.Duplex, request: ClientRequest): void;
+        /**
+         * Get a unique name for a set of request options, to determine whether a
+         * connection can be reused. For an HTTP agent, this returns`host:port:localAddress` or `host:port:localAddress:family`. For an HTTPS agent,
+         * the name includes the CA, cert, ciphers, and other HTTPS/TLS-specific options
+         * that determine socket reusability.
+         * @since v0.11.4
+         * @param options A set of options providing information for name generation
+         */
+        getName(options?: ClientRequestArgs): string;
     }
     const METHODS: string[];
     const STATUS_CODES: {
@@ -1966,18 +2116,18 @@ declare module "http" {
      */
     const maxHeaderSize: number;
     /**
-     * A browser-compatible implementation of [WebSocket](https://nodejs.org/docs/latest/api/http.html#websocket).
+     * A browser-compatible implementation of `WebSocket`.
      * @since v22.5.0
      */
-    const WebSocket: import("undici-types").WebSocket;
+    const WebSocket: typeof import("undici-types").WebSocket;
     /**
      * @since v22.5.0
      */
-    const CloseEvent: import("undici-types").CloseEvent;
+    const CloseEvent: typeof import("undici-types").CloseEvent;
     /**
      * @since v22.5.0
      */
-    const MessageEvent: import("undici-types").MessageEvent;
+    const MessageEvent: typeof import("undici-types").MessageEvent;
 }
 declare module "node:http" {
     export * from "http";