raffel 1.1.28 → 1.1.32

package/dist/ui/utils/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,IAAI,MAAM,MAAM,CAAA;AA4BvB;;GAEG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC,MAAM,CAE3D;AAED;;GAEG;AACH,wBAAgB,SAAS,IAAI,IAAI,CAAC,MAAM,CAEvC"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,IAAI,MAAM,MAAM,CAAA;AACvB,OAAO,KAAK,EAAE,aAAa,EAAc,MAAM,6BAA6B,CAAA;AAuF5E;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,GAAG,aAAa,GAAG,IAAI,CAQxE;AAED;;;GAGG;AACH,wBAAgB,WAAW,IAAI,IAAI,CAIlC;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC,MAAM,CAiC3D;AAED;;GAEG;AACH,wBAAgB,SAAS,IAAI,IAAI,CAAC,MAAM,CAEvC"}

package/dist/utils/logger.d.ts

@@ -1,15 +1,58 @@
 /**
  * Logger Utility
  *
- * Simple logger using pino with pretty-print in development.
+ * Logging built on pino, with pretty-print in development.
+ *
+ * The base logger is swappable at runtime via `configureLogger()` so a host
+ * application can inject its own pino instance (or a `LoggerFactory`) through
+ * `createServer({ logger })` and have *all* of Raffel's logs — internal
+ * adapters, core, request-scoped `ctx.logger`, and the `log` provider — flow
+ * through it in a single, Datadog-consistent format.
+ *
+ * ## Memory contract
+ *
+ * `createLogger()` returns a *stable* proxy created once (typically at module
+ * import). Its underlying pino child is resolved once per
+ * (logger generation, component) and memoized; method handles are cached too.
+ * It therefore never allocates a logger per call, and component loggers are
+ * process-scoped (one per module), never request-scoped. Swapping the base via
+ * `configureLogger()` only bumps a generation counter — it does not multiply
+ * allocations. Request correlation (`requestId`) is handled lazily in
+ * `createContext` (see `types/context.ts`), which materializes at most one
+ * child per request, and only if the handler actually logs.
  */
 import pino from 'pino';
+import type { LoggerFactory } from '../ports/outbound/logger.js';
 /**
- * Create a child logger with a component name
+ * Inject the host application's logger. Called once by `createServer({ logger })`
+ * before any request is served.
+ *
+ * Accepts either:
+ * - a `pino.Logger` — the rich path; component loggers become
+ *   `parent.child({ component })`, and request loggers
+ *   `parent.child({ requestId })`, so every binding is preserved end to end; or
+ * - a `LoggerFactory` — the abstract path; component loggers come from the
+ *   factory, mapped onto the pino-shaped surface (`trace`→`debug`,
+ *   `fatal`→`error`).
+ */
+export declare function configureLogger(input: pino.Logger | LoggerFactory): void;
+/**
+ * Reset the logger back to the env-derived default. Primarily for tests that
+ * inject a logger and need to restore global state afterwards.
+ */
+export declare function resetLogger(): void;
+/**
+ * Create a child logger scoped to a component.
+ *
+ * Returns a stable proxy: the call site keeps the same reference for the
+ * process lifetime, while the proxy transparently re-resolves and re-binds its
+ * underlying pino child whenever the base logger is swapped. The resolved child
+ * and its bound methods are memoized per generation, so logging never allocates
+ * in the hot path.
  */
 export declare function createLogger(component: string): pino.Logger;
 /**
- * Get the base logger
+ * Get the base logger (the active root the host injected, or the env default).
  */
 export declare function getLogger(): pino.Logger;
 //# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,IAAI,MAAM,MAAM,CAAA;AA4BvB;;GAEG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC,MAAM,CAE3D;AAED;;GAEG;AACH,wBAAgB,SAAS,IAAI,IAAI,CAAC,MAAM,CAEvC"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,IAAI,MAAM,MAAM,CAAA;AACvB,OAAO,KAAK,EAAE,aAAa,EAAc,MAAM,6BAA6B,CAAA;AAuF5E;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,GAAG,aAAa,GAAG,IAAI,CAQxE;AAED;;;GAGG;AACH,wBAAgB,WAAW,IAAI,IAAI,CAIlC;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC,MAAM,CAiC3D;AAED;;GAEG;AACH,wBAAgB,SAAS,IAAI,IAAI,CAAC,MAAM,CAEvC"}

package/dist/utils/logger.js

@@ -1,42 +1,178 @@
 /**
  * Logger Utility
  *
- * Simple logger using pino with pretty-print in development.
+ * Logging built on pino, with pretty-print in development.
+ *
+ * The base logger is swappable at runtime via `configureLogger()` so a host
+ * application can inject its own pino instance (or a `LoggerFactory`) through
+ * `createServer({ logger })` and have *all* of Raffel's logs — internal
+ * adapters, core, request-scoped `ctx.logger`, and the `log` provider — flow
+ * through it in a single, Datadog-consistent format.
+ *
+ * ## Memory contract
+ *
+ * `createLogger()` returns a *stable* proxy created once (typically at module
+ * import). Its underlying pino child is resolved once per
+ * (logger generation, component) and memoized; method handles are cached too.
+ * It therefore never allocates a logger per call, and component loggers are
+ * process-scoped (one per module), never request-scoped. Swapping the base via
+ * `configureLogger()` only bumps a generation counter — it does not multiply
+ * allocations. Request correlation (`requestId`) is handled lazily in
+ * `createContext` (see `types/context.ts`), which materializes at most one
+ * child per request, and only if the handler actually logs.
  */
 import pino from 'pino';
 const isDev = process.env.NODE_ENV !== 'production';
-// Respect `LOG_FORMAT=json` to opt into JSON output even in dev. Without
-// this override raffel always emits pino-pretty in dev, which mixes
-// badly with a host service's own JSON logs and is hostile to grep / jq
-// when the operator is shipping aggregated logs to a JSON sink.
-const logFormat = String(process.env.LOG_FORMAT ?? '').toLowerCase();
-const wantsPretty = isDev && logFormat !== 'json';
-/**
- * Base logger instance
- */
-const baseLogger = pino({
-    level: process.env.LOG_LEVEL ?? (isDev ? 'debug' : 'info'),
-    transport: wantsPretty
-        ? {
-            target: 'pino-pretty',
-            options: {
-                colorize: true,
-                translateTime: 'SYS:standard',
-                ignore: 'pid,hostname',
-            },
-        }
-        : undefined,
-});
 /**
- * Create a child logger with a component name
+ * Build the env-derived default pino logger.
+ *
+ * Respects `LOG_FORMAT=json` to opt into JSON output even in dev. Without this
+ * override raffel always emits pino-pretty in dev, which mixes badly with a
+ * host service's own JSON logs and is hostile to grep / jq when the operator is
+ * shipping aggregated logs to a JSON sink.
+ */
+function buildDefaultLogger() {
+    const logFormat = String(process.env.LOG_FORMAT ?? '').toLowerCase();
+    const wantsPretty = isDev && logFormat !== 'json';
+    return pino({
+        level: process.env.LOG_LEVEL ?? (isDev ? 'debug' : 'info'),
+        transport: wantsPretty
+            ? {
+                target: 'pino-pretty',
+                options: {
+                    colorize: true,
+                    translateTime: 'SYS:standard',
+                    ignore: 'pid,hostname',
+                },
+            }
+            : undefined,
+    });
+}
+/** Active base logger. Swapped by `configureLogger()`. */
+let baseLogger = buildDefaultLogger();
+/**
+ * Optional component factory. When a host injects a `LoggerFactory` (rather than
+ * a pino instance) the component loggers are produced by it instead of via
+ * `baseLogger.child(...)`.
+ */
+let componentFactory = null;
+/**
+ * Generation counter, bumped on every `configureLogger()` / `resetLogger()`
+ * call so the lazy proxies returned by `createLogger()` know to re-resolve and
+ * re-bind their cached child.
+ */
+let generation = 0;
+/**
+ * Adapt a minimal `LoggerPort` (debug/info/warn/error) up to the
+ * pino.Logger-shaped surface the rest of the codebase expects:
+ * `trace`→`debug`, `fatal`→`error`, and `child` rebinding to itself (a
+ * `LoggerPort` carries no bindings, so child loggers share the same sink).
+ */
+function portToPinoShape(port) {
+    const forward = (method) => (...args) => {
+        ;
+        port[method](...args);
+    };
+    const shaped = {
+        trace: forward('debug'),
+        debug: forward('debug'),
+        info: forward('info'),
+        warn: forward('warn'),
+        error: forward('error'),
+        fatal: forward('error'),
+        child: () => shaped,
+        level: process.env.LOG_LEVEL ?? (isDev ? 'debug' : 'info'),
+    };
+    return shaped;
+}
+/** Cache of the resolved active base, keyed by generation. */
+let resolvedBaseGen = -1;
+let resolvedBase = baseLogger;
+function activeBase() {
+    if (resolvedBaseGen !== generation) {
+        resolvedBase = componentFactory ? portToPinoShape(componentFactory('')) : baseLogger;
+        resolvedBaseGen = generation;
+    }
+    return resolvedBase;
+}
+/**
+ * Inject the host application's logger. Called once by `createServer({ logger })`
+ * before any request is served.
+ *
+ * Accepts either:
+ * - a `pino.Logger` — the rich path; component loggers become
+ *   `parent.child({ component })`, and request loggers
+ *   `parent.child({ requestId })`, so every binding is preserved end to end; or
+ * - a `LoggerFactory` — the abstract path; component loggers come from the
+ *   factory, mapped onto the pino-shaped surface (`trace`→`debug`,
+ *   `fatal`→`error`).
+ */
+export function configureLogger(input) {
+    if (typeof input === 'function') {
+        componentFactory = input;
+    }
+    else {
+        baseLogger = input;
+        componentFactory = null;
+    }
+    generation += 1;
+}
+/**
+ * Reset the logger back to the env-derived default. Primarily for tests that
+ * inject a logger and need to restore global state afterwards.
+ */
+export function resetLogger() {
+    baseLogger = buildDefaultLogger();
+    componentFactory = null;
+    generation += 1;
+}
+/**
+ * Create a child logger scoped to a component.
+ *
+ * Returns a stable proxy: the call site keeps the same reference for the
+ * process lifetime, while the proxy transparently re-resolves and re-binds its
+ * underlying pino child whenever the base logger is swapped. The resolved child
+ * and its bound methods are memoized per generation, so logging never allocates
+ * in the hot path.
  */
 export function createLogger(component) {
-    return baseLogger.child({ component });
+    let cachedGen = -1;
+    let child;
+    const boundCache = new Map();
+    const resolve = () => {
+        if (cachedGen !== generation) {
+            child = componentFactory
+                ? portToPinoShape(componentFactory(component))
+                : activeBase().child({ component });
+            cachedGen = generation;
+            boundCache.clear();
+        }
+        return child;
+    };
+    return new Proxy(Object.create(null), {
+        get(_target, prop) {
+            const target = resolve();
+            const value = target[prop];
+            if (typeof value !== 'function')
+                return value;
+            let bound = boundCache.get(prop);
+            if (bound === undefined) {
+                bound = value.bind(target);
+                boundCache.set(prop, bound);
+            }
+            return bound;
+        },
+        set(_target, prop, value) {
+            ;
+            resolve()[prop] = value;
+            return true;
+        },
+    });
 }
 /**
- * Get the base logger
+ * Get the base logger (the active root the host injected, or the env default).
  */
 export function getLogger() {
-    return baseLogger;
+    return activeBase();
 }
 //# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -1 +1 @@
-{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,IAAI,MAAM,MAAM,CAAA;AAEvB,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,CAAA;AAEnD,yEAAyE;AACzE,oEAAoE;AACpE,wEAAwE;AACxE,gEAAgE;AAChE,MAAM,SAAS,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAA;AACpE,MAAM,WAAW,GAAG,KAAK,IAAI,SAAS,KAAK,MAAM,CAAA;AAEjD;;GAEG;AACH,MAAM,UAAU,GAAG,IAAI,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC;IAC1D,SAAS,EAAE,WAAW;QACpB,CAAC,CAAC;YACE,MAAM,EAAE,aAAa;YACrB,OAAO,EAAE;gBACP,QAAQ,EAAE,IAAI;gBACd,aAAa,EAAE,cAAc;gBAC7B,MAAM,EAAE,cAAc;aACvB;SACF;QACH,CAAC,CAAC,SAAS;CACd,CAAC,CAAA;AAEF;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,SAAiB;IAC5C,OAAO,UAAU,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC,CAAA;AACxC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,SAAS;IACvB,OAAO,UAAU,CAAA;AACnB,CAAC"}
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "raffel",
-  "version": "1.1.28",
+  "version": "1.1.32",
   "description": "Unified multi-protocol server runtime. One core, multiple transports.",
   "type": "module",
   "main": "./dist/index.js",