@nxtedition/nxt-undici 7.4.3 → 7.5.0

package/lib/interceptor/priority.js

@@ -1,14 +1,17 @@
 import { Scheduler } from '@nxtedition/scheduler'
 import { DecoratorHandler } from '../utils.js'
+import { traceWrite, traceSafe, traceUrl } from '../trace.js'
 
 class Handler extends DecoratorHandler {
   #scheduler
   #onIdle
+  #trace
 
-  constructor(handler, scheduler, onIdle) {
+  constructor(handler, scheduler, onIdle, trace) {
     super(handler)
     this.#scheduler = scheduler
     this.#onIdle = onIdle
+    this.#trace = trace
   }
 
   onConnect(abort) {
@@ -30,8 +33,34 @@ class Handler extends DecoratorHandler {
     if (this.#scheduler) {
       const scheduler = this.#scheduler
       this.#scheduler = null
+
+      // Slot-release timestamp is captured BEFORE release(): it synchronously
+      // pumps queued dispatches, whose work must not inflate this request's
+      // holdMs. Emission happens after release + eviction, inside the same
+      // once-guard as release() (every terminal callback funnels here), so
+      // the end doc cannot double-fire and the writer never observes a
+      // handler that still holds the slot.
+      const trace = this.#trace
+      const released = trace !== null ? performance.now() : 0
+
       scheduler.release()
       this.#onIdle?.()
+
+      if (trace !== null) {
+        traceSafe(
+          trace.write,
+          {
+            id: trace.id,
+            key: trace.key,
+            priority: trace.priority,
+            phase: 'end',
+            pending: null,
+            waitMs: Math.round(trace.dispatched - trace.acquired),
+            holdMs: Math.round(released - trace.dispatched),
+          },
+          'undici:priority',
+        )
+      }
     }
   }
 }
@@ -66,9 +95,30 @@ export default () => (dispatch) => {
       }
     }
 
-    const priorityHandler = new Handler(handler, scheduler, onIdle)
-    scheduler.acquire(
+    // Trace state (op 'undici:priority') is resolved once per request:
+    // capture-once keeps the queued/end pair on one writer, and when tracing
+    // is off the cost is one property read — no clock reads, no string work.
+    // `acquired` must be stamped BEFORE acquire(): a free slot invokes the
+    // callback synchronously and `dispatched` would otherwise predate it.
+    const write = traceWrite(opts.trace)
+    const trace =
+      write !== null
+        ? {
+            write,
+            id: opts.id ?? null,
+            key: traceUrl({ origin: key }),
+            priority: String(opts.priority).slice(0, 16),
+            acquired: performance.now(),
+            dispatched: 0,
+          }
+        : null
+
+    const priorityHandler = new Handler(handler, scheduler, onIdle, trace)
+    const acquired = scheduler.acquire(
       (priorityHandler) => {
+        if (trace !== null) {
+          trace.dispatched = performance.now()
+        }
         try {
           dispatch(opts, priorityHandler)
         } catch (err) {
@@ -78,5 +128,25 @@ export default () => (dispatch) => {
       opts.priority,
       priorityHandler,
     )
+
+    // acquire() returns false only when no slot was free and the request was
+    // queued — the breadcrumb for a request that enters the queue and never
+    // leaves. pending is the post-enqueue queue depth, so it counts this
+    // request.
+    if (!acquired && trace !== null) {
+      traceSafe(
+        trace.write,
+        {
+          id: trace.id,
+          key: trace.key,
+          priority: trace.priority,
+          phase: 'queued',
+          pending: scheduler.pending,
+          waitMs: null,
+          holdMs: null,
+        },
+        'undici:priority',
+      )
+    }
   }
 }

package/lib/interceptor/redirect.js

@@ -1,5 +1,6 @@
 import assert from 'node:assert'
 import { DecoratorHandler, isDisturbed, parseURL, parseHeaders, buildURL } from '../utils.js'
+import { traceWrite, traceSafe, traceUrl } from '../trace.js'
 
 const redirectableStatusCodes = [300, 301, 302, 303, 307, 308]
 
@@ -105,6 +106,13 @@ class Handler extends DecoratorHandler {
       }
     }
 
+    // The redirect decision is final past this point, so trace work stays off
+    // the non-redirect path entirely. Resolve the writer per emission (trace
+    // survives the opts spread across hops) and capture `from` before #opts
+    // is rebuilt below.
+    const write = traceWrite(this.#opts.trace)
+    const from = write !== null ? traceUrl(this.#opts) : null
+
     // Build the base URL by concatenating origin + path via buildURL rather
     // than `new URL(path, origin)`: the latter is unsafe when `path` is
     // protocol-relative (e.g. `//evil-host/x`, reachable via a request URL like
@@ -140,6 +148,24 @@ class Handler extends DecoratorHandler {
         body: null,
       }
     }
+
+    if (write !== null) {
+      traceSafe(
+        write,
+        {
+          id: this.#opts.id ?? null,
+          // Post-rewrite method for the next hop (303 may have swapped it above).
+          method: this.#opts.method ?? null,
+          statusCode,
+          from,
+          to: traceUrl(this.#opts),
+          // #count is 1-based: incremented above for this hop, so the first
+          // followed redirect emits count 1.
+          count: this.#count,
+        },
+        'undici:redirect',
+      )
+    }
   }
 
   onData(chunk) {

package/lib/interceptor/response-retry.js

@@ -8,6 +8,7 @@ import {
   parseHeaders,
 } from '../utils.js'
 import { RequestAbortedError } from '../errors.js'
+import { traceWrite, traceSafe, traceErr, traceUrl } from '../trace.js'
 
 // Maximum number of >= 400 response body bytes buffered for replay in case
 // the response is not retried. Larger bodies are passed straight through and
@@ -16,6 +17,30 @@ const MAX_ERROR_BODY_SIZE = 256 * 1024
 
 function noop() {}
 
+// Emit an `undici:retry` trace doc at the point a retry is actually scheduled.
+// Cold path only — a retry already implies a failed attempt — so resolving the
+// writer per emission (same resolution as the trace interceptor: explicit
+// opts.trace wins, absent falls back to the global) costs nothing on the
+// request hot path. `cause` is the triggering failure: the attempt's error, or
+// the bare status code for a status-code retry without one.
+function traceRetry(opts, retryCount, delay, cause) {
+  const write = traceWrite(opts.trace)
+  if (write !== null) {
+    traceSafe(
+      write,
+      {
+        id: opts.id ?? null,
+        method: opts.method ?? null,
+        url: traceUrl(opts),
+        retryCount,
+        delayMs: delay,
+        err: traceErr(cause),
+      },
+      'undici:retry',
+    )
+  }
+}
+
 // Subscribe `onAbort` to an EventEmitter-style OR EventTarget-style signal and
 // return an unsubscribe function; return null when it cannot be done safely.
 //
@@ -618,6 +643,7 @@ class Handler extends DecoratorHandler {
             Math.min(retryAfter, 60e3)
           : Math.min(10e3, retryCount * 1e3)
       this.#opts.logger?.debug({ statusCode, retryAfter, delay, retryCount }, 'retry delay')
+      traceRetry(this.#opts, retryCount, delay, err ?? statusCode)
       return this.#backoff(delay, opts)
     }
 
@@ -638,13 +664,17 @@ class Handler extends DecoratorHandler {
         'UND_ERR_SOCKET',
       ].includes(err.code)
     ) {
+      const delay = Math.min(10e3, retryCount * 1e3)
       this.#opts.logger?.debug({ err, retryCount }, 'retry delay')
-      return this.#backoff(Math.min(10e3, retryCount * 1e3), opts)
+      traceRetry(this.#opts, retryCount, delay, err)
+      return this.#backoff(delay, opts)
     }
 
     if (err?.message && ['other side closed'].includes(err.message)) {
+      const delay = Math.min(10e3, retryCount * 1e3)
       this.#opts.logger?.debug({ err, retryCount }, 'retry delay')
-      return this.#backoff(Math.min(10e3, retryCount * 1e3), opts)
+      traceRetry(this.#opts, retryCount, delay, err)
+      return this.#backoff(delay, opts)
     }
 
     return false

package/lib/interceptor/response-verify.js

@@ -1,7 +1,38 @@
 import crypto from 'node:crypto'
 import { DecoratorHandler, parseContentRange } from '../utils.js'
+import { traceWrite, traceSafe, traceUrl } from '../trace.js'
+
+// Emit an `undici:verify` trace doc carrying the by-how-much/what-values
+// detail of a verification failure, immediately before the error is delivered.
+// The undici:request end doc already tags THAT the request failed; this doc is
+// for fingerprinting truncation vs corruption. Cold path only — every call
+// site is an already-failing branch — so the writer is resolved per emission
+// (explicit opts.trace wins, absent falls back to the global) at zero cost on
+// the per-chunk hot path. Hash values are origin-influenced strings (a
+// duplicated Content-MD5 header keeps `expected` as an array of conflicting
+// values, which String() flattens), so bound them.
+function traceVerify(opts, kind, expectedSize, actualSize, expectedHash, actualHash) {
+  const write = traceWrite(opts.trace)
+  if (write !== null) {
+    traceSafe(
+      write,
+      {
+        id: opts.id ?? null,
+        method: opts.method ?? null,
+        url: traceUrl(opts),
+        kind,
+        expectedSize,
+        actualSize,
+        expectedHash: expectedHash != null ? String(expectedHash).slice(0, 64) : null,
+        actualHash: actualHash != null ? String(actualHash).slice(0, 64) : null,
+      },
+      'undici:verify',
+    )
+  }
+}
 
 class Handler extends DecoratorHandler {
+  #opts
   #verifyOpts
   #contentMD5
   #expectedSize
@@ -12,6 +43,8 @@ class Handler extends DecoratorHandler {
   constructor(opts, { handler }) {
     super(handler)
 
+    // Retained only for failure-time trace tagging (id/method/url).
+    this.#opts = opts
     this.#verifyOpts = opts.verify === true ? { hash: true, size: true } : opts.verify
   }
 
@@ -70,6 +103,7 @@ class Handler extends DecoratorHandler {
         expected: this.#expectedSize,
         actual: this.#pos,
       })
+      traceVerify(this.#opts, 'overrun', this.#expectedSize, this.#pos, null, null)
       super.onError(err)
       // Returning false only applies backpressure; the socket would stay
       // paused until bodyTimeout. Abort to release the connection now.
@@ -84,6 +118,7 @@ class Handler extends DecoratorHandler {
     const contentMD5 = this.#hasher?.digest('base64')
 
     if (this.#expectedSize != null && this.#pos !== this.#expectedSize) {
+      traceVerify(this.#opts, 'size', this.#expectedSize, this.#pos, null, null)
       super.onError(
         Object.assign(new Error('Response body size mismatch'), {
           expected: this.#expectedSize,
@@ -91,6 +126,7 @@ class Handler extends DecoratorHandler {
         }),
       )
     } else if (this.#contentMD5 != null && contentMD5 !== this.#contentMD5) {
+      traceVerify(this.#opts, 'hash', null, null, this.#contentMD5, contentMD5)
       super.onError(
         Object.assign(new Error('Response Content-MD5 mismatch'), {
           expected: this.#contentMD5,

package/lib/trace.js

@@ -0,0 +1,87 @@
+// Trace plumbing shared by the interceptors. The writer contract and the
+// generic helpers live in @nxtedition/trace; only the nxt-undici-specific
+// pieces (dispatch-opts url tagging, undici-flavored option validation) are
+// implemented here.
+//
+// Importing @nxtedition/trace statically is safe despite the package cycle
+// (@nxtedition/trace flushes through nxt-undici): the trace package imports
+// nxt-undici lazily at first flush precisely so consumers can depend on it
+// statically. The only constraint is publish order — @nxtedition/trace must
+// be published before a nxt-undici release that depends on it.
+//
+// The contract in short: a writer is `{ write }` where `write` is the trace
+// function while tracing is enabled and null while disabled (it flips between
+// the two at runtime), so call sites gate on the resolved fn at zero cost when
+// off. `write` must not call back into the request being traced — emission
+// happens inside dispatch/handler control flow, and reentrancy there is
+// unsupported.
+
+import { validateTrace as validateTraceWriter } from '@nxtedition/trace'
+import { InvalidArgumentError } from './errors.js'
+
+// installTrace is part of the surface: the per-thread default writer lives in
+// the Symbol.for('@nxtedition/app/trace') slot and is mirrored
+// module-locally inside @nxtedition/trace, so a
+// writer must be installed through installTrace — a bare slot assignment only
+// propagates on the next mirror refresh.
+export { traceWrite, traceSafe, traceErr, installTrace } from '@nxtedition/trace'
+
+/**
+ * @typedef {import('@nxtedition/trace').TraceWriter} TraceWriter
+ */
+
+/**
+ * Validate an opts.trace value, rethrowing the package's plain Error as the
+ * InvalidArgumentError (UND_ERR_INVALID_ARG) that dispatch option validation
+ * is expected to throw. Returns the input unchanged.
+ *
+ * @param {unknown} trace
+ * @returns {TraceWriter | null | undefined}
+ */
+export function validateTrace(trace) {
+  try {
+    return validateTraceWriter(trace)
+  } catch {
+    throw new InvalidArgumentError('invalid trace')
+  }
+}
+
+/**
+ * Bounded origin+path tag for trace docs. Mirrors log.js's sanitizeOrigin
+ * userinfo guard: an origin string carrying `user:pass@host` credentials is
+ * reduced to URL#origin (which never contains userinfo) before it can reach
+ * the trace index; if such a string is not a parseable URL, prefer losing the
+ * value over risking embedded credentials. Never throws — evaluated while
+ * building docs inside handler control flow.
+ *
+ * @param {{ origin?: unknown, path?: unknown }} opts
+ * @returns {string | null}
+ */
+export function traceUrl(opts) {
+  try {
+    const origin = opts.origin
+    let str
+    if (origin == null) {
+      str = ''
+    } else if (origin instanceof URL) {
+      // Real URL instances already expose a credential-free origin.
+      str = origin.origin
+    } else {
+      // Raw dispatch()/compose() callers may pass URL-like objects or arrays
+      // (defaultLookup resolves those deeper in the chain) — stringify rather
+      // than lose the doc.
+      str = typeof origin === 'string' ? origin : String(origin)
+      if (str.includes('@')) {
+        try {
+          str = new URL(str).origin
+        } catch {
+          str = '[redacted]'
+        }
+      }
+    }
+    const path = typeof opts.path === 'string' ? opts.path : ''
+    return `${str}${path}`.slice(0, 256)
+  } catch {
+    return null
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nxtedition/nxt-undici",
-  "version": "7.4.3",
+  "version": "7.5.0",
   "license": "MIT",
   "author": "Robert Nagy <robert.nagy@boffins.se>",
   "main": "lib/index.js",
@@ -10,6 +10,7 @@
   ],
   "dependencies": {
     "@nxtedition/scheduler": "^4.1.1",
+    "@nxtedition/trace": "^1.0.0",
     "@nxtedition/undici": "^11.1.4",
     "fast-querystring": "^1.1.2",
     "http-errors": "^2.0.1",