logixia 1.8.2 → 1.8.3

package/dist/{logitron-logger.module-Fof9Er2E.js → logitron-logger.module-B-sUxEiz.js}

@@ -1,5 +1,5 @@
 const require_chunk = require('./chunk-BTgCAUrQ.js');
-const require_transport_manager = require('./transport.manager-DU1W0wV3.js');
+const require_transport_manager = require('./transport.manager-CqPyddCV.js');
 let fast_json_stringify = require("fast-json-stringify");
 fast_json_stringify = require_chunk.__toESM(fast_json_stringify);
 let node_async_hooks = require("node:async_hooks");
@@ -854,8 +854,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() ?? {};
@@ -900,9 +911,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);
@@ -911,6 +936,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;
@@ -918,23 +953,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;
 		}
 	}
@@ -942,7 +977,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;
 		}
 	}
@@ -1010,6 +1045,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) {
@@ -1017,6 +1059,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);
 	}
@@ -1692,7 +1739,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;
@@ -10583,9 +10630,33 @@ var require_cjs = /* @__PURE__ */ require_chunk.__commonJS({ "node_modules/rxjs/
 //#endregion
 //#region src/core/kafka-trace.interceptor.ts
 var import_cjs$1 = /* @__PURE__ */ require_chunk.__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,
@@ -10610,12 +10681,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,
@@ -10635,7 +10716,7 @@ let KafkaTraceInterceptor = class KafkaTraceInterceptor$1 {
 		});
 	}
 };
-KafkaTraceInterceptor = __decorate([(0, __nestjs_common.Injectable)(), __decorateMetadata("design:paramtypes", [Object])], KafkaTraceInterceptor);
+KafkaTraceInterceptor = _KafkaTraceInterceptor = __decorate([(0, __nestjs_common.Injectable)(), __decorateMetadata("design:paramtypes", [Object, Boolean])], KafkaTraceInterceptor);
 
 //#endregion
 //#region \0@oxc-project+runtime@0.95.0/helpers/decorateParam.js
@@ -10647,6 +10728,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;
@@ -10665,16 +10758,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,
@@ -10768,6 +10867,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.
@@ -10790,17 +10912,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);
 	}
@@ -10850,7 +10970,7 @@ let LogixiaLoggerModule = class LogixiaLoggerModule$1 {
 							},
 							...loggerConfig
 						});
-						_LogixiaLoggerModule._globalLogger = service;
+						_LogixiaLoggerModule._setGlobalLogger(service);
 						return service;
 					},
 					inject: [LOGIXIA_LOGGER_CONFIG]
@@ -10922,7 +11042,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]
@@ -11227,6 +11347,12 @@ Object.defineProperty(exports, 'resetShutdownHandlers', {
     return resetShutdownHandlers;
   }
 });
+Object.defineProperty(exports, 'resolveResponseHeader', {
+  enumerable: true,
+  get: function () {
+    return resolveResponseHeader;
+  }
+});
 Object.defineProperty(exports, 'runWithTraceId', {
   enumerable: true,
   get: function () {
@@ -11257,4 +11383,4 @@ Object.defineProperty(exports, 'usePlugin', {
     return usePlugin;
   }
 });
-//# sourceMappingURL=logitron-logger.module-Fof9Er2E.js.map
+//# sourceMappingURL=logitron-logger.module-B-sUxEiz.js.map