This method defines the interception rules for matching against requests for a MockPool or MockPool. We can intercept multiple times on a single instance, but each intercept is only used once. For example if you expect to make 2 requests inside a test, you need to call `intercept()` twice. Assuming you use `disableNetConnect()` you will get `MockNotMatchedError` on the second request when you only call `intercept()` once.

When defining interception rules, all the rules must pass for a request to be intercepted. If a request is not intercepted, a real request will be attempted.

* **path** `string | RegExp | (path: string) => boolean` - a matcher for the HTTP request path. When a `RegExp` or callback is used, it will match against the request path including all query parameters in alphabetical order. When a `string` is provided, the query parameters can be conveniently specified through the `MockPoolInterceptOptions.query` setting.

* **method** `string | RegExp | (method: string) => boolean` - (optional) - a matcher for the HTTP request method. Defaults to `GET`.

* **body** `string | RegExp | (body: string) => boolean` - (optional) - a matcher for the HTTP request body.

* **headers** `Record<string, string | RegExp | (body: string) => boolean`> - (optional) - a matcher for the HTTP request headers. To be intercepted, a request must match all defined headers. Extra headers not defined here may (or may not) be included in the request and do not affect the interception in any way.

* **query** `Record<string, any> | null` - (optional) - a matcher for the HTTP request query string params. Only applies when a `string` was provided for `MockPoolInterceptOptions.path`.

import { MockAgent, setGlobalDispatcher, request } from 'undici'

import querystring from 'querystring'

const mockAgent = new MockAgent()

setGlobalDispatcher(mockAgent)

const mockPool = mockAgent.get('http://localhost:3000')

const matchPath = requestPath => {

const [pathname, search] = requestPath.split('?')

const requestQuery = querystring.parse(search)

if (!pathname.startsWith('/foo')) {

return false

}

if (!Object.keys(requestQuery).includes('foo') || requestQuery.foo !== 'bar') {

return false

}

return true

}

mockPool.intercept({

path: matchPath,

method: 'GET'

}).reply(200, 'foo')

const result = await request('http://localhost:3000/foo?foo=bar')

Closes the mock pool and de-registers from associated MockAgent.

Extends: `undici.DispatcherHandlers`

A handler class that implements the retry logic for a request.

Arguments:

- **options** `Dispatch.DispatchOptions & RetryOptions` (required) - It is an intersection of `Dispatcher.DispatchOptions` and `RetryOptions`.

- **retryHandlers** `RetryHandlers` (required) - Object containing the `dispatch` to be used on every retry, and `handler` for handling the `dispatch` lifecycle.

Returns: `retryHandler`

Extends: [`Dispatch.DispatchOptions`](Dispatcher.md#parameter-dispatchoptions).

- **retry** `(err: Error, context: RetryContext, callback: (err?: Error | null) => void) => void` (optional) - Function to be called after every retry. It should pass error if no more retries should be performed.

- **maxRetries** `number` (optional) - Maximum number of retries. Default: `5`

- **maxTimeout** `number` (optional) - Maximum number of milliseconds to wait before retrying. Default: `30000` (30 seconds)

- **minTimeout** `number` (optional) - Minimum number of milliseconds to wait before retrying. Default: `500` (half a second)

- **timeoutFactor** `number` (optional) - Factor to multiply the timeout by for each retry attempt. Default: `2`

- **retryAfter** `boolean` (optional) - It enables automatic retry after the `Retry-After` header is received. Default: `true`

- **methods** `string[]` (optional) - Array of HTTP methods to retry. Default: `['GET', 'PUT', 'HEAD', 'OPTIONS', 'DELETE']`

- **statusCodes** `number[]` (optional) - Array of HTTP status codes to retry. Default: `[429, 500, 502, 503, 504]`

- **errorCodes** `string[]` (optional) - Array of Error codes to retry. Default: `['ECONNRESET', 'ECONNREFUSED', 'ENOTFOUND', 'ENETDOWN','ENETUNREACH', 'EHOSTDOWN',

- `state`: `RetryState` - Current retry state. It can be mutated.

- `opts`: `Dispatch.DispatchOptions & RetryOptions` - Options passed to the retry handler.

- **dispatch** `(options: Dispatch.DispatchOptions, handlers: Dispatch.DispatchHandlers) => Promise<Dispatch.DispatchResponse>` (required) - Dispatch function to be called after every retry.

- **handler** Extends [`Dispatch.DispatchHandlers`](Dispatcher.md#dispatcherdispatchoptions-handler) (required) - Handler function to be called after the request is successful or the retries are exhausted.

Examples:

const client = new Client(`http://localhost:${server.address().port}`);

const chunks = [];

const handler = new RetryHandler(

{

...dispatchOptions,

retryOptions: {

// custom retry function

retry: function (err, state, callback) {

counter++;

if (err.code && err.code === "UND_ERR_DESTROYED") {

callback(err);

return;

}

if (err.statusCode === 206) {

callback(err);

return;

}

setTimeout(() => callback(null), 1000);

},

},

},

{

dispatch: (...args) => {

return client.dispatch(...args);

},

handler: {

onConnect() {},

onBodySent() {},

onHeaders(status, _rawHeaders, resume, _statusMessage) {

// do something with headers

},

onData(chunk) {

chunks.push(chunk);

return true;

},

onComplete() {},

onError() {

// handle error properly

},

},

}

);

const client = new Client(`http://localhost:${server.address().port}`);

const handler = new RetryHandler(dispatchOptions, {

dispatch: client.dispatch.bind(client),

handler: {

onConnect() {},

onBodySent() {},

onHeaders(status, _rawHeaders, resume, _statusMessage) {},

onData(chunk) {},

onComplete() {},

onError(err) {},

},

});

const MockPool = require('./lib/mock/mock-pool')

const mockErrors = require('./lib/mock/mock-errors')

const ProxyAgent = require('./lib/proxy-agent')

const RetryHandler = require('./lib/handler/RetryHandler')

const { getGlobalDispatcher, setGlobalDispatcher } = require('./lib/global')

const DecoratorHandler = require('./lib/handler/DecoratorHandler')

const RedirectHandler = require('./lib/handler/RedirectHandler')

module.exports.BalancedPool = BalancedPool

module.exports.Agent = Agent

module.exports.ProxyAgent = ProxyAgent

module.exports.RetryHandler = RetryHandler

module.exports.DecoratorHandler = DecoratorHandler

module.exports.RedirectHandler = RedirectHandler

const kAbort = Symbol('abort')

const kContentType = Symbol('kContentType')

const noop = () => {}

module.exports = class BodyReadable extends Readable {

constructor ({

resume,

return this[kBody]

}

dump (opts) {

let limit = opts && Number.isFinite(opts.limit) ? opts.limit : 262144

const signal = opts && opts.signal

if (signal) {

try {

if (typeof signal !== 'object' || !('aborted' in signal)) {

throw new InvalidArgumentError('signal must be an AbortSignal')

}

util.throwIfAborted(signal)

} catch (err) {

return Promise.reject(err)

}

}

if (this.closed) {

return Promise.resolve(null)

}

return new Promise((resolve, reject) => {

const signalListenerCleanup = signal

? util.addAbortListener(signal, () => {

this.destroy()

})

: noop

this

.on('close', function () {

signalListenerCleanup()

if (signal?.aborted) {

reject(signal.reason || Object.assign(new Error('The operation was aborted'), { name: 'AbortError' }))

} else {

resolve(null)

}

})

.on('error', noop)

.on('data', function (chunk) {

limit -= chunk.length

if (limit <= 0) {

this.destroy()

}

})

.resume()

})

}

const idx = hostname.indexOf(']')

assert(idx !== -1)

const ip = hostname.substring(1, idx)

assert(net.isIP(ip))

hostname = ip

return false

}

/** @type {import('node:http2').ClientHttp2Stream} */

let stream

const h2State = client[kHTTP2SessionState]

const shouldEndStream = method === 'GET' || method === 'HEAD'

if (expectContinue) {

headers[HTTP2_HEADER_EXPECT] = '100-continue'

stream = session.request(headers, { endStream: shouldEndStream, signal })

stream.once('continue', writeBodyH2)

} else {

stream = session.request(headers, {

endStream: shouldEndStream,

signal

++h2State.openStreams

stream.once('response', headers => {

const { [HTTP2_HEADER_STATUS]: statusCode, ...realHeaders } = headers

if (request.onHeaders(Number(statusCode), realHeaders, stream.resume.bind(stream), '') === false) {

stream.pause()

}

})

}

}

const onAbort = function () {

if (finished) {

return

}

const err = new RequestAbortedError()

queueMicrotask(() => onFinished(err))

}

const onFinished = function (err) {

if (finished) {

}

class RequestRetryError extends UndiciError {

constructor (message, code, { headers, data }) {

super(message)

Error.captureStackTrace(this, RequestRetryError)

this.name = 'RequestRetryError'

this.message = message || 'Request retry error'

this.code = 'UND_ERR_REQ_RETRY'

this.statusCode = code

this.data = data

this.headers = headers

}

module.exports = {

HTTPParserError,

UndiciError,

NotSupportedError,

ResponseContentLengthMismatchError,

BalancedPoolMissingUpstreamError,

ResponseExceededMaxSizeError,

RequestRetryError

onBodySent (chunk) {

if (this[kHandler].onBodySent) {

return this[kHandler].onBodySent(chunk)

}

}

}

if (this[kHandler].onRequestSent) {

return this[kHandler].onRequestSent()

}

}