undici 7.4.0 → 7.5.0

package/docs/docs/api/MockAgent.md

@@ -179,7 +179,9 @@ for await (const data of result2.body) {
   console.log('data', data.toString('utf8')) // data hello
 }
 ```
+
 #### Example - Mock different requests within the same file
+
 ```js
 const { MockAgent, setGlobalDispatcher } = require('undici');
 const agent = new MockAgent();
@@ -540,3 +542,60 @@ agent.assertNoPendingInterceptors()
 // │    0    │ 'GET'  │ 'https://example.com' │ '/'  │     200     │    '❌'    │      0      │     1     │
 // └─────────┴────────┴───────────────────────┴──────┴─────────────┴────────────┴─────────────┴───────────┘
 ```
+
+#### Example - access call history on MockAgent
+
+You can register every call made within a MockAgent to be able to retrieve the body, headers and so on.
+
+This is not enabled by default.
+
+```js
+import { MockAgent, setGlobalDispatcher, request } from 'undici'
+
+const mockAgent = new MockAgent({ enableCallHistory: true })
+setGlobalDispatcher(mockAgent)
+
+await request('http://example.com', { query: { item: 1 }})
+
+mockAgent.getCallHistory()?.firstCall()
+// Returns
+// MockCallHistoryLog {
+//   body: undefined,
+//   headers: undefined,
+//   method: 'GET',
+//   origin: 'http://example.com',
+//   fullUrl: 'http://example.com/?item=1',
+//   path: '/',
+//   searchParams: { item: '1' },
+//   protocol: 'http:',
+//   host: 'example.com',
+//   port: ''
+// }
+```
+
+#### Example - clear call history
+
+```js
+const mockAgent = new MockAgent()
+
+mockAgent.clearAllCallHistory()
+```
+
+#### Example - call history instance class method
+
+```js
+const mockAgent = new MockAgent()
+
+const mockAgentHistory = mockAgent.getCallHistory()
+
+mockAgentHistory?.calls() // returns an array of MockCallHistoryLogs
+mockAgentHistory?.firstCall() // returns the first MockCallHistoryLogs or undefined
+mockAgentHistory?.lastCall() // returns the last MockCallHistoryLogs or undefined
+mockAgentHistory?.nthCall(3) // returns the third MockCallHistoryLogs or undefined
+mockAgentHistory?.filterCalls({ path: '/endpoint', hash: '#hash-value' }) // returns an Array of MockCallHistoryLogs WHERE path === /endpoint OR hash === #hash-value
+mockAgentHistory?.filterCalls({ path: '/endpoint', hash: '#hash-value' }, { operator: 'AND' }) // returns an Array of MockCallHistoryLogs WHERE path === /endpoint AND hash === #hash-value
+mockAgentHistory?.filterCalls(/"data": "{}"/) // returns an Array of MockCallHistoryLogs where any value match regexp
+mockAgentHistory?.filterCalls('application/json') // returns an Array of MockCallHistoryLogs where any value === 'application/json'
+mockAgentHistory?.filterCalls((log) => log.path === '/endpoint') // returns an Array of MockCallHistoryLogs when given function returns true
+mockAgentHistory?.clear() // clear the history
+```

package/docs/docs/api/MockCallHistory.md

@@ -0,0 +1,197 @@
+# Class: MockCallHistory
+
+Access to an instance with :
+
+```js
+const mockAgent = new MockAgent({ enableCallHistory: true })
+mockAgent.getCallHistory()
+
+// or
+const mockAgent = new MockAgent()
+mockAgent.enableMockHistory()
+mockAgent.getCallHistory()
+
+```
+
+a MockCallHistory instance implements a **Symbol.iterator** letting you iterate on registered logs :
+
+```ts
+for (const log of mockAgent.getCallHistory()) {
+  //...
+}
+
+const array: Array<MockCallHistoryLog> = [...mockAgent.getCallHistory()]
+const set: Set<MockCallHistoryLog> = new Set(mockAgent.getCallHistory())
+```
+
+## class methods
+
+### clear
+
+Clear all MockCallHistoryLog registered. This is automatically done when calling `mockAgent.close()`
+
+```js
+mockAgent.clearCallHistory()
+// same as
+mockAgent.getCallHistory()?.clear()
+```
+
+### calls
+
+Get all MockCallHistoryLog registered as an array
+
+```js
+mockAgent.getCallHistory()?.calls()
+```
+
+### firstCall
+
+Get the first MockCallHistoryLog registered or undefined
+
+```js
+mockAgent.getCallHistory()?.firstCall()
+```
+
+### lastCall
+
+Get the last MockCallHistoryLog registered or undefined
+
+```js
+mockAgent.getCallHistory()?.lastCall()
+```
+
+### nthCall
+
+Get the nth MockCallHistoryLog registered or undefined
+
+```js
+mockAgent.getCallHistory()?.nthCall(3) // the third MockCallHistoryLog registered
+```
+
+### filterCallsByProtocol
+
+Filter MockCallHistoryLog by protocol.
+
+> more details for the first parameter can be found [here](/docs/docs/api/MockCallHistory.md#filter-parameter)
+
+```js
+mockAgent.getCallHistory()?.filterCallsByProtocol(/https/)
+mockAgent.getCallHistory()?.filterCallsByProtocol('https:')
+```
+
+### filterCallsByHost
+
+Filter MockCallHistoryLog by host.
+
+> more details for the first parameter can be found [here](/docs/docs/api/MockCallHistory.md#filter-parameter)
+
+```js
+mockAgent.getCallHistory()?.filterCallsByHost(/localhost/)
+mockAgent.getCallHistory()?.filterCallsByHost('localhost:3000')
+```
+
+### filterCallsByPort
+
+Filter MockCallHistoryLog by port.
+
+> more details for the first parameter can be found [here](/docs/docs/api/MockCallHistory.md#filter-parameter)
+
+```js
+mockAgent.getCallHistory()?.filterCallsByPort(/3000/)
+mockAgent.getCallHistory()?.filterCallsByPort('3000')
+mockAgent.getCallHistory()?.filterCallsByPort('')
+```
+
+### filterCallsByOrigin
+
+Filter MockCallHistoryLog by origin.
+
+> more details for the first parameter can be found [here](/docs/docs/api/MockCallHistory.md#filter-parameter)
+
+```js
+mockAgent.getCallHistory()?.filterCallsByOrigin(/http:\/\/localhost:3000/)
+mockAgent.getCallHistory()?.filterCallsByOrigin('http://localhost:3000')
+```
+
+### filterCallsByPath
+
+Filter MockCallHistoryLog by path.
+
+> more details for the first parameter can be found [here](/docs/docs/api/MockCallHistory.md#filter-parameter)
+
+```js
+mockAgent.getCallHistory()?.filterCallsByPath(/api\/v1\/graphql/)
+mockAgent.getCallHistory()?.filterCallsByPath('/api/v1/graphql')
+```
+
+### filterCallsByHash
+
+Filter MockCallHistoryLog by hash.
+
+> more details for the first parameter can be found [here](/docs/docs/api/MockCallHistory.md#filter-parameter)
+
+```js
+mockAgent.getCallHistory()?.filterCallsByPath(/hash/)
+mockAgent.getCallHistory()?.filterCallsByPath('#hash')
+```
+
+### filterCallsByFullUrl
+
+Filter MockCallHistoryLog by fullUrl. fullUrl contains protocol, host, port, path, hash, and query params
+
+> more details for the first parameter can be found [here](/docs/docs/api/MockCallHistory.md#filter-parameter)
+
+```js
+mockAgent.getCallHistory()?.filterCallsByFullUrl(/https:\/\/localhost:3000\/\?query=value#hash/)
+mockAgent.getCallHistory()?.filterCallsByFullUrl('https://localhost:3000/?query=value#hash')
+```
+
+### filterCallsByMethod
+
+Filter MockCallHistoryLog by method.
+
+> more details for the first parameter can be found [here](/docs/docs/api/MockCallHistory.md#filter-parameter)
+
+```js
+mockAgent.getCallHistory()?.filterCallsByMethod(/POST/)
+mockAgent.getCallHistory()?.filterCallsByMethod('POST')
+```
+
+### filterCalls
+
+This class method is a meta function / alias to apply complex filtering in a single way.
+
+Parameters :
+
+- criteria : the first parameter. a function, regexp or object.
+  - function : filter MockCallHistoryLog when the function returns false
+  - regexp : filter MockCallHistoryLog when the regexp does not match on MockCallHistoryLog.toString() ([see](./MockCallHistoryLog.md#to-string))
+  - object : an object with MockCallHistoryLog properties as keys to apply multiple filters. each values are a [filter parameter](/docs/docs/api/MockCallHistory.md#filter-parameter)
+- options : the second parameter. an object.
+  - options.operator : `'AND'` or `'OR'` (default `'OR'`). Used only if criteria is an object. see below
+
+```js
+mockAgent.getCallHistory()?.filterCalls((log) => log.hash === value && log.headers?.['authorization'] !== undefined)
+mockAgent.getCallHistory()?.filterCalls(/"data": "{ "errors": "wrong body" }"/)
+
+// returns an Array of MockCallHistoryLog which all have
+// - a hash containing my-hash
+// - OR
+// - a path equal to /endpoint
+mockAgent.getCallHistory()?.filterCalls({ hash: /my-hash/, path: '/endpoint' })
+
+// returns an Array of MockCallHistoryLog which all have
+// - a hash containing my-hash
+// - AND
+// - a path equal to /endpoint
+mockAgent.getCallHistory()?.filterCalls({ hash: /my-hash/, path: '/endpoint' }, { operator: 'AND' })
+```
+
+## filter parameter
+
+Can be :
+
+- string. MockCallHistoryLog filtered if `value !== parameterValue`
+- null. MockCallHistoryLog filtered if `value !== parameterValue`
+- undefined. MockCallHistoryLog filtered if `value !== parameterValue`
+- regexp. MockCallHistoryLog filtered if `!parameterValue.test(value)`

package/docs/docs/api/MockCallHistoryLog.md

@@ -0,0 +1,43 @@
+# Class: MockCallHistoryLog
+
+Access to an instance with :
+
+```js
+const mockAgent = new MockAgent({ enableCallHistory: true })
+mockAgent.getCallHistory()?.firstCall()
+```
+
+## class properties
+
+- body `mockAgent.getCallHistory()?.firstCall()?.body`
+- headers `mockAgent.getCallHistory()?.firstCall()?.headers` an object
+- method `mockAgent.getCallHistory()?.firstCall()?.method` a string
+- fullUrl `mockAgent.getCallHistory()?.firstCall()?.fullUrl` a string containing the protocol, origin, path, query and hash
+- origin `mockAgent.getCallHistory()?.firstCall()?.origin` a string containing the protocol and the host
+- headers `mockAgent.getCallHistory()?.firstCall()?.headers` an object
+- path `mockAgent.getCallHistory()?.firstCall()?.path` a string always starting with `/`
+- searchParams `mockAgent.getCallHistory()?.firstCall()?.searchParams` an object
+- protocol `mockAgent.getCallHistory()?.firstCall()?.protocol` a string (`https:`)
+- host `mockAgent.getCallHistory()?.firstCall()?.host` a string
+- port `mockAgent.getCallHistory()?.firstCall()?.port` an empty string or a string containing numbers
+- hash `mockAgent.getCallHistory()?.firstCall()?.hash` an empty string or a string starting with `#`
+
+## class methods
+
+### toMap
+
+Returns a Map instance
+
+```js
+mockAgent.getCallHistory()?.firstCall()?.toMap()?.get('hash')
+// #hash
+```
+
+### toString
+
+Returns a string computed with any class property name and value pair
+
+```js
+mockAgent.getCallHistory()?.firstCall()?.toString()
+// protocol->https:|host->localhost:4000|port->4000|origin->https://localhost:4000|path->/endpoint|hash->#here|searchParams->{"query":"value"}|fullUrl->https://localhost:4000/endpoint?query=value#here|method->PUT|body->"{ "data": "hello" }"|headers->{"content-type":"application/json"}
+```

package/docs/docs/best-practices/mocking-request.md

@@ -29,7 +29,7 @@ And this is what the test file looks like:
 
 ```js
 // index.test.mjs
-import { strict as assert } from 'assert'
+import { strict as assert } from 'node:assert'
 import { MockAgent, setGlobalDispatcher, } from 'undici'
 import { bankTransfer } from './bank.mjs'
 
@@ -75,6 +75,60 @@ assert.deepEqual(badRequest, { message: 'bank account not found' })
 
 Explore other MockAgent functionality [here](/docs/docs/api/MockAgent.md)
 
+## Access agent call history
+
+Using a MockAgent also allows you to make assertions on the configuration used to make your request in your application.
+
+Here is an example :
+
+```js
+// index.test.mjs
+import { strict as assert } from 'node:assert'
+import { MockAgent, setGlobalDispatcher, fetch } from 'undici'
+import { app } from './app.mjs'
+
+// given an application server running on http://localhost:3000
+await app.start()
+
+// enable call history at instantiation
+const mockAgent = new MockAgent({ enableCallHistory: true })
+// or after instantiation
+mockAgent.enableCallHistory()
+
+setGlobalDispatcher(mockAgent)
+
+// this call is made (not intercepted)
+await fetch(`http://localhost:3000/endpoint?query='hello'`, {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' }
+  body: JSON.stringify({ data: '' })
+})
+
+// access to the call history of the MockAgent (which register every call made intercepted or not)
+assert.ok(mockAgent.getCallHistory()?.calls().length === 1)
+assert.strictEqual(mockAgent.getCallHistory()?.firstCall()?.fullUrl, `http://localhost:3000/endpoint?query='hello'`)
+assert.strictEqual(mockAgent.getCallHistory()?.firstCall()?.body, JSON.stringify({ data: '' }))
+assert.deepStrictEqual(mockAgent.getCallHistory()?.firstCall()?.searchParams, { query: 'hello' })
+assert.strictEqual(mockAgent.getCallHistory()?.firstCall()?.port, '3000')
+assert.strictEqual(mockAgent.getCallHistory()?.firstCall()?.host, 'localhost:3000')
+assert.strictEqual(mockAgent.getCallHistory()?.firstCall()?.method, 'POST')
+assert.strictEqual(mockAgent.getCallHistory()?.firstCall()?.path, '/endpoint')
+assert.deepStrictEqual(mockAgent.getCallHistory()?.firstCall()?.headers, { 'content-type': 'application/json' })
+
+// clear all call history logs
+mockAgent.clearCallHistory()
+
+assert.ok(mockAgent.getCallHistory()?.calls().length === 0)
+```
+
+Calling `mockAgent.close()` will automatically clear and delete every call history for you.
+
+Explore other MockAgent functionality [here](/docs/docs/api/MockAgent.md)
+
+Explore other MockCallHistory functionality [here](/docs/docs/api/MockCallHistory.md)
+
+Explore other MockCallHistoryLog functionality [here](/docs/docs/api/MockCallHistoryLog.md)
+
 ## Debug Mock Value
 
 When the interceptor and the request options are not the same, undici will automatically make a real HTTP request. To prevent real requests from being made, use `mockAgent.disableNetConnect()`:

package/index.js

@@ -14,6 +14,7 @@ const { InvalidArgumentError } = errors
 const api = require('./lib/api')
 const buildConnector = require('./lib/core/connect')
 const MockClient = require('./lib/mock/mock-client')
+const { MockCallHistory, MockCallHistoryLog } = require('./lib/mock/mock-call-history')
 const MockAgent = require('./lib/mock/mock-agent')
 const MockPool = require('./lib/mock/mock-pool')
 const mockErrors = require('./lib/mock/mock-errors')
@@ -169,6 +170,8 @@ module.exports.connect = makeDispatcher(api.connect)
 module.exports.upgrade = makeDispatcher(api.upgrade)
 
 module.exports.MockClient = MockClient
+module.exports.MockCallHistory = MockCallHistory
+module.exports.MockCallHistoryLog = MockCallHistoryLog
 module.exports.MockPool = MockPool
 module.exports.MockAgent = MockAgent
 module.exports.mockErrors = mockErrors

package/lib/dispatcher/client.js

@@ -207,7 +207,7 @@ class Client extends DispatcherBase {
         allowH2,
         socketPath,
         timeout: connectTimeout,
-        ...(autoSelectFamily ? { autoSelectFamily, autoSelectFamilyAttemptTimeout } : undefined),
+        ...(typeof autoSelectFamily === 'boolean' ? { autoSelectFamily, autoSelectFamilyAttemptTimeout } : undefined),
         ...connect
       })
     }

package/lib/dispatcher/pool.js

@@ -58,7 +58,7 @@ class Pool extends PoolBase {
         allowH2,
         socketPath,
         timeout: connectTimeout,
-        ...(autoSelectFamily ? { autoSelectFamily, autoSelectFamilyAttemptTimeout } : undefined),
+        ...(typeof autoSelectFamily === 'boolean' ? { autoSelectFamily, autoSelectFamilyAttemptTimeout } : undefined),
         ...connect
       })
     }
@@ -70,6 +70,20 @@ class Pool extends PoolBase {
       ? { ...options.interceptors }
       : undefined
     this[kFactory] = factory
+
+    this.on('connectionError', (origin, targets, error) => {
+      // If a connection error occurs, we remove the client from the pool,
+      // and emit a connectionError event. They will not be re-used.
+      // Fixes https://github.com/nodejs/undici/issues/3895
+      for (const target of targets) {
+        // Do not use kRemoveClient here, as it will close the client,
+        // but the client cannot be closed in this state.
+        const idx = this[kClients].indexOf(target)
+        if (idx !== -1) {
+          this[kClients].splice(idx, 1)
+        }
+      }
+    })
   }
 
   [kGetDispatcher] () {

package/lib/handler/retry-handler.js

@@ -11,8 +11,8 @@ const {
 } = require('../core/util')
 
 function calculateRetryAfterHeader (retryAfter) {
-  const current = Date.now()
-  return new Date(retryAfter).getTime() - current
+  const retryTime = new Date(retryAfter).getTime()
+  return isNaN(retryTime) ? 0 : retryTime - Date.now()
 }
 
 class RetryHandler {
@@ -124,7 +124,7 @@ class RetryHandler {
     if (retryAfterHeader) {
       retryAfterHeader = Number(retryAfterHeader)
       retryAfterHeader = Number.isNaN(retryAfterHeader)
-        ? calculateRetryAfterHeader(retryAfterHeader)
+        ? calculateRetryAfterHeader(headers['retry-after'])
         : retryAfterHeader * 1e3 // Retry-After is in seconds
     }
 

package/lib/mock/mock-agent.js

@@ -11,31 +11,44 @@ const {
   kNetConnect,
   kGetNetConnect,
   kOptions,
-  kFactory
+  kFactory,
+  kMockAgentRegisterCallHistory,
+  kMockAgentIsCallHistoryEnabled,
+  kMockAgentAddCallHistoryLog,
+  kMockAgentMockCallHistoryInstance,
+  kMockCallHistoryAddLog
 } = require('./mock-symbols')
 const MockClient = require('./mock-client')
 const MockPool = require('./mock-pool')
-const { matchValue, buildMockOptions } = require('./mock-utils')
+const { matchValue, buildAndValidateMockOptions } = require('./mock-utils')
 const { InvalidArgumentError, UndiciError } = require('../core/errors')
 const Dispatcher = require('../dispatcher/dispatcher')
 const PendingInterceptorsFormatter = require('./pending-interceptors-formatter')
+const { MockCallHistory } = require('./mock-call-history')
 
 class MockAgent extends Dispatcher {
   constructor (opts) {
     super(opts)
 
+    const mockOptions = buildAndValidateMockOptions(opts)
+
     this[kNetConnect] = true
     this[kIsMockActive] = true
+    this[kMockAgentIsCallHistoryEnabled] = mockOptions?.enableCallHistory ?? false
 
     // Instantiate Agent and encapsulate
-    if ((opts?.agent && typeof opts.agent.dispatch !== 'function')) {
+    if (opts?.agent && typeof opts.agent.dispatch !== 'function') {
       throw new InvalidArgumentError('Argument opts.agent must implement Agent')
     }
     const agent = opts?.agent ? opts.agent : new Agent(opts)
     this[kAgent] = agent
 
     this[kClients] = agent[kClients]
-    this[kOptions] = buildMockOptions(opts)
+    this[kOptions] = mockOptions
+
+    if (this[kMockAgentIsCallHistoryEnabled]) {
+      this[kMockAgentRegisterCallHistory]()
+    }
   }
 
   get (origin) {
@@ -51,10 +64,14 @@ class MockAgent extends Dispatcher {
   dispatch (opts, handler) {
     // Call MockAgent.get to perform additional setup before dispatching as normal
     this.get(opts.origin)
+
+    this[kMockAgentAddCallHistoryLog](opts)
+
     return this[kAgent].dispatch(opts, handler)
   }
 
   async close () {
+    this.clearCallHistory()
     await this[kAgent].close()
     this[kClients].clear()
   }
@@ -85,12 +102,50 @@ class MockAgent extends Dispatcher {
     this[kNetConnect] = false
   }
 
+  enableCallHistory () {
+    this[kMockAgentIsCallHistoryEnabled] = true
+
+    return this
+  }
+
+  disableCallHistory () {
+    this[kMockAgentIsCallHistoryEnabled] = false
+
+    return this
+  }
+
+  getCallHistory () {
+    return this[kMockAgentMockCallHistoryInstance]
+  }
+
+  clearCallHistory () {
+    if (this[kMockAgentMockCallHistoryInstance] !== undefined) {
+      this[kMockAgentMockCallHistoryInstance].clear()
+    }
+  }
+
   // This is required to bypass issues caused by using global symbols - see:
   // https://github.com/nodejs/undici/issues/1447
   get isMockActive () {
     return this[kIsMockActive]
   }
 
+  [kMockAgentRegisterCallHistory] () {
+    if (this[kMockAgentMockCallHistoryInstance] === undefined) {
+      this[kMockAgentMockCallHistoryInstance] = new MockCallHistory()
+    }
+  }
+
+  [kMockAgentAddCallHistoryLog] (opts) {
+    if (this[kMockAgentIsCallHistoryEnabled]) {
+      // additional setup when enableCallHistory class method is used after mockAgent instantiation
+      this[kMockAgentRegisterCallHistory]()
+
+      // add call history log on every call (intercepted or not)
+      this[kMockAgentMockCallHistoryInstance][kMockCallHistoryAddLog](opts)
+    }
+  }
+
   [kMockAgentSet] (origin, dispatcher) {
     this[kClients].set(origin, dispatcher)
   }

package/lib/mock/mock-call-history.js

@@ -0,0 +1,248 @@
+'use strict'
+
+const { kMockCallHistoryAddLog } = require('./mock-symbols')
+const { InvalidArgumentError } = require('../core/errors')
+
+function handleFilterCallsWithOptions (criteria, options, handler, store) {
+  switch (options.operator) {
+    case 'OR':
+      store.push(...handler(criteria))
+
+      return store
+    case 'AND':
+      return handler.call({ logs: store }, criteria)
+    default:
+      // guard -- should never happens because buildAndValidateFilterCallsOptions is called before
+      throw new InvalidArgumentError('options.operator must to be a case insensitive string equal to \'OR\' or \'AND\'')
+  }
+}
+
+function buildAndValidateFilterCallsOptions (options = {}) {
+  const finalOptions = {}
+
+  if ('operator' in options) {
+    if (typeof options.operator !== 'string' || (options.operator.toUpperCase() !== 'OR' && options.operator.toUpperCase() !== 'AND')) {
+      throw new InvalidArgumentError('options.operator must to be a case insensitive string equal to \'OR\' or \'AND\'')
+    }
+
+    return {
+      ...finalOptions,
+      operator: options.operator.toUpperCase()
+    }
+  }
+
+  return finalOptions
+}
+
+function makeFilterCalls (parameterName) {
+  return (parameterValue) => {
+    if (typeof parameterValue === 'string' || parameterValue == null) {
+      return this.logs.filter((log) => {
+        return log[parameterName] === parameterValue
+      })
+    }
+    if (parameterValue instanceof RegExp) {
+      return this.logs.filter((log) => {
+        return parameterValue.test(log[parameterName])
+      })
+    }
+
+    throw new InvalidArgumentError(`${parameterName} parameter should be one of string, regexp, undefined or null`)
+  }
+}
+function computeUrlWithMaybeSearchParameters (requestInit) {
+  // path can contains query url parameters
+  // or query can contains query url parameters
+  try {
+    const url = new URL(requestInit.path, requestInit.origin)
+
+    // requestInit.path contains query url parameters
+    // requestInit.query is then undefined
+    if (url.search.length !== 0) {
+      return url
+    }
+
+    // requestInit.query can be populated here
+    url.search = new URLSearchParams(requestInit.query).toString()
+
+    return url
+  } catch (error) {
+    throw new InvalidArgumentError('An error occurred when computing MockCallHistoryLog.url', { cause: error })
+  }
+}
+
+class MockCallHistoryLog {
+  constructor (requestInit = {}) {
+    this.body = requestInit.body
+    this.headers = requestInit.headers
+    this.method = requestInit.method
+
+    const url = computeUrlWithMaybeSearchParameters(requestInit)
+
+    this.fullUrl = url.toString()
+    this.origin = url.origin
+    this.path = url.pathname
+    this.searchParams = Object.fromEntries(url.searchParams)
+    this.protocol = url.protocol
+    this.host = url.host
+    this.port = url.port
+    this.hash = url.hash
+  }
+
+  toMap () {
+    return new Map([
+      ['protocol', this.protocol],
+      ['host', this.host],
+      ['port', this.port],
+      ['origin', this.origin],
+      ['path', this.path],
+      ['hash', this.hash],
+      ['searchParams', this.searchParams],
+      ['fullUrl', this.fullUrl],
+      ['method', this.method],
+      ['body', this.body],
+      ['headers', this.headers]]
+    )
+  }
+
+  toString () {
+    const options = { betweenKeyValueSeparator: '->', betweenPairSeparator: '|' }
+    let result = ''
+
+    this.toMap().forEach((value, key) => {
+      if (typeof value === 'string' || value === undefined || value === null) {
+        result = `${result}${key}${options.betweenKeyValueSeparator}${value}${options.betweenPairSeparator}`
+      }
+      if ((typeof value === 'object' && value !== null) || Array.isArray(value)) {
+        result = `${result}${key}${options.betweenKeyValueSeparator}${JSON.stringify(value)}${options.betweenPairSeparator}`
+      }
+      // maybe miss something for non Record / Array headers and searchParams here
+    })
+
+    // delete last betweenPairSeparator
+    return result.slice(0, -1)
+  }
+}
+
+class MockCallHistory {
+  logs = []
+
+  calls () {
+    return this.logs
+  }
+
+  firstCall () {
+    return this.logs.at(0)
+  }
+
+  lastCall () {
+    return this.logs.at(-1)
+  }
+
+  nthCall (number) {
+    if (typeof number !== 'number') {
+      throw new InvalidArgumentError('nthCall must be called with a number')
+    }
+    if (!Number.isInteger(number)) {
+      throw new InvalidArgumentError('nthCall must be called with an integer')
+    }
+    if (Math.sign(number) !== 1) {
+      throw new InvalidArgumentError('nthCall must be called with a positive value. use firstCall or lastCall instead')
+    }
+
+    // non zero based index. this is more human readable
+    return this.logs.at(number - 1)
+  }
+
+  filterCalls (criteria, options) {
+    // perf
+    if (this.logs.length === 0) {
+      return this.logs
+    }
+    if (typeof criteria === 'function') {
+      return this.logs.filter(criteria)
+    }
+    if (criteria instanceof RegExp) {
+      return this.logs.filter((log) => {
+        return criteria.test(log.toString())
+      })
+    }
+    if (typeof criteria === 'object' && criteria !== null) {
+      // no criteria - returning all logs
+      if (Object.keys(criteria).length === 0) {
+        return this.logs
+      }
+
+      const finalOptions = { operator: 'OR', ...buildAndValidateFilterCallsOptions(options) }
+
+      let maybeDuplicatedLogsFiltered = []
+      if ('protocol' in criteria) {
+        maybeDuplicatedLogsFiltered = handleFilterCallsWithOptions(criteria.protocol, finalOptions, this.filterCallsByProtocol, maybeDuplicatedLogsFiltered)
+      }
+      if ('host' in criteria) {
+        maybeDuplicatedLogsFiltered = handleFilterCallsWithOptions(criteria.host, finalOptions, this.filterCallsByHost, maybeDuplicatedLogsFiltered)
+      }
+      if ('port' in criteria) {
+        maybeDuplicatedLogsFiltered = handleFilterCallsWithOptions(criteria.port, finalOptions, this.filterCallsByPort, maybeDuplicatedLogsFiltered)
+      }
+      if ('origin' in criteria) {
+        maybeDuplicatedLogsFiltered = handleFilterCallsWithOptions(criteria.origin, finalOptions, this.filterCallsByOrigin, maybeDuplicatedLogsFiltered)
+      }
+      if ('path' in criteria) {
+        maybeDuplicatedLogsFiltered = handleFilterCallsWithOptions(criteria.path, finalOptions, this.filterCallsByPath, maybeDuplicatedLogsFiltered)
+      }
+      if ('hash' in criteria) {
+        maybeDuplicatedLogsFiltered = handleFilterCallsWithOptions(criteria.hash, finalOptions, this.filterCallsByHash, maybeDuplicatedLogsFiltered)
+      }
+      if ('fullUrl' in criteria) {
+        maybeDuplicatedLogsFiltered = handleFilterCallsWithOptions(criteria.fullUrl, finalOptions, this.filterCallsByFullUrl, maybeDuplicatedLogsFiltered)
+      }
+      if ('method' in criteria) {
+        maybeDuplicatedLogsFiltered = handleFilterCallsWithOptions(criteria.method, finalOptions, this.filterCallsByMethod, maybeDuplicatedLogsFiltered)
+      }
+
+      const uniqLogsFiltered = [...new Set(maybeDuplicatedLogsFiltered)]
+
+      return uniqLogsFiltered
+    }
+
+    throw new InvalidArgumentError('criteria parameter should be one of function, regexp, or object')
+  }
+
+  filterCallsByProtocol = makeFilterCalls.call(this, 'protocol')
+
+  filterCallsByHost = makeFilterCalls.call(this, 'host')
+
+  filterCallsByPort = makeFilterCalls.call(this, 'port')
+
+  filterCallsByOrigin = makeFilterCalls.call(this, 'origin')
+
+  filterCallsByPath = makeFilterCalls.call(this, 'path')
+
+  filterCallsByHash = makeFilterCalls.call(this, 'hash')
+
+  filterCallsByFullUrl = makeFilterCalls.call(this, 'fullUrl')
+
+  filterCallsByMethod = makeFilterCalls.call(this, 'method')
+
+  clear () {
+    this.logs = []
+  }
+
+  [kMockCallHistoryAddLog] (requestInit) {
+    const log = new MockCallHistoryLog(requestInit)
+
+    this.logs.push(log)
+
+    return log
+  }
+
+  * [Symbol.iterator] () {
+    for (const log of this.calls()) {
+      yield log
+    }
+  }
+}
+
+module.exports.MockCallHistory = MockCallHistory
+module.exports.MockCallHistoryLog = MockCallHistoryLog

package/lib/mock/mock-symbols.js

@@ -21,5 +21,10 @@ module.exports = {
   kNetConnect: Symbol('net connect'),
   kGetNetConnect: Symbol('get net connect'),
   kConnected: Symbol('connected'),
-  kIgnoreTrailingSlash: Symbol('ignore trailing slash')
+  kIgnoreTrailingSlash: Symbol('ignore trailing slash'),
+  kMockAgentMockCallHistoryInstance: Symbol('mock agent mock call history name'),
+  kMockAgentRegisterCallHistory: Symbol('mock agent register mock call history'),
+  kMockAgentAddCallHistoryLog: Symbol('mock agent add call history log'),
+  kMockAgentIsCallHistoryEnabled: Symbol('mock agent is call history enabled'),
+  kMockCallHistoryAddLog: Symbol('mock call history add log')
 }

package/lib/mock/mock-utils.js

@@ -15,6 +15,7 @@ const {
     isPromise
   }
 } = require('node:util')
+const { InvalidArgumentError } = require('../core/errors')
 
 function matchValue (match, value) {
   if (typeof match === 'string') {
@@ -367,9 +368,14 @@ function checkNetConnect (netConnect, origin) {
   return false
 }
 
-function buildMockOptions (opts) {
+function buildAndValidateMockOptions (opts) {
   if (opts) {
     const { agent, ...mockOptions } = opts
+
+    if ('enableCallHistory' in mockOptions && typeof mockOptions.enableCallHistory !== 'boolean') {
+      throw new InvalidArgumentError('options.enableCallHistory must to be a boolean')
+    }
+
     return mockOptions
   }
 }
@@ -387,7 +393,7 @@ module.exports = {
   mockDispatch,
   buildMockDispatch,
   checkNetConnect,
-  buildMockOptions,
+  buildAndValidateMockOptions,
   getHeaderByName,
   buildHeadersFromArray
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "undici",
-  "version": "7.4.0",
+  "version": "7.5.0",
   "description": "An HTTP/1.1 client, written from scratch for Node.js",
   "homepage": "https://undici.nodejs.org",
   "bugs": {

package/types/client.d.ts

@@ -70,7 +70,7 @@ export declare namespace Client {
     /** TODO */
     maxRedirections?: number;
     /** TODO */
-    connect?: buildConnector.BuildOptions | buildConnector.connector;
+    connect?: Partial<buildConnector.BuildOptions> | buildConnector.connector;
     /** TODO */
     maxRequestsPerClient?: number;
     /** TODO */

package/types/index.d.ts

@@ -12,6 +12,7 @@ import Agent from './agent'
 import MockClient from './mock-client'
 import MockPool from './mock-pool'
 import MockAgent from './mock-agent'
+import { MockCallHistory, MockCallHistoryLog } from './mock-call-history'
 import mockErrors from './mock-errors'
 import ProxyAgent from './proxy-agent'
 import EnvHttpProxyAgent from './env-http-proxy-agent'
@@ -31,7 +32,7 @@ export * from './content-type'
 export * from './cache'
 export { Interceptable } from './mock-interceptor'
 
-export { Dispatcher, BalancedPool, Pool, Client, buildConnector, errors, Agent, request, stream, pipeline, connect, upgrade, setGlobalDispatcher, getGlobalDispatcher, setGlobalOrigin, getGlobalOrigin, interceptors, MockClient, MockPool, MockAgent, mockErrors, ProxyAgent, EnvHttpProxyAgent, RedirectHandler, DecoratorHandler, RetryHandler, RetryAgent }
+export { Dispatcher, BalancedPool, Pool, Client, buildConnector, errors, Agent, request, stream, pipeline, connect, upgrade, setGlobalDispatcher, getGlobalDispatcher, setGlobalOrigin, getGlobalOrigin, interceptors, MockClient, MockPool, MockAgent, MockCallHistory, MockCallHistoryLog, mockErrors, ProxyAgent, EnvHttpProxyAgent, RedirectHandler, DecoratorHandler, RetryHandler, RetryAgent }
 export default Undici
 
 declare namespace Undici {
@@ -55,6 +56,8 @@ declare namespace Undici {
   const MockClient: typeof import('./mock-client').default
   const MockPool: typeof import('./mock-pool').default
   const MockAgent: typeof import('./mock-agent').default
+  const MockCallHistory: typeof import('./mock-call-history').MockCallHistory
+  const MockCallHistoryLog: typeof import('./mock-call-history').MockCallHistoryLog
   const mockErrors: typeof import('./mock-errors').default
   const fetch: typeof import('./fetch').fetch
   const Headers: typeof import('./fetch').Headers

package/types/mock-agent.d.ts

@@ -2,6 +2,7 @@ import Agent from './agent'
 import Dispatcher from './dispatcher'
 import { Interceptable, MockInterceptor } from './mock-interceptor'
 import MockDispatch = MockInterceptor.MockDispatch
+import { MockCallHistory } from './mock-call-history'
 
 export default MockAgent
 
@@ -31,6 +32,14 @@ declare class MockAgent<TMockAgentOptions extends MockAgent.Options = MockAgent.
   enableNetConnect (host: ((host: string) => boolean)): void
   /** Causes all requests to throw when requests are not matched in a MockAgent intercept. */
   disableNetConnect (): void
+  /** get call history. returns the MockAgent call history or undefined if the option is not enabled. */
+  getCallHistory (): MockCallHistory | undefined
+  /** clear every call history. Any MockCallHistoryLog will be deleted on the MockCallHistory instance */
+  clearCallHistory (): void
+  /** Enable call history. Any subsequence calls will then be registered. */
+  enableCallHistory (): this
+  /** Disable call history. Any subsequence calls will then not be registered. */
+  disableCallHistory (): this
   pendingInterceptors (): PendingInterceptor[]
   assertNoPendingInterceptors (options?: {
     pendingInterceptorsFormatter?: PendingInterceptorsFormatter;
@@ -49,5 +58,8 @@ declare namespace MockAgent {
 
     /** Ignore trailing slashes in the path */
     ignoreTrailingSlash?: boolean;
+
+    /** Enable call history. you can either call MockAgent.enableCallHistory(). default false */
+    enableCallHistory?: boolean
   }
 }

package/types/mock-call-history.d.ts

@@ -0,0 +1,111 @@
+import Dispatcher from './dispatcher'
+
+declare namespace MockCallHistoryLog {
+  /** request's configuration properties */
+  export type MockCallHistoryLogProperties = 'protocol' | 'host' | 'port' | 'origin' | 'path' | 'hash' | 'fullUrl' | 'method' | 'searchParams' | 'body' | 'headers'
+}
+
+/** a log reflecting request configuration  */
+declare class MockCallHistoryLog {
+  constructor (requestInit: Dispatcher.DispatchOptions)
+  /** protocol used. ie. 'https:' or 'http:' etc... */
+  protocol: string
+  /** request's host. */
+  host: string
+  /** request's port. */
+  port: string
+  /** request's origin. ie. https://localhost:3000. */
+  origin: string
+  /** path. never contains searchParams. */
+  path: string
+  /** request's hash. */
+  hash: string
+  /** the full url requested. */
+  fullUrl: string
+  /** request's method. */
+  method: string
+  /** search params. */
+  searchParams: Record<string, string>
+  /** request's body */
+  body: string | null | undefined
+  /** request's headers */
+  headers: Record<string, string | string[]> | null | undefined
+
+  /** returns an Map of property / value pair */
+  toMap (): Map<MockCallHistoryLog.MockCallHistoryLogProperties, string | Record<string, string | string[]> | null | undefined>
+
+  /** returns a string computed with all key value pair */
+  toString (): string
+}
+
+declare namespace MockCallHistory {
+  export type FilterCallsOperator = 'AND' | 'OR'
+
+  /** modify the filtering behavior */
+  export interface FilterCallsOptions {
+    /** the operator to apply when filtering. 'OR' will adds any MockCallHistoryLog matching any criteria given. 'AND' will adds only MockCallHistoryLog matching every criteria given. (default 'OR')  */
+    operator?: FilterCallsOperator | Lowercase<FilterCallsOperator>
+  }
+  /** a function to be executed for filtering MockCallHistoryLog */
+  export type FilterCallsFunctionCriteria = (log: MockCallHistoryLog) => boolean
+
+  /** parameter to filter MockCallHistoryLog */
+  export type FilterCallsParameter = string | RegExp | undefined | null
+
+  /** an object to execute multiple filtering at once */
+  export interface FilterCallsObjectCriteria extends Record<string, FilterCallsParameter> {
+    /** filter by request protocol. ie https: */
+    protocol?: FilterCallsParameter;
+    /** filter by request host. */
+    host?: FilterCallsParameter;
+    /** filter by request port. */
+    port?: FilterCallsParameter;
+    /** filter by request origin. */
+    origin?: FilterCallsParameter;
+    /** filter by request path. */
+    path?: FilterCallsParameter;
+    /** filter by request hash. */
+    hash?: FilterCallsParameter;
+    /** filter by request fullUrl. */
+    fullUrl?: FilterCallsParameter;
+    /** filter by request method. */
+    method?: FilterCallsParameter;
+  }
+}
+
+/** a call history to track requests configuration */
+declare class MockCallHistory {
+  constructor (name: string)
+  /** returns an array of MockCallHistoryLog. */
+  calls (): Array<MockCallHistoryLog>
+  /** returns the first MockCallHistoryLog */
+  firstCall (): MockCallHistoryLog | undefined
+  /** returns the last MockCallHistoryLog. */
+  lastCall (): MockCallHistoryLog | undefined
+  /** returns the nth MockCallHistoryLog. */
+  nthCall (position: number): MockCallHistoryLog | undefined
+  /** return all MockCallHistoryLog matching any of criteria given. if an object is used with multiple properties, you can change the operator to apply during filtering on options */
+  filterCalls (criteria: MockCallHistory.FilterCallsFunctionCriteria | MockCallHistory.FilterCallsObjectCriteria | RegExp, options?: MockCallHistory.FilterCallsOptions): Array<MockCallHistoryLog>
+  /** return all MockCallHistoryLog matching the given protocol. if a string is given, it is matched with includes */
+  filterCallsByProtocol (protocol: MockCallHistory.FilterCallsParameter): Array<MockCallHistoryLog>
+  /** return all MockCallHistoryLog matching the given host. if a string is given, it is matched with includes */
+  filterCallsByHost (host: MockCallHistory.FilterCallsParameter): Array<MockCallHistoryLog>
+  /** return all MockCallHistoryLog matching the given port. if a string is given, it is matched with includes */
+  filterCallsByPort (port: MockCallHistory.FilterCallsParameter): Array<MockCallHistoryLog>
+  /** return all MockCallHistoryLog matching the given origin. if a string is given, it is matched with includes */
+  filterCallsByOrigin (origin: MockCallHistory.FilterCallsParameter): Array<MockCallHistoryLog>
+  /** return all MockCallHistoryLog matching the given path. if a string is given, it is matched with includes */
+  filterCallsByPath (path: MockCallHistory.FilterCallsParameter): Array<MockCallHistoryLog>
+  /** return all MockCallHistoryLog matching the given hash. if a string is given, it is matched with includes */
+  filterCallsByHash (hash: MockCallHistory.FilterCallsParameter): Array<MockCallHistoryLog>
+  /** return all MockCallHistoryLog matching the given fullUrl. if a string is given, it is matched with includes */
+  filterCallsByFullUrl (fullUrl: MockCallHistory.FilterCallsParameter): Array<MockCallHistoryLog>
+  /** return all MockCallHistoryLog matching the given method. if a string is given, it is matched with includes */
+  filterCallsByMethod (method: MockCallHistory.FilterCallsParameter): Array<MockCallHistoryLog>
+  /** clear all MockCallHistoryLog on this MockCallHistory. */
+  clear (): void
+  /** use it with for..of loop or spread operator */
+  [Symbol.iterator]: () => Generator<MockCallHistoryLog>
+}
+
+export { MockCallHistoryLog, MockCallHistory }