@nxtedition/nxt-undici 7.3.26 → 7.4.0

package/lib/index.d.ts

@@ -137,6 +137,61 @@ export interface LogInterceptorOptions {
   bindings?: Record<string, unknown>
 }
 
+export interface PressureInterceptorOptions {
+  /** Sampling interval for the internal EWMA loop, in ms (default 200).
+   *  Set to 0 to disable the internal timer and drive sampling yourself via
+   *  `sample()` from a loop you already run. */
+  sampleInterval?: number
+  /** EWMA time-constant in ms — the smoothing/desensitizing window (default 10000). */
+  tau?: number
+  /** Schmitt-trigger dead-band for `some` (shed discretionary work). */
+  someHi?: number
+  someLo?: number
+  /** Schmitt-trigger dead-band for `full` (pause the producer). */
+  fullHi?: number
+  fullLo?: number
+}
+
+export interface PressureStats {
+  /** Gauge: requests dispatched but not yet connected (waiting for a slot). */
+  pending: number
+  /** Gauge: requests connected and in-flight. */
+  running: number
+  /** Counter: cumulative settled requests (onComplete + onError). */
+  completed: number
+  /** EWMA in [0,1]: fraction of recent time the origin had a connection backlog. */
+  some: number
+  /** EWMA in [0,1]: fraction of recent time the origin made zero progress under backlog. */
+  full: number
+  /** Latched: shed discretionary work (engaged when `some` crosses `someHi`). */
+  shed: boolean
+  /** Latched: pause the producer (engaged when `full` crosses `fullHi`). */
+  paused: boolean
+}
+
+export interface PressureReading {
+  some: number
+  full: number
+  shed: boolean
+  paused: boolean
+}
+
+export interface PressureInterceptor {
+  (dispatch: DispatchFn): DispatchFn
+  /** Per-origin snapshot, or — with no argument — an array over every tracked origin. */
+  stats(origin: string): PressureStats | undefined
+  stats(): Array<PressureStats & { origin: string }>
+  /** Smoothed pressure for an origin (zeroed/false for an untracked origin). */
+  pressure(origin: string): PressureReading
+  /** `full` pauses everything; `some` sheds only discretionary (low-priority) work. */
+  shouldBackoff(origin: string, priority?: Priority): boolean
+  /** Manually tick the EWMA loop (for `sampleInterval: 0`). */
+  sample(): void
+  /** Stop the internal timer and drop all tracked origins. */
+  close(): void
+  [Symbol.dispose](): void
+}
+
 export interface CacheKey {
   origin: string
   method: string
@@ -230,6 +285,7 @@ export const interceptors: {
   dns: () => Interceptor
   lookup: () => Interceptor
   priority: () => Interceptor
+  pressure: (opts?: PressureInterceptorOptions) => PressureInterceptor
 }
 
 export const cache: {

package/lib/index.js

@@ -21,6 +21,7 @@ export const interceptors = {
   dns: (await import('./interceptor/dns.js')).default,
   lookup: (await import('./interceptor/lookup.js')).default,
   priority: (await import('./interceptor/priority.js')).default,
+  pressure: (await import('./interceptor/pressure.js')).default,
 }
 
 export const cache = {
@@ -139,7 +140,12 @@ function wrapDispatch(dispatcher) {
         }
 
         if (globalThis.__nxt_undici_global_headers) {
-          Object.assign(headers, globalThis.__nxt_undici_global_headers)
+          // Run global headers through parseHeaders too, so they share the
+          // pipeline invariant (lowercased names, stringified values) instead
+          // of landing verbatim with mixed-case keys or non-string values.
+          // parseHeaders into a fresh object keeps Object.assign's overwrite
+          // semantics (its two-arg form would append instead).
+          Object.assign(headers, parseHeaders(globalThis.__nxt_undici_global_headers))
         }
 
         return dispatch(
@@ -170,7 +176,14 @@ function wrapDispatch(dispatcher) {
             logger: opts.logger ?? null,
             dns: opts.dns ?? true,
             connect: opts.connect,
-            priority: opts.priority ?? headers['nxt-priority'],
+            // A duplicated nxt-priority request header parses to an array; the
+            // scheduler and PRIORITY_TOS_MAP expect a scalar, so take the last
+            // (last-wins). opts.priority, when set, is already scalar.
+            priority:
+              opts.priority ??
+              (Array.isArray(headers['nxt-priority'])
+                ? headers['nxt-priority'][headers['nxt-priority'].length - 1]
+                : headers['nxt-priority']),
             lookup: opts.lookup ?? defaultLookup,
           },
           handler,

package/lib/interceptor/cache.js

@@ -1,8 +1,8 @@
 import undici from '@nxtedition/undici'
-import { DecoratorHandler, parseCacheControl, parseContentRange } from '../utils.js'
+import { DecoratorHandler, getFastNow, parseCacheControl, parseContentRange } from '../utils.js'
 import { SqliteCacheStore } from '../sqlite-cache-store.js'
 
-const DEFAULT_STORE = new SqliteCacheStore({ location: ':memory:' })
+let DEFAULT_STORE = null
 const DEFAULT_MAX_ENTRY_SIZE = 128 * 1024
 const DEFAULT_MAX_ENTRY_TTL = 30 * 24 * 3600
 const NOOP = () => {}
@@ -40,18 +40,36 @@ class CacheHandler extends DecoratorHandler {
       return super.onHeaders(statusCode, headers, resume)
     }
 
-    if (headers.vary === '*' || headers.trailers) {
+    // 'trailer' is the RFC 9110 field name; 'trailers' is kept for backwards
+    // compatibility with servers that misspell it.
+    if (headers.vary === '*' || headers.trailer || headers.trailers) {
       // Not cacheble...
       return super.onHeaders(statusCode, headers, resume)
     }
 
+    if (headers['set-cookie']) {
+      // Shared cache: replaying Set-Cookie to other clients leaks sessions.
+      return super.onHeaders(statusCode, headers, resume)
+    }
+
     let contentRange
     if (headers['content-range']) {
       contentRange = parseContentRange(headers['content-range'])
-      if (contentRange === null) {
+      if (
+        contentRange == null ||
+        (contentRange.end != null &&
+          (contentRange.end <= contentRange.start ||
+            (contentRange.size != null && contentRange.end > contentRange.size)))
+      ) {
         // We don't support caching responses with invalid content-range...
         return super.onHeaders(statusCode, headers, resume)
       }
+      if (this.#key.method === 'HEAD') {
+        // A HEAD response delivers no body, so we never receive the byte
+        // window Content-Range describes — storing it would fail the store's
+        // body-length validation.
+        return super.onHeaders(statusCode, headers, resume)
+      }
     }
 
     let contentLength
@@ -104,6 +122,10 @@ class CacheHandler extends DecoratorHandler {
       }
 
       for (const key of headers.vary.split(',').map((key) => key.trim().toLowerCase())) {
+        if (key === '*') {
+          // RFC 9111 §4.1: a Vary field containing '*' never matches.
+          return super.onHeaders(statusCode, headers, resume)
+        }
         // Record every selecting header, using a null sentinel when it was
         // absent from the request. RFC 9111 §4.1: absent-vs-present is a
         // mismatch, so an empty vary object must NOT act as a wildcard that
@@ -218,23 +240,46 @@ export default () => (dispatch) => (opts, handler) => {
   }
 
   if (
-    cacheControlDirectives['max-age'] ||
-    cacheControlDirectives['max-stale'] ||
-    cacheControlDirectives['min-fresh'] ||
+    // != null: 'max-age=0' parses to 0 (falsy) but still demands revalidation.
+    cacheControlDirectives['max-age'] != null ||
     cacheControlDirectives['no-cache'] ||
-    cacheControlDirectives['stale-if-error']
+    cacheControlDirectives['stale-if-error'] != null ||
+    // cache-control-parser does not recognise 'max-stale'/'min-fresh', so
+    // check the raw string like we do for 'only-if-cached'.
+    (typeof rawCacheControl === 'string' &&
+      (rawCacheControl.includes('max-stale') || rawCacheControl.includes('min-fresh')))
   ) {
     // TODO (fix): Support all cache control directives...
     return dispatch(opts, handler)
   }
 
-  const store = opts.cache.store ?? DEFAULT_STORE
+  const store =
+    opts.cache.store ?? (DEFAULT_STORE ??= new SqliteCacheStore({ location: ':memory:' }))
 
   // TODO (fix): enable range requests
 
+  // Build the key the same way for lookups and stores: makeCacheKey
+  // stringifies the origin (e.g. URL objects), so using raw opts on the get
+  // path while the set path normalizes would make the cache permanently miss.
+  const key = undici.util.cache.makeCacheKey(opts)
+
+  // makeCacheKey preserves request header names verbatim. Vary selector names
+  // are lowercased (in onHeaders and matchesValue), so lowercase the key's
+  // header names once here — the same key feeds both the get and set paths, so
+  // this keeps Vary matching symmetric even when a caller supplies non-lowercase
+  // header names (the standalone interceptors.cache() composition; the wrapped
+  // pipeline already normalizes). A fresh object avoids mutating opts.headers.
+  if (key.headers && typeof key.headers === 'object') {
+    const lower = {}
+    for (const name in key.headers) {
+      lower[name.toLowerCase()] = key.headers[name]
+    }
+    key.headers = lower
+  }
+
   let entry
   try {
-    entry = store.get(opts)
+    entry = store.get(key)
   } catch (err) {
     if (err.message === 'database is locked') {
       // Database is busy. We don't bother trying again...
@@ -251,16 +296,34 @@ export default () => (dispatch) => (opts, handler) => {
   }
 
   // RFC 9110 Section 13: Evaluate conditional request headers against cached entry.
+  // typeof guards: duplicated conditional headers arrive as arrays — treat
+  // them as non-matching and bypass to origin rather than crashing.
   if (entry && opts.headers?.['if-none-match']) {
-    if (entry.etag && weakMatch(opts.headers['if-none-match'], entry.etag)) {
-      return serveFromCache({ statusCode: 304, headers: entry.headers }, opts, handler)
+    if (
+      typeof opts.headers['if-none-match'] === 'string' &&
+      entry.etag &&
+      weakMatch(opts.headers['if-none-match'], entry.etag)
+    ) {
+      return serveFromCache(
+        { statusCode: 304, headers: entry.headers, cachedAt: entry.cachedAt },
+        opts,
+        handler,
+      )
     }
     // Etag didn't match — bypass to origin.
     entry = undefined
   } else if (entry && opts.headers?.['if-modified-since']) {
     const lastModified = entry.headers?.['last-modified']
-    if (lastModified && new Date(lastModified) <= new Date(opts.headers['if-modified-since'])) {
-      return serveFromCache({ statusCode: 304, headers: entry.headers }, opts, handler)
+    if (
+      typeof opts.headers['if-modified-since'] === 'string' &&
+      lastModified &&
+      new Date(lastModified) <= new Date(opts.headers['if-modified-since'])
+    ) {
+      return serveFromCache(
+        { statusCode: 304, headers: entry.headers, cachedAt: entry.cachedAt },
+        opts,
+        handler,
+      )
     }
     // No last-modified or modified since — bypass to origin.
     entry = undefined
@@ -280,7 +343,7 @@ export default () => (dispatch) => (opts, handler) => {
       opts,
       cacheControlDirectives['no-store']
         ? handler
-        : new CacheHandler(undici.util.cache.makeCacheKey(opts), {
+        : new CacheHandler(key, {
             maxEntrySize: opts.cache.maxEntrySize,
             maxEntryTTL: opts.cache.maxEntryTTL,
             store,
@@ -294,11 +357,30 @@ export default () => (dispatch) => (opts, handler) => {
 }
 
 function serveFromCache(entry, opts, handler) {
-  const { statusCode, headers, trailers, body } = entry
+  const { statusCode, trailers, body } = entry
+
+  let headers = entry.headers
+  if (entry.cachedAt != null) {
+    // RFC 9111 §5.1: every response served from cache must carry an Age header
+    // reflecting time spent in this cache plus any age it arrived with —
+    // otherwise downstream caches treat it as fresh-from-origin.
+    // getFastNow has 1s resolution — Age is whole seconds, so that's enough.
+    const residentAge = Math.max(0, Math.floor((getFastNow() - entry.cachedAt) / 1000))
+    const originAge = Number(headers?.age)
+    const age = Number.isFinite(originAge) && originAge > 0 ? originAge + residentAge : residentAge
+    headers = { ...headers, age: `${age}` }
+  }
 
+  // serveFromCache drives the raw user handler directly (no DecoratorHandler),
+  // so it must enforce the contract itself: onError is terminal and mutually
+  // exclusive with onComplete. The `completed` guard makes a late abort() a
+  // no-op, and onComplete runs outside the try so a throw from the user's
+  // terminal callback propagates instead of being converted into a second
+  // (post-complete) onError.
   let aborted = false
+  let completed = false
   const abort = (reason) => {
-    if (!aborted) {
+    if (!aborted && !completed) {
       aborted = true
       handler.onError(reason)
     }
@@ -324,11 +406,13 @@ function serveFromCache(entry, opts, handler) {
         return
       }
     }
-
-    handler.onComplete(trailers ?? {})
   } catch (err) {
     abort(err)
+    return
   }
+
+  completed = true
+  handler.onComplete(trailers ?? {})
 }
 
 /**

package/lib/interceptor/dns.js

@@ -30,10 +30,29 @@ class Handler extends DecoratorHandler {
   }
 }
 
+const SWEEP_INTERVAL = 30e3
+
 export default () => (dispatch) => {
   const cache = new Map()
   const promises = new Map()
 
+  // The `cache` Map is otherwise only ever written, never trimmed, so a process
+  // touching many distinct hostnames over its lifetime would leak entries that
+  // can never be selected again. Sweep dead entries (all records expired and
+  // none in flight) at most once per SWEEP_INTERVAL to bound the O(n) cost.
+  let lastSweep = 0
+  function sweep(now) {
+    if (now - lastSweep < SWEEP_INTERVAL) {
+      return
+    }
+    lastSweep = now
+    for (const [hostname, records] of cache) {
+      if (records.every((x) => x.expires < now && x.pending === 0)) {
+        cache.delete(hostname)
+      }
+    }
+  }
+
   function resolve(hostname, { ttl }) {
     let promise = promises.get(hostname)
     if (!promise) {
@@ -84,6 +103,8 @@ export default () => (dispatch) => {
 
       const now = getFastNow()
 
+      sweep(now)
+
       let records = cache.get(hostname)
 
       if (records == null || records.every((x) => x.expires < now)) {

package/lib/interceptor/lookup.js

@@ -1,3 +1,5 @@
+import { DecoratorHandler } from '../utils.js'
+
 export default () => (dispatch) => async (opts, handler) => {
   const lookup = opts.lookup
 
@@ -5,6 +7,12 @@ export default () => (dispatch) => async (opts, handler) => {
     return dispatch(opts, handler)
   }
 
+  // Wrap so the catch below can't deliver a second onError: if a downstream
+  // layer already reported a terminal callback and then let an error escape
+  // dispatch synchronously, DecoratorHandler's #errored/#completed guards
+  // absorb the duplicate instead of violating the once-only onError contract.
+  const wrapped = new DecoratorHandler(handler)
+
   try {
     const origin = await new Promise((resolve, reject) => {
       const thenable = lookup(opts.origin, { signal: opts.signal ?? undefined }, (err, val) => {
@@ -24,8 +32,8 @@ export default () => (dispatch) => async (opts, handler) => {
       throw new Error('invalid origin: ' + origin)
     }
 
-    return dispatch({ ...opts, origin }, handler)
+    return dispatch({ ...opts, origin }, wrapped)
   } catch (err) {
-    handler.onError(err)
+    wrapped.onError(err)
   }
 }

package/lib/interceptor/pressure.js

@@ -0,0 +1,317 @@
+import { parsePriority, Scheduler } from '@nxtedition/scheduler'
+import { DecoratorHandler } from '../utils.js'
+
+// Reconstruct a PSI-style pressure signal per origin from the request lifecycle
+// this interceptor observes, then expose latched flags so producers can back
+// off. See @nxtedition/scheduler's README ("Pressure & backoff: utilization is
+// the wrong trigger"): a resource can be 100% utilized with ~0 pressure — what
+// you must throttle on is the fraction of time runnable work is *stalled*, not
+// how busy you are.
+//
+// The HTTP analogue of the scheduler's `pending > 0 && saturated` is simply
+// `pending > 0`: undici leaves a request un-connected (`pending`, in our
+// accounting: dispatched but no `onConnect` yet) *only* when it has no free
+// connection slot to place it on. The instant a slot frees, the queued request
+// connects. So a standing `pending > 0` already means "backlog AND no free
+// capacity" — a busy-but-keeping-up origin drains `pending` back to 0 between
+// samples and scores 0, exactly the healthy-saturation false positive the naive
+// `running/concurrency` recipe fires on.
+//
+//  - some (PSI "some"): at least one request waiting for a connection -> shed
+//    discretionary work.
+//  - full (PSI "full"): a backlog AND zero completions this window -> nothing is
+//    making progress (origin hung / all sockets stuck) -> pause the producer.
+//
+// Two independent defenses give "sensitive to real overload, not so twitchy it
+// flaps": the predicate filters healthy saturation before it enters the signal,
+// and the EWMA window + Schmitt-trigger dead-band (engage high, release low) is
+// the oomd-style sustained-duration requirement.
+
+const EPS = 1e-3
+
+// Smallest priority that is still "discretionary" — sheddable under `some`
+// pressure. low/lower/lowest (<= -1); normal and above are never shed.
+function isDiscretionary(priority) {
+  if (priority == null) {
+    return false
+  }
+  try {
+    return parsePriority(priority) <= Scheduler.LOW
+  } catch {
+    return false
+  }
+}
+
+class PressureMonitor {
+  #origins = new Map()
+  /** @type {ReturnType<typeof setInterval> | null} */
+  #timer = null
+
+  #sampleInterval
+  #tau
+  #someHi
+  #someLo
+  #fullHi
+  #fullLo
+
+  constructor({
+    sampleInterval = 200,
+    tau = 10_000,
+    someHi = 0.5,
+    someLo = 0.2,
+    fullHi = 0.3,
+    fullLo = 0.1,
+  } = {}) {
+    this.#sampleInterval = sampleInterval
+    this.#tau = tau
+    this.#someHi = someHi
+    this.#someLo = someLo
+    this.#fullHi = fullHi
+    this.#fullLo = fullLo
+  }
+
+  // Called from the interceptor on each dispatch to get (or lazily create) the
+  // per-origin record the handler mutates as the request progresses. The
+  // `pending` increment is done by the Handler constructor, not here, so it is
+  // tied to a *successfully* constructed handler: a handler that fails
+  // validation (DecoratorHandler throws on a non-object handler) never leaves a
+  // phantom pending count wedging the origin under pressure. A record created
+  // here but never incremented is harmless — it reports no pressure and is
+  // evicted on the next idle tick.
+  track(key) {
+    let rec = this.#origins.get(key)
+    if (rec == null) {
+      rec = {
+        pending: 0, // gauge: dispatched, awaiting onConnect (waiting for a slot)
+        running: 0, // gauge: connected and in-flight
+        completed: 0, // counter: cumulative settled (onComplete + onError)
+        prevCompleted: 0, // snapshot of `completed` at the previous sample
+        some: 0, // EWMA: fraction of recent time `someNow` held
+        full: 0, // EWMA: fraction of recent time `fullNow` held
+        shed: false, // latched: shed discretionary work
+        paused: false, // latched: pause the producer
+        lastSample: performance.now(),
+      }
+      this.#origins.set(key, rec)
+    }
+    this.#ensureTimer()
+    return rec
+  }
+
+  // One sample -> instantaneous "stalled right now?" per level, smoothed into
+  // loadavg-shaped EWMAs with a dt-aware gain (keeps the time-constant honest
+  // under a jittery loop). Counters (completed) carry the `full` decision so a
+  // burst that fills and drains between two samples can't alias it away.
+  #sample(rec, now) {
+    const dt = now - rec.lastSample
+    if (dt <= 0) {
+      return
+    }
+    rec.lastSample = now
+
+    const someNow = rec.pending > 0
+    const progressed = rec.completed - rec.prevCompleted > 0
+    const fullNow = someNow && !progressed
+    rec.prevCompleted = rec.completed
+
+    const a = 1 - Math.exp(-dt / this.#tau)
+    rec.some += a * ((someNow ? 1 : 0) - rec.some)
+    rec.full += a * ((fullNow ? 1 : 0) - rec.full)
+
+    // Hysteresis: engage high, release low.
+    if (!rec.shed && rec.some > this.#someHi) {
+      rec.shed = true
+    } else if (rec.shed && rec.some < this.#someLo) {
+      rec.shed = false
+    }
+    if (!rec.paused && rec.full > this.#fullHi) {
+      rec.paused = true
+    } else if (rec.paused && rec.full < this.#fullLo) {
+      rec.paused = false
+    }
+  }
+
+  // Tick every tracked origin, then evict any that is fully idle and has decayed
+  // back to ~0 on both levels, so a client touching many origins doesn't
+  // accumulate records forever. Stop the timer once nothing is tracked.
+  #tick() {
+    const now = performance.now()
+    for (const [key, rec] of this.#origins) {
+      this.#sample(rec, now)
+      if (rec.pending === 0 && rec.running === 0 && rec.some < EPS && rec.full < EPS) {
+        this.#origins.delete(key)
+      }
+    }
+    if (this.#origins.size === 0 && this.#timer != null) {
+      clearInterval(this.#timer)
+      this.#timer = null
+    }
+  }
+
+  #ensureTimer() {
+    if (this.#timer == null && this.#sampleInterval > 0 && this.#origins.size > 0) {
+      this.#timer = setInterval(() => this.#tick(), this.#sampleInterval)
+      // Never keep the event loop alive just to sample — the producer's own
+      // activity is what matters.
+      this.#timer.unref?.()
+    }
+  }
+
+  // Manual tick, for callers that disable the internal timer (sampleInterval: 0)
+  // and drive sampling from a loop they already run (health check, metrics
+  // scrape) — the scheduler README's preferred "the loop is YOURS" pattern.
+  sample() {
+    this.#tick()
+  }
+
+  #snapshot(rec) {
+    return {
+      pending: rec.pending,
+      running: rec.running,
+      completed: rec.completed,
+      some: rec.some,
+      full: rec.full,
+      shed: rec.shed,
+      paused: rec.paused,
+    }
+  }
+
+  // No arg -> array of { origin, ...snapshot } for every tracked origin (a
+  // metrics scrape). With an origin -> that origin's snapshot, or undefined if
+  // it isn't being tracked (never seen, or evicted after going idle).
+  stats(origin) {
+    if (origin == null) {
+      const out = []
+      for (const [key, rec] of this.#origins) {
+        out.push({ origin: key, ...this.#snapshot(rec) })
+      }
+      return out
+    }
+    const rec = this.#origins.get(origin)
+    return rec ? this.#snapshot(rec) : undefined
+  }
+
+  // The smoothed pressure for an origin. An untracked origin is, by definition,
+  // not under pressure.
+  pressure(origin) {
+    const rec = this.#origins.get(origin)
+    return rec
+      ? { some: rec.some, full: rec.full, shed: rec.shed, paused: rec.paused }
+      : { some: 0, full: 0, shed: false, paused: false }
+  }
+
+  // Producer-side gate mirroring the README's `submit` recipe: `full` pauses
+  // everything; `some` sheds only discretionary (low-priority) work.
+  shouldBackoff(origin, priority) {
+    const rec = this.#origins.get(origin)
+    if (rec == null) {
+      return false
+    }
+    if (rec.paused) {
+      return true
+    }
+    if (rec.shed) {
+      return isDiscretionary(priority)
+    }
+    return false
+  }
+
+  close() {
+    if (this.#timer != null) {
+      clearInterval(this.#timer)
+      this.#timer = null
+    }
+    this.#origins.clear()
+  }
+
+  [Symbol.dispose]() {
+    this.close()
+  }
+}
+
+class Handler extends DecoratorHandler {
+  #rec
+  // 'pending' (awaiting onConnect) -> 'running' (connected) -> 'done' (settled).
+  // Tracked here so each transition fires exactly once regardless of how many
+  // times onConnect is invoked (e.g. a retry handler upstream) or which
+  // terminal callback fires.
+  #state = 'pending'
+
+  constructor(handler, rec) {
+    // super() validates the handler and throws on a non-object before we touch
+    // the gauge, so a rejected handler can't leak a pending count.
+    super(handler)
+    this.#rec = rec
+    rec.pending += 1
+  }
+
+  onConnect(abort) {
+    if (this.#state === 'pending') {
+      this.#state = 'running'
+      this.#rec.pending -= 1
+      this.#rec.running += 1
+    }
+    super.onConnect(abort)
+  }
+
+  onComplete(trailers) {
+    this.#settle()
+    super.onComplete(trailers)
+  }
+
+  onError(err) {
+    this.#settle()
+    super.onError(err)
+  }
+
+  #settle() {
+    if (this.#state === 'done') {
+      return
+    }
+    if (this.#state === 'pending') {
+      this.#rec.pending -= 1
+    } else {
+      this.#rec.running -= 1
+    }
+    this.#rec.completed += 1
+    this.#state = 'done'
+  }
+}
+
+export default (opts) => {
+  const monitor = new PressureMonitor(opts)
+
+  const interceptor = (dispatch) => (opts, handler) => {
+    if (!opts.origin) {
+      return dispatch(opts, handler)
+    }
+
+    // Key on opts.origin — the logical origin the caller knows and queries by.
+    // Compose this interceptor *ahead of* (outer to) `dns()` so opts.origin is
+    // still the logical host rather than a rotating resolved IP.
+    const key = opts.origin
+
+    const rec = monitor.track(key)
+    // Construct before the try: a handler that fails validation throws straight
+    // to the caller (as with any DecoratorHandler-based interceptor) and, since
+    // the constructor increments `pending` only on success, leaks nothing.
+    const pressureHandler = new Handler(handler, rec)
+
+    try {
+      return dispatch(opts, pressureHandler)
+    } catch (err) {
+      pressureHandler.onError(err)
+    }
+  }
+
+  // The monitor is owned by the interceptor instance; surface its read API on
+  // the composed function so callers hold a single handle.
+  interceptor.stats = (origin) => monitor.stats(origin)
+  interceptor.pressure = (origin) => monitor.pressure(origin)
+  interceptor.shouldBackoff = (origin, priority) => monitor.shouldBackoff(origin, priority)
+  interceptor.sample = () => monitor.sample()
+  interceptor.close = () => monitor.close()
+  interceptor[Symbol.dispose] = () => monitor.close()
+
+  return interceptor
+}

package/lib/interceptor/priority.js

@@ -3,10 +3,12 @@ import { DecoratorHandler } from '../utils.js'
 
 class Handler extends DecoratorHandler {
   #scheduler
+  #onIdle
 
-  constructor(handler, scheduler) {
+  constructor(handler, scheduler, onIdle) {
     super(handler)
     this.#scheduler = scheduler
+    this.#onIdle = onIdle
   }
 
   onConnect(abort) {
@@ -29,6 +31,7 @@ class Handler extends DecoratorHandler {
       const scheduler = this.#scheduler
       this.#scheduler = null
       scheduler.release()
+      this.#onIdle?.()
     }
   }
 }
@@ -41,13 +44,29 @@ export default () => (dispatch) => {
       return dispatch(opts, handler)
     }
 
-    let scheduler = schedulers.get(opts.origin)
+    // Key on the logical origin, not opts.origin: an outer dns interceptor
+    // rewrites opts.origin to a rotating resolved IP, which would scatter one
+    // logical host across many schedulers and silently defeat the per-origin
+    // concurrency limit. dns preserves the logical host in the `host` header.
+    const key = (typeof opts.headers?.host === 'string' && opts.headers.host) || opts.origin
+
+    let scheduler = schedulers.get(key)
     if (!scheduler) {
       scheduler = new Scheduler({ concurrency: 1 })
-      schedulers.set(opts.origin, scheduler)
+      schedulers.set(key, scheduler)
+    }
+
+    // Evict a scheduler once it has fully drained, so a client touching many
+    // distinct origins doesn't accumulate them forever. The `=== scheduler`
+    // guard avoids deleting a freshly-created replacement; release() drains
+    // pending synchronously, so running===0 && pending===0 here means idle.
+    const onIdle = () => {
+      if (schedulers.get(key) === scheduler && scheduler.running === 0 && scheduler.pending === 0) {
+        schedulers.delete(key)
+      }
     }
 
-    const priorityHandler = new Handler(handler, scheduler)
+    const priorityHandler = new Handler(handler, scheduler, onIdle)
     scheduler.acquire(
       (priorityHandler) => {
         try {

package/lib/interceptor/proxy.js

@@ -31,7 +31,10 @@ class Handler extends DecoratorHandler {
         {
           headers,
           httpVersion: this.#opts.httpVersion ?? this.#opts.req?.httpVersion,
-          socket: this.#opts.socket,
+          // Response path: never synthesize a Forwarded header (it is
+          // request-only, RFC 7239) — passing socket would leak the proxy's
+          // own addresses downstream. isResponse still rejects an inbound one.
+          isResponse: true,
           proxyName: this.#opts.name,
         },
         copyHeader,
@@ -48,7 +51,7 @@ class Handler extends DecoratorHandler {
         {
           headers,
           httpVersion: this.#opts.httpVersion ?? this.#opts.req?.httpVersion,
-          socket: this.#opts.socket,
+          isResponse: true,
           proxyName: this.#opts.name,
         },
         copyHeader,
@@ -134,15 +137,18 @@ function isHopByHop(key) {
  * @param {string} [options.httpVersion] Protocol token for the appended Via
  *   segment; defaults to `'HTTP/1.1'`.
  * @param {{ localAddress?: string, localPort?: number, remoteAddress?: string,
- *   remotePort?: number, encrypted?: boolean } | null} [options.socket] When
- *   present a Forwarded header is synthesised; when absent an inbound Forwarded
- *   header is treated as a BadGateway.
+ *   remotePort?: number, encrypted?: boolean } | null} [options.socket] Request
+ *   path only: when present a Forwarded header is synthesised. An inbound
+ *   Forwarded header is always treated as a BadGateway (it is request-only).
+ * @param {boolean} [options.isResponse] Response path marker. When set,
+ *   Forwarded is never synthesised regardless of `socket` (it would leak the
+ *   proxy's own addresses downstream); an inbound Forwarded is still rejected.
  * @param {(acc: T, key: string, value: string) => T} fn Accumulator invoked
  *   once per retained header.
  * @param {T} acc Initial accumulator value.
  * @returns {T}
  */
-function reduceHeaders({ headers, proxyName, httpVersion, socket }, fn, acc) {
+function reduceHeaders({ headers, proxyName, httpVersion, socket, isResponse }, fn, acc) {
   let via = ''
   let forwarded = ''
   let host = ''
@@ -163,14 +169,20 @@ function reduceHeaders({ headers, proxyName, httpVersion, socket }, fn, acc) {
   // the parts are semantically one comma-separated value — those we combine.
   // Singular fields with more than one value are a protocol error — those we
   // reject.
+  //
+  // Field names are case-insensitive (RFC 7230). The production path lowercases
+  // keys (parseHeaders) before this runs, but the standalone interceptors.proxy()
+  // composition may pass mixed-case keys, so capture case-insensitively via the
+  // allocation-free eqiLower — otherwise a mixed-case `Forwarded`/`Connection`/
+  // `Via`/`Host` would skip capture and leak/bypass the handling below.
   for (let i = 0; i < keys.length; i++) {
     const key = keys[i]
     const len = key.length
-    if (len === 3 && key === 'via') {
+    if (len === 3 && eqiLower(key, 'via')) {
       // Via is list-valued (RFC 9110 §7.6.3): combine repeated field-lines.
       const v = headers[key]
       via = Array.isArray(v) ? v.join(', ') : v
-    } else if (len === 4 && key === 'host') {
+    } else if (len === 4 && eqiLower(key, 'host')) {
       // Host is singular (RFC 9110 §7.2, RFC 7230 §5.4): more than one is a
       // protocol error, so reject rather than combine.
       const v = headers[key]
@@ -178,16 +190,17 @@ function reduceHeaders({ headers, proxyName, httpVersion, socket }, fn, acc) {
         throw new createError.BadGateway()
       }
       host = v
-    } else if (len === 9 && key === 'forwarded') {
+    } else if (len === 9 && eqiLower(key, 'forwarded')) {
       // Forwarded is list-valued (RFC 7239 §4): combine repeated field-lines.
       const v = headers[key]
       forwarded = Array.isArray(v) ? v.join(', ') : v
-    } else if (len === 10 && key === 'connection') {
+    } else if (len === 10 && eqiLower(key, 'connection')) {
       // Connection is list-valued (RFC 9110 §7.6.1): captured raw and tokenised
       // below — combining then re-splitting would be wasteful.
       connection = headers[key]
     } else if (len === 10 && key === ':authority') {
-      // :authority is singular (RFC 9113 §8.3.1): reject more than one.
+      // :authority is singular (RFC 9113 §8.3.1): reject more than one. Pseudo
+      // headers are always lowercase, so an exact compare is correct here.
       const v = headers[key]
       if (Array.isArray(v)) {
         throw new createError.BadGateway()
@@ -229,16 +242,26 @@ function reduceHeaders({ headers, proxyName, httpVersion, socket }, fn, acc) {
 
   for (let i = 0; i < keys.length; i++) {
     const key = keys[i]
+    const len = key.length
     if (
       key.charCodeAt(0) !== 0x3a /* ':' */ &&
-      (remove === null || !remove.includes(key)) &&
+      // via/forwarded are captured above and (re)emitted by the dedicated
+      // finalization below; letting the retain loop also emit them leaks an
+      // empty inbound value (e.g. `via: ''`) that the `if (via)` guard then
+      // never overwrites, and bypasses the Forwarded BadGateway rejection.
+      // Case-insensitive (eqiLower) to match the case-insensitive capture above.
+      !(len === 3 && eqiLower(key, 'via')) &&
+      !(len === 9 && eqiLower(key, 'forwarded')) &&
+      // toLowerCase: `remove` entries are lowercased but keys may not be (the
+      // standalone interceptor path), so match case-insensitively like isHopByHop.
+      (remove === null || !remove.includes(key.toLowerCase())) &&
       !isHopByHop(key)
     ) {
       acc = fn(acc, key, headers[key].toString())
     }
   }
 
-  if (socket) {
+  if (!isResponse && socket) {
     const forwardedHost = authority || host
     acc = fn(
       acc,
@@ -254,7 +277,8 @@ function reduceHeaders({ headers, proxyName, httpVersion, socket }, fn, acc) {
           .join(';'),
     )
   } else if (forwarded) {
-    // The forwarded header should not be included in response.
+    // Forwarded is a request-only header (RFC 7239): a proxy must neither emit
+    // it on a response nor relay one an upstream echoed back.
     throw new createError.BadGateway()
   }
 

package/lib/interceptor/query.js

@@ -11,6 +11,12 @@ export default () => (dispatch) => (opts, handler) => {
 }
 
 function serializePathWithQuery(url, queryParams) {
+  if (typeof url !== 'string') {
+    // A path-less object URL leaves opts.path undefined; fail with a clear
+    // message instead of a cryptic "Cannot read properties of undefined".
+    throw new Error('Query params require a string path.')
+  }
+
   if (url.includes('?') || url.includes('#')) {
     throw new Error('Query params cannot be passed when url already contains "?" or "#".')
   }

package/lib/interceptor/redirect.js

@@ -1,5 +1,5 @@
 import assert from 'node:assert'
-import { DecoratorHandler, isDisturbed, parseURL } from '../utils.js'
+import { DecoratorHandler, isDisturbed, parseURL, parseHeaders } from '../utils.js'
 
 const redirectableStatusCodes = [300, 301, 302, 303, 307, 308]
 
@@ -21,15 +21,23 @@ class Handler extends DecoratorHandler {
 
     this.#dispatch = dispatch
     this.#opts = opts
-    this.#maxCount = Number.isFinite(opts.follow) ? opts.follow : (opts.follow?.count ?? 0)
+    // `follow: true` means "follow redirects" — map it to the project default
+    // cap rather than letting `true.count ?? 0` collapse to 0, which would
+    // reject the very first redirect with "Max redirections reached: 0".
+    this.#maxCount =
+      opts.follow === true
+        ? 8
+        : Number.isFinite(opts.follow)
+          ? opts.follow
+          : (opts.follow?.count ?? 0)
 
     super.onConnect((reason) => {
       this.#aborted = true
-      if (this.#abort) {
-        this.#abort(reason)
-      } else {
-        this.#reason = reason
-      }
+      // Always remember the latest reason so it survives a caller abort that
+      // lands in the window between one hop completing and the next hop's
+      // onConnect; #abort may still point at the finished hop's no-op abort.
+      this.#reason = reason
+      this.#abort?.(reason)
     })
   }
 
@@ -73,7 +81,11 @@ class Handler extends DecoratorHandler {
         return super.onHeaders(statusCode, headers, resume)
       }
     } else {
-      if (this.#count >= this.#maxCount) {
+      // `follow: N` follows up to N redirects and errors on the N+1th, matching
+      // undici/fetch maxRedirections semantics. `>` (not `>=`): with `>=`,
+      // `follow: 1` threw on the very first redirect with a self-contradictory
+      // "Max redirections reached: 1." message.
+      if (this.#count > this.#maxCount) {
         throw Object.assign(new Error(`Max redirections reached: ${this.#maxCount}.`), {
           history: this.#history,
         })
@@ -181,6 +193,13 @@ function shouldRemoveHeader(header, removeContent, unknownOrigin) {
 // https://tools.ietf.org/html/rfc7231#section-6.4
 function cleanRequestHeaders(headers, removeContent, unknownOrigin) {
   const ret = {}
+  if (Array.isArray(headers)) {
+    // undici accepts request headers as a flat [name, value, ...] array.
+    // Object.keys on that yields numeric indices, not field names, so the
+    // strip checks below would never match and the headers would be mangled
+    // into { '0': name, '1': value, ... }. Normalize to an object first.
+    headers = parseHeaders(headers)
+  }
   if (headers && typeof headers === 'object') {
     for (const key of Object.keys(headers)) {
       if (!shouldRemoveHeader(key, removeContent, unknownOrigin)) {

package/lib/interceptor/request-body-factory.js

@@ -1,4 +1,4 @@
-import { Readable } from 'node:stream'
+import { Readable, finished } from 'node:stream'
 import { isStream } from '../utils.js'
 
 function noop() {}
@@ -38,9 +38,16 @@ class FactoryStream extends Readable {
               .on('end', () => {
                 this.push(null)
               })
-              .on('error', (err) => {
+            // `finished` (not a bare 'error' listener) so a premature close —
+            // the inner body destroyed without emitting 'end' or 'error', which
+            // surfaces only as 'close' — becomes ERR_STREAM_PREMATURE_CLOSE and
+            // fails the request, instead of hanging forever with no terminal
+            // push(null). writable:false: these inner bodies are read-only.
+            finished(this.#body, { writable: false }, (err) => {
+              if (err) {
                 this.destroy(err)
-              })
+              }
+            })
           }
 
           callback(null)

package/lib/interceptor/request-id.js

@@ -12,8 +12,15 @@ function genReqId() {
 }
 
 export default () => (dispatch) => (opts, handler) => {
-  const prevId = opts.id ?? opts.headers?.['request-id']
-  const nextId = prevId ? `${prevId},${genReqId()}` : genReqId()
+  // Treat an empty string the same as absent in BOTH the selection and the
+  // chaining test (the old `??`-vs-truthy split kept a falsy opts.id, skipped
+  // the request-id header fallback, then dropped it anyway — losing a real
+  // parent id and breaking trace correlation).
+  let prevId = opts.id
+  if (prevId == null || prevId === '') {
+    prevId = opts.headers?.['request-id']
+  }
+  const nextId = prevId != null && prevId !== '' ? `${prevId},${genReqId()}` : genReqId()
   return dispatch(
     {
       ...opts,

package/lib/interceptor/response-error.js

@@ -35,10 +35,12 @@ class Handler extends DecoratorHandler {
       return super.onHeaders(statusCode, headers, resume)
     }
 
-    if (
-      this.#headers['content-type']?.startsWith('application/json') ||
-      this.#headers['content-type']?.startsWith('text/plain')
-    ) {
+    // A duplicated content-type header is an array; .startsWith would throw
+    // synchronously out of this parser callback. Coerce to the first value.
+    const contentType = Array.isArray(this.#headers['content-type'])
+      ? this.#headers['content-type'][0]
+      : this.#headers['content-type']
+    if (contentType?.startsWith('application/json') || contentType?.startsWith('text/plain')) {
       this.#decoder = new TextDecoder('utf-8')
       this.#body = ''
     }

package/lib/interceptor/response-verify.js

@@ -29,7 +29,13 @@ class Handler extends DecoratorHandler {
   }
 
   onHeaders(statusCode, headers, resume) {
-    this.#contentMD5 = this.#verifyOpts.hash ? headers['content-md5'] : null
+    // A duplicated Content-MD5 header arrives as an array. Several identical
+    // copies (a CDN/proxy re-appending its own) describe the same digest, so
+    // collapse them to one; genuinely conflicting copies are kept as an array
+    // so the strict comparison in onComplete still fails. A non-array (the
+    // common single-header case) is used verbatim.
+    const md5 = this.#verifyOpts.hash ? headers['content-md5'] : null
+    this.#contentMD5 = Array.isArray(md5) && md5.every((v) => v === md5[0]) ? md5[0] : md5
 
     if (this.#verifyOpts.size) {
       const contentRange = parseContentRange(headers['content-range'])

package/lib/request.js

@@ -188,7 +188,9 @@ export function request(dispatch, urlOrOpts, optsOrNully) {
     const protocol = url.protocol ?? 'http:'
     const host =
       url.host ??
-      (url.hostname ? `${url.hostname}:${url.port ?? (protocol === 'https:' ? 443 : 80)}` : null)
+      // `||` not `??`: an empty-string port must fall back to the default,
+      // matching defaultLookup; `??` would yield a trailing-colon origin.
+      (url.hostname ? `${url.hostname}:${url.port || (protocol === 'https:' ? 443 : 80)}` : null)
 
     if (!host || !protocol) {
       throw new InvalidArgumentError('invalid url')
@@ -209,5 +211,16 @@ export function request(dispatch, urlOrOpts, optsOrNully) {
     body: isStream(opts?.body) && opts.body.closed ? null : opts?.body,
   }
 
-  return new Promise((resolve) => dispatch(opts, new RequestHandler(opts, resolve)))
+  return new Promise((resolve) => {
+    const handler = new RequestHandler(opts, resolve)
+    try {
+      dispatch(opts, handler)
+    } catch (err) {
+      // A synchronous throw from dispatch otherwise skips onConnect/onError, so
+      // the request body stream is never destroyed and the signal's abort
+      // listener is never removed — both leak. Route it through onError, whose
+      // idempotent guards make this harmless if dispatch already reported.
+      handler.onError(err)
+    }
+  })
 }

package/lib/sqlite-cache-store.js

@@ -420,6 +420,23 @@ export class SqliteCacheStore {
     const now = getFastNow()
     const requestedStart = range?.start ?? 0
 
+    if (this.#insertBatch.length === 0) {
+      // Fast path: rows arrive sorted (cachedAt DESC, id DESC) and there are
+      // no pending batch entries to merge, so fetch only the newest candidate.
+      // This covers misses and first-row hits (the overwhelmingly common
+      // cases) with a single row materialized — re-cached duplicates of a hot
+      // key would otherwise all be read including their blobs. Only when the
+      // newest row doesn't match (vary variant, range/206 mismatch) do we
+      // fall through to scan the full candidate set.
+      const value = this.#getValuesQuery.get(url, method, requestedStart, now)
+      if (value === undefined) {
+        return undefined
+      }
+      if (matchesValue(value, range, headers)) {
+        return value
+      }
+    }
+
     /**
      * @type {SqliteStoreValue[]}
      */
@@ -445,55 +462,63 @@ export class SqliteCacheStore {
     // deterministically toward the freshest write: pending batch entries
     // (tagged with a monotonic seq) are always newer than any flushed DB row,
     // and within each source a higher seq/id wins.
-    values.sort((a, b) => {
-      if (a.cachedAt !== b.cachedAt) {
-        return b.cachedAt - a.cachedAt
-      }
-      const aBatch = a.seq != null
-      const bBatch = b.seq != null
-      if (aBatch !== bBatch) {
-        return aBatch ? -1 : 1
-      }
-      if (aBatch) {
-        return b.seq - a.seq
-      }
-      return (b.id ?? 0) - (a.id ?? 0)
-    })
+    if (values.length > 1) {
+      values.sort((a, b) => {
+        if (a.cachedAt !== b.cachedAt) {
+          return b.cachedAt - a.cachedAt
+        }
+        const aBatch = a.seq != null
+        const bBatch = b.seq != null
+        if (aBatch !== bBatch) {
+          return aBatch ? -1 : 1
+        }
+        if (aBatch) {
+          return b.seq - a.seq
+        }
+        return (b.id ?? 0) - (a.id ?? 0)
+      })
+    }
 
     for (const value of values) {
-      // TODO (fix): Allow full and partial match?
-      if (range && (range.start !== value.start || range.end !== value.end)) {
-        continue
+      if (matchesValue(value, range, headers)) {
+        return value
       }
+    }
 
-      // A request without a Range header asks for the full representation, so
-      // a stored 206 partial (e.g. content-range bytes 0-4/100, which the SQL
-      // `start <= 0` filter does not exclude) must not be served verbatim.
-      if (!range && value.statusCode === 206) {
-        continue
-      }
+    return undefined
+  }
+}
 
-      if (value.vary) {
-        const vary = JSON.parse(value.vary)
-        let matches = true
+/**
+ * @param {SqliteStoreValue} value
+ * @param {import('./utils.js').RangeHeader | undefined} range
+ * @param {Record<string, string | string[]> | undefined} headers
+ * @returns {boolean}
+ */
+function matchesValue(value, range, headers) {
+  // TODO (fix): Allow full and partial match?
+  if (range && (range.start !== value.start || range.end !== value.end)) {
+    return false
+  }
 
-        for (const header in vary) {
-          if (!headerValueEquals(headers?.[header], vary[header])) {
-            matches = false
-            break
-          }
-        }
+  // A request without a Range header asks for the full representation, so
+  // a stored 206 partial (e.g. content-range bytes 0-4/100, which the SQL
+  // `start <= 0` filter does not exclude) must not be served verbatim.
+  if (!range && value.statusCode === 206) {
+    return false
+  }
 
-        if (!matches) {
-          continue
-        }
-      }
+  if (value.vary) {
+    const vary = JSON.parse(value.vary)
 
-      return value
+    for (const header in vary) {
+      if (!headerValueEquals(headers?.[header], vary[header])) {
+        return false
+      }
     }
-
-    return undefined
   }
+
+  return true
 }
 
 /**
@@ -510,15 +535,21 @@ function headerValueEquals(lhs, rhs) {
     return false
   }
 
-  if (Array.isArray(lhs) && Array.isArray(rhs)) {
-    if (lhs.length !== rhs.length) {
+  // A single-element array and the bare scalar denote the same logical header
+  // value (e.g. 'gzip' vs ['gzip']); normalize so an inconsistently-shaped
+  // selecting header doesn't cause an avoidable cache miss.
+  const a = Array.isArray(lhs) && lhs.length === 1 ? lhs[0] : lhs
+  const b = Array.isArray(rhs) && rhs.length === 1 ? rhs[0] : rhs
+
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) {
       return false
     }
 
-    return lhs.every((x, i) => x === rhs[i])
+    return a.every((x, i) => x === b[i])
   }
 
-  return lhs === rhs
+  return a === b
 }
 
 /**
@@ -531,11 +562,15 @@ function makeValueUrl(key) {
 
 function makeResult(value) {
   return {
-    // Copy rather than alias: on the in-flight batch read-through path
-    // value.body is the exact Buffer still queued for flushing, and the
-    // three-arg Buffer.from(arrayBuffer, ...) form would share its memory,
-    // so a consumer mutating the served body could corrupt the cached bytes.
-    body: value.body ? Buffer.from(value.body) : undefined,
+    // Batch entries (tagged with seq) must be copied: value.body is the exact
+    // Buffer still queued for flushing, so a consumer mutating the served body
+    // could corrupt the bytes about to be written. DB rows are safe to alias —
+    // node:sqlite allocates a fresh Uint8Array per read, so wrap it zero-copy.
+    body: value.body
+      ? value.seq != null
+        ? Buffer.from(value.body)
+        : Buffer.from(value.body.buffer, value.body.byteOffset, value.body.byteLength)
+      : undefined,
     statusCode: value.statusCode,
     statusMessage: value.statusMessage,
     headers: value.headers ? JSON.parse(value.headers) : undefined,

package/lib/utils.js

@@ -291,7 +291,10 @@ export function parseHeaders(headers, obj) {
       const key = util.headerNameToString(key2)
       let val = obj[key]
 
-      if (val) {
+      // `key in obj`, not `if (val)`: an empty-string value ('') is a valid,
+      // present header. A truthy check would treat it as absent and overwrite
+      // it on a duplicate occurrence, silently dropping the first value.
+      if (key in obj) {
         if (!Array.isArray(val)) {
           val = [val]
           obj[key] = val
@@ -322,7 +325,9 @@ export function parseHeaders(headers, obj) {
       const key = util.headerNameToString(key2)
       let val = obj[key]
 
-      if (val) {
+      // See the array branch above: presence check, not truthiness, so a
+      // stored empty string is not clobbered by a later duplicate.
+      if (key in obj) {
         if (!Array.isArray(val)) {
           val = [val]
           obj[key] = val
@@ -332,7 +337,7 @@ export function parseHeaders(headers, obj) {
         } else {
           val.push(`${val2}`)
         }
-      } else if (val2 != null) {
+      } else {
         obj[key] = Array.isArray(val2)
           ? val2.filter((x) => x != null).map((x) => `${x}`)
           : `${val2}`
@@ -374,10 +379,14 @@ export function decorateError(err, opts, { statusCode, headers, trailers, body }
       body = null
     }
 
-    if (
-      typeof body === 'string' &&
-      (!headers?.['content-type'] || headers['content-type'].startsWith('application/json'))
-    ) {
+    // A duplicated content-type response header arrives as an array (undici's
+    // parseHeaders collapses repeats); coerce to the first value before
+    // calling string methods, otherwise this throws and the catch below
+    // discards all decoration into an opaque AggregateError.
+    const contentType = Array.isArray(headers?.['content-type'])
+      ? headers['content-type'][0]
+      : headers?.['content-type']
+    if (typeof body === 'string' && (!contentType || contentType.startsWith('application/json'))) {
       try {
         body = JSON.parse(body)
       } catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nxtedition/nxt-undici",
-  "version": "7.3.26",
+  "version": "7.4.0",
   "license": "MIT",
   "author": "Robert Nagy <robert.nagy@boffins.se>",
   "main": "lib/index.js",