urllib 3.20.0 → 3.22.0

package/dist/esm/HttpClient.js

@@ -11,6 +11,7 @@ import { createReadStream } from 'node:fs';
 import { format as urlFormat } from 'node:url';
 import { performance } from 'node:perf_hooks';
 import { FormData as FormDataNative, request as undiciRequest, Agent, getGlobalDispatcher, } from 'undici';
+import undiciSymbols from 'undici/lib/core/symbols.js';
 import { FormData as FormDataNode } from 'formdata-node';
 import { FormDataEncoder } from 'form-data-encoder';
 import createUserAgent from 'default-user-agent';
@@ -23,6 +24,7 @@ import { HttpAgent } from './HttpAgent.js';
 import { parseJSON, sleep, digestAuthHeader, globalId, performanceTime, isReadable } from './utils.js';
 import symbols from './symbols.js';
 import { initDiagnosticsChannel } from './diagnosticsChannel.js';
+import { HttpClientConnectTimeoutError, HttpClientRequestTimeoutError } from './HttpClientError.js';
 const PROTO_RE = /^https?:\/\//i;
 const FormData = FormDataNative ?? FormDataNode;
 // impl promise pipeline on Node.js 14
@@ -59,15 +61,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);
-    }
-}
-export const HEADER_USER_AGENT = createUserAgent('node-urllib', '3.20.0');
+export const HEADER_USER_AGENT = createUserAgent('node-urllib', '3.22.0');
 function getFileName(stream) {
     const filePath = stream.path;
     if (filePath) {
@@ -108,10 +102,31 @@ export class HttpClient extends EventEmitter {
     setDispatcher(dispatcher) {
         this.#dispatcher = dispatcher;
     }
+    getDispatcherPoolStats() {
+        const agent = this.getDispatcher();
+        // origin => Pool Instance
+        const clients = agent[undiciSymbols.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);
     }
@@ -574,14 +589,17 @@ export class HttpClient extends 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 HttpClientRequestTimeoutError(headersTimeout, { cause: err });
             }
             else if (err.name === 'BodyTimeoutError') {
-                err = new HttpClientRequestTimeoutError(bodyTimeout, { cause: e });
+                err = new HttpClientRequestTimeoutError(bodyTimeout, { cause: err });
+            }
+            else if (err.code === 'UND_ERR_CONNECT_TIMEOUT') {
+                err = new 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
@@ -604,7 +622,7 @@ export class HttpClient extends EventEmitter {
                 res.requestUrls.push(requestUrl.href);
             }
             res.rt = performanceTime(requestStartTime);
-            this.#updateSocketInfo(socketInfo, internalOpaque);
+            this.#updateSocketInfo(socketInfo, internalOpaque, rawError);
             channels.response.publish({
                 request: reqMeta,
                 response: res,
@@ -625,21 +643,38 @@ export class HttpClient extends EventEmitter {
             throw err;
         }
     }
-    #updateSocketInfo(socketInfo, internalOpaque) {
-        const socket = internalOpaque[symbols.kRequestSocket];
+    #updateSocketInfo(socketInfo, internalOpaque, err) {
+        const socket = internalOpaque[symbols.kRequestSocket] ?? err?.[symbols.kErrorSocket];
         if (socket) {
             socketInfo.id = socket[symbols.kSocketId];
             socketInfo.handledRequests = socket[symbols.kHandledRequests];
             socketInfo.handledResponses = socket[symbols.kHandledResponses];
-            socketInfo.localAddress = socket[symbols.kSocketLocalAddress];
-            socketInfo.localPort = socket[symbols.kSocketLocalPort];
-            socketInfo.remoteAddress = socket.remoteAddress;
-            socketInfo.remotePort = socket.remotePort;
-            socketInfo.remoteFamily = socket.remoteFamily;
+            if (socket[symbols.kSocketLocalAddress]) {
+                socketInfo.localAddress = socket[symbols.kSocketLocalAddress];
+                socketInfo.localPort = socket[symbols.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.kSocketConnectedTime];
-            socketInfo.lastRequestEndTime = socket[symbols.kSocketRequestEndTime];
+            if (socket[symbols.kSocketConnectErrorTime]) {
+                socketInfo.connectErrorTime = socket[symbols.kSocketConnectErrorTime];
+                if (Array.isArray(socket.autoSelectFamilyAttemptedAddresses)) {
+                    socketInfo.attemptedRemoteAddresses = socket.autoSelectFamilyAttemptedAddresses;
+                }
+                socketInfo.connectProtocol = socket[symbols.kSocketConnectProtocol];
+                socketInfo.connectHost = socket[symbols.kSocketConnectHost];
+                socketInfo.connectPort = socket[symbols.kSocketConnectPort];
+            }
+            if (socket[symbols.kSocketConnectedTime]) {
+                socketInfo.connectedTime = socket[symbols.kSocketConnectedTime];
+            }
+            if (socket[symbols.kSocketRequestEndTime]) {
+                socketInfo.lastRequestEndTime = socket[symbols.kSocketRequestEndTime];
+            }
             socket[symbols.kSocketRequestEndTime] = new Date();
         }
     }

package/dist/esm/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/esm/HttpClientError.js

@@ -0,0 +1,23 @@
+export class HttpClientRequestError extends Error {
+    status;
+    headers;
+    socket;
+    res;
+}
+export 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);
+    }
+}
+export 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);
+    }
+}

package/dist/esm/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/esm/diagnosticsChannel.js

@@ -1,6 +1,7 @@
 import diagnosticsChannel from 'node:diagnostics_channel';
 import { performance } from 'node:perf_hooks';
 import { debuglog } from 'node:util';
+import { Socket } from 'node:net';
 import symbols from './symbols.js';
 import { globalId, performanceTime } from './utils.js';
 const debug = debuglog('urllib:DiagnosticsChannel');
@@ -32,8 +33,23 @@ function formatSocket(socket) {
         localPort: socket[symbols.kSocketLocalPort],
         remoteAddress: socket.remoteAddress,
         remotePort: socket.remotePort,
+        attemptedAddresses: socket.autoSelectFamilyAttemptedAddresses,
+        connecting: socket.connecting,
     };
 }
+// make sure error contains socket info
+const kDestroy = Symbol('kDestroy');
+Socket.prototype[kDestroy] = Socket.prototype.destroy;
+Socket.prototype.destroy = function (err) {
+    if (err) {
+        Object.defineProperty(err, symbols.kErrorSocket, {
+            // don't show on console log
+            enumerable: false,
+            value: this,
+        });
+    }
+    return this[kDestroy](err);
+};
 export function initDiagnosticsChannel() {
     // makre sure init global DiagnosticsChannel once
     if (initedDiagnosticsChannel)
@@ -63,10 +79,34 @@ export function initDiagnosticsChannel() {
         opaque[symbols.kRequestTiming].queuing = performanceTime(opaque[symbols.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.kErrorSocket]) {
+            socket = error[symbols.kErrorSocket];
+        }
+        if (socket) {
+            socket[symbols.kSocketId] = globalId('UndiciSocket');
+            socket[symbols.kSocketConnectErrorTime] = new Date();
+            socket[symbols.kHandledRequests] = 0;
+            socket[symbols.kHandledResponses] = 0;
+            // copy local address to symbol, avoid them be reset after request error throw
+            if (socket.localAddress) {
+                socket[symbols.kSocketLocalAddress] = socket.localAddress;
+                socket[symbols.kSocketLocalPort] = socket.localPort;
+            }
+            socket[symbols.kSocketConnectProtocol] = connectParams.protocol;
+            socket[symbols.kSocketConnectHost] = connectParams.host;
+            socket[symbols.kSocketConnectPort] = connectParams.port;
+            debug('[%s] Socket#%d connectError, connectParams: %o, error: %s, (sock: %o)', name, socket[symbols.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.kSocketId] = globalId('UndiciSocket');
         socket[symbols.kSocketStartTime] = performance.now();
         socket[symbols.kSocketConnectedTime] = new Date();
@@ -75,6 +115,9 @@ export function initDiagnosticsChannel() {
         // copy local address to symbol, avoid them be reset after request error throw
         socket[symbols.kSocketLocalAddress] = socket.localAddress;
         socket[symbols.kSocketLocalPort] = socket.localPort;
+        socket[symbols.kSocketConnectProtocol] = connectParams.protocol;
+        socket[symbols.kSocketConnectHost] = connectParams.host;
+        socket[symbols.kSocketConnectPort] = connectParams.port;
         debug('[%s] Socket#%d connected (sock: %o)', name, socket[symbols.kSocketId], formatSocket(socket));
     });
     // This message is published right before the first byte of the request is written to the socket.

package/dist/esm/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/esm/index.js

@@ -1,22 +1,25 @@
 import LRU from 'ylru';
 import { HttpClient, HEADER_USER_AGENT } from './HttpClient.js';
-let httpclient;
-const domainSocketHttpclients = new LRU(50);
+let httpClient;
+const domainSocketHttpClients = new LRU(50);
+export function getDefaultHttpClient() {
+    if (!httpClient) {
+        httpClient = new HttpClient();
+    }
+    return httpClient;
+}
 export 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({
                 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({});
-    }
-    return await httpclient.request(url, options);
+    return await getDefaultHttpClient().request(url, options);
 }
 // export curl method is keep compatible with urllib.curl()
 // ```ts
@@ -27,8 +30,9 @@ export async function curl(url, options) {
     return await request(url, options);
 }
 export { MockAgent, ProxyAgent, Agent, Dispatcher, setGlobalDispatcher, getGlobalDispatcher, } from 'undici';
-// HttpClient2 is keep compatible with urlib@2 HttpClient2
+// HttpClient2 is keep compatible with urllib@2 HttpClient2
 export { HttpClient, HttpClient as HttpClient2, HEADER_USER_AGENT as USER_AGENT, } from './HttpClient.js';
+export * from './HttpClientError.js';
 export default {
     request,
     curl,

package/dist/esm/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/esm/symbols.js

@@ -2,9 +2,13 @@ export 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'),
@@ -13,4 +17,5 @@ export default {
     kEnableRequestTiming: Symbol('enable request timing or not'),
     kRequestTiming: Symbol('request timing'),
     kRequestOriginalOpaque: Symbol('request original opaque'),
+    kErrorSocket: Symbol('socket of error'),
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "urllib",
-  "version": "3.20.0",
+  "version": "3.22.0",
   "publishConfig": {
     "tag": "latest"
   },
@@ -32,8 +32,9 @@
     "build:esm:test": "cd test/esm && rm -rf node_modules && npm link ../.. && node index.js",
     "build:mts:test": "cd test/mts && rm -rf node_modules && npm link ../.. && tsc",
     "build:test": "npm run build && npm run build:cjs:test && npm run build:esm:test && npm run build:mts:test && npm run test-tsc",
-    "test-tsc": "npm run test-tsc:cjs && npm run test-tsc:esm",
+    "test-tsc": "npm run test-tsc:cjs:es2021 && npm run test-tsc:cjs && npm run test-tsc:esm",
     "test-tsc:cjs": "cd test/fixtures/ts && rm -rf node_modules && npm link ../../.. && npm run build",
+    "test-tsc:cjs:es2021": "cd test/fixtures/ts-cjs-es2021 && rm -rf node_modules && npm link ../../.. && npm run build",
     "test-tsc:esm": "cd test/fixtures/ts-esm && rm -rf node_modules && npm link ../../.. && npm run build",
     "test": "npm run lint && vitest run",
     "test-keepalive": "cross-env TEST_KEEPALIVE_COUNT=50 vitest run --test-timeout 180000 keep-alive-header.test.ts",
@@ -68,7 +69,7 @@
     "@types/qs": "^6.9.7",
     "@types/selfsigned": "^2.0.1",
     "@types/tar-stream": "^2.2.2",
-    "@vitest/coverage-v8": "beta",
+    "@vitest/coverage-v8": "^1.0.1",
     "busboy": "^1.6.0",
     "cross-env": "^7.0.3",
     "eslint": "^8.25.0",
@@ -81,7 +82,7 @@
     "tshy": "^1.0.0",
     "tshy-after": "^1.0.0",
     "typescript": "^5.0.4",
-    "vitest": "beta"
+    "vitest": "^1.0.1"
   },
   "engines": {
     "node": ">= 14.19.3"

package/src/HttpAgent.ts

@@ -77,7 +77,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/src/HttpClient.ts

@@ -22,7 +22,9 @@ import {
   Dispatcher,
   Agent,
   getGlobalDispatcher,
+  Pool,
 } from 'undici';
+import undiciSymbols from 'undici/lib/core/symbols.js';
 import { FormData as FormDataNode } from 'formdata-node';
 import { FormDataEncoder } from 'form-data-encoder';
 import createUserAgent from 'default-user-agent';
@@ -38,6 +40,7 @@ import { RawResponseWithMeta, HttpClientResponse, SocketInfo } from './Response.
 import { parseJSON, sleep, digestAuthHeader, globalId, performanceTime, isReadable } from './utils.js';
 import symbols from './symbols.js';
 import { initDiagnosticsChannel } from './diagnosticsChannel.js';
+import { HttpClientConnectTimeoutError, HttpClientRequestTimeoutError } from './HttpClientError.js';
 
 type Exists<T> = T extends undefined ? never : T;
 type UndiciRequestOption = Exists<Parameters<typeof undiciRequest>[1]>;
@@ -121,15 +124,6 @@ class BlobFromStream {
   }
 }
 
-class HttpClientRequestTimeoutError extends Error {
-  constructor(timeout: number, options: ErrorOptions) {
-    const message = `Request timeout for ${timeout} ms`;
-    super(message, options);
-    this.name = this.constructor.name;
-    Error.captureStackTrace(this, this.constructor);
-  }
-}
-
 export const HEADER_USER_AGENT = createUserAgent('node-urllib', 'VERSION');
 
 function getFileName(stream: Readable) {
@@ -144,7 +138,7 @@ function defaultIsRetry(response: HttpClientResponse) {
   return response.status >= 500;
 }
 
-type RequestContext = {
+export type RequestContext = {
   retries: number;
   socketErrorRetries: number;
   requestStartTime?: number;
@@ -165,6 +159,20 @@ export type ResponseDiagnosticsMessage = {
   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 class HttpClient extends EventEmitter {
   #defaultArgs?: RequestOptions;
@@ -195,11 +203,32 @@ export class HttpClient extends EventEmitter {
     this.#dispatcher = dispatcher;
   }
 
+  getDispatcherPoolStats() {
+    const agent = this.getDispatcher();
+    // origin => Pool Instance
+    const clients: Map<string, WeakRef<Pool>> = agent[undiciSymbols.kClients];
+    const poolStatsMap: Record<string, PoolStat> = {};
+    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,
+      } satisfies PoolStat;
+    }
+    return poolStatsMap;
+  }
+
   async request<T = any>(url: RequestURL, options?: RequestOptions) {
     return await this.#requestInternal<T>(url, options);
   }
 
-  // alias to request, keep compatible with urlib@2 HttpClient.curl
+  // alias to request, keep compatible with urllib@2 HttpClient.curl
   async curl<T = any>(url: RequestURL, options?: RequestOptions) {
     return await this.request<T>(url, options);
   }
@@ -653,13 +682,15 @@ export class HttpClient extends EventEmitter {
       }
 
       return clientResponse;
-    } catch (e: any) {
-      debug('Request#%d throw error: %s', requestId, e);
-      let err = e;
+    } catch (rawError: any) {
+      debug('Request#%d throw error: %s', requestId, rawError);
+      let err = rawError;
       if (err.name === 'HeadersTimeoutError') {
-        err = new HttpClientRequestTimeoutError(headersTimeout, { cause: e });
+        err = new HttpClientRequestTimeoutError(headersTimeout, { cause: err });
       } else if (err.name === 'BodyTimeoutError') {
-        err = new HttpClientRequestTimeoutError(bodyTimeout, { cause: e });
+        err = new HttpClientRequestTimeoutError(bodyTimeout, { cause: err });
+      } else if (err.code === 'UND_ERR_CONNECT_TIMEOUT') {
+        err = new 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
         if (args.socketErrorRetry > 0 && requestContext.socketErrorRetries < args.socketErrorRetry) {
@@ -681,7 +712,7 @@ export class HttpClient extends EventEmitter {
         res.requestUrls.push(requestUrl.href);
       }
       res.rt = performanceTime(requestStartTime);
-      this.#updateSocketInfo(socketInfo, internalOpaque);
+      this.#updateSocketInfo(socketInfo, internalOpaque, rawError);
 
       channels.response.publish({
         request: reqMeta,
@@ -704,21 +735,38 @@ export class HttpClient extends EventEmitter {
     }
   }
 
-  #updateSocketInfo(socketInfo: SocketInfo, internalOpaque: any) {
-    const socket = internalOpaque[symbols.kRequestSocket];
+  #updateSocketInfo(socketInfo: SocketInfo, internalOpaque: any, err?: any) {
+    const socket = internalOpaque[symbols.kRequestSocket] ?? err?.[symbols.kErrorSocket];
     if (socket) {
       socketInfo.id = socket[symbols.kSocketId];
       socketInfo.handledRequests = socket[symbols.kHandledRequests];
       socketInfo.handledResponses = socket[symbols.kHandledResponses];
-      socketInfo.localAddress = socket[symbols.kSocketLocalAddress];
-      socketInfo.localPort = socket[symbols.kSocketLocalPort];
-      socketInfo.remoteAddress = socket.remoteAddress;
-      socketInfo.remotePort = socket.remotePort;
-      socketInfo.remoteFamily = socket.remoteFamily;
+      if (socket[symbols.kSocketLocalAddress]) {
+        socketInfo.localAddress = socket[symbols.kSocketLocalAddress];
+        socketInfo.localPort = socket[symbols.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.kSocketConnectedTime];
-      socketInfo.lastRequestEndTime = socket[symbols.kSocketRequestEndTime];
+      if (socket[symbols.kSocketConnectErrorTime]) {
+        socketInfo.connectErrorTime = socket[symbols.kSocketConnectErrorTime];
+        if (Array.isArray(socket.autoSelectFamilyAttemptedAddresses)) {
+          socketInfo.attemptedRemoteAddresses = socket.autoSelectFamilyAttemptedAddresses;
+        }
+        socketInfo.connectProtocol = socket[symbols.kSocketConnectProtocol];
+        socketInfo.connectHost = socket[symbols.kSocketConnectHost];
+        socketInfo.connectPort = socket[symbols.kSocketConnectPort];
+      }
+      if (socket[symbols.kSocketConnectedTime]) {
+        socketInfo.connectedTime = socket[symbols.kSocketConnectedTime];
+      }
+      if (socket[symbols.kSocketRequestEndTime]) {
+        socketInfo.lastRequestEndTime = socket[symbols.kSocketRequestEndTime];
+      }
       socket[symbols.kSocketRequestEndTime] = new Date();
     }
   }

package/src/HttpClientError.ts

@@ -0,0 +1,34 @@
+import type { RawResponseWithMeta, SocketInfo } from './Response.js';
+import type { IncomingHttpHeaders } from './IncomingHttpHeaders.js';
+
+// need to support ES2021
+interface ErrorOptions {
+  cause?: Error;
+}
+
+export class HttpClientRequestError extends Error {
+  status?: number;
+  headers?: IncomingHttpHeaders;
+  socket?: SocketInfo;
+  res?: RawResponseWithMeta;
+}
+
+export class HttpClientRequestTimeoutError extends HttpClientRequestError {
+  constructor(timeout: number, options: ErrorOptions) {
+    const message = `Request timeout for ${timeout} ms`;
+    super(message, options);
+    this.name = this.constructor.name;
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+export class HttpClientConnectTimeoutError extends HttpClientRequestError {
+  code: string;
+
+  constructor(message: string, code: string, options: ErrorOptions) {
+    super(message, options);
+    this.name = this.constructor.name;
+    this.code = code;
+    Error.captureStackTrace(this, this.constructor);
+  }
+}

package/src/Response.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;
 };
 
 /**