logixia 1.8.2 → 1.8.3

package/dist/{logitron-logger.module-DucvDnxZ.mjs → logitron-logger.module-B0A-mnc7.mjs}

@@ -1,5 +1,5 @@
 import { a as __toESM, r as __require, t as __commonJS } from "./chunk-uEZWKkIX.mjs";
-import { d as internalLog, f as internalWarn, t as TransportManager, u as internalError } from "./transport.manager-BCnLEmOy.mjs";
+import { d as internalLog, f as internalWarn, t as TransportManager, u as internalError } from "./transport.manager-DMdotLoQ.mjs";
 import buildFastStringify from "fast-json-stringify";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { randomUUID } from "node:crypto";
@@ -849,8 +849,19 @@ var TraceContext = class TraceContext {
 	/**
 	* Mutate the CURRENT async context in-place.
 	*
-	* ⚠️  Uses `enterWith()` — prefer `run()` when you can wrap the operation
-	* in a callback, as it scopes the context to the callback only.
+	* ⚠️  DEPRECATED — unsafe for concurrent requests.
+	*
+	* Uses `AsyncLocalStorage.enterWith()`, which mutates the current async
+	* execution context and every Promise chain spawned from it. In a server
+	* processing overlapping requests this can cause a trace ID set for one
+	* request to bleed into *other* in-flight requests that share the same
+	* async parent (e.g. a module-level setup function or a cached handler).
+	*
+	* Use {@link run} instead — it scopes the context to a callback so there
+	* is no risk of cross-request leakage.
+	*
+	* @deprecated Use `TraceContext.instance.run(traceId, fn)` — do not call
+	*             `setTraceId` from request-handling code.
 	*/
 	setTraceId(traceId, data) {
 		const current = this.storage.getStore() ?? {};
@@ -895,9 +906,23 @@ function getCurrentTraceId() {
 /**
 * Set trace ID in the CURRENT async context without starting a new one.
 *
-* ⚠️  Uses `enterWith()` — mutates the context for the current async execution
-* and all futures spawned from it. Prefer `runWithTraceId()` when you can wrap
-* the operation in a callback.
+* ⚠️  DEPRECATED — unsafe for concurrent requests.
+*
+* Uses `AsyncLocalStorage.enterWith()`, which mutates the current async
+* execution context and every Promise chain spawned from it. Under load this
+* can cause a trace ID from one request to bleed into others sharing the same
+* async parent.
+*
+* Use {@link runWithTraceId} instead:
+*
+* ```ts
+* await runWithTraceId(traceId, async () => {
+*   // everything here is scoped to this traceId only
+* });
+* ```
+*
+* @deprecated Use `runWithTraceId(traceId, fn)` — do not call `setTraceId`
+*             from request-handling code.
 */
 function setTraceId(traceId, data) {
 	TraceContext.instance.setTraceId(traceId, data);
@@ -906,6 +931,16 @@ function setTraceId(traceId, data) {
 function runWithTraceId(traceId, fn, data) {
 	return TraceContext.instance.run(traceId, fn, data);
 }
+/**
+* Coerce an arbitrary value to a non-empty trace ID string, or `undefined`.
+* Rejects empty/whitespace-only strings, non-strings, and non-first array elements.
+*/
+function toValidTraceId(value) {
+	const first$1 = Array.isArray(value) ? value[0] : value;
+	if (typeof first$1 !== "string") return void 0;
+	const trimmed = first$1.trim();
+	return trimmed.length > 0 ? trimmed : void 0;
+}
 /** Extract trace ID from request using configuration (header → query → body → params). */
 function extractTraceId(request, config) {
 	const req = request;
@@ -913,23 +948,23 @@ function extractTraceId(request, config) {
 		const headers = Array.isArray(config.header) ? config.header : [config.header];
 		for (const header of headers) {
 			var _req$headers;
-			const value = (_req$headers = req.headers) === null || _req$headers === void 0 ? void 0 : _req$headers[header.toLowerCase()];
-			if (value) return Array.isArray(value) ? value[0] : value;
+			const value = toValidTraceId((_req$headers = req.headers) === null || _req$headers === void 0 ? void 0 : _req$headers[header.toLowerCase()]);
+			if (value) return value;
 		}
 	}
 	if (config.query) {
 		const queries = Array.isArray(config.query) ? config.query : [config.query];
 		for (const query of queries) {
 			var _req$query;
-			const value = (_req$query = req.query) === null || _req$query === void 0 ? void 0 : _req$query[query];
-			if (value) return Array.isArray(value) ? value[0] : value;
+			const value = toValidTraceId((_req$query = req.query) === null || _req$query === void 0 ? void 0 : _req$query[query]);
+			if (value) return value;
 		}
 	}
 	if (config.body) {
 		const bodyFields = Array.isArray(config.body) ? config.body : [config.body];
 		for (const field of bodyFields) {
 			var _req$body;
-			const value = (_req$body = req.body) === null || _req$body === void 0 ? void 0 : _req$body[field];
+			const value = toValidTraceId((_req$body = req.body) === null || _req$body === void 0 ? void 0 : _req$body[field]);
 			if (value) return value;
 		}
 	}
@@ -937,7 +972,7 @@ function extractTraceId(request, config) {
 		const paramFields = Array.isArray(config.params) ? config.params : [config.params];
 		for (const param of paramFields) {
 			var _req$params;
-			const value = (_req$params = req.params) === null || _req$params === void 0 ? void 0 : _req$params[param];
+			const value = toValidTraceId((_req$params = req.params) === null || _req$params === void 0 ? void 0 : _req$params[param]);
 			if (value) return value;
 		}
 	}
@@ -1005,6 +1040,13 @@ function namespacePatternToRegex(pattern) {
 /** Max compiled patterns to keep in memory. Oldest entry is evicted when full. */
 const _NS_CACHE_MAX = 1e3;
 const _nsPatternCache = /* @__PURE__ */ new Map();
+/**
+* One-shot warning so operators notice runaway pattern growth.
+* If the cache is being thrashed (>N evictions) the namespace level config is
+* almost certainly wrong — likely dynamic/unique patterns being registered.
+*/
+let _nsCacheEvictionWarned = false;
+let _nsCacheEvictionCount = 0;
 function matchesNamespacePattern(ns, pattern) {
 	let re = _nsPatternCache.get(pattern);
 	if (!re) {
@@ -1012,6 +1054,11 @@ function matchesNamespacePattern(ns, pattern) {
 		if (_nsPatternCache.size >= _NS_CACHE_MAX) {
 			const firstKey = _nsPatternCache.keys().next().value;
 			if (firstKey !== void 0) _nsPatternCache.delete(firstKey);
+			_nsCacheEvictionCount++;
+			if (!_nsCacheEvictionWarned) {
+				_nsCacheEvictionWarned = true;
+				process.stderr.write(`[logixia] namespace pattern cache hit ${_NS_CACHE_MAX} entries — evicting. This usually means dynamic/unique patterns are being registered at runtime; review your levelOptions.namespaces configuration.\n`);
+			}
 		}
 		_nsPatternCache.set(pattern, re);
 	}
@@ -1687,7 +1734,7 @@ let LogixiaLoggerService = _LogixiaLoggerService = class LogixiaLoggerService$1
 		return this.logger.getLevel();
 	}
 	child(context$1, data) {
-		const childService = new _LogixiaLoggerService();
+		const childService = new _LogixiaLoggerService(this._mergedConfig);
 		childService.logger = this.logger.child(context$1, data);
 		childService.context = context$1;
 		return childService;
@@ -10578,9 +10625,33 @@ var require_cjs = /* @__PURE__ */ __commonJS({ "node_modules/rxjs/dist/cjs/index
 //#endregion
 //#region src/core/kafka-trace.interceptor.ts
 var import_cjs$1 = /* @__PURE__ */ __toESM(require_cjs());
+var _KafkaTraceInterceptor;
 let KafkaTraceInterceptor = class KafkaTraceInterceptor$1 {
-	constructor(config) {
+	static {
+		_KafkaTraceInterceptor = this;
+	}
+	static #_ = this.metrics = {
+		accepted: 0,
+		acceptedWithoutTrace: 0,
+		dropped: 0
+	};
+	/** Reset counters (tests). */
+	static resetMetrics() {
+		_KafkaTraceInterceptor.metrics.accepted = 0;
+		_KafkaTraceInterceptor.metrics.acceptedWithoutTrace = 0;
+		_KafkaTraceInterceptor.metrics.dropped = 0;
+	}
+	/**
+	* @param config        - TraceIdConfig options (extractor keys, contextKey, etc.)
+	* @param requireTraceId - When true, messages with no traceId are silently skipped
+	*                         (EMPTY Observable — message is ack'd, consumer stays alive).
+	*                         A WARN is logged AND `KafkaTraceInterceptor.metrics.dropped`
+	*                         increments so the missing traceId is observable end-to-end.
+	*                         Default: false (handler runs without trace context).
+	*/
+	constructor(config, requireTraceId = false) {
 		this.config = config;
+		this.requireTraceId = requireTraceId;
 		this.ctx = TraceContext.instance;
 		this.config = {
 			enabled: true,
@@ -10605,12 +10676,22 @@ let KafkaTraceInterceptor = class KafkaTraceInterceptor$1 {
 		let traceId;
 		if (this.config.extractor) traceId = extractTraceId({
 			body: data,
-			headers: (rpcData === null || rpcData === void 0 ? void 0 : rpcData.headers) || {},
+			headers: (rpcData === null || rpcData === void 0 ? void 0 : rpcData.headers) ?? {},
 			query: {},
 			params: {}
 		}, this.config.extractor);
 		if (!traceId) traceId = this.ctx.getCurrentTraceId();
-		if (!traceId) return next.handle();
+		if (!traceId) {
+			if (this.requireTraceId) {
+				var _LogixiaLoggerModule$;
+				_KafkaTraceInterceptor.metrics.dropped++;
+				(_LogixiaLoggerModule$ = LogixiaLoggerModule.getGlobalLogger()) === null || _LogixiaLoggerModule$ === void 0 || _LogixiaLoggerModule$.warn(`[KafkaTraceInterceptor] Missing traceId on topic "${rpcData === null || rpcData === void 0 ? void 0 : rpcData.topic}" — message skipped.`);
+				return import_cjs$1.EMPTY;
+			}
+			_KafkaTraceInterceptor.metrics.acceptedWithoutTrace++;
+			return next.handle();
+		}
+		_KafkaTraceInterceptor.metrics.accepted++;
 		const kafkaContext = {
 			messageType: "kafka",
 			topic: rpcData === null || rpcData === void 0 ? void 0 : rpcData.topic,
@@ -10630,7 +10711,7 @@ let KafkaTraceInterceptor = class KafkaTraceInterceptor$1 {
 		});
 	}
 };
-KafkaTraceInterceptor = __decorate([Injectable(), __decorateMetadata("design:paramtypes", [Object])], KafkaTraceInterceptor);
+KafkaTraceInterceptor = _KafkaTraceInterceptor = __decorate([Injectable(), __decorateMetadata("design:paramtypes", [Object, Boolean])], KafkaTraceInterceptor);
 
 //#endregion
 //#region \0@oxc-project+runtime@0.95.0/helpers/decorateParam.js
@@ -10642,6 +10723,18 @@ function __decorateParam(paramIndex, decorator) {
 
 //#endregion
 //#region src/core/trace.middleware.ts
+/** Default response header used to echo the resolved traceId back to the caller. */
+const DEFAULT_TRACE_RESPONSE_HEADER = "X-Trace-Id";
+/**
+* Resolve the response header name from config.
+* - `undefined`   → default `'X-Trace-Id'`
+* - `string`      → user's custom header
+* - `false`       → `null` (suppress entirely)
+*/
+function resolveResponseHeader(config) {
+	if ((config === null || config === void 0 ? void 0 : config.responseHeader) === false) return null;
+	return (config === null || config === void 0 ? void 0 : config.responseHeader) ?? DEFAULT_TRACE_RESPONSE_HEADER;
+}
 let TraceMiddleware = class TraceMiddleware$1 {
 	constructor(config) {
 		this.config = config;
@@ -10660,16 +10753,22 @@ let TraceMiddleware = class TraceMiddleware$1 {
 				...config.extractor
 			} : defaultExtractor
 		};
-		this.ctx.setContextKey(this.config.contextKey ?? "traceId");
+		if (this.config.enabled) this.ctx.setContextKey(this.config.contextKey ?? "traceId");
 	}
 	use(req, res, next) {
 		var _this$config;
 		if (!((_this$config = this.config) === null || _this$config === void 0 ? void 0 : _this$config.enabled)) return next();
 		let traceId;
 		if (this.config.extractor) traceId = extractTraceId(req, this.config.extractor);
-		if (!traceId) traceId = this.config.generator ? this.config.generator() : this.ctx.generate();
+		if (!traceId && this.config.generator) {
+			const candidate = this.config.generator();
+			if (typeof candidate === "string" && candidate.trim().length > 0) traceId = candidate;
+			else process.stderr.write("[logixia] TraceIdConfig.generator returned a non-string/empty value — using built-in generator.\n");
+		}
+		if (!traceId) traceId = this.ctx.generate();
 		req.traceId = traceId;
-		res.setHeader("X-Trace-Id", traceId);
+		const header = resolveResponseHeader(this.config);
+		if (header) res.setHeader(header, traceId);
 		this.ctx.run(traceId, () => next(), {
 			method: req.method,
 			url: req.url,
@@ -10763,6 +10862,29 @@ let LogixiaLoggerModule = class LogixiaLoggerModule$1 {
 	static #_ = this.loggerConfig = {};
 	static #_2 = this._globalLogger = null;
 	/**
+	* @internal Set the global logger exactly once.
+	*
+	* Called from the module's forRoot / forRootAsync factory. If the module is
+	* initialised more than once in the same process (nested DI context, test
+	* harness creating multiple apps, hot reload, etc.) a warning is written to
+	* stderr and the first logger wins — silently overwriting would allow the
+	* newer instance's transport config to replace the live one while the old
+	* one is still being used by registered shutdown hooks, decorators, etc.
+	*
+	* Use {@link _resetGlobalLogger} in tests to reset between runs.
+	*/
+	static _setGlobalLogger(service) {
+		if (_LogixiaLoggerModule._globalLogger !== null) {
+			process.stderr.write("[logixia] LogixiaLoggerModule.forRoot() was called more than once — ignoring the second init. If this is intentional (e.g. in tests), call LogixiaLoggerModule._resetGlobalLogger() first.\n");
+			return;
+		}
+		_LogixiaLoggerModule._globalLogger = service;
+	}
+	/** @internal Clear the global logger. Tests only. */
+	static _resetGlobalLogger() {
+		_LogixiaLoggerModule._globalLogger = null;
+	}
+	/**
 	* Returns the global LogixiaLoggerService instance that was created when the
 	* module booted. Useful for logging outside of NestJS DI — utility functions,
 	* plain scripts, decorators — without injecting the service everywhere.
@@ -10785,17 +10907,15 @@ let LogixiaLoggerModule = class LogixiaLoggerModule$1 {
 	}
 	configure(consumer) {
 		const { forRoutes = DEFAULT_ROUTES, exclude } = this.config;
-		const middlewareConfig = (req, res, next) => {
-			let traceConfig;
-			if (typeof _LogixiaLoggerModule.loggerConfig.traceId === "object") traceConfig = _LogixiaLoggerModule.loggerConfig.traceId;
-			else if (_LogixiaLoggerModule.loggerConfig.traceId === true) traceConfig = {
-				enabled: true,
-				contextKey: "traceId",
-				generator: () => TraceContext.instance.generate()
-			};
-			else traceConfig = void 0;
-			return new TraceMiddleware(traceConfig).use(req, res, next);
+		let resolvedTraceConfig;
+		if (typeof _LogixiaLoggerModule.loggerConfig.traceId === "object") resolvedTraceConfig = _LogixiaLoggerModule.loggerConfig.traceId;
+		else if (_LogixiaLoggerModule.loggerConfig.traceId === true) resolvedTraceConfig = {
+			enabled: true,
+			contextKey: "traceId",
+			generator: () => TraceContext.instance.generate()
 		};
+		const middleware = new TraceMiddleware(resolvedTraceConfig);
+		const middlewareConfig = (req, res, next) => middleware.use(req, res, next);
 		if (exclude) consumer.apply(middlewareConfig).exclude(...exclude).forRoutes(...forRoutes);
 		else consumer.apply(middlewareConfig).forRoutes(...forRoutes);
 	}
@@ -10845,7 +10965,7 @@ let LogixiaLoggerModule = class LogixiaLoggerModule$1 {
 							},
 							...loggerConfig
 						});
-						_LogixiaLoggerModule._globalLogger = service;
+						_LogixiaLoggerModule._setGlobalLogger(service);
 						return service;
 					},
 					inject: [LOGIXIA_LOGGER_CONFIG]
@@ -10917,7 +11037,7 @@ let LogixiaLoggerModule = class LogixiaLoggerModule$1 {
 						};
 						_LogixiaLoggerModule.loggerConfig = defaultConfig;
 						const service = new LogixiaLoggerService(defaultConfig);
-						_LogixiaLoggerModule._globalLogger = service;
+						_LogixiaLoggerModule._setGlobalLogger(service);
 						return service;
 					},
 					inject: [LOGIXIA_LOGGER_CONFIG]
@@ -10982,5 +11102,5 @@ let LogixiaLoggerModule = class LogixiaLoggerModule$1 {
 LogixiaLoggerModule = _LogixiaLoggerModule = __decorate([Module({})], LogixiaLoggerModule);
 
 //#endregion
-export { disableOtelBridge as A, PluginRegistry as B, traceStorage as C, resetShutdownHandlers as D, registerForShutdown as E, normalizeError as F, createFastifyContextHook as G, usePlugin as H, serializeError as I, DEFAULT_LOG_COLORS as L, getOtelMetaFields as M, initOtelBridge as N, applyRedaction as O, isError as P, DEFAULT_LOG_LEVELS as R, setTraceId as S, flushOnExit as T, LogixiaContext as U, globalPluginRegistry as V, createExpressContextMiddleware as W, createTraceMiddleware as _, TraceMiddleware as a, getTraceContextKey as b, LogixiaLoggerService as c, LogixiaLogger as d, createLogger as f, _setActiveContextKey as g, TraceContext as h, WebSocketTraceInterceptor as i, getActiveOtelContext as j, redactObject as k, __decorate as l, TRACE_CONTEXT_KEY as m, LOGIXIA_LOGGER_PREFIX as n, __decorateParam as o, DEFAULT_TRACE_HEADERS as p, LogixiaLoggerModule as r, KafkaTraceInterceptor as s, LOGIXIA_LOGGER_CONFIG as t, __decorateMetadata as u, extractTraceId as v, deregisterFromShutdown as w, runWithTraceId as x, getCurrentTraceId as y, LogLevel as z };
-//# sourceMappingURL=logitron-logger.module-DucvDnxZ.mjs.map
+export { redactObject as A, LogLevel as B, setTraceId as C, registerForShutdown as D, flushOnExit as E, isError as F, createExpressContextMiddleware as G, globalPluginRegistry as H, normalizeError as I, createFastifyContextHook as K, serializeError as L, getActiveOtelContext as M, getOtelMetaFields as N, resetShutdownHandlers as O, initOtelBridge as P, DEFAULT_LOG_COLORS as R, runWithTraceId as S, deregisterFromShutdown as T, usePlugin as U, PluginRegistry as V, LogixiaContext as W, _setActiveContextKey as _, TraceMiddleware as a, getCurrentTraceId as b, KafkaTraceInterceptor as c, __decorateMetadata as d, LogixiaLogger as f, TraceContext as g, TRACE_CONTEXT_KEY as h, WebSocketTraceInterceptor as i, disableOtelBridge as j, applyRedaction as k, LogixiaLoggerService as l, DEFAULT_TRACE_HEADERS as m, LOGIXIA_LOGGER_PREFIX as n, resolveResponseHeader as o, createLogger as p, LogixiaLoggerModule as r, __decorateParam as s, LOGIXIA_LOGGER_CONFIG as t, __decorate as u, createTraceMiddleware as v, traceStorage as w, getTraceContextKey as x, extractTraceId as y, DEFAULT_LOG_LEVELS as z };
+//# sourceMappingURL=logitron-logger.module-B0A-mnc7.mjs.map