@depup/undici 7.24.3-depup.0

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

@@ -0,0 +1,190 @@
+# Mocking Request
+
+Undici has its own mocking [utility](/docs/docs/api/MockAgent.md). It allow us to intercept undici HTTP requests and return mocked values instead. It can be useful for testing purposes.
+
+Example:
+
+```js
+// bank.mjs
+import { request } from 'undici'
+
+export async function bankTransfer(recipient, amount) {
+  const { body } = await request('http://localhost:3000/bank-transfer',
+    {
+      method: 'POST',
+      headers: {
+        'X-TOKEN-SECRET': 'SuperSecretToken',
+      },
+      body: JSON.stringify({
+        recipient,
+        amount
+      })
+    }
+  )
+  return await body.json()
+}
+```
+
+And this is what the test file looks like:
+
+```js
+// index.test.mjs
+import { strict as assert } from 'node:assert'
+import { MockAgent, setGlobalDispatcher, } from 'undici'
+import { bankTransfer } from './bank.mjs'
+
+const mockAgent = new MockAgent();
+
+setGlobalDispatcher(mockAgent);
+
+// Provide the base url to the request
+const mockPool = mockAgent.get('http://localhost:3000');
+
+// intercept the request
+mockPool.intercept({
+  path: '/bank-transfer',
+  method: 'POST',
+  headers: {
+    'X-TOKEN-SECRET': 'SuperSecretToken',
+  },
+  body: JSON.stringify({
+    recipient: '1234567890',
+    amount: '100'
+  })
+}).reply(200, {
+  message: 'transaction processed'
+})
+
+const success = await bankTransfer('1234567890', '100')
+
+assert.deepEqual(success, { message: 'transaction processed' })
+
+// if you dont want to check whether the body or the headers contain the same value
+// just remove it from interceptor
+mockPool.intercept({
+  path: '/bank-transfer',
+  method: 'POST',
+}).reply(400, {
+  message: 'bank account not found'
+})
+
+const badRequest = await bankTransfer('1234567890', '100')
+
+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()`:
+
+```js
+const mockAgent = new MockAgent();
+
+setGlobalDispatcher(mockAgent);
+mockAgent.disableNetConnect()
+
+// Provide the base url to the request
+const mockPool = mockAgent.get('http://localhost:3000');
+
+mockPool.intercept({
+  path: '/bank-transfer',
+  method: 'POST',
+}).reply(200, {
+  message: 'transaction processed'
+})
+
+const badRequest = await bankTransfer('1234567890', '100')
+// Will throw an error
+// MockNotMatchedError: Mock dispatch not matched for path '/bank-transfer':
+// subsequent request to origin http://localhost:3000 was not allowed (net.connect disabled)
+```
+
+## Reply with data based on request
+
+If the mocked response needs to be dynamically derived from the request parameters, you can provide a function instead of an object to `reply`:
+
+```js
+mockPool.intercept({
+  path: '/bank-transfer',
+  method: 'POST',
+  headers: {
+    'X-TOKEN-SECRET': 'SuperSecretToken',
+  },
+  body: JSON.stringify({
+    recipient: '1234567890',
+    amount: '100'
+  })
+}).reply(200, (opts) => {
+  // do something with opts
+
+  return { message: 'transaction processed' }
+})
+```
+
+in this case opts will be
+
+```
+{
+  method: 'POST',
+  headers: { 'X-TOKEN-SECRET': 'SuperSecretToken' },
+  body: '{"recipient":"1234567890","amount":"100"}',
+  origin: 'http://localhost:3000',
+  path: '/bank-transfer'
+}
+```

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

@@ -0,0 +1,127 @@
+# Connecting through a proxy
+
+Connecting through a proxy is possible by:
+
+- Using [ProxyAgent](/docs/docs/api/ProxyAgent.md).
+- Configuring `Client` or `Pool` constructor.
+
+The proxy url should be passed to the `Client` or `Pool` constructor, while the upstream server url
+should be added to every request call in the `path`.
+For instance, if you need to send a request to the `/hello` route of your upstream server,
+the `path` should be `path: 'http://upstream.server:port/hello?foo=bar'`.
+
+If you proxy requires basic authentication, you can send it via the `proxy-authorization` header.
+
+### Connect without authentication
+
+```js
+import { Client } from 'undici'
+import { createServer } from 'http'
+import { createProxy } from 'proxy'
+
+const server = await buildServer()
+const proxyServer = await buildProxy()
+
+const serverUrl = `http://localhost:${server.address().port}`
+const proxyUrl = `http://localhost:${proxyServer.address().port}`
+
+server.on('request', (req, res) => {
+  console.log(req.url) // '/hello?foo=bar'
+  res.setHeader('content-type', 'application/json')
+  res.end(JSON.stringify({ hello: 'world' }))
+})
+
+const client = new Client(proxyUrl)
+
+const response = await client.request({
+  method: 'GET',
+  path: serverUrl + '/hello?foo=bar'
+})
+
+response.body.setEncoding('utf8')
+let data = ''
+for await (const chunk of response.body) {
+  data += chunk
+}
+console.log(response.statusCode) // 200
+console.log(JSON.parse(data)) // { hello: 'world' }
+
+server.close()
+proxyServer.close()
+client.close()
+
+function buildServer () {
+  return new Promise((resolve, reject) => {
+    const server = createServer()
+    server.listen(0, () => resolve(server))
+  })
+}
+
+function buildProxy () {
+  return new Promise((resolve, reject) => {
+    const server = createProxy(createServer())
+    server.listen(0, () => resolve(server))
+  })
+}
+```
+
+### Connect with authentication
+
+```js
+import { Client } from 'undici'
+import { createServer } from 'http'
+import { createProxy } from 'proxy'
+
+const server = await buildServer()
+const proxyServer = await buildProxy()
+
+const serverUrl = `http://localhost:${server.address().port}`
+const proxyUrl = `http://localhost:${proxyServer.address().port}`
+
+proxyServer.authenticate = function (req) {
+  return req.headers['proxy-authorization'] === `Basic ${Buffer.from('user:pass').toString('base64')}`
+}
+
+server.on('request', (req, res) => {
+  console.log(req.url) // '/hello?foo=bar'
+  res.setHeader('content-type', 'application/json')
+  res.end(JSON.stringify({ hello: 'world' }))
+})
+
+const client = new Client(proxyUrl)
+
+const response = await client.request({
+  method: 'GET',
+  path: serverUrl + '/hello?foo=bar',
+  headers: {
+    'proxy-authorization': `Basic ${Buffer.from('user:pass').toString('base64')}`
+  }
+})
+
+response.body.setEncoding('utf8')
+let data = ''
+for await (const chunk of response.body) {
+  data += chunk
+}
+console.log(response.statusCode) // 200
+console.log(JSON.parse(data)) // { hello: 'world' }
+
+server.close()
+proxyServer.close()
+client.close()
+
+function buildServer () {
+  return new Promise((resolve, reject) => {
+    const server = createServer()
+    server.listen(0, () => resolve(server))
+  })
+}
+
+function buildProxy () {
+  return new Promise((resolve, reject) => {
+    const server = createProxy(createServer())
+    server.listen(0, () => resolve(server))
+  })
+}
+```
+

package/docs/docs/best-practices/undici-vs-builtin-fetch.md

@@ -0,0 +1,137 @@
+# Undici Module vs. Node.js Built-in Fetch
+
+Node.js has shipped a built-in `fetch()` implementation powered by undici since
+Node.js v18. This guide explains the relationship between the `undici` npm
+package and the built-in `fetch`, and when you should install one versus relying
+on the other.
+
+## Background
+
+The `fetch()`, `Request`, `Response`, `Headers`, and `FormData` globals in
+Node.js v18+ are provided by a version of undici that is bundled into Node.js
+itself. You can check which version is bundled with:
+
+```js
+console.log(process.versions.undici); // e.g., "7.5.0"
+```
+
+When you install undici from npm, you get the full library with all of its
+additional APIs, and potentially a newer release than what your Node.js version
+bundles.
+
+## When you do NOT need to install undici
+
+If all of the following are true, you can rely on the built-in globals and skip
+adding undici to your dependencies:
+
+- You only need the standard Fetch API (`fetch`, `Request`, `Response`,
+  `Headers`, `FormData`).
+- You are running Node.js v18 or later.
+- You do not depend on features or bug fixes introduced in a version of undici
+  newer than the one bundled with your Node.js release.
+- You want zero additional runtime dependencies.
+- You want cross-platform interoperability with browsers and other runtimes
+  (Deno, Bun, Cloudflare Workers, etc.) using the same Fetch API surface.
+
+This is common in applications that make straightforward HTTP requests or in
+libraries that target multiple JavaScript runtimes.
+
+## When you SHOULD install undici
+
+Install undici from npm when you need capabilities beyond the standard Fetch API:
+
+### Advanced HTTP APIs
+
+undici exposes `request`, `stream`, `pipeline`, and `connect` methods that
+provide lower-level control and significantly better performance than `fetch`:
+
+```js
+import { request } from 'undici';
+
+const { statusCode, headers, body } = await request('https://example.com');
+const data = await body.json();
+```
+
+### Connection pooling and dispatchers
+
+`Client`, `Pool`, `BalancedPool`, `Agent`, and their configuration options
+let you manage connection lifecycle, keep-alive behavior, pipelining depth,
+and concurrency limits:
+
+```js
+import { Pool } from 'undici';
+
+const pool = new Pool('https://example.com', { connections: 10 });
+const { body } = await pool.request({ path: '/', method: 'GET' });
+```
+
+### Proxy support
+
+`ProxyAgent` and `EnvHttpProxyAgent` handle HTTP(S) proxying. Note that
+Node.js v22.21.0+ and v24.0.0+ support environment-variable-based proxy
+configuration for the built-in `fetch` via the `--use-env-proxy` flag (or
+`NODE_USE_ENV_PROXY=1`). However, undici's `ProxyAgent` still provides
+programmatic control through the dispatcher API:
+
+```js
+import { ProxyAgent, fetch } from 'undici';
+
+const proxyAgent = new ProxyAgent('https://my-proxy.example.com:8080');
+const response = await fetch('https://example.com', { dispatcher: proxyAgent });
+```
+
+### Testing and mocking
+
+`MockAgent`, `MockClient`, and `MockPool` let you intercept and mock HTTP
+requests without patching globals or depending on external libraries:
+
+```js
+import { MockAgent, setGlobalDispatcher, fetch } from 'undici';
+
+const mockAgent = new MockAgent();
+setGlobalDispatcher(mockAgent);
+
+const pool = mockAgent.get('https://example.com');
+pool.intercept({ path: '/api' }).reply(200, { message: 'mocked' });
+```
+
+### Interceptors and middleware
+
+Custom dispatchers and interceptors (retry, redirect, cache, DNS) give you
+fine-grained control over how requests are processed.
+
+### Newer version than what Node.js bundles
+
+The npm package often includes features, performance improvements, and bug fixes
+that have not yet landed in a Node.js release. If you need a specific fix or
+feature, you can install a newer version directly.
+
+## Version compatibility
+
+| Node.js version | Bundled undici version | Notes |
+|---|---|---|
+| v18.x | ~5.x | `fetch` is experimental (behind `--experimental-fetch` in early v18) |
+| v20.x | ~6.x | `fetch` is stable |
+| v22.x | ~6.x / ~7.x | `fetch` is stable |
+| v24.x | ~7.x | `fetch` is stable; env-proxy support via `--use-env-proxy` |
+
+You can always check the exact bundled version at runtime with
+`process.versions.undici`.
+
+Installing undici from npm does not replace the built-in globals. If you want
+your installed version to override the global `fetch`, use
+[`setGlobalDispatcher`](/docs/api/GlobalInstallation.md) or import `fetch`
+directly from `'undici'`:
+
+```js
+import { fetch } from 'undici'; // uses your installed version, not the built-in
+```
+
+## Further reading
+
+- [API Reference: Fetch](/docs/api/Fetch.md)
+- [API Reference: Client](/docs/api/Client.md)
+- [API Reference: Pool](/docs/api/Pool.md)
+- [API Reference: ProxyAgent](/docs/api/ProxyAgent.md)
+- [API Reference: MockAgent](/docs/api/MockAgent.md)
+- [API Reference: Global Installation](/docs/api/GlobalInstallation.md)

package/docs/docs/best-practices/writing-tests.md

@@ -0,0 +1,20 @@
+# Writing tests
+
+Undici is tuned for a production use case and its default will keep
+a socket open for a few seconds after an HTTP request is completed to
+remove the overhead of opening up a new socket. These settings that makes
+Undici shine in production are not a good fit for using Undici in automated
+tests, as it will result in longer execution times.
+
+The following are good defaults that will keep the socket open for only 10ms:
+
+```js
+import { request, setGlobalDispatcher, Agent } from 'undici'
+
+const agent = new Agent({
+  keepAliveTimeout: 10, // milliseconds
+  keepAliveMaxTimeout: 10 // milliseconds
+})
+
+setGlobalDispatcher(agent)
+```

package/index-fetch.js

@@ -0,0 +1,65 @@
+'use strict'
+
+const { getGlobalDispatcher, setGlobalDispatcher } = require('./lib/global')
+const EnvHttpProxyAgent = require('./lib/dispatcher/env-http-proxy-agent')
+const fetchImpl = require('./lib/web/fetch').fetch
+
+// Capture __filename at module load time for stack trace augmentation.
+// This may be undefined when bundled in environments like Node.js internals.
+const currentFilename = typeof __filename !== 'undefined' ? __filename : undefined
+
+function appendFetchStackTrace (err, filename) {
+  if (!err || typeof err !== 'object') {
+    return
+  }
+
+  const stack = typeof err.stack === 'string' ? err.stack : ''
+  const normalizedFilename = filename.replace(/\\/g, '/')
+
+  if (stack && (stack.includes(filename) || stack.includes(normalizedFilename))) {
+    return
+  }
+
+  const capture = {}
+  Error.captureStackTrace(capture, appendFetchStackTrace)
+
+  if (!capture.stack) {
+    return
+  }
+
+  const captureLines = capture.stack.split('\n').slice(1).join('\n')
+
+  err.stack = stack ? `${stack}\n${captureLines}` : capture.stack
+}
+
+module.exports.fetch = function fetch (init, options = undefined) {
+  return fetchImpl(init, options).catch(err => {
+    if (currentFilename) {
+      appendFetchStackTrace(err, currentFilename)
+    } else if (err && typeof err === 'object') {
+      Error.captureStackTrace(err, module.exports.fetch)
+    }
+    throw err
+  })
+}
+module.exports.FormData = require('./lib/web/fetch/formdata').FormData
+module.exports.Headers = require('./lib/web/fetch/headers').Headers
+module.exports.Response = require('./lib/web/fetch/response').Response
+module.exports.Request = require('./lib/web/fetch/request').Request
+
+const { CloseEvent, ErrorEvent, MessageEvent, createFastMessageEvent } = require('./lib/web/websocket/events')
+module.exports.WebSocket = require('./lib/web/websocket/websocket').WebSocket
+module.exports.CloseEvent = CloseEvent
+module.exports.ErrorEvent = ErrorEvent
+module.exports.MessageEvent = MessageEvent
+module.exports.createFastMessageEvent = createFastMessageEvent
+
+module.exports.EventSource = require('./lib/web/eventsource/eventsource').EventSource
+
+const api = require('./lib/api')
+const Dispatcher = require('./lib/dispatcher/dispatcher')
+Object.assign(Dispatcher.prototype, api)
+// Expose the fetch implementation to be enabled in Node.js core via a flag
+module.exports.EnvHttpProxyAgent = EnvHttpProxyAgent
+module.exports.getGlobalDispatcher = getGlobalDispatcher
+module.exports.setGlobalDispatcher = setGlobalDispatcher

package/index.d.ts

@@ -0,0 +1,3 @@
+import Undici from './types/index'
+export default Undici
+export * from './types/index'