@psnext/slingcli 2.4.20260520-3 → 2.4.20260520-5

package/node_modules/@earendil-works/pi-coding-agent/node_modules/undici/docs/docs/best-practices/migrating-from-v7-to-v8.md

@@ -0,0 +1,231 @@
+# Migrating from Undici 7 to 8
+
+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](/docs/api/Dispatcher.md)
+- [Client](/docs/api/Client.md)
+- [Global Installation](/docs/api/GlobalInstallation.md)
+- [Undici Module vs. Node.js Built-in Fetch](/docs/best-practices/undici-vs-builtin-fetch.md)

package/node_modules/@earendil-works/pi-coding-agent/node_modules/undici/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/node_modules/@earendil-works/pi-coding-agent/node_modules/undici/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))
+  })
+}
+```
+