@nxtedition/nxt-undici 7.4.1 → 7.4.3

package/lib/interceptor/response-error.js

@@ -10,6 +10,7 @@ class Handler extends DecoratorHandler {
   #body = ''
   #bodySize = 0
   #opts
+  #reason = null
 
   constructor(opts, { handler }) {
     super(handler)
@@ -23,8 +24,14 @@ class Handler extends DecoratorHandler {
     this.#headers = null
     this.#body = ''
     this.#bodySize = 0
-
-    super.onConnect(abort)
+    this.#reason = null
+
+    super.onConnect((reason) => {
+      // Remember the abort reason so onError can recognize it. The reason is
+      // owned by the caller (e.g. signal.reason) and must not be decorated.
+      this.#reason = reason ?? null
+      abort(reason)
+    })
   }
 
   onHeaders(statusCode, headers, resume) {
@@ -81,6 +88,16 @@ class Handler extends DecoratorHandler {
   }
 
   onError(err) {
+    // An abort reason is owned by the caller and may be shared by every
+    // request in flight on the same signal — decorating it in place would
+    // permanently mutate the caller's object and leak one request's req/res
+    // onto another request's rejection (last writer wins). Callers also rely
+    // on receiving the exact reason object, so pass it through untouched.
+    if (err != null && (err === this.#reason || err === this.#opts.signal?.reason)) {
+      super.onError(err)
+      return
+    }
+
     super.onError(
       decorateError(err, this.#opts, {
         statusCode: this.#statusCode || undefined,

package/lib/interceptor/response-retry.js

@@ -1,9 +1,96 @@
 import assert from 'node:assert'
 import tp from 'node:timers/promises'
-import { DecoratorHandler, isDisturbed, decorateError, parseContentRange } from '../utils.js'
+import {
+  DecoratorHandler,
+  isDisturbed,
+  decorateError,
+  parseContentRange,
+  parseHeaders,
+} from '../utils.js'
+import { RequestAbortedError } from '../errors.js'
+
+// Maximum number of >= 400 response body bytes buffered for replay in case
+// the response is not retried. Larger bodies are passed straight through and
+// the response is not status-code retried.
+const MAX_ERROR_BODY_SIZE = 256 * 1024
 
 function noop() {}
 
+// Subscribe `onAbort` to an EventEmitter-style OR EventTarget-style signal and
+// return an unsubscribe function; return null when it cannot be done safely.
+//
+// The caller (both sleep() and #backoff) must be able to unsubscribe once the
+// wait settles, so we require a MATCHING subscribe/unsubscribe PAIR up front:
+// subscribing with `on` but no `removeListener`/`off`, or `addEventListener`
+// but no `removeEventListener`, would crash later when we try to remove the
+// listener. request() validates signals up front (lib/request.js throws
+// InvalidArgumentError for anything without .on/.addEventListener), so garbage
+// only reaches here through a raw compose()/dispatch() caller — for that case
+// return null so the caller degrades to a plain timer instead of crashing.
+// A throwing subscribe is treated the same way.
+function subscribeAbort(signal, onAbort) {
+  const isEventTarget =
+    typeof signal.addEventListener === 'function' &&
+    typeof signal.removeEventListener === 'function'
+  const removeEmitterListener =
+    typeof signal.removeListener === 'function' ? signal.removeListener : signal.off
+  const isEmitter = typeof signal.on === 'function' && typeof removeEmitterListener === 'function'
+
+  if (!isEventTarget && !isEmitter) {
+    return null
+  }
+
+  try {
+    if (isEventTarget) {
+      signal.addEventListener('abort', onAbort)
+      return () => signal.removeEventListener('abort', onAbort)
+    }
+    signal.on('abort', onAbort)
+    return () => removeEmitterListener.call(signal, 'abort', onAbort)
+  } catch {
+    // A throwing subscribe leaves nothing to unsubscribe.
+    return null
+  }
+}
+
+// timers/promises.setTimeout only accepts a real AbortSignal and throws
+// ERR_INVALID_ARG_TYPE for anything else — but the library also accepts
+// EventEmitter-style abort signals (see RequestHandler in lib/request.js).
+// For those, race the backoff timer against the 'abort' event instead of
+// passing the signal through. When no complete subscribe/unsubscribe pair is
+// available (a raw dispatch() caller passing a bare object), fall back to a
+// plain timer rather than crash.
+function sleep(delay, signal) {
+  if (signal == null || signal instanceof AbortSignal) {
+    return tp.setTimeout(delay, true, { signal: signal ?? undefined })
+  }
+
+  if (signal.aborted) {
+    return Promise.reject(signal.reason ?? new RequestAbortedError())
+  }
+
+  return new Promise((resolve, reject) => {
+    let removeAbortListener = noop
+
+    const timer = setTimeout(() => {
+      removeAbortListener()
+      resolve(true)
+    }, delay)
+
+    const onAbort = () => {
+      clearTimeout(timer)
+      removeAbortListener()
+      reject(signal.reason ?? new RequestAbortedError())
+    }
+
+    // Decide the branch up front by verifying a matching add/remove pair;
+    // without one there is nothing to safely race against, so the already
+    // running plain timer completes the sleep. A throwing subscribe leaves
+    // removeAbortListener as noop, and the timer still resolves.
+    removeAbortListener = subscribeAbort(signal, onAbort) ?? noop
+  })
+}
+
 class Handler extends DecoratorHandler {
   #dispatch
   #opts
@@ -23,6 +110,7 @@ class Handler extends DecoratorHandler {
   #aborted = false
   #reason
   #resume
+  #retryAbortController = null
 
   #pos
   #end
@@ -60,11 +148,17 @@ class Handler extends DecoratorHandler {
       super.onConnect((reason) => {
         if (!this.#aborted) {
           this.#aborted = true
-          if (this.#abort) {
-            this.#abort(reason)
-          } else {
-            this.#reason = reason
-          }
+          // Always remember the reason: a downstream abort can land during the
+          // backoff wait between attempts, when #abort still points at the
+          // finished attempt's abort which undici has made a no-op. Without
+          // the recorded reason there is nothing to deliver once the retry
+          // machinery observes #aborted. Mirrors redirect.js.
+          this.#reason = reason
+          this.#abort?.(reason)
+          // Wake a pending backoff wait so the terminal onError is delivered
+          // promptly and the ref'd retry timer (up to 60s for retry-after)
+          // does not hold the event loop.
+          this.#retryAbortController?.abort(reason)
         }
       })
     }
@@ -121,18 +215,33 @@ class Handler extends DecoratorHandler {
         this.#end = contentLength
         this.#etag = headers.etag
       } else if (statusCode >= 400) {
+        if (
+          contentLength != null &&
+          contentLength > MAX_ERROR_BODY_SIZE &&
+          this.#opts.method !== 'HEAD'
+        ) {
+          // The error body is too large to buffer for a replay if the retry
+          // is declined. Pass it straight through instead of buffering —
+          // such a response is simply not status-code retried.
+          this.#headersSent = true
+          return super.onHeaders(statusCode, headers, resume)
+        }
+
         this.#body = []
         this.#bodySize = 0
+        this.#resume = resume
         return true
       } else {
         this.#headersSent = true
         return super.onHeaders(statusCode, headers, resume)
       }
 
+      // A duplicated etag response header arrives as an array, which has no
+      // startsWith and cannot be used for resumption — treat it as absent.
       // Weak etags are not useful for comparison nor cache
       // for instance not safe to assume if the response is byte-per-byte
       // equal
-      if (this.#etag != null && this.#etag.startsWith('W/')) {
+      if (this.#etag != null && (typeof this.#etag !== 'string' || this.#etag.startsWith('W/'))) {
         this.#etag = null
       }
 
@@ -158,6 +267,17 @@ class Handler extends DecoratorHandler {
         // permits ignoring Range; if-match still guards against changed
         // content via a 412.) Without this, a legal full 200 retry was
         // rejected with "Response retry failed".
+        //
+        // The server restarted the response from scratch, so the previous
+        // attempt's resume metadata no longer describes what we're receiving:
+        // refresh #end/#etag from THIS response's headers, otherwise a second
+        // failure would resume against the stale content-length/etag.
+        const contentLength = headers['content-length'] ? Number(headers['content-length']) : null
+        this.#end = Number.isFinite(contentLength) ? contentLength : null
+        // Same guard as the first-response path: only strong (non-weak),
+        // scalar etags are safe to use for resume validation.
+        this.#etag =
+          typeof headers.etag === 'string' && !headers.etag.startsWith('W/') ? headers.etag : null
         this.#resume = resume
         return true
       }
@@ -183,7 +303,17 @@ class Handler extends DecoratorHandler {
       // TODO (fix): What if we were paused before the error?
       return true
     } else {
-      this.#maybeError(this.#retryError)
+      // A resume attempt landed on an unexpected status (e.g. a 503 while
+      // resuming). #retryError describes the PREVIOUS failure — surfacing it
+      // as-is would report a stale error that says nothing about what just
+      // happened. Report the current status and keep the prior failure as
+      // the cause.
+      const err = new Error(
+        `Response retry failed with status code ${statusCode}`,
+        this.#retryError != null ? { cause: this.#retryError } : undefined,
+      )
+      err.statusCode = statusCode
+      this.#maybeError(err)
       return false
     }
   }
@@ -193,16 +323,32 @@ class Handler extends DecoratorHandler {
       this.#pos += chunk.byteLength
     }
 
-    if (this.#statusCode < 400) {
+    if (this.#statusCode < 400 || (this.#headersSent && !this.#errorSent)) {
       return super.onData(chunk)
     }
 
     if (this.#body) {
       this.#body.push(chunk)
       this.#bodySize += chunk.byteLength
-      if (this.#bodySize > 256 * 1024) {
+      if (this.#bodySize > MAX_ERROR_BODY_SIZE) {
+        // The error body has grown too large to buffer for a replay if the
+        // retry is declined. Flush the buffered chunks downstream and fall
+        // back to passing the response through — it is no longer
+        // status-code retried. Previously the buffer was discarded here,
+        // which made #maybeError replay headers followed by zero body bytes.
+        const body = this.#body
         this.#body = null
         this.#bodySize = 0
+
+        this.#headersSent = true
+        let ret = super.onHeaders(this.#statusCode, this.#headers, () => this.#resume?.())
+        for (const buffered of body) {
+          if (this.#aborted) {
+            return false
+          }
+          ret = super.onData(buffered)
+        }
+        return ret
       }
     }
   }
@@ -214,6 +360,12 @@ class Handler extends DecoratorHandler {
       return super.onComplete(trailers)
     }
 
+    if (this.#headersSent && !this.#errorSent) {
+      // The >= 400 response was passed through (too large to buffer for
+      // replay) — headers and data have already been forwarded downstream.
+      return super.onComplete(trailers)
+    }
+
     this.#maybeRetry(null)
   }
 
@@ -229,6 +381,18 @@ class Handler extends DecoratorHandler {
   }
 
   #maybeError(err) {
+    if (!err && this.#aborted) {
+      // Downstream aborted (e.g. during the backoff wait between attempts).
+      // The replay branches below are suppressed by the aborted
+      // DecoratorHandler, so without this no terminal event would ever reach
+      // downstream (raw dispatch would hang forever), or a generic
+      // 'Response retry failed' would replace the abort reason.
+      // DecoratorHandler.onError still forwards after an abort, so deliver
+      // the abort reason as the terminal onError (exactly once, guarded by
+      // #errorSent below).
+      err = this.#reason ?? new RequestAbortedError()
+    }
+
     if (err) {
       if (!this.#errorSent) {
         this.#errorSent = true
@@ -264,7 +428,22 @@ class Handler extends DecoratorHandler {
   }
 
   #maybeRetry(err) {
-    if (this.#aborted || isDisturbed(this.#opts.body) || (this.#pos && !this.#etag)) {
+    if (
+      this.#aborted ||
+      isDisturbed(this.#opts.body) ||
+      // Once headers have been forwarded, a range resume is the only option —
+      // but it is impossible when the response wasn't tracked for resumption
+      // (#pos == null, e.g. a trailer response or a passed-through >= 400
+      // body) or #end is not positive: zero means nothing left to request
+      // (`bytes=0--1` is invalid), negative means the server sent a bogus
+      // content-length (e.g. `-5`). A non-positive #end can enter both from
+      // the initial response and from a full-200 restart, so guard here at
+      // the single resume decision point, mirroring the precondition asserted
+      // below. Without this, the resume asserts would throw and be delivered
+      // to the user IN PLACE of the original error.
+      (this.#headersSent && (this.#pos == null || (this.#end != null && this.#end <= 0))) ||
+      (this.#pos && !this.#etag)
+    ) {
       this.#maybeError(err)
       return
     }
@@ -309,8 +488,29 @@ class Handler extends DecoratorHandler {
           assert(Number.isFinite(this.#pos))
           assert(this.#end == null || (Number.isFinite(this.#end) && this.#end > 0))
 
-          this.#opts = { ...this.#opts, headers: { ...this.#opts.headers } }
-          this.#opts.headers['if-match'] = this.#etag
+          // Direct dispatch()/compose() callers may pass undici's legal flat
+          // [name, value, ...] array headers; spreading that form would send
+          // garbage numeric header names ('0', '1', ...) on the wire instead
+          // of the real ones. Normalize to an object first (same as
+          // redirect.js does).
+          this.#opts = {
+            ...this.#opts,
+            headers: Array.isArray(this.#opts.headers)
+              ? parseHeaders(this.#opts.headers)
+              : { ...this.#opts.headers },
+          }
+          // A pos 0 resume is allowed without an etag (nothing was forwarded
+          // yet, so nothing can tear) — but then there is no etag to validate
+          // against. Only send if-match when we actually hold one; a null
+          // value would go on the wire as an invalid empty `if-match:` header.
+          // Delete any if-match a PREVIOUS resume attempt wrote first: the
+          // spread above copies it from the reassigned opts, and #etag may
+          // have been cleared since (e.g. a full-200 restart with a weak or
+          // missing etag) — the stale validator must not go on the wire.
+          delete this.#opts.headers['if-match']
+          if (typeof this.#etag === 'string') {
+            this.#opts.headers['if-match'] = this.#etag
+          }
           this.#opts.headers.range = `bytes=${this.#pos}-${this.#end ? this.#end - 1 : ''}`
           this.#opts.logger?.debug({ err, retryCount: this.#retryCount }, 'retry response body')
 
@@ -321,11 +521,67 @@ class Handler extends DecoratorHandler {
         }
       })
       .catch((err) => {
-        this.#maybeError(err)
+        // When the downstream abort cancelled the backoff timer, the timer's
+        // own AbortError rejection is just plumbing — deliver the recorded
+        // abort reason instead (falsy reasons are normalized in #maybeError).
+        this.#maybeError(this.#aborted ? this.#reason : err)
       })
   }
 
+  // Backoff wait that is abortable by the handler-chain abort (via the
+  // internal AbortController the onConnect wrapper aborts) AND by opts.signal —
+  // otherwise a downstream abort during the wait leaves a ref'd timer holding
+  // the event loop for up to 60s (retry-after).
+  //
+  // The internal controller's signal is always a real AbortSignal, so it is
+  // the single thing the wait races against:
+  //   - a real AbortSignal opts.signal is composed with AbortSignal.any (the
+  //     idiomatic path; a real AbortSignal already carries the add/remove pair
+  //     subscribeAbort would look for, so .any subsumes it), and
+  //   - an EventEmitter-style opts.signal (the library also accepts those, see
+  //     RequestHandler in lib/request.js) — which AbortSignal.any cannot take —
+  //     is bridged into the internal controller via the same crash-safe
+  //     subscribeAbort used by sleep(): its 'abort' aborts the controller with
+  //     the signal's reason. A signal with no complete subscribe/unsubscribe
+  //     pair (raw dispatch() garbage) yields no bridge and the wait is still
+  //     cancellable by the internal controller, so the retry proceeds.
+  // sleep() then takes its tp.setTimeout fast path on the resulting real
+  // AbortSignal.
+  #backoff(delay, opts) {
+    this.#retryAbortController ??= new AbortController()
+    const controller = this.#retryAbortController
+    const signal = opts?.signal
+
+    if (signal == null) {
+      return sleep(delay, controller.signal)
+    }
+
+    if (signal instanceof AbortSignal) {
+      return sleep(delay, AbortSignal.any([controller.signal, signal]))
+    }
+
+    if (signal.aborted) {
+      controller.abort(signal.reason ?? new RequestAbortedError())
+      return sleep(delay, controller.signal)
+    }
+
+    const removeAbortListener =
+      subscribeAbort(signal, () => controller.abort(signal.reason ?? new RequestAbortedError())) ??
+      noop
+    const wait = sleep(delay, controller.signal)
+    // Detach the bridge once the wait settles so an EE signal that outlives the
+    // backoff (e.g. aborted after a successful retry) is not still referenced.
+    return wait.finally(removeAbortListener)
+  }
+
   async #retryFn(err, retryCount, opts) {
+    if (this.#aborted) {
+      // A user retry callback may invoke this after downstream has already
+      // aborted — don't start a backoff timer that nothing will cancel.
+      // #maybeRetry's promise chain observes #aborted and delivers #reason.
+      return false
+    }
+
     let retryOpts = opts?.retry
 
     if (!retryOpts) {
@@ -362,7 +618,7 @@ class Handler extends DecoratorHandler {
             Math.min(retryAfter, 60e3)
           : Math.min(10e3, retryCount * 1e3)
       this.#opts.logger?.debug({ statusCode, retryAfter, delay, retryCount }, 'retry delay')
-      return tp.setTimeout(delay, true, { signal: opts?.signal ?? undefined })
+      return this.#backoff(delay, opts)
     }
 
     if (
@@ -383,16 +639,12 @@ class Handler extends DecoratorHandler {
       ].includes(err.code)
     ) {
       this.#opts.logger?.debug({ err, retryCount }, 'retry delay')
-      return tp.setTimeout(Math.min(10e3, retryCount * 1e3), true, {
-        signal: opts?.signal ?? undefined,
-      })
+      return this.#backoff(Math.min(10e3, retryCount * 1e3), opts)
     }
 
     if (err?.message && ['other side closed'].includes(err.message)) {
       this.#opts.logger?.debug({ err, retryCount }, 'retry delay')
-      return tp.setTimeout(Math.min(10e3, retryCount * 1e3), true, {
-        signal: opts?.signal ?? undefined,
-      })
+      return this.#backoff(Math.min(10e3, retryCount * 1e3), opts)
     }
 
     return false

package/lib/request.js

@@ -201,7 +201,11 @@ export function request(dispatch, urlOrOpts, optsOrNully) {
 
   let path = url.path
   if (!path) {
-    path = url.search ? `${url.pathname}${url.search}` : url.pathname
+    // URLObject marks every field optional; default the path so e.g.
+    // request({ origin }) works instead of undici rejecting with
+    // "path must be a string".
+    const pathname = url.pathname || '/'
+    path = url.search ? `${pathname}${url.search}` : pathname
   }
 
   opts = {