@nxtedition/nxt-undici 7.4.3 → 7.5.0

package/lib/index.d.ts

@@ -55,6 +55,13 @@ export interface LoggerLike {
   info(obj: unknown, msg?: string): void
 }
 
+/** The @nxtedition/trace writer contract: `write` is the emit fn while tracing
+ *  is enabled and null while disabled (it flips between the two at runtime).
+ *  The per-thread fallback writer lives in the Symbol.for('@nxtedition/app/trace')
+ *  slot and must be installed via the package's installTrace(). */
+export type { TraceWriter } from '@nxtedition/trace'
+import type { TraceWriter } from '@nxtedition/trace'
+
 export type BodyFactoryResult =
   | Readable
   | Uint8Array
@@ -98,6 +105,10 @@ export interface DispatchOptions {
   error?: boolean | null
   verify?: VerifyOptions | boolean | null
   logger?: LoggerLike | null
+  /** Per-request trace writer: undefined falls back to the per-thread writer
+   *  installed via @nxtedition/trace's installTrace(), null disables tracing
+   *  for this request. */
+  trace?: TraceWriter | null
   dns?: DnsOptions | boolean | null
   connect?: Record<string, unknown> | null
   priority?: Priority | null

package/lib/index.js

@@ -4,6 +4,7 @@ import { Scheduler } from '@nxtedition/scheduler'
 import { parseHeaders } from './utils.js'
 import { request as _request } from './request.js'
 import { SqliteCacheStore } from './sqlite-cache-store.js'
+import { validateTrace } from './trace.js'
 
 const dispatcherCache = new WeakMap()
 
@@ -118,6 +119,13 @@ function wrapDispatch(dispatcher) {
       interceptors.proxy(),
       interceptors.cache(),
       interceptors.redirect(),
+      // log also emits the undici:request trace start/end docs. Later entries
+      // in this list wrap earlier ones, so it sits OUTSIDE everything that
+      // does real work (redirect, cache, proxy, retry, dns) — durationMs
+      // spans the whole inner pipeline including retries, dns and cache
+      // lookups — but INSIDE requestId, so opts.id is already stamped and
+      // the emitted docs correlate with logs and undici:retry docs by
+      // request id.
       interceptors.log(),
       interceptors.lookup(),
       interceptors.requestId(),
@@ -186,6 +194,13 @@ function wrapDispatch(dispatcher) {
             error: opts.error ?? opts.throwOnError ?? true,
             verify: opts.verify ?? { size: true, hash: false },
             logger: opts.logger ?? null,
+            // Deliberately NOT defaulted: undefined means "fall back to the
+            // per-thread writer installed via installTrace()" (resolved lazily
+            // at each emission site — the writer may be installed after startup
+            // and its `write` flips at runtime), null means "tracing disabled
+            // for this request" (see lib/trace.js). Validation throws
+            // InvalidArgumentError for anything that is not a writer.
+            trace: validateTrace(opts.trace),
             dns: opts.dns ?? true,
             connect: opts.connect,
             // A duplicated nxt-priority request header parses to an array; the

package/lib/interceptor/cache.js

@@ -10,6 +10,7 @@ import {
 } from '../utils.js'
 import { isHopByHop } from './proxy.js'
 import { SqliteCacheStore } from '../sqlite-cache-store.js'
+import { traceWrite, traceSafe, traceErr, traceUrl } from '../trace.js'
 
 let DEFAULT_STORE = null
 const DEFAULT_MAX_ENTRY_SIZE = 128 * 1024
@@ -19,6 +20,28 @@ const DEFAULT_MAX_ENTRY_TTL = 30 * 24 * 3600 // seconds
 const IMMUTABLE_LIFETIME = 31556952 // seconds
 const NOOP = () => {}
 
+// Emit the per-dispatch `undici:cache` lookup doc at the outcome decision
+// (hit/miss/bypass). Call sites gate on the write fn captured once at the
+// dispatch entry (log.js style), so the off path pays no doc building; result
+// and reason stay low-cardinality (they become ES keywords).
+function traceLookup(write, opts, url, result, reason, statusCode, ageSec, sizeBytes, lookupMs) {
+  traceSafe(
+    write,
+    {
+      id: opts.id ?? null,
+      method: opts.method ?? null,
+      url,
+      result,
+      reason,
+      statusCode,
+      ageSec,
+      sizeBytes,
+      lookupMs,
+    },
+    'undici:cache',
+  )
+}
+
 /**
  * Explicit (or opt-in heuristic) freshness lifetime in seconds, or null when
  * the response carries no usable expiration information. RFC 9111 §4.2.1
@@ -147,7 +170,20 @@ class CacheHandler extends DecoratorHandler {
   #heuristic
   #defaultTTL
 
-  constructor(key, { store, logger, handler, maxEntrySize, maxEntryTTL, heuristic, defaultTTL }) {
+  // Trace plumbing captured once at the dispatch entry: the resolved write fn
+  // (null when tracing is off), the request id and the bounded url tag. One
+  // `undici:cache-store` doc is emitted per response at the storability
+  // outcome — no per-attempt emitted-flag is needed because every skip path
+  // leaves #value null (making the stored/overflow paths unreachable for the
+  // same attempt) and onConnect resets #value for retry re-entry.
+  #write
+  #id
+  #url
+
+  constructor(
+    key,
+    { store, logger, handler, maxEntrySize, maxEntryTTL, heuristic, defaultTTL, write, id, url },
+  ) {
     super(handler)
 
     this.#key = key
@@ -158,6 +194,39 @@ class CacheHandler extends DecoratorHandler {
     this.#maxEntryTTL = maxEntryTTL ?? store.maxEntryTTL ?? DEFAULT_MAX_ENTRY_TTL
     this.#heuristic = heuristic ?? false
     this.#defaultTTL = defaultTTL ?? null
+    this.#write = write ?? null
+    this.#id = id ?? null
+    this.#url = url ?? null
+  }
+
+  // The single `undici:cache-store` emitter. `err` is the raw error (or null);
+  // tagging is deferred here so no string work happens unless tracing is on.
+  #trace(statusCode, stored, reason, sizeBytes, ttlSec, err) {
+    if (this.#write !== null) {
+      traceSafe(
+        this.#write,
+        {
+          id: this.#id,
+          method: this.#key.method ?? null,
+          url: this.#url,
+          statusCode,
+          stored,
+          reason,
+          sizeBytes,
+          ttlSec,
+          err: err != null ? traceErr(err) : null,
+        },
+        'undici:cache-store',
+      )
+    }
+  }
+
+  // Storability declined at header time: emit the skip doc and pass the
+  // response through untouched. Keeps the many onHeaders early returns
+  // single-line; `reason` names the failed gate and must stay low-cardinality.
+  #skip(reason, statusCode, headers, resume) {
+    this.#trace(statusCode, false, reason, null, null, null)
+    return super.onHeaders(statusCode, headers, resume)
   }
 
   onConnect(abort) {
@@ -170,20 +239,28 @@ class CacheHandler extends DecoratorHandler {
   }
 
   onHeaders(statusCode, headers, resume) {
-    if (statusCode !== 307 && statusCode !== 200 && statusCode !== 206) {
+    if (statusCode < 200) {
+      // Interim informational responses precede the real response (raw undici
+      // strips them, composed/mock dispatchers may forward them — same guard
+      // as redirect/response-verify): not a storability outcome, so no
+      // cache-store doc either — the final response emits the one doc.
       return super.onHeaders(statusCode, headers, resume)
     }
 
+    if (statusCode !== 307 && statusCode !== 200 && statusCode !== 206) {
+      return this.#skip('status', statusCode, headers, resume)
+    }
+
     // '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)
+      return this.#skip(headers.vary === '*' ? 'vary-star' : 'trailer', statusCode, headers, resume)
     }
 
     if (headers['set-cookie']) {
       // Shared cache: replaying Set-Cookie to other clients leaks sessions.
-      return super.onHeaders(statusCode, headers, resume)
+      return this.#skip('set-cookie', statusCode, headers, resume)
     }
 
     let contentRange
@@ -196,13 +273,13 @@ class CacheHandler extends DecoratorHandler {
             (contentRange.size != null && contentRange.end > contentRange.size)))
       ) {
         // We don't support caching responses with invalid content-range...
-        return super.onHeaders(statusCode, headers, resume)
+        return this.#skip('content-range', 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)
+        return this.#skip('head-range', statusCode, headers, resume)
       }
     }
 
@@ -211,13 +288,13 @@ class CacheHandler extends DecoratorHandler {
       contentLength = Number(headers['content-length'])
       if (!Number.isFinite(contentLength) || contentLength <= 0) {
         // We don't support caching responses with invalid content-length...
-        return super.onHeaders(statusCode, headers, resume)
+        return this.#skip('content-length', statusCode, headers, resume)
       }
     }
 
     if (statusCode === 206 && !contentRange) {
       // We don't support caching range responses without content-range...
-      return super.onHeaders(statusCode, headers, resume)
+      return this.#skip('206-no-range', statusCode, headers, resume)
     }
 
     const cacheControlDirectives = parseCacheControl(headers['cache-control']) ?? {}
@@ -238,7 +315,7 @@ class CacheHandler extends DecoratorHandler {
           cacheControlDirectives['must-revalidate'] === true
         )
       ) {
-        return super.onHeaders(statusCode, headers, resume)
+        return this.#skip('auth', statusCode, headers, resume)
       }
     }
 
@@ -246,7 +323,7 @@ class CacheHandler extends DecoratorHandler {
     // qualified form (private="field") only forbids storing the listed
     // fields, which are stripped below (RFC 9111 §5.2.2.7).
     if (cacheControlDirectives['no-store'] || cacheControlDirectives.private === true) {
-      return super.onHeaders(statusCode, headers, resume)
+      return this.#skip('no-store', statusCode, headers, resume)
     }
 
     if (cacheControlDirectives['must-understand']) {
@@ -268,7 +345,7 @@ class CacheHandler extends DecoratorHandler {
       // not yet perform — so the responses are not stored (a follow-up adds
       // conditional revalidation and turns these into stored-and-validated
       // entries).
-      return super.onHeaders(statusCode, headers, resume)
+      return this.#skip('revalidate', statusCode, headers, resume)
     }
 
     // Null prototype: selector names come from the response Vary header and
@@ -277,13 +354,13 @@ class CacheHandler extends DecoratorHandler {
     const vary = Object.create(null)
     if (headers.vary) {
       if (typeof headers.vary !== 'string') {
-        return super.onHeaders(statusCode, headers, resume)
+        return this.#skip('vary-invalid', statusCode, headers, resume)
       }
 
       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)
+          return this.#skip('vary-star', 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
@@ -304,14 +381,14 @@ class CacheHandler extends DecoratorHandler {
       now,
     )
     if (lifetimeInfo == null) {
-      return super.onHeaders(statusCode, headers, resume)
+      return this.#skip('no-lifetime', statusCode, headers, resume)
     }
 
     const etag = typeof headers.etag === 'string' && isEtagUsable(headers.etag) ? headers.etag : ''
     const age = determineAge(headers, now)
     const times = computeEntryTimes(lifetimeInfo.lifetime, age, this.#maxEntryTTL, now)
     if (times == null) {
-      return super.onHeaders(statusCode, headers, resume)
+      return this.#skip('stale', statusCode, headers, resume)
     }
 
     const start = contentRange ? contentRange.start : 0
@@ -389,6 +466,8 @@ class CacheHandler extends DecoratorHandler {
         // Handler state.
         size: 0,
       }
+    } else {
+      return this.#skip('too-large', statusCode, headers, resume)
     }
 
     return super.onHeaders(statusCode, headers, resume)
@@ -400,7 +479,11 @@ class CacheHandler extends DecoratorHandler {
       this.#value.body.push(chunk)
 
       if (this.#value.size > this.#maxEntrySize) {
+        // The buffer flips to discarded exactly once per attempt (#value stays
+        // null afterwards), so this is the single skip emission for it.
+        const statusCode = this.#value.statusCode
         this.#value = null
+        this.#trace(statusCode, false, 'too-large', null, null, null)
       }
     }
 
@@ -410,9 +493,11 @@ class CacheHandler extends DecoratorHandler {
   onComplete(trailers) {
     if (this.#value && (!trailers || Object.keys(trailers).length === 0)) {
       this.#value.end ??= this.#value.start + this.#value.size
+      let storeErr = null
       try {
         this.#store.set(this.#key, this.#value)
       } catch (err) {
+        storeErr = err
         if (err.message === 'database is locked') {
           // Database is busy. We don't bother trying again...
           this.#logger?.debug({ err }, 'failed to set cache entry')
@@ -420,7 +505,23 @@ class CacheHandler extends DecoratorHandler {
           this.#logger?.error({ err }, 'failed to set cache entry')
         }
       }
+      // stored reflects what actually happened: a throwing set() (e.g.
+      // 'database is locked' under write contention) persisted nothing, and
+      // dashboards keyed on `stored` must not count it. reason stays null —
+      // this is a store failure, not a storability gate; err carries the why.
+      this.#trace(
+        this.#value.statusCode,
+        storeErr == null,
+        null,
+        this.#value.size,
+        Math.round((this.#value.staleAt - this.#value.cachedAt) / 1000),
+        storeErr,
+      )
       this.#value = null
+    } else if (this.#value) {
+      // Unexpected trailers arriving at completion decline storability late —
+      // still one doc per response at the outcome.
+      this.#trace(this.#value.statusCode, false, 'trailer', null, null, null)
     }
 
     super.onComplete(trailers)
@@ -438,27 +539,52 @@ class InvalidationHandler extends DecoratorHandler {
   #key
   #store
   #logger
+  #write
+  #id
+  #url
 
-  constructor(key, { store, logger, handler }) {
+  constructor(key, { store, logger, handler, write, id, url }) {
     super(handler)
     this.#key = key
     this.#store = store
     this.#logger = logger
+    this.#write = write ?? null
+    this.#id = id ?? null
+    this.#url = url ?? null
   }
 
   onHeaders(statusCode, headers, resume) {
     if (statusCode >= 200 && statusCode <= 399) {
       // Invalidation failures must never break the actual response. Deletes
       // are idempotent, so a retry re-driving onHeaders is harmless.
+      let paths = 0
+      let invalidateErr = null
       try {
-        this.#invalidate(headers)
+        paths = this.#invalidate(headers)
       } catch (err) {
+        invalidateErr = err
         if (err.message === 'database is locked') {
           this.#logger?.debug({ err }, 'failed to invalidate cache entry')
         } else {
           this.#logger?.error({ err }, 'failed to invalidate cache entry')
         }
       }
+      // One `undici:cache-invalidate` doc per settled invalidation; `paths` is
+      // the count of invalidated paths, never the list.
+      if (this.#write !== null) {
+        traceSafe(
+          this.#write,
+          {
+            id: this.#id,
+            method: this.#key.method ?? null,
+            url: this.#url,
+            statusCode,
+            paths,
+            err: invalidateErr != null ? traceErr(invalidateErr) : null,
+          },
+          'undici:cache-invalidate',
+        )
+      }
     }
     return super.onHeaders(statusCode, headers, resume)
   }
@@ -494,6 +620,8 @@ class InvalidationHandler extends DecoratorHandler {
         this.#store.delete({ ...this.#key, path })
       }
     }
+
+    return invalidated.size
   }
 }
 
@@ -584,6 +712,13 @@ export default () => (dispatch) => (opts, handler) => {
     return dispatch(opts, handler)
   }
 
+  // Capture-once per dispatch (log.js style): the same resolved fn drives the
+  // `undici:cache` lookup doc and is threaded into CacheHandler /
+  // InvalidationHandler for the store/invalidate docs, so a writer flipping
+  // mid-request cannot split a dispatch across writers. Resolution cost when
+  // tracing is off is one property read plus a typeof check.
+  const write = traceWrite(opts.trace)
+
   if (opts.method !== 'GET' && opts.method !== 'HEAD') {
     // RFC 9110 §9.2.1: OPTIONS and TRACE are safe — never cached, but they
     // must not invalidate either. Every other method (POST/PUT/DELETE/...)
@@ -598,15 +733,26 @@ export default () => (dispatch) => (opts, handler) => {
       return dispatch(opts, handler)
     }
 
+    const key = makeKey(opts)
     return dispatch(
       opts,
-      new InvalidationHandler(makeKey(opts), { store, logger: opts.logger, handler }),
+      new InvalidationHandler(key, {
+        store,
+        logger: opts.logger,
+        handler,
+        write,
+        id: opts.id ?? null,
+        url: write !== null ? traceUrl(key) : null,
+      }),
     )
   }
 
   // TODO (fix): enable range requests
 
   const key = makeKey(opts)
+  // Bounded url tag shared by every doc this dispatch emits; the key (not raw
+  // opts) so the tag reflects the canonical path incl. the folded-in query.
+  const url = write !== null ? traceUrl(key) : null
 
   // All request-directive and conditional-header guards below MUST read from
   // the lowercased key.headers, not raw opts.headers — otherwise a caller
@@ -632,7 +778,20 @@ export default () => (dispatch) => (opts, handler) => {
   const onlyIfCached = requestCacheControl['only-if-cached'] === true
   const store = getStore(opts)
 
-  let entry = tryGetEntry(store, key, opts.logger)
+  // The lookup is timed only while tracing is on (performance.now() is not
+  // free); a store get that throws is caught inside tryGetEntry and settles
+  // as a miss with reason 'none'. `missReason` tracks which gate cleared a
+  // returned entry so the eventual miss doc names it.
+  let missReason = 'none'
+  let lookupMs = null
+  let entry
+  if (write !== null) {
+    const lookupStart = performance.now()
+    entry = tryGetEntry(store, key, opts.logger)
+    lookupMs = Math.round(performance.now() - lookupStart)
+  } else {
+    entry = tryGetEntry(store, key, opts.logger)
+  }
 
   // RFC 9111 §3.5 serve-side authorization gate: a shared cache must not
   // reuse a stored response for a request with Authorization unless the
@@ -649,6 +808,7 @@ export default () => (dispatch) => (opts, handler) => {
       )
     ) {
       entry = undefined
+      missReason = 'auth'
     }
   }
 
@@ -658,6 +818,9 @@ export default () => (dispatch) => (opts, handler) => {
       store,
       logger: opts.logger,
       handler,
+      write,
+      id: opts.id ?? null,
+      url,
     })
 
   // Request Cache-Control directives that this cache does not evaluate locally
@@ -678,6 +841,21 @@ export default () => (dispatch) => (opts, handler) => {
       requestCacheControl['min-fresh'] != null)
 
   if (bypass) {
+    if (write !== null) {
+      // Name the (first, in evaluation order) directive that forced the
+      // bypass; the fallthrough is min-fresh by construction of `bypass`.
+      const reason =
+        requestCacheControl['max-age'] != null
+          ? 'max-age'
+          : requestCacheControl['no-cache'] === true
+            ? 'no-cache'
+            : requestCacheControl['stale-if-error'] != null
+              ? 'stale-if-error'
+              : requestCacheControl['max-stale'] != null
+                ? 'max-stale'
+                : 'min-fresh'
+      traceLookup(write, opts, url, 'bypass', reason, null, null, null, lookupMs)
+    }
     return dispatch(opts, requestCacheControl['no-store'] ? handler : cacheHandler())
   }
 
@@ -696,10 +874,14 @@ export default () => (dispatch) => (opts, handler) => {
         { statusCode: 304, headers: entry.headers, cachedAt: entry.cachedAt },
         opts,
         handler,
+        write,
+        url,
+        lookupMs,
       )
     }
     // Etag didn't match — bypass to origin.
     entry = undefined
+    missReason = 'etag'
   } else if (entry && headers['if-modified-since']) {
     const lastModified = entry.headers?.['last-modified']
     if (
@@ -711,32 +893,60 @@ export default () => (dispatch) => (opts, handler) => {
         { statusCode: 304, headers: entry.headers, cachedAt: entry.cachedAt },
         opts,
         handler,
+        write,
+        url,
+        lookupMs,
       )
     }
     // No last-modified or modified since — bypass to origin.
     entry = undefined
+    missReason = 'modified'
   }
 
   if (headers['if-match'] || headers['if-unmodified-since'] || headers['if-range']) {
     // TODO (fix): evaluate these conditional headers against cached entry.
+    if (write !== null) {
+      traceLookup(write, opts, url, 'bypass', 'conditional', null, null, null, lookupMs)
+    }
     return dispatch(opts, handler)
   }
 
   if (!entry && !onlyIfCached) {
+    if (write !== null) {
+      traceLookup(write, opts, url, 'miss', missReason, null, null, null, lookupMs)
+    }
     // A miss keeps the CacheHandler write-back unless the request's no-store
     // forbids storing.
     return dispatch(opts, requestCacheControl['no-store'] ? handler : cacheHandler())
   }
 
   // A hit (fresh, per the store) is served; only-if-cached with no usable
-  // entry yields 504 (RFC 9111 §5.2.1.7).
-  return serveFromCache(entry ?? { statusCode: 504 }, opts, handler)
+  // entry yields 504 (RFC 9111 §5.2.1.7) — the cache could NOT satisfy the
+  // request, so its doc must not pollute hit-rate aggregations: it is a miss
+  // the request forbade going to origin for.
+  return entry
+    ? serveFromCache(entry, opts, handler, write, url, lookupMs)
+    : serveFromCache(
+        { statusCode: 504 },
+        opts,
+        handler,
+        write,
+        url,
+        lookupMs,
+        'miss',
+        'only-if-cached',
+      )
 }
 
-function serveFromCache(entry, opts, handler) {
+/**
+ * @param {'hit' | 'miss'} [result] lookup outcome for the undici:cache doc
+ * @param {string | null} [reason]
+ */
+function serveFromCache(entry, opts, handler, write, url, lookupMs, result = 'hit', reason = null) {
   const { statusCode, trailers, body } = entry
 
   let headers = entry.headers
+  let age = null
   if (entry.cachedAt != null) {
     // RFC 9111 §5.1: every response served from cache must carry an Age
     // header. cachedAt is backdated by the corrected initial age at store
@@ -744,10 +954,20 @@ function serveFromCache(entry, opts, handler) {
     // IS the response's age — no origin-Age addition. Date.now(), not
     // getFastNow(): the lagging clock would understate a relayed response's
     // initial age by up to a second.
-    const age = Math.max(0, Math.floor((Date.now() - entry.cachedAt) / 1000))
+    age = Math.max(0, Math.floor((Date.now() - entry.cachedAt) / 1000))
     headers = { ...headers, age: `${age}` }
   }
 
+  // Entry serves and conditional 304s are lookup hits; the only-if-cached
+  // synthetic 504 arrives as result 'miss' from the caller. Emitted before
+  // onConnect and outside the try/catch below so trace code sits strictly
+  // outside the handler-contract enforcement (traceSafe cannot throw, but
+  // keep it out of that window anyway). Synthetic entries have no cachedAt,
+  // so their ageSec stays null.
+  if (write !== null) {
+    traceLookup(write, opts, url, result, reason, statusCode, age, body?.byteLength ?? 0, lookupMs)
+  }
+
   // 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