@entelligentsia/forgecli 0.7.9 → 0.8.4

package/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/undici/index.js

@@ -6,6 +6,7 @@ const Pool = require('./lib/dispatcher/pool')
 const BalancedPool = require('./lib/dispatcher/balanced-pool')
 const RoundRobinPool = require('./lib/dispatcher/round-robin-pool')
 const Agent = require('./lib/dispatcher/agent')
+const Dispatcher1Wrapper = require('./lib/dispatcher/dispatcher1-wrapper')
 const ProxyAgent = require('./lib/dispatcher/proxy-agent')
 const Socks5ProxyAgent = require('./lib/dispatcher/socks5-proxy-agent')
 const EnvHttpProxyAgent = require('./lib/dispatcher/env-http-proxy-agent')
@@ -35,6 +36,7 @@ module.exports.Pool = Pool
 module.exports.BalancedPool = BalancedPool
 module.exports.RoundRobinPool = RoundRobinPool
 module.exports.Agent = Agent
+module.exports.Dispatcher1Wrapper = Dispatcher1Wrapper
 module.exports.ProxyAgent = ProxyAgent
 module.exports.Socks5ProxyAgent = Socks5ProxyAgent
 module.exports.EnvHttpProxyAgent = EnvHttpProxyAgent
@@ -103,14 +105,14 @@ function makeDispatcher (fn) {
       url = util.parseURL(url)
     }
 
-    const { agent, dispatcher = getGlobalDispatcher() } = opts
+    const { agent, dispatcher = getGlobalDispatcher(), ...restOpts } = opts
 
     if (agent) {
       throw new InvalidArgumentError('unsupported opts.agent. Did you mean opts.client?')
     }
 
     return fn.call(dispatcher, {
-      ...opts,
+      ...restOpts,
       origin: url.origin,
       path: url.search ? `${url.pathname}${url.search}` : url.pathname,
       method: opts.method || (opts.body ? 'PUT' : 'GET')

package/node_modules/undici/lib/api/api-connect.js

@@ -32,45 +32,48 @@ class ConnectHandler extends AsyncResource {
     addSignal(this, signal)
   }
 
-  onConnect (abort, context) {
+  onRequestStart (controller, context) {
     if (this.reason) {
-      abort(this.reason)
+      controller.abort(this.reason)
       return
     }
 
     assert(this.callback)
 
-    this.abort = abort
+    this.abort = (reason) => controller.abort(reason)
     this.context = context
   }
 
-  onHeaders () {
+  onResponseStart () {
     throw new SocketError('bad connect', null)
   }
 
-  onUpgrade (statusCode, rawHeaders, socket) {
+  onRequestUpgrade (controller, statusCode, headers, socket) {
     const { callback, opaque, context } = this
 
     removeSignal(this)
 
     this.callback = null
 
-    let headers = rawHeaders
+    let responseHeaders = headers
+    const rawHeaders = controller?.rawHeaders
     // Indicates is an HTTP2Session
-    if (headers != null) {
-      headers = this.responseHeaders === 'raw' ? util.parseRawHeaders(rawHeaders) : util.parseHeaders(rawHeaders)
+    if (responseHeaders != null) {
+      responseHeaders = this.responseHeaders === 'raw'
+        ? util.parseRawHeaders(rawHeaders)
+        : headers
     }
 
     this.runInAsyncScope(callback, null, null, {
       statusCode,
-      headers,
+      headers: responseHeaders,
       socket,
       opaque,
       context
     })
   }
 
-  onError (err) {
+  onResponseError (_controller, err) {
     const { callback, opaque } = this
 
     removeSignal(this)
@@ -96,7 +99,6 @@ function connect (opts, callback) {
   try {
     const connectHandler = new ConnectHandler(opts, callback)
     const connectOptions = { ...opts, method: 'CONNECT' }
-
     this.dispatch(connectOptions, connectHandler)
   } catch (err) {
     if (typeof callback !== 'function') {

package/node_modules/undici/lib/api/api-pipeline.js

@@ -13,6 +13,7 @@ const {
   RequestAbortedError
 } = require('../core/errors')
 const util = require('../core/util')
+const { kBodyUsed } = require('../core/symbols')
 const { addSignal, removeSignal } = require('./abort-signal')
 
 function noop () {}
@@ -24,6 +25,9 @@ class PipelineRequest extends Readable {
     super({ autoDestroy: true })
 
     this[kResume] = null
+    // Pipeline request bodies come from a live writable side and cannot be
+    // replayed across redirects or retries, even before any bytes are read.
+    this[kBodyUsed] = true
   }
 
   _read () {
@@ -146,40 +150,46 @@ class PipelineHandler extends AsyncResource {
     addSignal(this, signal)
   }
 
-  onConnect (abort, context) {
+  onRequestStart (controller, context) {
     const { res } = this
 
     if (this.reason) {
-      abort(this.reason)
+      controller.abort(this.reason)
       return
     }
 
     assert(!res, 'pipeline cannot be retried')
 
-    this.abort = abort
+    this.abort = (reason) => controller.abort(reason)
     this.context = context
   }
 
-  onHeaders (statusCode, rawHeaders, resume) {
+  onResponseStart (controller, statusCode, headers, _statusMessage) {
     const { opaque, handler, context } = this
 
     if (statusCode < 200) {
       if (this.onInfo) {
-        const headers = this.responseHeaders === 'raw' ? util.parseRawHeaders(rawHeaders) : util.parseHeaders(rawHeaders)
-        this.onInfo({ statusCode, headers })
+        const rawHeaders = controller?.rawHeaders
+        const responseHeaders = this.responseHeaders === 'raw'
+          ? util.parseRawHeaders(rawHeaders)
+          : headers
+        this.onInfo({ statusCode, headers: responseHeaders })
       }
       return
     }
 
-    this.res = new PipelineResponse(resume)
+    this.res = new PipelineResponse(() => controller.resume())
 
     let body
     try {
       this.handler = null
-      const headers = this.responseHeaders === 'raw' ? util.parseRawHeaders(rawHeaders) : util.parseHeaders(rawHeaders)
+      const rawHeaders = controller?.rawHeaders
+      const responseHeaders = this.responseHeaders === 'raw'
+        ? util.parseRawHeaders(rawHeaders)
+        : headers
       body = this.runInAsyncScope(handler, null, {
         statusCode,
-        headers,
+        headers: responseHeaders,
         opaque,
         body: this.res,
         context
@@ -222,17 +232,20 @@ class PipelineHandler extends AsyncResource {
     this.body = body
   }
 
-  onData (chunk) {
+  onResponseData (controller, chunk) {
     const { res } = this
-    return res.push(chunk)
+
+    if (res.push(chunk) === false) {
+      controller.pause()
+    }
   }
 
-  onComplete (trailers) {
+  onResponseEnd (_controller, _trailers) {
     const { res } = this
     res.push(null)
   }
 
-  onError (err) {
+  onResponseError (_controller, err) {
     const { ret } = this
     this.handler = null
     util.destroy(ret, err)

package/node_modules/undici/lib/api/api-request.js

@@ -21,7 +21,7 @@ class RequestHandler extends AsyncResource {
         throw new InvalidArgumentError('invalid callback')
       }
 
-      if (highWaterMark && (typeof highWaterMark !== 'number' || highWaterMark < 0)) {
+      if (highWaterMark != null && (!Number.isFinite(highWaterMark) || highWaterMark < 0)) {
         throw new InvalidArgumentError('invalid highWaterMark')
       }
 
@@ -54,6 +54,7 @@ class RequestHandler extends AsyncResource {
     this.body = body
     this.trailers = {}
     this.context = null
+    this.controller = null
     this.onInfo = onInfo || null
     this.highWaterMark = highWaterMark
     this.reason = null
@@ -73,36 +74,40 @@ class RequestHandler extends AsyncResource {
     }
   }
 
-  onConnect (abort, context) {
+  onRequestStart (controller, context) {
     if (this.reason) {
-      abort(this.reason)
+      controller.abort(this.reason)
       return
     }
 
     assert(this.callback)
 
-    this.abort = abort
+    this.controller = controller
+    this.abort = (reason) => controller.abort(reason)
     this.context = context
   }
 
-  onHeaders (statusCode, rawHeaders, resume, statusMessage) {
-    const { callback, opaque, abort, context, responseHeaders, highWaterMark } = this
+  onResponseStart (controller, statusCode, headers, statusText) {
+    const { callback, opaque, context, responseHeaders, highWaterMark } = this
 
-    const headers = responseHeaders === 'raw' ? util.parseRawHeaders(rawHeaders) : util.parseHeaders(rawHeaders)
+    const rawHeaders = controller?.rawHeaders
+    const responseHeaderData = responseHeaders === 'raw'
+      ? util.parseRawHeaders(rawHeaders)
+      : headers
 
     if (statusCode < 200) {
       if (this.onInfo) {
-        this.onInfo({ statusCode, headers })
+        this.onInfo({ statusCode, headers: responseHeaderData })
       }
       return
     }
 
-    const parsedHeaders = responseHeaders === 'raw' ? util.parseHeaders(rawHeaders) : headers
-    const contentType = parsedHeaders['content-type']
-    const contentLength = parsedHeaders['content-length']
+    const parsedHeaders = headers
+    const contentType = parsedHeaders?.['content-type']
+    const contentLength = parsedHeaders?.['content-length']
     const res = new Readable({
-      resume,
-      abort,
+      resume: () => controller.resume(),
+      abort: (reason) => controller.abort(reason),
       contentType,
       contentLength: this.method !== 'HEAD' && contentLength
         ? Number(contentLength)
@@ -121,8 +126,8 @@ class RequestHandler extends AsyncResource {
       try {
         this.runInAsyncScope(callback, null, null, {
           statusCode,
-          statusText: statusMessage,
-          headers,
+          statusText,
+          headers: responseHeaderData,
           trailers: this.trailers,
           opaque,
           body: res,
@@ -144,16 +149,35 @@ class RequestHandler extends AsyncResource {
     }
   }
 
-  onData (chunk) {
-    return this.res.push(chunk)
+  onResponseData (controller, chunk) {
+    if (!this.res) {
+      return
+    }
+
+    if (this.res.push(chunk) === false) {
+      controller.pause()
+    }
   }
 
-  onComplete (trailers) {
-    util.parseHeaders(trailers, this.trailers)
-    this.res.push(null)
+  onResponseEnd (_controller, trailers) {
+    if (trailers && typeof trailers === 'object') {
+      for (const key of Object.keys(trailers)) {
+        if (key === '__proto__') {
+          Object.defineProperty(this.trailers, key, {
+            value: trailers[key],
+            enumerable: true,
+            configurable: true,
+            writable: true
+          })
+        } else {
+          this.trailers[key] = trailers[key]
+        }
+      }
+    }
+    this.res?.push(null)
   }
 
-  onError (err) {
+  onResponseError (_controller, err) {
     const { res, callback, body, opaque } = this
 
     if (callback) {