@nxtedition/nxt-undici 7.4.0 → 7.4.2

package/lib/index.d.ts

@@ -55,17 +55,25 @@ export interface LoggerLike {
   info(obj: unknown, msg?: string): void
 }
 
+export type BodyFactoryResult =
+  | Readable
+  | Uint8Array
+  | string
+  | Iterable<unknown>
+  | AsyncIterable<unknown>
+
+/** Called with an options object (not a bare signal); the signal aborts when the
+ *  request is destroyed before the factory resolves. May be async. */
+export type BodyFactory = (opts: {
+  signal: AbortSignal
+}) => BodyFactoryResult | Promise<BodyFactoryResult>
+
 export interface DispatchOptions {
   id?: string | null
   origin?: string | null
   path?: string | null
   method?: string | null
-  body?:
-    | Readable
-    | Uint8Array
-    | string
-    | ((signal: AbortSignal) => Readable | Uint8Array | string | Iterable<unknown>)
-    | null
+  body?: Readable | Uint8Array | string | BodyFactory | null
   query?: Record<string, unknown> | null
   headers?: Record<string, string | string[] | null | undefined> | null
   signal?: AbortSignal | null
@@ -80,8 +88,13 @@ export interface DispatchOptions {
   retry?: RetryOptions | number | boolean | RetryFn | null
   proxy?: ProxyOptions | boolean | null
   cache?: CacheOptions | boolean | null
-  upgrade?: boolean | null
+  /** Protocol to upgrade to (e.g. 'websocket'). undici requires a string and the
+   *  dispatch handler must implement onUpgrade — only meaningful with raw
+   *  dispatch()/compose(); request() has no upgrade support (see RequestOptions). */
+  upgrade?: string | null
   follow?: number | FollowFn | boolean | null
+  /** Alias for `follow`; ignored when `follow` is also set. */
+  redirect?: number | FollowFn | boolean | null
   error?: boolean | null
   verify?: VerifyOptions | boolean | null
   logger?: LoggerLike | null
@@ -121,6 +134,8 @@ export interface ProxyOptions {
 export interface CacheOptions {
   store?: CacheStore
   maxEntrySize?: number
+  /** Upper bound on an entry's freshness lifetime, in seconds (default 30 days). */
+  maxEntryTTL?: number
 }
 
 export interface VerifyOptions {
@@ -130,7 +145,16 @@ export interface VerifyOptions {
 
 export interface DnsOptions {
   ttl?: number
+  /** How long (ms) a failed lookup is negative-cached; requests inside this
+   *  window fail fast without hitting the resolver again (default 1000). */
+  negativeTTL?: number
   balance?: 'hash'
+  /** Custom resolver, `dns.lookup`-compatible (called with `{ all: true }`). */
+  lookup?: (
+    hostname: string,
+    options: { all: boolean },
+    callback: (err: Error | null, addresses: { address: string; family: number }[]) => void,
+  ) => void
 }
 
 export interface LogInterceptorOptions {
@@ -150,6 +174,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 +186,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 {
@@ -236,10 +271,14 @@ export interface CacheStore {
   close(): void
 }
 
-export interface RequestOptions extends DispatchOptions {
+/** `upgrade` is omitted: request()'s internal handler has no onUpgrade, so any
+ *  upgrade attempt rejects with InvalidArgumentError — use dispatch() instead. */
+export interface RequestOptions extends Omit<DispatchOptions, 'upgrade'> {
   url?: URLLike | null
   dispatch?: DispatchFn | null
   dispatcher?: Dispatcher | null
+  /** highWaterMark for the response body readable (non-negative number). */
+  highWaterMark?: number | null
 }
 
 export interface ResponseData {

package/lib/index.js

@@ -29,6 +29,7 @@ export const cache = {
 }
 
 export { parseHeaders } from './utils.js'
+export { SqliteCacheStore } from './sqlite-cache-store.js'
 export { Client, Pool, Agent, getGlobalDispatcher, setGlobalDispatcher } from '@nxtedition/undici'
 
 function defaultLookup(origin, opts, callback) {
@@ -160,9 +161,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
@@ -115,7 +121,10 @@ class CacheHandler extends DecoratorHandler {
       return super.onHeaders(statusCode, headers, resume)
     }
 
-    const vary = {}
+    // Null prototype: selector names come from the response Vary header and
+    // request header names are caller-controlled — on a plain `{}` a
+    // `__proto__` key would hit the prototype setter and be silently dropped.
+    const vary = Object.create(null)
     if (headers.vary) {
       if (typeof headers.vary !== 'string') {
         return super.onHeaders(statusCode, headers, resume)
@@ -135,9 +144,15 @@ class CacheHandler extends DecoratorHandler {
       }
     }
 
-    const ttl = cacheControlDirectives.immutable
-      ? 31556952
-      : Number(cacheControlDirectives['s-maxage'] ?? cacheControlDirectives['max-age'])
+    // RFC 8246: 'immutable' means the body won't change during the freshness
+    // lifetime — it does not define or extend that lifetime. An explicit
+    // s-maxage/max-age always wins; immutable only supplies a (long) default
+    // when no explicit lifetime is present. Capped by maxEntryTTL below.
+    const ttl = Number(
+      cacheControlDirectives['s-maxage'] ??
+        cacheControlDirectives['max-age'] ??
+        (cacheControlDirectives.immutable ? 31556952 : NaN),
+    )
     if (!ttl || !Number.isFinite(ttl) || ttl <= 0) {
       return super.onHeaders(statusCode, headers, resume)
     }
@@ -161,6 +176,23 @@ class CacheHandler extends DecoratorHandler {
 
     if (end == null || end - start <= this.#maxEntrySize) {
       const cachedAt = Date.now()
+      // Snapshot the headers: the same object is delivered downstream to the
+      // caller (request() resolves with it before the body finishes), and the
+      // entry isn't serialized to the store until onComplete. Without a copy,
+      // any mutation the caller makes to res.headers while the body streams
+      // would be persisted into the shared cache and replayed to every later
+      // request. parseHeaders values are strings or string arrays, so a
+      // one-level copy with array values sliced is a full snapshot. Use
+      // Object.keys so only own enumerable header fields are copied — never
+      // inherited properties from the prototype chain. Null prototype: on a
+      // plain `{}` a header literally named `__proto__` would hit the
+      // Object.prototype setter instead of becoming a data property (silent
+      // drop / prototype-pollution vector).
+      const storedHeaders = Object.create(null)
+      for (const name of Object.keys(headers)) {
+        const val = headers[name]
+        storedHeaders[name] = Array.isArray(val) ? val.slice() : val
+      }
       this.#value = {
         body: [],
         start,
@@ -168,7 +200,7 @@ class CacheHandler extends DecoratorHandler {
         deleteAt: cachedAt + lifetime * 1e3,
         statusCode,
         statusMessage: '',
-        headers,
+        headers: storedHeaders,
         cacheControlDirectives,
         etag: isEtagUsable(headers.etag) ? headers.etag : '',
         vary,
@@ -223,7 +255,45 @@ export default () => (dispatch) => (opts, handler) => {
     return dispatch(opts, handler)
   }
 
-  const rawCacheControl = opts?.headers?.['cache-control']
+  // 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.
+  // Header names are caller-controlled, so build a null-prototype map (a
+  // `__proto__` key on a plain object would silently overwrite the prototype
+  // instead of setting a property) and copy own keys only.
+  if (key.headers && typeof key.headers === 'object') {
+    const lower = Object.create(null)
+    for (const name of Object.keys(key.headers)) {
+      lower[name.toLowerCase()] = key.headers[name]
+    }
+    key.headers = lower
+  }
+
+  // All request-directive and conditional-header guards below MUST read from
+  // the lowercased key.headers, not raw opts.headers — otherwise a caller
+  // supplying capitalized names (e.g. `Authorization`, `Cache-Control` via the
+  // standalone composition) would silently skip the guards while the store
+  // side (CacheHandler) reads the lowercased form, e.g. serving a non-public
+  // cached response to an authorized request (RFC 9111 §3.5).
+  const headers = key.headers ?? {}
+
+  // Cache-Control is a list-typed field: duplicated field lines arrive as an
+  // array and combine into a single comma-separated value per RFC 9110 §5.2,
+  // keeping the raw-string directive checks below working.
+  let rawCacheControl = headers['cache-control']
+  if (Array.isArray(rawCacheControl)) {
+    rawCacheControl = rawCacheControl.join(', ')
+  }
   const cacheControlDirectives = parseCacheControl(rawCacheControl) ?? {}
   // cache-control-parser does not recognise 'only-if-cached', so check the raw string.
   const onlyIfCached =
@@ -231,7 +301,7 @@ export default () => (dispatch) => (opts, handler) => {
 
   // RFC 9111 Section 5.4: Pragma: no-cache should be treated as
   // Cache-Control: no-cache when Cache-Control is absent.
-  if (rawCacheControl == null && opts?.headers?.pragma === 'no-cache') {
+  if (rawCacheControl == null && headers.pragma === 'no-cache') {
     cacheControlDirectives['no-cache'] = true
   }
 
@@ -256,27 +326,6 @@ export default () => (dispatch) => (opts, handler) => {
   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(key)
@@ -291,18 +340,18 @@ export default () => (dispatch) => (opts, handler) => {
 
   // RFC 9111 Section 3.5: A shared cache must not use a cached response to a
   // request with Authorization unless the response includes a public directive.
-  if (entry && opts.headers?.authorization && !entry.cacheControlDirectives?.public) {
+  if (entry && headers.authorization && !entry.cacheControlDirectives?.public) {
     entry = undefined
   }
 
   // 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 && headers['if-none-match']) {
     if (
-      typeof opts.headers['if-none-match'] === 'string' &&
+      typeof headers['if-none-match'] === 'string' &&
       entry.etag &&
-      weakMatch(opts.headers['if-none-match'], entry.etag)
+      weakMatch(headers['if-none-match'], entry.etag)
     ) {
       return serveFromCache(
         { statusCode: 304, headers: entry.headers, cachedAt: entry.cachedAt },
@@ -312,12 +361,12 @@ export default () => (dispatch) => (opts, handler) => {
     }
     // Etag didn't match — bypass to origin.
     entry = undefined
-  } else if (entry && opts.headers?.['if-modified-since']) {
+  } else if (entry && headers['if-modified-since']) {
     const lastModified = entry.headers?.['last-modified']
     if (
-      typeof opts.headers['if-modified-since'] === 'string' &&
+      typeof headers['if-modified-since'] === 'string' &&
       lastModified &&
-      new Date(lastModified) <= new Date(opts.headers['if-modified-since'])
+      new Date(lastModified) <= new Date(headers['if-modified-since'])
     ) {
       return serveFromCache(
         { statusCode: 304, headers: entry.headers, cachedAt: entry.cachedAt },
@@ -329,11 +378,7 @@ export default () => (dispatch) => (opts, handler) => {
     entry = undefined
   }
 
-  if (
-    opts.headers?.['if-match'] ||
-    opts.headers?.['if-unmodified-since'] ||
-    opts.headers?.['if-range']
-  ) {
+  if (headers['if-match'] || headers['if-unmodified-since'] || headers['if-range']) {
     // TODO (fix): evaluate these conditional headers against cached entry.
     return dispatch(opts, handler)
   }
@@ -386,8 +431,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,14 +44,60 @@ class Handler extends DecoratorHandler {
 
 const SWEEP_INTERVAL = 30e3
 
+// A cached (or in-flight-shared) lookup error must never be handed to more
+// than one caller as-is: downstream decorateError call sites (response-retry,
+// response-error) mutate the error they receive (err.req, err.res,
+// err.statusCode), so a shared object would leak one request's decoration
+// into another's. Give each caller a fresh Error carrying the identifying
+// dns fields, with the original attached as `cause`.
+function makeLookupError(err) {
+  const wrapped = new Error(err.message, { cause: err })
+  wrapped.code = err.code
+  if (err.errno !== undefined) {
+    wrapped.errno = err.errno
+  }
+  if (err.syscall !== undefined) {
+    wrapped.syscall = err.syscall
+  }
+  if (err.hostname !== undefined) {
+    wrapped.hostname = err.hostname
+  }
+  return wrapped
+}
+
+// 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 negatives = 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.
+  // Negative entries are swept on the same cadence (they are also deleted
+  // eagerly on the next successful lookup / overwritten on the next failure,
+  // so the sweep only matters for hostnames that are never touched again).
   let lastSweep = 0
   function sweep(now) {
     if (now - lastSweep < SWEEP_INTERVAL) {
@@ -51,18 +109,33 @@ export default () => (dispatch) => {
         cache.delete(hostname)
       }
     }
+    for (const [hostname, negative] of negatives) {
+      if (negative.expires < now) {
+        negatives.delete(hostname)
+      }
+    }
   }
 
-  function resolve(hostname, { ttl }) {
+  function resolve(hostname, { ttl, negativeTTL, lookup }) {
     let promise = promises.get(hostname)
     if (!promise) {
       promise = new Promise((resolve) => {
-        dns.lookup(hostname, { all: true }, (err, records) => {
+        lookup(hostname, { all: true }, (err, records) => {
           promises.delete(hostname)
 
           if (err) {
+            // Negative cache: remember the failure for a short while so a hot
+            // caller of an unresolvable host fails fast instead of issuing a
+            // lookup storm (response-retry retries ENOTFOUND/EAI_AGAIN up to
+            // `retry` (default 8) times, so without this every logical
+            // request produced ~9 lookups). EAI_AGAIN is transient by
+            // definition, but the same small TTL applies — the window only
+            // needs to absorb a retry burst, and a short TTL keeps recovery
+            // fast either way.
+            negatives.set(hostname, { err, expires: getFastNow() + negativeTTL })
             resolve([err, null])
           } else {
+            negatives.delete(hostname)
             const now = getFastNow()
             const val = records.map(({ address }) => {
               return {
@@ -92,6 +165,8 @@ export default () => (dispatch) => {
       }
 
       const ttl = opts.dns.ttl ?? 2e3
+      const negativeTTL = opts.dns.negativeTTL ?? 1e3
+      const lookup = opts.dns.lookup ?? dns.lookup
       const url = new URL(opts.path ?? '', opts.origin)
       const balance = opts.dns.balance
 
@@ -108,9 +183,19 @@ export default () => (dispatch) => {
       let records = cache.get(hostname)
 
       if (records == null || records.every((x) => x.expires < now)) {
-        const [err, val] = await resolve(hostname, { ttl })
+        // A fresh negative entry means a lookup for this hostname failed less
+        // than negativeTTL ago — fail fast instead of hitting the resolver
+        // again. Fresh positive records (checked above) take precedence, so a
+        // failed pre-emptive refresh never fails requests that can still be
+        // served from cache.
+        const negative = negatives.get(hostname)
+        if (negative != null && negative.expires >= now) {
+          throw makeLookupError(negative.err)
+        }
+
+        const [err, val] = await resolve(hostname, { ttl, negativeTTL, lookup })
         if (err) {
-          throw err
+          throw makeLookupError(err)
         }
         records = val
       }
@@ -157,7 +242,7 @@ export default () => (dispatch) => {
       // refreshed records land in cache for the next request, smoothing
       // out DNS lookup latency. `resolve()` dedupes via `promises`.
       if (records.some((x) => x.expires < now + ttl / 2)) {
-        resolve(hostname, { ttl })
+        resolve(hostname, { ttl, negativeTTL, lookup })
       }
 
       url.hostname = net.isIPv6(record.address) ? `[${record.address}]` : record.address
@@ -177,15 +262,37 @@ 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++
         }
       }
 
       try {
+        // origin is rewritten to the resolved IP, so pin the host header to
+        // the logical hostname — but never clobber an explicit user-supplied
+        // host (virtual hosting). Lowercase lookup matches the pipeline
+        // invariant (parseHeaders) and priority.js, which reads the same key.
+        // Host is a singular header, so only a single non-empty string value
+        // is preserved (same rule as priority.js) — an array (duplicate Host
+        // field-lines) or an empty string falls back to the origin-derived
+        // host.
         return dispatch(
-          { ...opts, origin: url.origin, headers: { ...opts.headers, host } },
+          {
+            ...opts,
+            origin: url.origin,
+            headers: {
+              ...opts.headers,
+              host: (typeof opts.headers?.host === 'string' && opts.headers.host) || host,
+            },
+          },
           new Handler(handler, onSettle),
         )
       } catch (err) {