urllib 3.20.0 → 3.22.0

package/dist/commonjs/HttpAgent.js

@@ -68,7 +68,7 @@ class HttpAgent extends undici_1.Agent {
             }
             const family = (0, node_net_1.isIP)(hostname);
             if (family === 4 || family === 6) {
-                // if request hostname is ip, custom lookup won't excute
+                // if request hostname is ip, custom lookup won't execute
                 if (!this.#checkAddress(hostname, family)) {
                     throw new IllegalAddressError(hostname, hostname, family);
                 }

package/dist/commonjs/HttpClient.d.ts

@@ -42,6 +42,11 @@ export type ClientOptions = {
     };
 };
 export declare const HEADER_USER_AGENT: string;
+export type RequestContext = {
+    retries: number;
+    socketErrorRetries: number;
+    requestStartTime?: number;
+};
 export type RequestDiagnosticsMessage = {
     request: RequestMeta;
 };
@@ -50,11 +55,26 @@ export type ResponseDiagnosticsMessage = {
     response: RawResponseWithMeta;
     error?: Error;
 };
+export interface PoolStat {
+    /** Number of open socket connections in this pool. */
+    connected: number;
+    /** Number of open socket connections in this pool that do not have an active request. */
+    free: number;
+    /** Number of pending requests across all clients in this pool. */
+    pending: number;
+    /** Number of queued requests across all clients in this pool. */
+    queued: number;
+    /** Number of currently active requests across all clients in this pool. */
+    running: number;
+    /** Number of active, pending, or queued requests across all clients in this pool. */
+    size: number;
+}
 export declare class HttpClient extends EventEmitter {
     #private;
     constructor(clientOptions?: ClientOptions);
     getDispatcher(): Dispatcher;
     setDispatcher(dispatcher: Dispatcher): void;
+    getDispatcherPoolStats(): Record<string, PoolStat>;
     request<T = any>(url: RequestURL, options?: RequestOptions): Promise<HttpClientResponse<T>>;
     curl<T = any>(url: RequestURL, options?: RequestOptions): Promise<HttpClientResponse<T>>;
 }

package/dist/commonjs/HttpClient.js

@@ -17,6 +17,7 @@ const node_fs_1 = require("node:fs");
 const node_url_1 = require("node:url");
 const node_perf_hooks_1 = require("node:perf_hooks");
 const undici_1 = require("undici");
+const symbols_js_1 = __importDefault(require("undici/lib/core/symbols.js"));
 const formdata_node_1 = require("formdata-node");
 const form_data_encoder_1 = require("form-data-encoder");
 const default_user_agent_1 = __importDefault(require("default-user-agent"));
@@ -27,8 +28,9 @@ const pump_1 = __importDefault(require("pump"));
 const formstream_1 = __importDefault(require("formstream"));
 const HttpAgent_js_1 = require("./HttpAgent.js");
 const utils_js_1 = require("./utils.js");
-const symbols_js_1 = __importDefault(require("./symbols.js"));
+const symbols_js_2 = __importDefault(require("./symbols.js"));
 const diagnosticsChannel_js_1 = require("./diagnosticsChannel.js");
+const HttpClientError_js_1 = require("./HttpClientError.js");
 const PROTO_RE = /^https?:\/\//i;
 const FormData = undici_1.FormData ?? formdata_node_1.FormData;
 // impl promise pipeline on Node.js 14
@@ -65,15 +67,7 @@ class BlobFromStream {
         return 'Blob';
     }
 }
-class HttpClientRequestTimeoutError extends Error {
-    constructor(timeout, options) {
-        const message = `Request timeout for ${timeout} ms`;
-        super(message, options);
-        this.name = this.constructor.name;
-        Error.captureStackTrace(this, this.constructor);
-    }
-}
-exports.HEADER_USER_AGENT = (0, default_user_agent_1.default)('node-urllib', '3.20.0');
+exports.HEADER_USER_AGENT = (0, default_user_agent_1.default)('node-urllib', '3.22.0');
 function getFileName(stream) {
     const filePath = stream.path;
     if (filePath) {
@@ -114,10 +108,31 @@ class HttpClient extends node_events_1.EventEmitter {
     setDispatcher(dispatcher) {
         this.#dispatcher = dispatcher;
     }
+    getDispatcherPoolStats() {
+        const agent = this.getDispatcher();
+        // origin => Pool Instance
+        const clients = agent[symbols_js_1.default.kClients];
+        const poolStatsMap = {};
+        for (const [key, ref] of clients) {
+            const pool = ref.deref();
+            const stats = pool?.stats;
+            if (!stats)
+                continue;
+            poolStatsMap[key] = {
+                connected: stats.connected,
+                free: stats.free,
+                pending: stats.pending,
+                queued: stats.queued,
+                running: stats.running,
+                size: stats.size,
+            };
+        }
+        return poolStatsMap;
+    }
     async request(url, options) {
         return await this.#requestInternal(url, options);
     }
-    // alias to request, keep compatible with urlib@2 HttpClient.curl
+    // alias to request, keep compatible with urllib@2 HttpClient.curl
     async curl(url, options) {
         return await this.request(url, options);
     }
@@ -183,11 +198,11 @@ class HttpClient extends node_events_1.EventEmitter {
         const originalOpaque = args.opaque;
         // using opaque to diagnostics channel, binding request and socket
         const internalOpaque = {
-            [symbols_js_1.default.kRequestId]: requestId,
-            [symbols_js_1.default.kRequestStartTime]: requestStartTime,
-            [symbols_js_1.default.kEnableRequestTiming]: !!args.timing,
-            [symbols_js_1.default.kRequestTiming]: timing,
-            [symbols_js_1.default.kRequestOriginalOpaque]: originalOpaque,
+            [symbols_js_2.default.kRequestId]: requestId,
+            [symbols_js_2.default.kRequestStartTime]: requestStartTime,
+            [symbols_js_2.default.kEnableRequestTiming]: !!args.timing,
+            [symbols_js_2.default.kRequestTiming]: timing,
+            [symbols_js_2.default.kRequestOriginalOpaque]: originalOpaque,
         };
         const reqMeta = {
             requestId,
@@ -580,14 +595,17 @@ class HttpClient extends node_events_1.EventEmitter {
             }
             return clientResponse;
         }
-        catch (e) {
-            debug('Request#%d throw error: %s', requestId, e);
-            let err = e;
+        catch (rawError) {
+            debug('Request#%d throw error: %s', requestId, rawError);
+            let err = rawError;
             if (err.name === 'HeadersTimeoutError') {
-                err = new HttpClientRequestTimeoutError(headersTimeout, { cause: e });
+                err = new HttpClientError_js_1.HttpClientRequestTimeoutError(headersTimeout, { cause: err });
             }
             else if (err.name === 'BodyTimeoutError') {
-                err = new HttpClientRequestTimeoutError(bodyTimeout, { cause: e });
+                err = new HttpClientError_js_1.HttpClientRequestTimeoutError(bodyTimeout, { cause: err });
+            }
+            else if (err.code === 'UND_ERR_CONNECT_TIMEOUT') {
+                err = new HttpClientError_js_1.HttpClientConnectTimeoutError(err.message, err.code, { cause: err });
             }
             else if (err.code === 'UND_ERR_SOCKET' || err.code === 'ECONNRESET') {
                 // auto retry on socket error, https://github.com/node-modules/urllib/issues/454
@@ -610,7 +628,7 @@ class HttpClient extends node_events_1.EventEmitter {
                 res.requestUrls.push(requestUrl.href);
             }
             res.rt = (0, utils_js_1.performanceTime)(requestStartTime);
-            this.#updateSocketInfo(socketInfo, internalOpaque);
+            this.#updateSocketInfo(socketInfo, internalOpaque, rawError);
             channels.response.publish({
                 request: reqMeta,
                 response: res,
@@ -631,22 +649,39 @@ class HttpClient extends node_events_1.EventEmitter {
             throw err;
         }
     }
-    #updateSocketInfo(socketInfo, internalOpaque) {
-        const socket = internalOpaque[symbols_js_1.default.kRequestSocket];
+    #updateSocketInfo(socketInfo, internalOpaque, err) {
+        const socket = internalOpaque[symbols_js_2.default.kRequestSocket] ?? err?.[symbols_js_2.default.kErrorSocket];
         if (socket) {
-            socketInfo.id = socket[symbols_js_1.default.kSocketId];
-            socketInfo.handledRequests = socket[symbols_js_1.default.kHandledRequests];
-            socketInfo.handledResponses = socket[symbols_js_1.default.kHandledResponses];
-            socketInfo.localAddress = socket[symbols_js_1.default.kSocketLocalAddress];
-            socketInfo.localPort = socket[symbols_js_1.default.kSocketLocalPort];
-            socketInfo.remoteAddress = socket.remoteAddress;
-            socketInfo.remotePort = socket.remotePort;
-            socketInfo.remoteFamily = socket.remoteFamily;
+            socketInfo.id = socket[symbols_js_2.default.kSocketId];
+            socketInfo.handledRequests = socket[symbols_js_2.default.kHandledRequests];
+            socketInfo.handledResponses = socket[symbols_js_2.default.kHandledResponses];
+            if (socket[symbols_js_2.default.kSocketLocalAddress]) {
+                socketInfo.localAddress = socket[symbols_js_2.default.kSocketLocalAddress];
+                socketInfo.localPort = socket[symbols_js_2.default.kSocketLocalPort];
+            }
+            if (socket.remoteAddress) {
+                socketInfo.remoteAddress = socket.remoteAddress;
+                socketInfo.remotePort = socket.remotePort;
+                socketInfo.remoteFamily = socket.remoteFamily;
+            }
             socketInfo.bytesRead = socket.bytesRead;
             socketInfo.bytesWritten = socket.bytesWritten;
-            socketInfo.connectedTime = socket[symbols_js_1.default.kSocketConnectedTime];
-            socketInfo.lastRequestEndTime = socket[symbols_js_1.default.kSocketRequestEndTime];
-            socket[symbols_js_1.default.kSocketRequestEndTime] = new Date();
+            if (socket[symbols_js_2.default.kSocketConnectErrorTime]) {
+                socketInfo.connectErrorTime = socket[symbols_js_2.default.kSocketConnectErrorTime];
+                if (Array.isArray(socket.autoSelectFamilyAttemptedAddresses)) {
+                    socketInfo.attemptedRemoteAddresses = socket.autoSelectFamilyAttemptedAddresses;
+                }
+                socketInfo.connectProtocol = socket[symbols_js_2.default.kSocketConnectProtocol];
+                socketInfo.connectHost = socket[symbols_js_2.default.kSocketConnectHost];
+                socketInfo.connectPort = socket[symbols_js_2.default.kSocketConnectPort];
+            }
+            if (socket[symbols_js_2.default.kSocketConnectedTime]) {
+                socketInfo.connectedTime = socket[symbols_js_2.default.kSocketConnectedTime];
+            }
+            if (socket[symbols_js_2.default.kSocketRequestEndTime]) {
+                socketInfo.lastRequestEndTime = socket[symbols_js_2.default.kSocketRequestEndTime];
+            }
+            socket[symbols_js_2.default.kSocketRequestEndTime] = new Date();
         }
     }
 }

package/dist/commonjs/HttpClientError.d.ts

@@ -0,0 +1,19 @@
+import type { RawResponseWithMeta, SocketInfo } from './Response.js';
+import type { IncomingHttpHeaders } from './IncomingHttpHeaders.js';
+interface ErrorOptions {
+    cause?: Error;
+}
+export declare class HttpClientRequestError extends Error {
+    status?: number;
+    headers?: IncomingHttpHeaders;
+    socket?: SocketInfo;
+    res?: RawResponseWithMeta;
+}
+export declare class HttpClientRequestTimeoutError extends HttpClientRequestError {
+    constructor(timeout: number, options: ErrorOptions);
+}
+export declare class HttpClientConnectTimeoutError extends HttpClientRequestError {
+    code: string;
+    constructor(message: string, code: string, options: ErrorOptions);
+}
+export {};

package/dist/commonjs/HttpClientError.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpClientConnectTimeoutError = exports.HttpClientRequestTimeoutError = exports.HttpClientRequestError = void 0;
+class HttpClientRequestError extends Error {
+    status;
+    headers;
+    socket;
+    res;
+}
+exports.HttpClientRequestError = HttpClientRequestError;
+class HttpClientRequestTimeoutError extends HttpClientRequestError {
+    constructor(timeout, options) {
+        const message = `Request timeout for ${timeout} ms`;
+        super(message, options);
+        this.name = this.constructor.name;
+        Error.captureStackTrace(this, this.constructor);
+    }
+}
+exports.HttpClientRequestTimeoutError = HttpClientRequestTimeoutError;
+class HttpClientConnectTimeoutError extends HttpClientRequestError {
+    code;
+    constructor(message, code, options) {
+        super(message, options);
+        this.name = this.constructor.name;
+        this.code = code;
+        Error.captureStackTrace(this, this.constructor);
+    }
+}
+exports.HttpClientConnectTimeoutError = HttpClientConnectTimeoutError;

package/dist/commonjs/Response.d.ts

@@ -13,7 +13,12 @@ export type SocketInfo = {
     handledRequests: number;
     handledResponses: number;
     connectedTime?: Date;
+    connectErrorTime?: Date;
     lastRequestEndTime?: Date;
+    attemptedRemoteAddresses?: string[];
+    connectProtocol?: string;
+    connectHost?: string;
+    connectPort?: string;
 };
 /**
  * https://eggjs.org/en/core/httpclient.html#timing-boolean

package/dist/commonjs/diagnosticsChannel.js

@@ -7,6 +7,7 @@ exports.initDiagnosticsChannel = void 0;
 const node_diagnostics_channel_1 = __importDefault(require("node:diagnostics_channel"));
 const node_perf_hooks_1 = require("node:perf_hooks");
 const node_util_1 = require("node:util");
+const node_net_1 = require("node:net");
 const symbols_js_1 = __importDefault(require("./symbols.js"));
 const utils_js_1 = require("./utils.js");
 const debug = (0, node_util_1.debuglog)('urllib:DiagnosticsChannel');
@@ -38,8 +39,23 @@ function formatSocket(socket) {
         localPort: socket[symbols_js_1.default.kSocketLocalPort],
         remoteAddress: socket.remoteAddress,
         remotePort: socket.remotePort,
+        attemptedAddresses: socket.autoSelectFamilyAttemptedAddresses,
+        connecting: socket.connecting,
     };
 }
+// make sure error contains socket info
+const kDestroy = Symbol('kDestroy');
+node_net_1.Socket.prototype[kDestroy] = node_net_1.Socket.prototype.destroy;
+node_net_1.Socket.prototype.destroy = function (err) {
+    if (err) {
+        Object.defineProperty(err, symbols_js_1.default.kErrorSocket, {
+            // don't show on console log
+            enumerable: false,
+            value: this,
+        });
+    }
+    return this[kDestroy](err);
+};
 function initDiagnosticsChannel() {
     // makre sure init global DiagnosticsChannel once
     if (initedDiagnosticsChannel)
@@ -69,10 +85,34 @@ function initDiagnosticsChannel() {
         opaque[symbols_js_1.default.kRequestTiming].queuing = (0, utils_js_1.performanceTime)(opaque[symbols_js_1.default.kRequestStartTime]);
     });
     // diagnosticsChannel.channel('undici:client:beforeConnect')
-    // diagnosticsChannel.channel('undici:client:connectError')
+    subscribe('undici:client:connectError', (message, name) => {
+        const { error, connectParams } = message;
+        let { socket } = message;
+        if (!socket && error[symbols_js_1.default.kErrorSocket]) {
+            socket = error[symbols_js_1.default.kErrorSocket];
+        }
+        if (socket) {
+            socket[symbols_js_1.default.kSocketId] = (0, utils_js_1.globalId)('UndiciSocket');
+            socket[symbols_js_1.default.kSocketConnectErrorTime] = new Date();
+            socket[symbols_js_1.default.kHandledRequests] = 0;
+            socket[symbols_js_1.default.kHandledResponses] = 0;
+            // copy local address to symbol, avoid them be reset after request error throw
+            if (socket.localAddress) {
+                socket[symbols_js_1.default.kSocketLocalAddress] = socket.localAddress;
+                socket[symbols_js_1.default.kSocketLocalPort] = socket.localPort;
+            }
+            socket[symbols_js_1.default.kSocketConnectProtocol] = connectParams.protocol;
+            socket[symbols_js_1.default.kSocketConnectHost] = connectParams.host;
+            socket[symbols_js_1.default.kSocketConnectPort] = connectParams.port;
+            debug('[%s] Socket#%d connectError, connectParams: %o, error: %s, (sock: %o)', name, socket[symbols_js_1.default.kSocketId], connectParams, error.message, formatSocket(socket));
+        }
+        else {
+            debug('[%s] connectError, connectParams: %o, error: %o', name, connectParams, error);
+        }
+    });
     // This message is published after a connection is established.
     subscribe('undici:client:connected', (message, name) => {
-        const { socket } = message;
+        const { socket, connectParams } = message;
         socket[symbols_js_1.default.kSocketId] = (0, utils_js_1.globalId)('UndiciSocket');
         socket[symbols_js_1.default.kSocketStartTime] = node_perf_hooks_1.performance.now();
         socket[symbols_js_1.default.kSocketConnectedTime] = new Date();
@@ -81,6 +121,9 @@ function initDiagnosticsChannel() {
         // copy local address to symbol, avoid them be reset after request error throw
         socket[symbols_js_1.default.kSocketLocalAddress] = socket.localAddress;
         socket[symbols_js_1.default.kSocketLocalPort] = socket.localPort;
+        socket[symbols_js_1.default.kSocketConnectProtocol] = connectParams.protocol;
+        socket[symbols_js_1.default.kSocketConnectHost] = connectParams.host;
+        socket[symbols_js_1.default.kSocketConnectPort] = connectParams.port;
         debug('[%s] Socket#%d connected (sock: %o)', name, socket[symbols_js_1.default.kSocketId], formatSocket(socket));
     });
     // This message is published right before the first byte of the request is written to the socket.

package/dist/commonjs/index.d.ts

@@ -1,4 +1,6 @@
+import { HttpClient } from './HttpClient.js';
 import { RequestOptions, RequestURL } from './Request.js';
+export declare function getDefaultHttpClient(): HttpClient;
 export declare function request<T = any>(url: RequestURL, options?: RequestOptions): Promise<import("./Response.js").HttpClientResponse<T>>;
 export declare function curl<T = any>(url: RequestURL, options?: RequestOptions): Promise<import("./Response.js").HttpClientResponse<T>>;
 export { MockAgent, ProxyAgent, Agent, Dispatcher, setGlobalDispatcher, getGlobalDispatcher, } from 'undici';
@@ -6,6 +8,7 @@ export { HttpClient, HttpClient as HttpClient2, HEADER_USER_AGENT as USER_AGENT,
 export { RequestOptions, RequestOptions as RequestOptions2, RequestURL, HttpMethod, FixJSONCtlCharsHandler, FixJSONCtlChars, } from './Request.js';
 export { SocketInfo, Timing, RawResponseWithMeta, HttpClientResponse, } from './Response.js';
 export { IncomingHttpHeaders, } from './IncomingHttpHeaders.js';
+export * from './HttpClientError.js';
 declare const _default: {
     request: typeof request;
     curl: typeof curl;

package/dist/commonjs/index.js

@@ -1,28 +1,46 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.USER_AGENT = exports.HttpClient2 = exports.HttpClient = exports.getGlobalDispatcher = exports.setGlobalDispatcher = exports.Dispatcher = exports.Agent = exports.ProxyAgent = exports.MockAgent = exports.curl = exports.request = void 0;
+exports.USER_AGENT = exports.HttpClient2 = exports.HttpClient = exports.getGlobalDispatcher = exports.setGlobalDispatcher = exports.Dispatcher = exports.Agent = exports.ProxyAgent = exports.MockAgent = exports.curl = exports.request = exports.getDefaultHttpClient = void 0;
 const ylru_1 = __importDefault(require("ylru"));
 const HttpClient_js_1 = require("./HttpClient.js");
-let httpclient;
-const domainSocketHttpclients = new ylru_1.default(50);
+let httpClient;
+const domainSocketHttpClients = new ylru_1.default(50);
+function getDefaultHttpClient() {
+    if (!httpClient) {
+        httpClient = new HttpClient_js_1.HttpClient();
+    }
+    return httpClient;
+}
+exports.getDefaultHttpClient = getDefaultHttpClient;
 async function request(url, options) {
     if (options?.socketPath) {
-        let domainSocketHttpclient = domainSocketHttpclients.get(options.socketPath);
+        let domainSocketHttpclient = domainSocketHttpClients.get(options.socketPath);
         if (!domainSocketHttpclient) {
             domainSocketHttpclient = new HttpClient_js_1.HttpClient({
                 connect: { socketPath: options.socketPath },
             });
-            domainSocketHttpclients.set(options.socketPath, domainSocketHttpclient);
+            domainSocketHttpClients.set(options.socketPath, domainSocketHttpclient);
         }
         return await domainSocketHttpclient.request(url, options);
     }
-    if (!httpclient) {
-        httpclient = new HttpClient_js_1.HttpClient({});
-    }
-    return await httpclient.request(url, options);
+    return await getDefaultHttpClient().request(url, options);
 }
 exports.request = request;
 // export curl method is keep compatible with urllib.curl()
@@ -41,11 +59,12 @@ Object.defineProperty(exports, "Agent", { enumerable: true, get: function () { r
 Object.defineProperty(exports, "Dispatcher", { enumerable: true, get: function () { return undici_1.Dispatcher; } });
 Object.defineProperty(exports, "setGlobalDispatcher", { enumerable: true, get: function () { return undici_1.setGlobalDispatcher; } });
 Object.defineProperty(exports, "getGlobalDispatcher", { enumerable: true, get: function () { return undici_1.getGlobalDispatcher; } });
-// HttpClient2 is keep compatible with urlib@2 HttpClient2
+// HttpClient2 is keep compatible with urllib@2 HttpClient2
 var HttpClient_js_2 = require("./HttpClient.js");
 Object.defineProperty(exports, "HttpClient", { enumerable: true, get: function () { return HttpClient_js_2.HttpClient; } });
 Object.defineProperty(exports, "HttpClient2", { enumerable: true, get: function () { return HttpClient_js_2.HttpClient; } });
 Object.defineProperty(exports, "USER_AGENT", { enumerable: true, get: function () { return HttpClient_js_2.HEADER_USER_AGENT; } });
+__exportStar(require("./HttpClientError.js"), exports);
 exports.default = {
     request,
     curl,

package/dist/commonjs/symbols.d.ts

@@ -2,9 +2,13 @@ declare const _default: {
     kSocketId: symbol;
     kSocketStartTime: symbol;
     kSocketConnectedTime: symbol;
+    kSocketConnectErrorTime: symbol;
     kSocketRequestEndTime: symbol;
     kSocketLocalAddress: symbol;
     kSocketLocalPort: symbol;
+    kSocketConnectHost: symbol;
+    kSocketConnectPort: symbol;
+    kSocketConnectProtocol: symbol;
     kHandledRequests: symbol;
     kHandledResponses: symbol;
     kRequestSocket: symbol;
@@ -13,5 +17,6 @@ declare const _default: {
     kEnableRequestTiming: symbol;
     kRequestTiming: symbol;
     kRequestOriginalOpaque: symbol;
+    kErrorSocket: symbol;
 };
 export default _default;

package/dist/commonjs/symbols.js

@@ -4,9 +4,13 @@ exports.default = {
     kSocketId: Symbol('socket id'),
     kSocketStartTime: Symbol('socket start time'),
     kSocketConnectedTime: Symbol('socket connected time'),
+    kSocketConnectErrorTime: Symbol('socket connectError time'),
     kSocketRequestEndTime: Symbol('socket request end time'),
     kSocketLocalAddress: Symbol('socket local address'),
     kSocketLocalPort: Symbol('socket local port'),
+    kSocketConnectHost: Symbol('socket connect params: host'),
+    kSocketConnectPort: Symbol('socket connect params: port'),
+    kSocketConnectProtocol: Symbol('socket connect params: protocol'),
     kHandledRequests: Symbol('handled requests per socket'),
     kHandledResponses: Symbol('handled responses per socket'),
     kRequestSocket: Symbol('request on the socket'),
@@ -15,4 +19,5 @@ exports.default = {
     kEnableRequestTiming: Symbol('enable request timing or not'),
     kRequestTiming: Symbol('request timing'),
     kRequestOriginalOpaque: Symbol('request original opaque'),
+    kErrorSocket: Symbol('socket of error'),
 };

package/dist/esm/HttpAgent.js

@@ -62,7 +62,7 @@ export class HttpAgent extends Agent {
             }
             const family = isIP(hostname);
             if (family === 4 || family === 6) {
-                // if request hostname is ip, custom lookup won't excute
+                // if request hostname is ip, custom lookup won't execute
                 if (!this.#checkAddress(hostname, family)) {
                     throw new IllegalAddressError(hostname, hostname, family);
                 }

package/dist/esm/HttpClient.d.ts

@@ -42,6 +42,11 @@ export type ClientOptions = {
     };
 };
 export declare const HEADER_USER_AGENT: string;
+export type RequestContext = {
+    retries: number;
+    socketErrorRetries: number;
+    requestStartTime?: number;
+};
 export type RequestDiagnosticsMessage = {
     request: RequestMeta;
 };
@@ -50,11 +55,26 @@ export type ResponseDiagnosticsMessage = {
     response: RawResponseWithMeta;
     error?: Error;
 };
+export interface PoolStat {
+    /** Number of open socket connections in this pool. */
+    connected: number;
+    /** Number of open socket connections in this pool that do not have an active request. */
+    free: number;
+    /** Number of pending requests across all clients in this pool. */
+    pending: number;
+    /** Number of queued requests across all clients in this pool. */
+    queued: number;
+    /** Number of currently active requests across all clients in this pool. */
+    running: number;
+    /** Number of active, pending, or queued requests across all clients in this pool. */
+    size: number;
+}
 export declare class HttpClient extends EventEmitter {
     #private;
     constructor(clientOptions?: ClientOptions);
     getDispatcher(): Dispatcher;
     setDispatcher(dispatcher: Dispatcher): void;
+    getDispatcherPoolStats(): Record<string, PoolStat>;
     request<T = any>(url: RequestURL, options?: RequestOptions): Promise<HttpClientResponse<T>>;
     curl<T = any>(url: RequestURL, options?: RequestOptions): Promise<HttpClientResponse<T>>;
 }