@emiliosp/pi-maestro 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,226 @@
+# Undici Module vs. Node.js Built-in Fetch
+
+<!--type=misc-->
+
+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.
+
+## Keep `fetch` and `FormData` from the same implementation
+
+When you send a `FormData` body, keep `fetch` and `FormData` together from the
+same implementation.
+
+Use one of these patterns:
+
+### Built-in globals
+
+```js
+const body = new FormData()
+body.set('name', 'some')
+body.set('someOtherProperty', '8000')
+
+await fetch('https://example.com', {
+  method: 'POST',
+  body
+})
+```
+
+### `undici` module imports
+
+```js
+import { fetch, FormData } from 'undici'
+
+const body = new FormData()
+body.set('name', 'some')
+body.set('someOtherProperty', '8000')
+
+await fetch('https://example.com', {
+  method: 'POST',
+  body
+})
+```
+
+### `undici.install()` globals
+
+If you want the installed `undici` package to provide the globals, call
+[`install()`](../api/GlobalInstallation.md):
+
+```js
+import { install } from 'undici'
+
+install()
+
+const body = new FormData()
+body.set('name', 'some')
+body.set('someOtherProperty', '8000')
+
+await fetch('https://example.com', {
+  method: 'POST',
+  body
+})
+```
+
+`install()` replaces the global `fetch`, `Headers`, `Response`, `Request`, and
+`FormData` implementations with undici's versions, and also installs undici's
+`WebSocket`, `CloseEvent`, `ErrorEvent`, `MessageEvent`, and `EventSource`
+globals.
+
+Avoid mixing implementations in the same request, for example:
+
+```js
+import { fetch } from 'undici'
+
+const body = new FormData()
+
+await fetch('https://example.com', {
+  method: 'POST',
+  body
+})
+```
+
+```js
+import { FormData } from 'undici'
+
+const body = new FormData()
+
+await fetch('https://example.com', {
+  method: 'POST',
+  body
+})
+```
+
+Those combinations may behave differently across Node.js and undici versions.
+Using matching pairs keeps multipart handling predictable.
+
+## 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 replace the global `fetch` and related classes, use
+[`install()`](../api/GlobalInstallation.md). Otherwise, import `fetch`
+directly from `'undici'`:
+
+```js
+import { fetch } from 'undici' // uses your installed version, not the built-in
+```
+
+## Further reading
+
+- [API Reference: Fetch](../api/Fetch.md)
+- [API Reference: Client](../api/Client.md)
+- [API Reference: Pool](../api/Pool.md)
+- [API Reference: ProxyAgent](../api/ProxyAgent.md)
+- [API Reference: MockAgent](../api/MockAgent.md)
+- [API Reference: Global Installation](../api/GlobalInstallation.md)

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

@@ -0,0 +1,65 @@
+# Writing tests
+
+<!--type=misc-->
+
+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)
+```
+
+## Guarding against unexpected disconnects
+
+Undici's `Client` automatically reconnects after a socket error. This means
+a test can silently disconnect, reconnect, and still pass. Unfortunately, 
+this could mask bugs like unexpected parser errors or protocol violations.
+To catch these silent reconnections, add a disconnect guard after creating 
+a `Client`:
+
+```js
+const { Client } = require('undici')
+const { test, after } = require('node:test')
+const { tspl } = require('@matteo.collina/tspl')
+
+test('example with disconnect guard', async (t) => {
+  t = tspl(t, { plan: 1 })
+
+  const client = new Client('http://localhost:3000')
+  after(() => client.close())
+
+  client.on('disconnect', () => {
+    if (!client.closed && !client.destroyed) {
+      t.fail('unexpected disconnect')
+    }
+  })
+
+  // ... test logic ...
+})
+```
+
+`client.close()` and `client.destroy()` both emit `'disconnect'` events, but
+those are expected. The guard only fails when a disconnect happens during the
+active test (i.e., `!client.closed && !client.destroyed` is true).
+
+Skip the guard for tests where a disconnect is expected behavior, such as:
+
+- Signal aborts (`signal.emit('abort')`, `ac.abort()`)
+- Server-side destruction (`res.destroy()`, `req.socket.destroy()`)
+- Client-side body destruction mid-stream (`data.body.destroy()`)
+- Timeout errors (`HeadersTimeoutError`, `BodyTimeoutError`)
+- Successful upgrades (the socket is detached from the `Client`)
+- Retry/reconnect tests where the disconnect triggers the retry
+- HTTP parser errors from malformed responses (`HTTPParserError`)

package/node_modules/undici/docs/docs/getting-started.md

@@ -0,0 +1,281 @@
+# Getting Started
+
+<!--type=misc-->
+
+## Installation
+
+```bash
+npm install undici
+```
+
+## Fetch
+
+The quickest way to get started is with `fetch`, which follows the
+[Fetch Standard](https://fetch.spec.whatwg.org/) and works the same way as
+the browser API:
+
+```mjs
+import { fetch } from 'undici'
+
+const res = await fetch('https://example.com')
+const data = await res.json()
+console.log(data)
+```
+
+### Using the Request object
+
+undici also exports a `Request` class that follows the Fetch Standard:
+
+```mjs
+import { fetch, Request } from 'undici'
+
+const req = new Request('https://example.com', {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({ hello: 'world' })
+})
+const res = await fetch(req)
+console.log(res.status)
+```
+
+### Streaming the response
+
+`res.body` is a web `ReadableStream`. Use `pipeline` from
+`node:stream/promises` to stream it to a file:
+
+```mjs
+import { fetch } from 'undici'
+import { pipeline } from 'node:stream/promises'
+import { createWriteStream } from 'node:fs'
+
+const res = await fetch('https://example.com/large-file.zip')
+await pipeline(res.body, createWriteStream('./file.zip'))
+```
+
+> Always consume or cancel the response body. In Node.js, garbage collection
+> is not aggressive enough to release connections promptly, so leaving a body
+> unread can cause connection leaks and stalled requests. See
+> [Specification Compliance - Garbage Collection](/#garbage-collection)
+> for details.
+
+For more on `fetch`, see [API Reference: Fetch](api/Fetch.md).
+
+## Dispatchers: Connection reuse and pooling
+
+By default, `fetch`, `request`, `stream`, and `pipeline` create a new connection
+for each call. For applications that make many requests to the same origin,
+this is wasteful. undici provides **dispatchers** that manage connections
+internally.
+
+### `Agent` — for requests to multiple origins
+
+`Agent` is the most general-purpose dispatcher. It pools connections per-origin
+and is the recommended default for most applications. Use it with
+`setGlobalDispatcher` to affect all undici calls globally:
+
+```js
+import { Agent, setGlobalDispatcher, fetch } from 'undici'
+
+const agent = new Agent({
+  keepAliveTimeout: 30_000,
+  keepAliveMaxTimeout: 600_000
+})
+setGlobalDispatcher(agent)
+
+// All subsequent fetch/request/stream/pipeline calls reuse connections
+const res = await fetch('https://api.example.com/data')
+```
+
+You can also pass a dispatcher per-request:
+
+```js
+await fetch('https://api.example.com/data', { dispatcher: agent })
+```
+
+### `Pool` — for requests to a single origin
+
+`Pool` manages a fixed set of connections to one origin. It gives you explicit
+control over concurrency:
+
+```js
+import { Pool, request } from 'undici'
+
+const pool = new Pool('https://api.example.com', { connections: 10 })
+
+const { body } = await request('https://api.example.com/data', {
+  dispatcher: pool
+})
+const data = await body.json()
+
+pool.close()
+```
+
+### `Client` — for a single connection
+
+`Client` maps to a single TCP connection. It supports pipelining (sending
+multiple requests before responses arrive), which should only be enabled for
+trusted remote servers:
+
+```js
+import { Client } from 'undici'
+
+const client = new Client('https://api.example.com', {
+  pipelining: 5
+})
+
+const { body } = await client.request({ path: '/', method: 'GET' })
+await body.dump()
+
+client.close()
+```
+
+For more on dispatcher options and lifecycle, see:
+- [API Reference: Agent](api/Agent.md)
+- [API Reference: Pool](api/Pool.md)
+- [API Reference: Client](api/Client.md)
+
+## Timeouts
+
+undici applies timeouts at two levels:
+
+- **`headersTimeout`** — time to wait for response headers (default: 300s).
+- **`bodyTimeout`** — time between consecutive body chunks (default: 300s).
+
+Set these on the dispatcher or per-request:
+
+```js
+import { Agent, setGlobalDispatcher } from 'undici'
+
+const agent = new Agent({
+  headersTimeout: 5_000,
+  bodyTimeout: 30_000
+})
+
+setGlobalDispatcher(agent)
+```
+
+Timeout errors are thrown as `HeadersTimeoutError` and `BodyTimeoutError`.
+See [API Reference: Errors](api/Errors.md) for the full list.
+
+## Error handling
+
+undici exposes structured errors via `error.code`:
+
+```js
+import { request, errors } from 'undici'
+
+try {
+  const { body } = await request('https://example.com')
+  await body.json()
+} catch (err) {
+  switch (err.code) {
+    case 'UND_ERR_CONNECT_TIMEOUT':
+      console.error('Connection timed out')
+      break
+    case 'UND_ERR_HEADERS_TIMEOUT':
+      console.error('Headers timed out')
+      break
+    case 'UND_ERR_BODY_TIMEOUT':
+      console.error('Body timed out')
+      break
+    case 'UND_ERR_ABORTED':
+      console.error('Request was aborted')
+      break
+    default:
+      console.error(err)
+  }
+}
+```
+
+### Aborting requests
+
+```js
+import { request } from 'undici'
+
+const ac = new AbortController()
+
+setTimeout(() => ac.abort(), 1000)
+
+try {
+  const { body } = await request('https://example.com', {
+    signal: ac.signal
+  })
+  await body.dump()
+} catch (err) {
+  console.error(err.code) // UND_ERR_ABORTED
+}
+```
+
+## Common patterns
+
+### Proxies
+
+Use `ProxyAgent` for HTTP(S) proxies, or `EnvHttpProxyAgent` to pick up
+proxy settings from environment variables:
+
+```js
+import { ProxyAgent, setGlobalDispatcher } from 'undici'
+
+const proxy = new ProxyAgent('http://proxy.internal:8080')
+setGlobalDispatcher(proxy)
+```
+
+See [Best Practices: Proxy](best-practices/proxy.md) and
+[API Reference: ProxyAgent](api/ProxyAgent.md).
+
+### Mocking in tests
+
+```js
+import { MockAgent, setGlobalDispatcher, request } from 'undici'
+
+const mockAgent = new MockAgent()
+setGlobalDispatcher(mockAgent)
+
+const mockPool = mockAgent.get('https://api.example.com')
+mockPool.intercept({ path: '/users' }).reply(200, [{ id: 1 }])
+
+const { body } = await request('https://api.example.com/users')
+console.log(await body.json())
+```
+
+See [Best Practices: Mocking Request](best-practices/mocking-request.md)
+and [API Reference: MockAgent](api/MockAgent.md).
+
+### Testing with undici
+
+For test suites, set short keep-alive timeouts to avoid slow teardowns:
+
+```js
+import { Agent, setGlobalDispatcher } from 'undici'
+
+const agent = new Agent({
+  keepAliveTimeout: 10,
+  keepAliveMaxTimeout: 10
+})
+setGlobalDispatcher(agent)
+```
+
+See [Best Practices: Writing Tests](best-practices/writing-tests.md).
+
+### Customizing the global fetch
+
+You can override Node.js's built-in globals with `install()`:
+
+```js
+import { install } from 'undici'
+
+install()
+
+// Global fetch, Headers, Response, Request, and FormData
+// now come from undici, not the Node.js bundle
+const res = await fetch('https://example.com')
+```
+
+See [API Reference: Global Installation](api/GlobalInstallation.md).
+
+## Further reading
+
+- [Undici vs. Built-in Fetch](best-practices/undici-vs-builtin-fetch.md) —
+  when to install undici vs using Node.js built-in fetch
+- [API Reference](api/Dispatcher.md) — full dispatcher API documentation
+- [Examples](/examples/) — runnable code examples