@emiliosp/pi-maestro 0.17.0 → 0.18.0

package/node_modules/undici/docs/docs/best-practices/client-certificate.md

@@ -1,66 +0,0 @@
-# Client certificate
-
-<!--type=misc-->
-
-Client certificate authentication can be configured with the `Client`, the required options are passed along through the `connect` option.
-
-The client certificates must be signed by a trusted CA. The Node.js default is to trust the well-known CAs curated by Mozilla.
-
-Setting the server option `requestCert: true` tells the server to request the client certificate.
-
-The server option `rejectUnauthorized: false` allows us to handle any invalid certificate errors in client code. The `authorized` property on the socket of the incoming request will show if the client certificate was valid. The `authorizationError` property will give the reason if the certificate was not valid.
-
-### Client Certificate Authentication
-
-```js
-const { readFileSync } = require('node:fs')
-const { join } = require('node:path')
-const { createServer } = require('node:https')
-const { Client } = require('undici')
-
-const serverOptions = {
-  ca: [
-    readFileSync(join(__dirname, 'client-ca-crt.pem'), 'utf8')
-  ],
-  key: readFileSync(join(__dirname, 'server-key.pem'), 'utf8'),
-  cert: readFileSync(join(__dirname, 'server-crt.pem'), 'utf8'),
-  requestCert: true,
-  rejectUnauthorized: false
-}
-
-const server = createServer(serverOptions, (req, res) => {
-  // true if client cert is valid
-  if(req.client.authorized === true) {
-    console.log('valid')
-  } else {
-    console.error(req.client.authorizationError)
-  }
-  res.end()
-})
-
-server.listen(0, function () {
-  const tls = {
-    ca: [
-      readFileSync(join(__dirname, 'server-ca-crt.pem'), 'utf8')
-    ],
-    key: readFileSync(join(__dirname, 'client-key.pem'), 'utf8'),
-    cert: readFileSync(join(__dirname, 'client-crt.pem'), 'utf8'),
-    rejectUnauthorized: false,
-    servername: 'agent1'
-  }
-  const client = new Client(`https://localhost:${server.address().port}`, {
-    connect: tls
-  })
-
-  client.request({
-    path: '/',
-    method: 'GET'
-  }, (err, { body }) => {
-    body.on('data', (buf) => {})
-    body.on('end', () => {
-      client.close()
-      server.close()
-    })
-  })
-})
-```

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

@@ -1,60 +0,0 @@
-# Crawling
-
-<!--type=misc-->
-
-[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:
-
-```text
-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/node_modules/undici/docs/docs/best-practices/migrating-from-v7-to-v8.md

@@ -1,233 +0,0 @@
-# Migrating from Undici 7 to 8
-
-<!--type=misc-->
-
-This guide covers the changes you are most likely to hit when upgrading an
-application or library from Undici v7 to v8.
-
-## Before you upgrade
-
-- Make sure your runtime is Node.js `>= 22.19.0`.
-- If you have custom dispatchers, interceptors, or handlers, review the
-  handler API changes before updating.
-- If you rely on HTTP/1.1-only behavior, plan to set `allowH2: false`
-  explicitly.
-
-## 1. Update your Node.js version
-
-Undici v8 requires Node.js `>= 22.19.0`.
-
-If you are still on Node.js 20 or an older Node.js 22 release, upgrade Node.js
-first:
-
-```bash
-node -v
-```
-
-If that command prints a version lower than `v22.19.0`, upgrade Node.js before
-installing Undici v8.
-
-## 2. Migrate custom dispatcher handlers to the v2 API
-
-Undici v8 uses the newer dispatcher handler API consistently.
-
-If you implemented custom dispatchers, interceptors, or wrappers around
-`dispatch()`, update legacy callbacks such as `onConnect`, `onHeaders`, and
-`onComplete` to the newer callback names.
-
-### Old handler callbacks vs. v8 callbacks
-
-| Undici 7 style | Undici 8 style |
-|---|---|
-| `onConnect(abort, context)` | `onRequestStart(controller, context)` |
-| `onHeaders(statusCode, rawHeaders, resume, statusText)` | `onResponseStart(controller, statusCode, headers, statusText)` |
-| `onData(chunk)` | `onResponseData(controller, chunk)` |
-| `onComplete(trailers)` | `onResponseEnd(controller, trailers)` |
-| `onError(err)` | `onResponseError(controller, err)` |
-| `onUpgrade(statusCode, rawHeaders, socket)` | `onRequestUpgrade(controller, statusCode, headers, socket)` |
-
-### Example
-
-Before:
-
-```js
-client.dispatch(options, {
-  onConnect (abort) {
-    this.abort = abort
-  },
-  onHeaders (statusCode, headers, resume) {
-    this.resume = resume
-    return true
-  },
-  onData (chunk) {
-    chunks.push(chunk)
-    return true
-  },
-  onComplete (trailers) {
-    console.log(trailers)
-  },
-  onError (err) {
-    console.error(err)
-  }
-})
-```
-
-After:
-
-```js
-client.dispatch(options, {
-  onRequestStart (controller) {
-    this.controller = controller
-  },
-  onResponseStart (controller, statusCode, headers, statusText) {
-    console.log(statusCode, statusText, headers)
-  },
-  onResponseData (controller, chunk) {
-    chunks.push(chunk)
-  },
-  onResponseEnd (controller, trailers) {
-    console.log(trailers)
-  },
-  onResponseError (controller, err) {
-    console.error(err)
-  }
-})
-```
-
-### Pause, resume, and abort now go through the controller
-
-In Undici v7, legacy handlers could return `false` or keep references to
-`abort()` and `resume()` callbacks. In Undici v8, use the controller instead:
-
-```js
-onRequestStart (controller) {
-  this.controller = controller
-}
-
-onResponseData (controller, chunk) {
-  controller.pause()
-  setImmediate(() => controller.resume())
-}
-
-onResponseError (controller, err) {
-  controller.abort(err)
-}
-```
-
-### Raw headers and trailers moved to the controller
-
-If you need the raw header arrays, read them from the controller:
-
-- `controller.rawHeaders`
-- `controller.rawTrailers`
-
-## 3. Update `onBodySent()` handlers
-
-If you implemented `onBodySent()`, note that its signature changed.
-
-Before, handlers received counters:
-
-```js
-onBodySent (chunkSize, totalBytesSent) {}
-```
-
-In Undici v8, handlers receive the actual chunk:
-
-```js
-onBodySent (chunk) {}
-```
-
-If you need a notification that the whole body has been sent, use
-`onRequestSent()`:
-
-```js
-onRequestSent () {
-  console.log('request body fully sent')
-}
-```
-
-## 4. If you need HTTP/1.1 only, disable HTTP/2 explicitly
-
-Undici v8 enables HTTP/2 by default when a TLS server negotiates it via ALPN.
-
-If your application depends on HTTP/1.1-specific behavior, set `allowH2: false`
-explicitly.
-
-Before:
-
-```js
-const client = new Client('https://example.com')
-```
-
-After, to keep HTTP/1.1 only:
-
-```js
-const client = new Client('https://example.com', {
-  allowH2: false
-})
-```
-
-The same applies when you configure an `Agent`:
-
-```js
-const agent = new Agent({
-  allowH2: false
-})
-```
-
-## 5. Use real `Blob` and `File` instances
-
-Undici v8 no longer accepts fake Blob-like values that only imitate `Blob` or
-`File` via properties such as `Symbol.toStringTag`.
-
-If you were passing custom objects that looked like `Blob`s, replace them with
-actual `Blob` or `File` instances:
-
-```js
-const body = new Blob(['hello'])
-```
-
-## 6. Avoid depending on the internal global dispatcher symbol
-
-`setGlobalDispatcher()` and `getGlobalDispatcher()` remain the public APIs and
-should continue to be used.
-
-Internally, Undici v8 stores its dispatcher under
-`Symbol.for('undici.globalDispatcher.2')` and mirrors a v1-compatible wrapper
-for legacy consumers such as Node.js built-in `fetch`.
-
-If your code was reading or writing `Symbol.for('undici.globalDispatcher.1')`
-directly, migrate to the public APIs instead:
-
-```js
-import { setGlobalDispatcher, getGlobalDispatcher, Agent } from 'undici'
-
-setGlobalDispatcher(new Agent())
-const dispatcher = getGlobalDispatcher()
-```
-
-If you must expose a dispatcher to legacy v1 handler consumers, wrap it with
-`Dispatcher1Wrapper`:
-
-```js
-import { Agent, Dispatcher1Wrapper } from 'undici'
-
-const legacyCompatibleDispatcher = new Dispatcher1Wrapper(new Agent())
-```
-
-## 7. Verify the upgrade
-
-After moving to Undici v8, it is worth checking these paths in your test suite:
-
-- requests that use a custom `dispatcher`
-- `setGlobalDispatcher()` behavior
-- any custom interceptor or retry handler
-- uploads that use `Blob`, `File`, or `FormData`
-- integrations that depend on HTTP/1.1-only behavior
-
-## Related documentation
-
-- [Dispatcher](../api/Dispatcher.md)
-- [Client](../api/Client.md)
-- [Global Installation](../api/GlobalInstallation.md)
-- [Undici Module vs. Node.js Built-in Fetch](./undici-vs-builtin-fetch.md)

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

@@ -1,192 +0,0 @@
-# Mocking Request
-
-<!--type=misc-->
-
-Undici has its own mocking [utility](../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](../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](../api/MockAgent.md)
-
-Explore other MockCallHistory functionality [here](../api/MockCallHistory.md)
-
-Explore other MockCallHistoryLog functionality [here](../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
-
-```js
-{
-  method: 'POST',
-  headers: { 'X-TOKEN-SECRET': 'SuperSecretToken' },
-  body: '{"recipient":"1234567890","amount":"100"}',
-  origin: 'http://localhost:3000',
-  path: '/bank-transfer'
-}
-```

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

@@ -1,129 +0,0 @@
-# Connecting through a proxy
-
-<!--type=misc-->
-
-Connecting through a proxy is possible by:
-
-- Using {ProxyAgent}.
-- 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))
-  })
-}
-```
-