@nxtedition/nxt-undici 7.4.0 → 7.4.1

package/lib/index.d.ts

@@ -150,6 +150,9 @@ export interface PressureInterceptorOptions {
   /** Schmitt-trigger dead-band for `full` (pause the producer). */
   fullHi?: number
   fullLo?: number
+  /** Schmitt-trigger dead-band for `errorRate` (mark the origin degraded). */
+  errHi?: number
+  errLo?: number
 }
 
 export interface PressureStats {
@@ -159,21 +162,29 @@ export interface PressureStats {
   running: number
   /** Counter: cumulative settled requests (onComplete + onError). */
   completed: number
+  /** Counter: cumulative settled requests that were overload errors (429/420/5xx, transport failures). */
+  errored: 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
+  /** EWMA in [0,1]: smoothed fraction of completions that were overload errors. */
+  errorRate: number
   /** Latched: shed discretionary work (engaged when `some` crosses `someHi`). */
   shed: boolean
   /** Latched: pause the producer (engaged when `full` crosses `fullHi`). */
   paused: boolean
+  /** Latched: error rate too high (engaged when `errorRate` crosses `errHi`). */
+  degraded: boolean
 }
 
 export interface PressureReading {
   some: number
   full: number
+  errorRate: number
   shed: boolean
   paused: boolean
+  degraded: boolean
 }
 
 export interface PressureInterceptor {

package/lib/index.js

@@ -160,9 +160,20 @@ function wrapDispatch(dispatcher) {
             signal: opts.signal ?? undefined,
             reset: opts.reset ?? false,
             blocking: opts.blocking ?? true,
+            // opts.timeout may be a number (applies to both phases) or an
+            // object { headers, body }. The bare `?? opts.timeout` fallback must
+            // only apply the SCALAR form — otherwise an object form that sets
+            // just one of the two fields leaks the whole object into the other
+            // timeout, which undici rejects with InvalidArgumentError.
             headersTimeout:
-              opts.timeout?.headers ?? opts.headersTimeout ?? opts.headerTimeout ?? opts.timeout,
-            bodyTimeout: opts.timeout?.body ?? opts.bodyTimeout ?? opts.timeout,
+              opts.timeout?.headers ??
+              opts.headersTimeout ??
+              opts.headerTimeout ??
+              (typeof opts.timeout === 'number' ? opts.timeout : undefined),
+            bodyTimeout:
+              opts.timeout?.body ??
+              opts.bodyTimeout ??
+              (typeof opts.timeout === 'number' ? opts.timeout : undefined),
             idempotent: opts.idempotent,
             typeOfService:
               opts.typeOfService ?? (opts.priority ? (PRIORITY_TOS_MAP[opts.priority] ?? 0) : 0),

package/lib/interceptor/cache.js

@@ -1,5 +1,11 @@
 import undici from '@nxtedition/undici'
-import { DecoratorHandler, getFastNow, parseCacheControl, parseContentRange } from '../utils.js'
+import {
+  DecoratorHandler,
+  getFastNow,
+  isStream,
+  parseCacheControl,
+  parseContentRange,
+} from '../utils.js'
 import { SqliteCacheStore } from '../sqlite-cache-store.js'
 
 let DEFAULT_STORE = null
@@ -386,8 +392,13 @@ function serveFromCache(entry, opts, handler) {
     }
   }
 
-  // Dump body...
-  opts.body?.on('error', () => {}).resume()
+  // Dump the request body so its underlying resources are released. Only a
+  // stream needs draining; a Buffer/string body has no .on()/.resume(), and
+  // calling them would throw a TypeError that aborts an otherwise-valid cache
+  // hit (a cached GET/HEAD issued with a non-stream body).
+  if (isStream(opts.body)) {
+    opts.body.on('error', () => {}).resume()
+  }
 
   try {
     handler.onConnect(abort)

package/lib/interceptor/dns.js

@@ -19,6 +19,18 @@ class Handler extends DecoratorHandler {
     return super.onHeaders(statusCode, headers, resume)
   }
 
+  onUpgrade(statusCode, headers, socket) {
+    // A successful upgrade (HTTP 101) is its own terminal branch — neither
+    // onComplete nor onError follows it. Settle the gauge here too, otherwise
+    // record.pending is incremented (before dispatch) but never decremented for
+    // any upgraded request, which permanently skews load balancing and pins the
+    // hostname against sweep() (it requires pending === 0). onHeaders is not
+    // guaranteed to run before onUpgrade, so settle with the upgrade status;
+    // 101 < 500, so this only decrements pending without bumping `errored`.
+    this.#callback(null, statusCode)
+    super.onUpgrade(statusCode, headers, socket)
+  }
+
   onComplete(trailers) {
     this.#callback(null, this.#statusCode)
     super.onComplete(trailers)
@@ -32,6 +44,27 @@ class Handler extends DecoratorHandler {
 
 const SWEEP_INTERVAL = 30e3
 
+// Error codes that mean the IP itself is unreachable/bad, so the selected
+// record should be invalidated immediately (expires = 0), forcing a re-resolve.
+// Anything else surfaced on the response path — a headers/body timeout, a
+// content-length mismatch, a generic application error — means the IP was
+// reachable (a connection was established); invalidating it would thrash DNS
+// for a healthy host, so those only bump the soft `errored` load score instead.
+const CONNECTION_ERROR_CODES = new Set([
+  'ECONNREFUSED',
+  'ECONNRESET',
+  'ETIMEDOUT',
+  'EHOSTDOWN',
+  'EHOSTUNREACH',
+  'ENETDOWN',
+  'ENETUNREACH',
+  'ENOTFOUND',
+  'EAI_AGAIN',
+  'EPIPE',
+  'UND_ERR_CONNECT_TIMEOUT',
+  'UND_ERR_SOCKET',
+])
+
 export default () => (dispatch) => {
   const cache = new Map()
   const promises = new Map()
@@ -177,7 +210,14 @@ export default () => (dispatch) => {
         record.pending--
 
         if (err != null && err.name !== 'AbortError') {
-          record.expires = 0
+          if (err.code != null && CONNECTION_ERROR_CODES.has(err.code)) {
+            // The IP is bad/unreachable — drop it from rotation immediately.
+            record.expires = 0
+          } else {
+            // Reachable IP, request failed for an unrelated reason (timeout
+            // mid-stream, size mismatch, ...) — penalize softly, don't evict.
+            record.errored++
+          }
         } else if (statusCode != null && statusCode >= 500) {
           record.errored++
         }

package/lib/interceptor/pressure.js

@@ -26,9 +26,29 @@ import { DecoratorHandler } from '../utils.js'
 // 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.
+//
+// PSI measures *stall* (latency) pressure; an HTTP origin has a second failure
+// mode the latency signal is blind to: responding *fast* but *failing*. A flood
+// of 503/429 drains `pending` and ticks `completed`, so neither `some` nor
+// `full` fires — yet it is exactly when you should back off. So we add a third,
+// HTTP-specific tier alongside the two PSI levels:
+//
+//  - errorRate (EWMA of the fraction of completions that were overload errors:
+//    429/420 or 5xx, plus transport failures) -> `degraded` -> shed
+//    discretionary work, same tier as `some`. (A *rate*, not a per-tick bool, so
+//    a trickle of errors under heavy traffic doesn't latch.) The `peer.dns`
+//    interceptor already tracks 5xx per resolved IP for load balancing; this is
+//    the same insight applied at the logical-origin level for backoff.
 
 const EPS = 1e-3
 
+// Overload-shaped response statuses: explicit rate limits (429/420) and server
+// errors (5xx). 4xx client errors (404, 400, 401, …) are NOT origin pressure —
+// they don't mean the origin is struggling — so they don't count.
+function isErrorStatus(statusCode) {
+  return statusCode === 429 || statusCode === 420 || statusCode >= 500
+}
+
 // Smallest priority that is still "discretionary" — sheddable under `some`
 // pressure. low/lower/lowest (<= -1); normal and above are never shed.
 function isDiscretionary(priority) {
@@ -53,6 +73,8 @@ class PressureMonitor {
   #someLo
   #fullHi
   #fullLo
+  #errHi
+  #errLo
 
   constructor({
     sampleInterval = 200,
@@ -61,6 +83,8 @@ class PressureMonitor {
     someLo = 0.2,
     fullHi = 0.3,
     fullLo = 0.1,
+    errHi = 0.5,
+    errLo = 0.2,
   } = {}) {
     this.#sampleInterval = sampleInterval
     this.#tau = tau
@@ -68,6 +92,8 @@ class PressureMonitor {
     this.#someLo = someLo
     this.#fullHi = fullHi
     this.#fullLo = fullLo
+    this.#errHi = errHi
+    this.#errLo = errLo
   }
 
   // Called from the interceptor on each dispatch to get (or lazily create) the
@@ -85,11 +111,15 @@ class PressureMonitor {
         pending: 0, // gauge: dispatched, awaiting onConnect (waiting for a slot)
         running: 0, // gauge: connected and in-flight
         completed: 0, // counter: cumulative settled (onComplete + onError)
+        errored: 0, // counter: cumulative settled with an overload error
         prevCompleted: 0, // snapshot of `completed` at the previous sample
+        prevErrored: 0, // snapshot of `errored` at the previous sample
         some: 0, // EWMA: fraction of recent time `someNow` held
         full: 0, // EWMA: fraction of recent time `fullNow` held
+        errorRate: 0, // EWMA: smoothed fraction of completions that errored
         shed: false, // latched: shed discretionary work
         paused: false, // latched: pause the producer
+        degraded: false, // latched: error rate too high
         lastSample: performance.now(),
       }
       this.#origins.set(key, rec)
@@ -109,14 +139,21 @@ class PressureMonitor {
     }
     rec.lastSample = now
 
+    const dCompleted = rec.completed - rec.prevCompleted
+    const dErrored = rec.errored - rec.prevErrored
     const someNow = rec.pending > 0
-    const progressed = rec.completed - rec.prevCompleted > 0
-    const fullNow = someNow && !progressed
+    const fullNow = someNow && dCompleted === 0
+    // Error *fraction* this window — a rate, so volume doesn't matter. No
+    // completions this window (idle, or hung — `full` covers that) means no new
+    // error evidence, so the signal relaxes toward 0.
+    const errNow = dCompleted > 0 ? dErrored / dCompleted : 0
     rec.prevCompleted = rec.completed
+    rec.prevErrored = rec.errored
 
     const a = 1 - Math.exp(-dt / this.#tau)
     rec.some += a * ((someNow ? 1 : 0) - rec.some)
     rec.full += a * ((fullNow ? 1 : 0) - rec.full)
+    rec.errorRate += a * (errNow - rec.errorRate)
 
     // Hysteresis: engage high, release low.
     if (!rec.shed && rec.some > this.#someHi) {
@@ -129,6 +166,11 @@ class PressureMonitor {
     } else if (rec.paused && rec.full < this.#fullLo) {
       rec.paused = false
     }
+    if (!rec.degraded && rec.errorRate > this.#errHi) {
+      rec.degraded = true
+    } else if (rec.degraded && rec.errorRate < this.#errLo) {
+      rec.degraded = false
+    }
   }
 
   // Tick every tracked origin, then evict any that is fully idle and has decayed
@@ -138,7 +180,13 @@ class PressureMonitor {
     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) {
+      if (
+        rec.pending === 0 &&
+        rec.running === 0 &&
+        rec.some < EPS &&
+        rec.full < EPS &&
+        rec.errorRate < EPS
+      ) {
         this.#origins.delete(key)
       }
     }
@@ -169,10 +217,13 @@ class PressureMonitor {
       pending: rec.pending,
       running: rec.running,
       completed: rec.completed,
+      errored: rec.errored,
       some: rec.some,
       full: rec.full,
+      errorRate: rec.errorRate,
       shed: rec.shed,
       paused: rec.paused,
+      degraded: rec.degraded,
     }
   }
 
@@ -196,12 +247,20 @@ class PressureMonitor {
   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 }
+      ? {
+          some: rec.some,
+          full: rec.full,
+          errorRate: rec.errorRate,
+          shed: rec.shed,
+          paused: rec.paused,
+          degraded: rec.degraded,
+        }
+      : { some: 0, full: 0, errorRate: 0, shed: false, paused: false, degraded: false }
   }
 
   // Producer-side gate mirroring the README's `submit` recipe: `full` pauses
-  // everything; `some` sheds only discretionary (low-priority) work.
+  // everything; `some` (backlog) or `degraded` (error rate) sheds only
+  // discretionary (low-priority) work.
   shouldBackoff(origin, priority) {
     const rec = this.#origins.get(origin)
     if (rec == null) {
@@ -210,7 +269,7 @@ class PressureMonitor {
     if (rec.paused) {
       return true
     }
-    if (rec.shed) {
+    if (rec.shed || rec.degraded) {
       return isDiscretionary(priority)
     }
     return false
@@ -236,6 +295,7 @@ class Handler extends DecoratorHandler {
   // times onConnect is invoked (e.g. a retry handler upstream) or which
   // terminal callback fires.
   #state = 'pending'
+  #statusCode = 0
 
   constructor(handler, rec) {
     // super() validates the handler and throws on a non-object before we touch
@@ -246,6 +306,11 @@ class Handler extends DecoratorHandler {
   }
 
   onConnect(abort) {
+    // A (re)connect begins a fresh attempt: clear the captured status so a prior
+    // attempt's status can't leak into a later transport failure's
+    // classification. A handler upstream (e.g. response-retry) may reconnect
+    // this same handler across retries, and response-retry itself resets here.
+    this.#statusCode = 0
     if (this.#state === 'pending') {
       this.#state = 'running'
       this.#rec.pending -= 1
@@ -254,17 +319,31 @@ class Handler extends DecoratorHandler {
     super.onConnect(abort)
   }
 
+  onHeaders(statusCode, headers, resume) {
+    // Latest status wins, so an informational 1xx is superseded by the final
+    // response. Read at onComplete to classify the outcome.
+    this.#statusCode = statusCode
+    return super.onHeaders(statusCode, headers, resume)
+  }
+
   onComplete(trailers) {
-    this.#settle()
+    this.#settle(isErrorStatus(this.#statusCode))
     super.onComplete(trailers)
   }
 
   onError(err) {
-    this.#settle()
+    // A status-bearing error is `responseError`'s decorated 4xx/5xx (when this
+    // interceptor sits outside it); classify by that status. A status-less
+    // error is a transport/connection failure (ECONNREFUSED, timeout, a sync
+    // dispatch throw) — count it, unless it's a client-initiated abort.
+    const statusCode = err?.statusCode ?? this.#statusCode
+    const isError =
+      err?.name === 'AbortError' ? false : statusCode >= 200 ? isErrorStatus(statusCode) : true
+    this.#settle(isError)
     super.onError(err)
   }
 
-  #settle() {
+  #settle(isError) {
     if (this.#state === 'done') {
       return
     }
@@ -274,6 +353,9 @@ class Handler extends DecoratorHandler {
       this.#rec.running -= 1
     }
     this.#rec.completed += 1
+    if (isError) {
+      this.#rec.errored += 1
+    }
     this.#state = 'done'
   }
 }

package/lib/interceptor/proxy.js

@@ -104,8 +104,13 @@ function isHopByHop(key) {
     case 4:
       return eqiLower(key, 'host')
     case 7:
-      return eqiLower(key, 'upgrade')
+      // `trailer` (RFC 7230 §4.4) is hop-by-hop and must not be relayed; it was
+      // previously missed here (only `upgrade` shares this length), leaking the
+      // upstream's Trailer announcement to the next hop after transfer-encoding
+      // was already stripped.
+      return eqiLower(key, 'upgrade') || eqiLower(key, 'trailer')
     case 8:
+      // 'trailers' is the RFC 2616 §13.5.1 spelling kept for compatibility.
       return eqiLower(key, 'trailers')
     case 10:
       return eqiLower(key, 'connection') || eqiLower(key, 'keep-alive')

package/lib/interceptor/redirect.js

@@ -54,6 +54,19 @@ class Handler extends DecoratorHandler {
   }
 
   onHeaders(statusCode, headers, resume) {
+    // Informational (1xx, e.g. 100 Continue / 103 Early Hints) responses are
+    // interim — not final and not redirects — so forward them through without
+    // marking headersSent or counting a redirect hop. Otherwise the
+    // `assert(!headersSent)` below trips (turning a good response into an
+    // onError) when the real final response arrives after an interim one. This
+    // matches the 1xx passthrough already in response-retry and RequestHandler;
+    // it is exercised when an inner dispatcher forwards a 1xx (raw undici
+    // strips them, but composed/mock dispatchers and future early-hints support
+    // do not).
+    if (statusCode < 200) {
+      return super.onHeaders(statusCode, headers, resume)
+    }
+
     if (redirectableStatusCodes.indexOf(statusCode) === -1) {
       assert(!this.#headersSent)
       this.#headersSent = true

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

@@ -31,8 +31,10 @@ class FactoryStream extends Readable {
           if (this.#body != null) {
             this.#body
               .on('data', (data) => {
+                // `?.`: a 'data' event can still be queued when _destroy() has
+                // already nulled #body, and `_read` guards the same way.
                 if (!this.push(data)) {
-                  this.#body.pause()
+                  this.#body?.pause()
                 }
               })
               .on('end', () => {

package/lib/interceptor/response-verify.js

@@ -29,6 +29,16 @@ class Handler extends DecoratorHandler {
   }
 
   onHeaders(statusCode, headers, resume) {
+    // Responses that by definition carry no body — 1xx informational, 204 No
+    // Content, 205 Reset Content, 304 Not Modified — must not be size/hash-
+    // verified. A 304 in particular may echo the Content-Length of the full
+    // representation it refers to; verifying the (absent) body against it would
+    // falsely trip the size check and break conditional-request revalidation.
+    // Leaving #expectedSize/#hasher null makes onData/onComplete no-ops here.
+    if (statusCode < 200 || statusCode === 204 || statusCode === 205 || statusCode === 304) {
+      return super.onHeaders(statusCode, headers, resume)
+    }
+
     // 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

package/package.json

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