logixia 2.2.0 → 2.3.0

package/dist/request-trace-txUhyyre.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"request-trace-txUhyyre.mjs","names":[],"sources":["../src/utils/trace.utils.ts","../src/utils/request-trace.ts"],"sourcesContent":["/**\n * Trace ID utilities for Logitron\n */\n\nimport { AsyncLocalStorage } from 'node:async_hooks';\nimport { randomUUID } from 'node:crypto';\n\nimport type { TraceIdConfig, TraceIdExtractorConfig } from '../types';\n\n/** Default key used to store the trace ID in AsyncLocalStorage. */\nexport const TRACE_CONTEXT_KEY = 'traceId' as const;\n\n// ── TraceContext class ────────────────────────────────────────────────────────\n\n/**\n * Singleton that owns the AsyncLocalStorage and the active contextKey.\n *\n * Why a class instead of bare module-level variables?\n *  - The contextKey is user-configurable; encapsulating it here means there is\n *    exactly one place that reads and writes it.\n *  - All helpers (getCurrentTraceId, runWithTraceId, etc.) delegate to this\n *    instance, so the key is always in sync without hidden global state.\n *  - Easier to test: you can reset the singleton between test cases.\n *\n * Usage (advanced):\n *   import { TraceContext } from 'logixia';\n *   TraceContext.instance.contextKey          // → 'traceId' (or custom)\n *   TraceContext.instance.getCurrentTraceId() // same as standalone fn\n */\nexport class TraceContext {\n  private static _instance: TraceContext | null = null;\n\n  readonly storage = new AsyncLocalStorage<Record<string, unknown>>();\n  private _contextKey: string = TRACE_CONTEXT_KEY;\n\n  private constructor() {}\n\n  /** The process-wide singleton. */\n  static get instance(): TraceContext {\n    if (!TraceContext._instance) {\n      TraceContext._instance = new TraceContext();\n    }\n    return TraceContext._instance;\n  }\n\n  /** @internal Reset the singleton (useful in tests). */\n  static _reset(): void {\n    TraceContext._instance = null;\n  }\n\n  // ── Key management ──────────────────────────────────────────────────────────\n\n  /** The AsyncLocalStorage key that holds the trace ID value. */\n  get contextKey(): string {\n    return this._contextKey;\n  }\n\n  /** @internal Called by TraceMiddleware when it boots to register the user's key. */\n  setContextKey(key: string): void {\n    this._contextKey = key;\n  }\n\n  // ── Core operations ─────────────────────────────────────────────────────────\n\n  /** UUID v4 generator (default). */\n  generate(): string {\n    return randomUUID();\n  }\n\n  /** Read the trace ID from the current async context. */\n  getCurrentTraceId(): string | undefined {\n    return this.storage.getStore()?.[this._contextKey] as string | undefined;\n  }\n\n  /**\n   * Mutate the CURRENT async context in-place.\n   *\n   * ⚠️  DEPRECATED — unsafe for concurrent requests.\n   *\n   * Uses `AsyncLocalStorage.enterWith()`, which mutates the current async\n   * execution context and every Promise chain spawned from it. In a server\n   * processing overlapping requests this can cause a trace ID set for one\n   * request to bleed into *other* in-flight requests that share the same\n   * async parent (e.g. a module-level setup function or a cached handler).\n   *\n   * Use {@link run} instead — it scopes the context to a callback so there\n   * is no risk of cross-request leakage.\n   *\n   * @deprecated Use `TraceContext.instance.run(traceId, fn)` — do not call\n   *             `setTraceId` from request-handling code.\n   */\n  setTraceId(traceId: string, data?: Record<string, unknown>): void {\n    const current = this.storage.getStore() ?? {};\n    this.storage.enterWith({ ...current, [this._contextKey]: traceId, ...data });\n  }\n\n  /** Run `fn` inside a new async context that carries `traceId`. */\n  run<T>(traceId: string, fn: () => T, data?: Record<string, unknown>): T {\n    return this.storage.run({ [this._contextKey]: traceId, ...data }, fn);\n  }\n}\n\n// ── Module-level aliases (backwards-compatible public API) ────────────────────\n\n/**\n * The shared AsyncLocalStorage instance.\n * @deprecated Prefer `TraceContext.instance.storage` for new code.\n */\nexport const traceStorage = TraceContext.instance.storage;\n\n/** Returns the key currently used to store the trace ID in AsyncLocalStorage. */\nexport function getTraceContextKey(): string {\n  return TraceContext.instance.contextKey;\n}\n\n/** @internal Called by TraceMiddleware / traceMiddleware() when they boot. */\nexport function _setActiveContextKey(key: string): void {\n  TraceContext.instance.setContextKey(key);\n}\n\n/** Generate a UUID v4 trace ID. */\nexport function generateTraceId(): string {\n  return TraceContext.instance.generate();\n}\n\n/**\n * Get the current trace ID from async context.\n * Returns `undefined` when called outside a traced request.\n */\nexport function getCurrentTraceId(): string | undefined {\n  return TraceContext.instance.getCurrentTraceId();\n}\n\n/**\n * Set trace ID in the CURRENT async context without starting a new one.\n *\n * ⚠️  DEPRECATED — unsafe for concurrent requests.\n *\n * Uses `AsyncLocalStorage.enterWith()`, which mutates the current async\n * execution context and every Promise chain spawned from it. Under load this\n * can cause a trace ID from one request to bleed into others sharing the same\n * async parent.\n *\n * Use {@link runWithTraceId} instead. Migration patterns:\n *\n * **Express / Fastify middleware — before:**\n * ```ts\n * app.use((req, _res, next) => {\n *   setTraceId(req.headers['x-trace-id'] ?? generateTraceId());\n *   next();\n * });\n * ```\n * **after:**\n * ```ts\n * app.use((req, _res, next) => {\n *   runWithTraceId(req.headers['x-trace-id'] ?? generateTraceId(), () => next());\n * });\n * ```\n *\n * **Kafka / queue consumer — before:**\n * ```ts\n * async function handle(msg) {\n *   setTraceId(msg.headers['x-trace-id']);\n *   await processMessage(msg);\n * }\n * ```\n * **after:**\n * ```ts\n * async function handle(msg) {\n *   await runWithTraceId(msg.headers['x-trace-id'], () => processMessage(msg));\n * }\n * ```\n *\n * **Background job — before:**\n * ```ts\n * setTraceId(generateTraceId(), { jobId: job.id });\n * await job.run();\n * ```\n * **after:**\n * ```ts\n * await runWithTraceId(generateTraceId(), () => job.run(), { jobId: job.id });\n * ```\n *\n * @deprecated Use `runWithTraceId(traceId, fn)` — do not call `setTraceId`\n *             from request-handling code.\n */\nexport function setTraceId(traceId: string, data?: Record<string, unknown>): void {\n  TraceContext.instance.setTraceId(traceId, data);\n}\n\n/** Run `fn` inside a new async context carrying `traceId`. */\nexport function runWithTraceId<T>(traceId: string, fn: () => T, data?: Record<string, unknown>): T {\n  return TraceContext.instance.run(traceId, fn, data);\n}\n\n// ── Request extraction ────────────────────────────────────────────────────────\n\ntype HeaderValue = string | string[] | undefined;\n\n/** Shape that extractTraceId accepts (Express-compatible) */\ninterface RequestLike {\n  headers?: Record<string, HeaderValue>;\n  query?: Record<string, HeaderValue>;\n  body?: Record<string, string | undefined>;\n  params?: Record<string, string | undefined>;\n}\n\n/** Maximum accepted length for an incoming trace / correlation / request ID. */\nexport const MAX_INCOMING_ID_LENGTH = 128;\n\nconst SAFE_INCOMING_ID = /^[A-Za-z0-9._:-]{1,128}$/;\n\n/**\n * Validate an externally supplied identifier (trace ID, correlation ID, origin\n * service name, message-queue ID). Accepts only 1-128 characters from\n * `[A-Za-z0-9._:-]`; surrounding whitespace is trimmed first. Arrays use their\n * first element. Returns the cleaned value, or `undefined` when it is unusable\n * so callers can generate a fresh ID instead of passing client text through.\n */\nexport function sanitizeIncomingId(value: unknown): string | undefined {\n  const first = Array.isArray(value) ? value[0] : value;\n  if (typeof first !== 'string' || first.length > MAX_INCOMING_ID_LENGTH * 2) return undefined;\n  const trimmed = first.trim();\n  return SAFE_INCOMING_ID.test(trimmed) ? trimmed : undefined;\n}\n\n/** W3C trace-context: `version-traceId(32hex)-spanId(16hex)-flags(2hex)`. */\nconst W3C_TRACEPARENT_RE = /^[\\da-f]{2}-([\\da-f]{32})-[\\da-f]{16}-[\\da-f]{2}$/i;\n\n/**\n * Extract the 32-hex trace-id segment from a W3C `traceparent` header value.\n * Returns the parsed trace ID, or the original value unchanged when it is not a\n * well-formed traceparent (so non-W3C propagation still works).\n */\nfunction parseTraceparent(value: string): string {\n  const m = W3C_TRACEPARENT_RE.exec(value);\n  return m ? m[1]! : value;\n}\n\n/** Extract trace ID from request using configuration (header → query → body → params). */\nexport function extractTraceId(\n  request: unknown,\n  config: TraceIdExtractorConfig\n): string | undefined {\n  const req = request as RequestLike;\n\n  if (config.header) {\n    const headers = Array.isArray(config.header) ? config.header : [config.header];\n    for (const header of headers) {\n      const lower = header.toLowerCase();\n      const value = sanitizeIncomingId(req.headers?.[lower]);\n      if (value) return lower === 'traceparent' ? parseTraceparent(value) : value;\n    }\n  }\n\n  if (config.query) {\n    const queries = Array.isArray(config.query) ? config.query : [config.query];\n    for (const query of queries) {\n      const value = sanitizeIncomingId(req.query?.[query]);\n      if (value) return value;\n    }\n  }\n\n  if (config.body) {\n    const bodyFields = Array.isArray(config.body) ? config.body : [config.body];\n    for (const field of bodyFields) {\n      const value = sanitizeIncomingId(req.body?.[field]);\n      if (value) return value;\n    }\n  }\n\n  if (config.params) {\n    const paramFields = Array.isArray(config.params) ? config.params : [config.params];\n    for (const param of paramFields) {\n      const value = sanitizeIncomingId(req.params?.[param]);\n      if (value) return value;\n    }\n  }\n\n  return undefined;\n}\n\n/**\n * Default headers checked for incoming trace ID propagation, in priority order:\n *   traceparent (W3C/OTel) → x-trace-id → x-request-id → x-correlation-id → trace-id\n */\nexport const DEFAULT_TRACE_HEADERS = [\n  'traceparent',\n  'x-trace-id',\n  'x-request-id',\n  'x-correlation-id',\n  'trace-id',\n];\n\n/**\n * Create trace ID middleware for Express/NestJS\n */\nexport function createTraceMiddleware(config: TraceIdConfig) {\n  const defaultExtractor = {\n    header: DEFAULT_TRACE_HEADERS,\n    query: ['traceId', 'trace_id'],\n  };\n  const resolvedConfig: TraceIdConfig = {\n    ...config,\n    extractor: config?.extractor ? { ...defaultExtractor, ...config.extractor } : defaultExtractor,\n  };\n\n  _setActiveContextKey(resolvedConfig.contextKey ?? TRACE_CONTEXT_KEY);\n\n  return (req: unknown, res: unknown, next: () => void) => {\n    let traceId: string | undefined;\n\n    if (resolvedConfig.extractor) {\n      traceId = extractTraceId(req, resolvedConfig.extractor);\n    }\n\n    if (!traceId) {\n      traceId = resolvedConfig.generator ? resolvedConfig.generator() : generateTraceId();\n    }\n\n    (req as Record<string, unknown>).traceId = traceId;\n    // Echo the trace ID back on the response, tolerating different response APIs:\n    // Express/Node use res.setHeader(), Fastify replies use reply.header(). Guard\n    // both and never let a missing/!function method (or already-sent headers)\n    // crash the request — the trace ID is still propagated via async context.\n    const resObj = res as {\n      setHeader?: (k: string, v: string) => void;\n      header?: (k: string, v: string) => void;\n      headersSent?: boolean;\n    };\n    if (!resObj.headersSent) {\n      try {\n        if (typeof resObj.setHeader === 'function') {\n          resObj.setHeader('X-Trace-Id', traceId);\n        } else if (typeof resObj.header === 'function') {\n          resObj.header('X-Trace-Id', traceId);\n        }\n      } catch {\n        /* response not in a header-settable state — context propagation still works */\n      }\n    }\n\n    runWithTraceId(traceId, () => next());\n  };\n}\n","/**\n * Per-request trace ID resolution shared by the HTTP logger middleware and the\n * context helpers. Internal: not re-exported from the package entry points.\n */\n\nimport type { HttpRequestShape } from '../types/http-shapes';\nimport {\n  DEFAULT_TRACE_HEADERS,\n  extractTraceId,\n  generateTraceId,\n  sanitizeIncomingId,\n} from './trace.utils';\n\nexport type TraceHeaderOption = string | readonly string[];\n\n/** Minimal structural request shape; Express and Fastify requests satisfy it. */\nexport type ContextRequestLike = HttpRequestShape;\n\n/** Fastify's default `genReqId` output (`req-` + base36 counter), unique only per process. */\nconst FASTIFY_COUNTER_ID = /^req-[\\da-z]+$/;\n\nconst FALLBACK_KEY = '_logixiaFallbackId';\n\n/** A caller-supplied request ID that is safe to use as a trace ID, or `undefined` for a counter ID. */\nexport function usableRequestId(id: unknown): string | undefined {\n  const sanitized = sanitizeIncomingId(id);\n  return sanitized !== undefined && !FASTIFY_COUNTER_ID.test(sanitized) ? sanitized : undefined;\n}\n\n/** Header names to read a trace ID from, defaulting to the library-wide list. */\nexport function resolveTraceHeaders(option: TraceHeaderOption | undefined): readonly string[] {\n  if (option === undefined) return DEFAULT_TRACE_HEADERS;\n  return typeof option === 'string' ? [option] : option;\n}\n\n/**\n * Resolve the trace ID for a request: a sanitised incoming header (honouring\n * `traceparent`), then a non-counter `request.id`, then a generated ID. Header\n * and `request.id` are recomputed per call so each caller's own header list is\n * honoured; only the generated fallback is stored on the request so every helper\n * agrees when no ID was sent.\n */\nexport function resolveRequestTraceId(req: ContextRequestLike, headers: readonly string[]): string {\n  const fromHeader = extractTraceId(req, { header: [...headers] });\n  if (fromHeader !== undefined) return fromHeader;\n\n  const fromId = usableRequestId(req.id);\n  if (fromId !== undefined) return fromId;\n\n  const holder = req as Record<string, unknown>;\n  const cached = holder[FALLBACK_KEY];\n  if (typeof cached === 'string') return cached;\n  const generated = generateTraceId();\n  try {\n    holder[FALLBACK_KEY] = generated;\n  } catch {\n    // frozen request object: each caller generates its own\n  }\n  return generated;\n}\n"],"mappings":"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"}