@nxtedition/nxt-undici 7.4.2 → 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
@@ -134,8 +145,15 @@ export interface ProxyOptions {
 export interface CacheOptions {
   store?: CacheStore
   maxEntrySize?: number
-  /** Upper bound on an entry's freshness lifetime, in seconds (default 30 days). */
+  /** Upper bound on an entry's freshness lifetime AND retention, in seconds
+   *  (default 30 days). */
   maxEntryTTL?: number
+  /** Opt-in RFC 9111 §4.2.2 heuristic freshness (10% of time since
+   *  Last-Modified) for 200 responses without explicit expiration. */
+  heuristic?: boolean
+  /** Opt-in fallback freshness lifetime in seconds for 200 responses without
+   *  any expiration information. */
+  defaultTTL?: number
 }
 
 export interface VerifyOptions {
@@ -245,6 +263,8 @@ export interface CacheValue {
   etag?: string
   vary?: Record<string, string | string[]>
   cachedAt: number
+  /** Optional on set(): omitting it defaults to deleteAt (staleAt === deleteAt). */
+  staleAt?: number
   deleteAt?: number
 }
 
@@ -257,6 +277,7 @@ export interface CacheGetResult {
   cacheControlDirectives?: Record<string, unknown>
   vary?: Record<string, string | string[]>
   cachedAt: number
+  staleAt: number
   deleteAt: number
 }
 
@@ -266,6 +287,9 @@ export interface CacheStore {
     key: CacheKey,
     value: CacheValue & { body: null | Buffer | Buffer[]; start: number; end: number },
   ): void
+  /** RFC 9111 §4.4 invalidation — optional; the cache interceptor
+   *  feature-detects it and skips invalidation when absent. */
+  delete?(key: CacheKey): void
   gc(): void
   clear(): void
   close(): void
@@ -338,6 +362,8 @@ export class SqliteCacheStore implements CacheStore {
     key: CacheKey,
     value: CacheValue & { body: null | Buffer | Buffer[]; start: number; end: number },
   ): void
+  /** RFC 9111 §4.4: invalidates every stored response for the key's URI. */
+  delete(key: CacheKey): void
   gc(): void
   clear(): void
   close(): void

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