undici 7.16.0 → 7.17.0

package/README.md

@@ -166,6 +166,8 @@ Installing undici as a module allows you to use a newer version than what's bund
 
 ## Quick Start
 
+### Basic Request
+
 ```js
 import { request } from 'undici'
 
@@ -184,6 +186,50 @@ for await (const data of body) { console.log('data', data) }
 console.log('trailers', trailers)
 ```
 
+### Using Cache Interceptor
+
+Undici provides a powerful HTTP caching interceptor that follows HTTP caching best practices. Here's how to use it:
+
+```js
+import { fetch, Agent, interceptors, cacheStores } from 'undici';
+
+// Create a client with cache interceptor
+const client = new Agent().compose(interceptors.cache({
+  // Optional: Configure cache store (defaults to MemoryCacheStore)
+  store: new cacheStores.MemoryCacheStore({
+    maxSize: 100 * 1024 * 1024, // 100MB
+    maxCount: 1000,
+    maxEntrySize: 5 * 1024 * 1024 // 5MB
+  }),
+  
+  // Optional: Specify which HTTP methods to cache (default: ['GET', 'HEAD'])
+  methods: ['GET', 'HEAD']
+}));
+
+// Set the global dispatcher to use our caching client
+setGlobalDispatcher(client);
+
+// Now all fetch requests will use the cache
+async function getData() {
+  const response = await fetch('https://api.example.com/data');
+  // The server should set appropriate Cache-Control headers in the response
+  // which the cache will respect based on the cache policy
+  return response.json();
+}
+
+// First request - fetches from origin
+const data1 = await getData();
+
+// Second request - served from cache if within max-age
+const data2 = await getData();
+```
+
+#### Key Features:
+- **Automatic Caching**: Respects `Cache-Control` and `Expires` headers
+- **Validation**: Supports `ETag` and `Last-Modified` validation
+- **Storage Options**: In-memory or persistent SQLite storage
+- **Flexible**: Configure cache size, TTL, and more
+
 ## Global Installation
 
 Undici provides an `install()` function to add all WHATWG fetch classes to `globalThis`, making them available globally:
@@ -472,7 +518,7 @@ Note that consuming the response body is _mandatory_ for `request`:
 ```js
 // Do
 const { body, headers } = await request(url);
-await res.body.dump(); // force consumption of body
+await body.dump(); // force consumption of body
 
 // Do not
 const { headers } = await request(url);

package/docs/docs/api/Client.md

@@ -30,6 +30,7 @@ Returns: `Client`
 * **autoSelectFamily**: `boolean` (optional) - Default: depends on local Node version, on Node 18.13.0 and above is `false`. Enables a family autodetection algorithm that loosely implements section 5 of [RFC 8305](https://tools.ietf.org/html/rfc8305#section-5). See [here](https://nodejs.org/api/net.html#socketconnectoptions-connectlistener) for more details. This option is ignored if not supported by the current Node version.
 * **autoSelectFamilyAttemptTimeout**: `number` - Default: depends on local Node version, on Node 18.13.0 and above is `250`. The amount of time in milliseconds to wait for a connection attempt to finish before trying the next address when using the `autoSelectFamily` option. See [here](https://nodejs.org/api/net.html#socketconnectoptions-connectlistener) for more details.
 * **allowH2**: `boolean` - Default: `false`. Enables support for H2 if the server has assigned bigger priority to it through ALPN negotiation.
+* **useH2c**: `boolean` - Default: `false`. Enforces h2c for non-https connections.
 * **maxConcurrentStreams**: `number` - Default: `100`. Dictates the maximum number of concurrent streams for a single H2 session. It can be overridden by a SETTINGS remote frame.
 
 > **Notes about HTTP/2**

package/docs/docs/api/DiagnosticsChannel.md

@@ -254,3 +254,60 @@ diagnosticsChannel.channel('undici:websocket:pong').subscribe(({ payload, websoc
   console.log(websocket) // the WebSocket instance
 })
 ```
+
+## `undici:proxy:connected`
+
+This message is published after the `ProxyAgent` establishes a connection to the proxy server.
+
+```js
+import diagnosticsChannel from 'diagnostics_channel'
+
+diagnosticsChannel.channel('undici:proxy:connected').subscribe(({ socket, connectParams }) => {
+  console.log(socket)
+  console.log(connectParams)
+  // const { origin, port, path, signal, headers, servername } = connectParams
+})
+```
+
+## `undici:request:pending-requests`
+
+This message is published when the deduplicate interceptor's pending request map changes. This is useful for monitoring and debugging request deduplication behavior.
+
+The deduplicate interceptor automatically deduplicates concurrent requests for the same resource. When multiple identical requests are made while one is already in-flight, only one request is sent to the origin server, and all waiting handlers receive the same response.
+
+```js
+import diagnosticsChannel from 'diagnostics_channel'
+
+diagnosticsChannel.channel('undici:request:pending-requests').subscribe(({ type, size, key }) => {
+  console.log(type)  // 'added' or 'removed'
+  console.log(size)  // current number of pending requests
+  console.log(key)   // the deduplication key for this request
+})
+```
+
+### Event Properties
+
+- `type` (`string`): Either `'added'` when a new pending request is registered, or `'removed'` when a pending request completes (successfully or with an error).
+- `size` (`number`): The current number of pending requests after the change.
+- `key` (`string`): The deduplication key for the request, composed of the origin, method, path, and request headers.
+
+### Example: Monitoring Request Deduplication
+
+```js
+import diagnosticsChannel from 'diagnostics_channel'
+
+const channel = diagnosticsChannel.channel('undici:request:pending-requests')
+
+channel.subscribe(({ type, size, key }) => {
+  if (type === 'added') {
+    console.log(`New pending request: ${key} (${size} total pending)`)
+  } else {
+    console.log(`Request completed: ${key} (${size} remaining)`)
+  }
+})
+```
+
+This can be useful for:
+- Verifying that request deduplication is working as expected
+- Monitoring the number of concurrent in-flight requests
+- Debugging deduplication behavior in production environments

package/docs/docs/api/Dispatcher.md

@@ -1043,6 +1043,7 @@ The `dns` interceptor enables you to cache DNS lookups for a given duration, per
   - The function should return a single record from the records array.
   - By default a simplified version of Round Robin is used.
   - The `records` property can be mutated to store the state of the balancing algorithm.
+- `storage: DNSStorage` - Custom storage for resolved DNS records
 
 > The `Dispatcher#options` also gets extended with the options `dns.affinity`, `dns.dualStack`, `dns.lookup` and `dns.pick` which can be used to configure the interceptor at a request-per-request basis.
 
@@ -1057,6 +1058,14 @@ It represents a map of DNS IP addresses records for a single origin.
 - `4.ips` - (`DNSInterceptorRecord[] | null`) The IPv4 addresses.
 - `6.ips` - (`DNSInterceptorRecord[] | null`) The IPv6 addresses.
 
+**DNSStorage**
+It represents a storage object for resolved DNS records.
+- `size` - (`number`) current size of the storage.
+- `get` - (`(origin: string) => DNSInterceptorOriginRecords | null`) method to get the records for a given origin.
+- `set` - (`(origin: string, records: DNSInterceptorOriginRecords | null, options: { ttl: number }) => void`) method to set the records for a given origin.
+- `delete` - (`(origin: string) => void`) method to delete records for a given origin.
+- `full` - (`() => boolean`) method to check if the storage is full, if returns `true`, DNS lookup will be skipped in this interceptor and new records will not be stored.
+
 **Example - Basic DNS Interceptor**
 
 ```js
@@ -1073,6 +1082,45 @@ const response = await client.request({
 })
 ```
 
+**Example - DNS Interceptor and LRU cache as a storage**
+
+```js
+const { Client, interceptors } = require("undici");
+const QuickLRU = require("quick-lru");
+const { dns } = interceptors;
+
+const lru = new QuickLRU({ maxSize: 100 });
+
+const lruAdapter = {
+  get size() {
+    return lru.size;
+  },
+  get(origin) {
+    return lru.get(origin);
+  },
+  set(origin, records, { ttl }) {
+    lru.set(origin, records, { maxAge: ttl });
+  },
+  delete(origin) {
+    lru.delete(origin);
+  },
+  full() {
+    // For LRU cache, we can always store new records,
+    // old records will be evicted automatically
+    return false;
+  }
+}
+
+const client = new Agent().compose([
+  dns({ storage: lruAdapter })
+])
+
+const response = await client.request({
+  origin: `http://localhost:3030`,
+  ...requestOpts
+})
+```
+
 ##### `responseError`
 
 The `responseError` interceptor throws an error for responses with status code errors (>= 400).
@@ -1165,6 +1213,44 @@ The `cache` interceptor implements client-side response caching as described in
 - `cacheByDefault` - The default expiration time to cache responses by if they don't have an explicit expiration and cannot have an heuristic expiry computed. If this isn't present, responses neither with an explicit expiration nor heuristically cacheable will not be cached. Default `undefined`.
 - `type` - The [type of cache](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Caching#types_of_caches) for Undici to act as. Can be `shared` or `private`. Default `shared`. `private` implies privately cacheable responses will be cached and potentially shared with other users of your application.
 
+##### `Deduplicate Interceptor`
+
+The `deduplicate` interceptor deduplicates concurrent identical requests. When multiple identical requests are made while one is already in-flight, only one request is sent to the origin server, and all waiting handlers receive the same response. This reduces server load and improves performance.
+
+**Options**
+
+- `methods` - The [**safe** HTTP methods](https://www.rfc-editor.org/rfc/rfc9110#section-9.2.1) to deduplicate. Default `['GET']`.
+- `skipHeaderNames` - Header names that, if present in a request, will cause the request to skip deduplication entirely. Useful for headers like `idempotency-key` where presence indicates unique processing. Header name matching is case-insensitive. Default `[]`.
+- `excludeHeaderNames` - Header names to exclude from the deduplication key. Requests with different values for these headers will still be deduplicated together. Useful for headers like `x-request-id` that vary per request but shouldn't affect deduplication. Header name matching is case-insensitive. Default `[]`.
+
+**Usage**
+
+```js
+const { Client, interceptors } = require("undici");
+const { deduplicate, cache } = interceptors;
+
+// Deduplicate only
+const client = new Client("http://example.com").compose(
+  deduplicate()
+);
+
+// Deduplicate with caching
+const clientWithCache = new Client("http://example.com").compose(
+  deduplicate(),
+  cache()
+);
+```
+
+Requests are considered identical if they have the same:
+- Origin
+- HTTP method
+- Path
+- Request headers (excluding any headers specified in `excludeHeaderNames`)
+
+All deduplicated requests receive the complete response including status code, headers, and body.
+
+For observability, request deduplication events are published to the `undici:request:pending-requests` [diagnostic channel](/docs/docs/api/DiagnosticsChannel.md#undicirequestpending-requests).
+
 ## Instance Events
 
 ### Event: `'connect'`

package/docs/docs/api/RoundRobinPool.md

@@ -0,0 +1,145 @@
+# Class: RoundRobinPool
+
+Extends: `undici.Dispatcher`
+
+A pool of [Client](/docs/docs/api/Client.md) instances connected to the same upstream target with round-robin client selection.
+
+Unlike [`Pool`](/docs/docs/api/Pool.md), which always selects the first available client, `RoundRobinPool` cycles through clients in a round-robin fashion. This ensures even distribution of requests across all connections, which is particularly useful when the upstream target is behind a load balancer that round-robins TCP connections across multiple backend servers (e.g., Kubernetes Services).
+
+Requests are not guaranteed to be dispatched in order of invocation.
+
+## `new RoundRobinPool(url[, options])`
+
+Arguments:
+
+* **url** `URL | string` - It should only include the **protocol, hostname, and port**.
+* **options** `RoundRobinPoolOptions` (optional)
+
+### Parameter: `RoundRobinPoolOptions`
+
+Extends: [`ClientOptions`](/docs/docs/api/Client.md#parameter-clientoptions)
+
+* **factory** `(origin: URL, opts: Object) => Dispatcher` - Default: `(origin, opts) => new Client(origin, opts)`
+* **connections** `number | null` (optional) - Default: `null` - The number of `Client` instances to create. When set to `null`, the `RoundRobinPool` instance will create an unlimited amount of `Client` instances.
+* **clientTtl** `number | null` (optional) - Default: `null` - The amount of time before a `Client` instance is removed from the `RoundRobinPool` and closed. When set to `null`, `Client` instances will not be removed or closed based on age.
+
+## Use Case
+
+`RoundRobinPool` is designed for scenarios where:
+
+1. You connect to a single origin (e.g., `http://my-service.namespace.svc`)
+2. That origin is backed by a load balancer distributing TCP connections across multiple servers
+3. You want requests evenly distributed across all backend servers
+
+**Example**: In Kubernetes, when using a Service DNS name with multiple Pod replicas, kube-proxy load balances TCP connections. `RoundRobinPool` ensures each connection (and thus each Pod) receives an equal share of requests.
+
+### Important: Backend Distribution Considerations
+
+`RoundRobinPool` distributes **HTTP requests** evenly across **TCP connections**. Whether this translates to even backend server distribution depends on the load balancer's behavior:
+
+**✓ Works when the load balancer**:
+- Assigns different backends to different TCP connections from the same client
+- Uses algorithms like: round-robin, random, least-connections (without client affinity)
+- Example: Default Kubernetes Services without `sessionAffinity`
+
+**✗ Does NOT work when**:
+- Load balancer has client/source IP affinity (all connections from one IP → same backend)
+- Load balancer uses source-IP-hash or sticky sessions
+
+**How it works:**
+1. `RoundRobinPool` creates N TCP connections to the load balancer endpoint
+2. Load balancer assigns each TCP connection to a backend (per its algorithm)
+3. `RoundRobinPool` cycles HTTP requests across those N connections
+4. Result: Requests distributed proportionally to how the LB distributed the connections
+
+If the load balancer assigns all connections to the same backend (e.g., due to session affinity), `RoundRobinPool` cannot overcome this. In such cases, consider using [`BalancedPool`](/docs/docs/api/BalancedPool.md) with direct backend addresses (e.g., individual pod IPs) instead of a load-balanced endpoint.
+
+## Instance Properties
+
+### `RoundRobinPool.closed`
+
+Implements [Client.closed](/docs/docs/api/Client.md#clientclosed)
+
+### `RoundRobinPool.destroyed`
+
+Implements [Client.destroyed](/docs/docs/api/Client.md#clientdestroyed)
+
+### `RoundRobinPool.stats`
+
+Returns [`PoolStats`](PoolStats.md) instance for this pool.
+
+## Instance Methods
+
+### `RoundRobinPool.close([callback])`
+
+Implements [`Dispatcher.close([callback])`](/docs/docs/api/Dispatcher.md#dispatcherclosecallback-promise).
+
+### `RoundRobinPool.destroy([error, callback])`
+
+Implements [`Dispatcher.destroy([error, callback])`](/docs/docs/api/Dispatcher.md#dispatcherdestroyerror-callback-promise).
+
+### `RoundRobinPool.connect(options[, callback])`
+
+See [`Dispatcher.connect(options[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherconnectoptions-callback).
+
+### `RoundRobinPool.dispatch(options, handler)`
+
+Implements [`Dispatcher.dispatch(options, handler)`](/docs/docs/api/Dispatcher.md#dispatcherdispatchoptions-handler).
+
+### `RoundRobinPool.pipeline(options, handler)`
+
+See [`Dispatcher.pipeline(options, handler)`](/docs/docs/api/Dispatcher.md#dispatcherpipelineoptions-handler).
+
+### `RoundRobinPool.request(options[, callback])`
+
+See [`Dispatcher.request(options [, callback])`](/docs/docs/api/Dispatcher.md#dispatcherrequestoptions-callback).
+
+### `RoundRobinPool.stream(options, factory[, callback])`
+
+See [`Dispatcher.stream(options, factory[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherstreamoptions-factory-callback).
+
+### `RoundRobinPool.upgrade(options[, callback])`
+
+See [`Dispatcher.upgrade(options[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherupgradeoptions-callback).
+
+## Instance Events
+
+### Event: `'connect'`
+
+See [Dispatcher Event: `'connect'`](/docs/docs/api/Dispatcher.md#event-connect).
+
+### Event: `'disconnect'`
+
+See [Dispatcher Event: `'disconnect'`](/docs/docs/api/Dispatcher.md#event-disconnect).
+
+### Event: `'drain'`
+
+See [Dispatcher Event: `'drain'`](/docs/docs/api/Dispatcher.md#event-drain).
+
+## Example
+
+```javascript
+import { RoundRobinPool } from 'undici'
+
+const pool = new RoundRobinPool('http://my-service.default.svc.cluster.local', {
+  connections: 10
+})
+
+// Requests will be distributed evenly across all 10 connections
+for (let i = 0; i < 100; i++) {
+  const { body } = await pool.request({
+    path: '/api/data',
+    method: 'GET'
+  })
+  console.log(await body.json())
+}
+
+await pool.close()
+```
+
+## See Also
+
+- [Pool](/docs/docs/api/Pool.md) - Connection pool without round-robin
+- [BalancedPool](/docs/docs/api/BalancedPool.md) - Load balancing across multiple origins
+- [Issue #3648](https://github.com/nodejs/undici/issues/3648) - Original issue describing uneven distribution
+

package/docs/docs/api/WebSocket.md

@@ -34,6 +34,27 @@ import { WebSocket } from 'undici'
 const ws = new WebSocket('wss://echo.websocket.events', ['echo', 'chat'])
 ```
 
+### Example with HTTP/2:
+
+> ⚠️ Warning: WebSocket over HTTP/2 is experimental, it is likely to change in the future.
+
+> 🗒️ Note: WebSocket over HTTP/2 may be enabled by default in a future version,
+> this will happen by enabling HTTP/2 connections as the default behavior of Undici's Agent as well the global dispatcher.
+> Stay tuned to the changelog for more information.
+
+This example will not work in browsers or other platforms that don't allow passing an object.
+
+```mjs
+import { Agent } from 'undici'
+
+const agent = new Agent({ allowH2: true })
+
+const ws = new WebSocket('wss://echo.websocket.events', {
+  dispatcher: agent,
+  protocols: ['echo', 'chat']
+})
+```
+
 # Class: WebSocketStream
 
 > ⚠️ Warning: the WebSocketStream API has not been finalized and is likely to change.

package/docs/docs/best-practices/crawling.md

@@ -0,0 +1,58 @@
+# Crawling
+
+[RFC 9309](https://datatracker.ietf.org/doc/html/rfc9309) defines crawlers as automated clients.
+
+Some web servers may reject requests that omit the `User-Agent` header or that use common defaults such as `'curl/7.79.1'`.
+
+In **undici**, the default user agent is `'undici'`. Since undici is integrated into Node.js core as the implementation of `fetch()`, requests made via `fetch()` use `'node'` as the default user agent.
+
+It is recommended to specify a **custom `User-Agent` header** when implementing crawlers. Providing a descriptive user agent allows servers to correctly identify the client and reduces the likelihood of requests being denied.
+
+A user agent string should include sufficient detail to identify the crawler and provide contact information. For example:
+
+```
+AcmeCo Crawler - acme.co - contact@acme.co
+```
+
+When adding contact details, avoid using personal identifiers such as your own name or a private email address—especially in a professional or employment context. Instead, use a role-based or organizational contact (e.g., crawler-team@company.com) to protect individual privacy while still enabling communication.
+
+If a crawler behaves unexpectedly—for example, due to misconfiguration or implementation errors—server administrators can use the information in the user agent to contact the operator and coordinate an appropriate resolution.
+
+The `User-Agent` header can be set on individual requests or applied globally by configuring a custom dispatcher.
+
+**Example: setting a `User-Agent` per request**
+
+```js
+import { fetch } from 'undici'
+
+const headers = {
+  'User-Agent': 'AcmeCo Crawler - acme.co - contact@acme.co'
+}
+
+const res = await fetch('https://example.com', { headers })
+```
+
+## Best Practices for Crawlers
+
+When developing a crawler, the following practices are recommended in addition to setting a descriptive `User-Agent` header:
+
+* **Respect `robots.txt`**
+  Follow the directives defined in the target site’s `robots.txt` file, including disallowed paths and optional crawl-delay settings (see [W3C guidelines](https://www.w3.org/wiki/Write_Web_Crawler)).
+
+* **Rate limiting**
+  Regulate request frequency to avoid imposing excessive load on servers. Introduce delays between requests or limit the number of concurrent requests. The W3C suggests at least one second between requests.
+
+* **Error handling**
+  Implement retry logic with exponential backoff for transient failures, and stop requests when persistent errors occur (e.g., HTTP 403 or 429).
+
+* **Monitoring and logging**
+  Track request volume, response codes, and error rates to detect misbehavior and address issues proactively.
+
+* **Contact information**
+  Always include valid and current contact details in the `User-Agent` string so that administrators can reach the crawler operator if necessary.
+
+## References and Further Reading
+
+* [RFC 9309: The Robots Exclusion Protocol](https://datatracker.ietf.org/doc/html/rfc9309)
+* [W3C Wiki: Write Web Crawler](https://www.w3.org/wiki/Write_Web_Crawler)
+* [Ethical Web Crawling (WWW 2010 Conference Paper)](https://archives.iw3c2.org/www2010/proceedings/www/p1101.pdf)

package/index.js

@@ -4,6 +4,7 @@ const Client = require('./lib/dispatcher/client')
 const Dispatcher = require('./lib/dispatcher/dispatcher')
 const Pool = require('./lib/dispatcher/pool')
 const BalancedPool = require('./lib/dispatcher/balanced-pool')
+const RoundRobinPool = require('./lib/dispatcher/round-robin-pool')
 const Agent = require('./lib/dispatcher/agent')
 const ProxyAgent = require('./lib/dispatcher/proxy-agent')
 const EnvHttpProxyAgent = require('./lib/dispatcher/env-http-proxy-agent')
@@ -31,6 +32,7 @@ module.exports.Dispatcher = Dispatcher
 module.exports.Client = Client
 module.exports.Pool = Pool
 module.exports.BalancedPool = BalancedPool
+module.exports.RoundRobinPool = RoundRobinPool
 module.exports.Agent = Agent
 module.exports.ProxyAgent = ProxyAgent
 module.exports.EnvHttpProxyAgent = EnvHttpProxyAgent
@@ -47,7 +49,8 @@ module.exports.interceptors = {
   dump: require('./lib/interceptor/dump'),
   dns: require('./lib/interceptor/dns'),
   cache: require('./lib/interceptor/cache'),
-  decompress: require('./lib/interceptor/decompress')
+  decompress: require('./lib/interceptor/decompress'),
+  deduplicate: require('./lib/interceptor/deduplicate')
 }
 
 module.exports.cacheStores = {

package/lib/api/api-upgrade.js

@@ -4,6 +4,7 @@ const { InvalidArgumentError, SocketError } = require('../core/errors')
 const { AsyncResource } = require('node:async_hooks')
 const assert = require('node:assert')
 const util = require('../core/util')
+const { kHTTP2Stream } = require('../core/symbols')
 const { addSignal, removeSignal } = require('./abort-signal')
 
 class UpgradeHandler extends AsyncResource {
@@ -50,7 +51,7 @@ class UpgradeHandler extends AsyncResource {
   }
 
   onUpgrade (statusCode, rawHeaders, socket) {
-    assert(statusCode === 101)
+    assert(socket[kHTTP2Stream] === true ? statusCode === 200 : statusCode === 101)
 
     const { callback, opaque, context } = this
 

package/lib/core/connect.js

@@ -43,7 +43,7 @@ const SessionCache = class WeakSessionCache {
   }
 }
 
-function buildConnector ({ allowH2, maxCachedSessions, socketPath, timeout, session: customSession, ...opts }) {
+function buildConnector ({ allowH2, useH2c, maxCachedSessions, socketPath, timeout, session: customSession, ...opts }) {
   if (maxCachedSessions != null && (!Number.isInteger(maxCachedSessions) || maxCachedSessions < 0)) {
     throw new InvalidArgumentError('maxCachedSessions must be a positive integer or zero')
   }
@@ -96,6 +96,9 @@ function buildConnector ({ allowH2, maxCachedSessions, socketPath, timeout, sess
         port,
         host: hostname
       })
+      if (useH2c === true) {
+        socket.alpnProtocol = 'h2'
+      }
     }
 
     // Set TCP keep alive options on the socket here instead of in connect() for the case of assigning the socket

package/lib/core/diagnostics.js

@@ -26,7 +26,9 @@ const channels = {
   close: diagnosticsChannel.channel('undici:websocket:close'),
   socketError: diagnosticsChannel.channel('undici:websocket:socket_error'),
   ping: diagnosticsChannel.channel('undici:websocket:ping'),
-  pong: diagnosticsChannel.channel('undici:websocket:pong')
+  pong: diagnosticsChannel.channel('undici:websocket:pong'),
+  // ProxyAgent
+  proxyConnected: diagnosticsChannel.channel('undici:proxy:connected')
 }
 
 let isTrackingClientEvents = false
@@ -36,6 +38,14 @@ function trackClientEvents (debugLog = undiciDebugLog) {
     return
   }
 
+  // Check if any of the channels already have subscribers to prevent duplicate subscriptions
+  // This can happen when both Node.js built-in undici and undici as a dependency are present
+  if (channels.beforeConnect.hasSubscribers || channels.connected.hasSubscribers ||
+      channels.connectError.hasSubscribers || channels.sendHeaders.hasSubscribers) {
+    isTrackingClientEvents = true
+    return
+  }
+
   isTrackingClientEvents = true
 
   diagnosticsChannel.subscribe('undici:client:beforeConnect',
@@ -98,6 +108,14 @@ function trackRequestEvents (debugLog = undiciDebugLog) {
     return
   }
 
+  // Check if any of the channels already have subscribers to prevent duplicate subscriptions
+  // This can happen when both Node.js built-in undici and undici as a dependency are present
+  if (channels.headers.hasSubscribers || channels.trailers.hasSubscribers ||
+      channels.error.hasSubscribers) {
+    isTrackingRequestEvents = true
+    return
+  }
+
   isTrackingRequestEvents = true
 
   diagnosticsChannel.subscribe('undici:request:headers',
@@ -146,6 +164,15 @@ function trackWebSocketEvents (debugLog = websocketDebuglog) {
     return
   }
 
+  // Check if any of the channels already have subscribers to prevent duplicate subscriptions
+  // This can happen when both Node.js built-in undici and undici as a dependency are present
+  if (channels.open.hasSubscribers || channels.close.hasSubscribers ||
+      channels.socketError.hasSubscribers || channels.ping.hasSubscribers ||
+      channels.pong.hasSubscribers) {
+    isTrackingWebSocketEvents = true
+    return
+  }
+
   isTrackingWebSocketEvents = true
 
   diagnosticsChannel.subscribe('undici:websocket:open',

package/lib/core/symbols.js

@@ -62,6 +62,9 @@ module.exports = {
   kListeners: Symbol('listeners'),
   kHTTPContext: Symbol('http context'),
   kMaxConcurrentStreams: Symbol('max concurrent streams'),
+  kEnableConnectProtocol: Symbol('http2session connect protocol'),
+  kRemoteSettings: Symbol('http2session remote settings'),
+  kHTTP2Stream: Symbol('http2session client stream'),
   kNoProxyAgent: Symbol('no proxy agent'),
   kHttpProxyAgent: Symbol('http proxy agent'),
   kHttpsProxyAgent: Symbol('https proxy agent')