logixia 1.3.0 → 1.4.0

package/dist/{logitron-logger.module-2AzkadqZ.mjs → logitron-logger.module-C939PIEV.mjs}

@@ -1,5 +1,5 @@
-import { a as __toESM, t as __commonJS } from "./chunk-uEZWKkIX.mjs";
-import { d as internalLog, f as internalWarn, t as TransportManager, u as internalError } from "./transport.manager-5VVdqS3o.mjs";
+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-DR7TLXQT.mjs";
 import buildFastStringify from "fast-json-stringify";
 import { AsyncLocalStorage } from "node:async_hooks";
 import crypto$1 from "crypto";
@@ -73,6 +73,103 @@ function createFastifyContextHook(options = {}) {
 	};
 }
 
+//#endregion
+//#region src/plugin.ts
+/**
+* Holds an ordered list of `LogixiaPlugin` instances and dispatches lifecycle
+* events to them. One registry is created per logger instance; a global
+* singleton is also exported for process-wide registration.
+*/
+var PluginRegistry = class {
+	constructor() {
+		this._plugins = [];
+	}
+	/**
+	* Register a plugin. Silently skips if a plugin with the same `name` is
+	* already registered on this registry.
+	*/
+	register(plugin) {
+		if (this._plugins.some((p) => p.name === plugin.name)) return;
+		this._plugins.push(plugin);
+		if (plugin.onInit) {
+			const result = plugin.onInit();
+			if (result instanceof Promise) result.catch(() => {});
+		}
+	}
+	/** Remove a previously registered plugin by name. No-op if not found. */
+	unregister(name) {
+		const idx = this._plugins.findIndex((p) => p.name === name);
+		if (idx !== -1) this._plugins.splice(idx, 1);
+	}
+	/** Returns `true` if a plugin with the given name is registered. */
+	has(name) {
+		return this._plugins.some((p) => p.name === name);
+	}
+	/** Number of currently registered plugins. */
+	get size() {
+		return this._plugins.length;
+	}
+	/**
+	* Run all `onLog` hooks in order.
+	* Returns `null` if any plugin cancels the entry; otherwise returns the
+	* (possibly transformed) entry.
+	*/
+	async runOnLog(entry) {
+		let current = entry;
+		for (const plugin of this._plugins) {
+			if (!plugin.onLog) continue;
+			current = await plugin.onLog(current);
+			if (current === null) return null;
+		}
+		return current;
+	}
+	/**
+	* Notify all `onError` hooks.
+	* Errors thrown inside hooks are swallowed to prevent error cascades.
+	*/
+	async runOnError(error, entry) {
+		for (const plugin of this._plugins) if (plugin.onError) {
+			const r = plugin.onError(error, entry);
+			if (r instanceof Promise) await r.catch(() => {});
+		}
+	}
+	/** Run all `onShutdown` hooks concurrently. Hook errors are swallowed. */
+	async runOnShutdown() {
+		await Promise.all(this._plugins.filter((p) => Boolean(p.onShutdown)).map((p) => {
+			const r = p.onShutdown();
+			return r instanceof Promise ? r.catch(() => {}) : Promise.resolve();
+		}));
+	}
+};
+/**
+* Module-level singleton registry.
+*
+* Plugins registered here are automatically copied into every **new** logger
+* instance created after the registration. Already-created loggers are not
+* retroactively affected — use `logger.use(plugin)` for per-instance control.
+*/
+const globalPluginRegistry = new PluginRegistry();
+/**
+* Register a plugin in the global registry so it applies to every future
+* logger instance.
+*
+* @example
+* ```ts
+* import { usePlugin } from 'logixia';
+*
+* usePlugin({
+*   name: 'audit-sink',
+*   onLog(entry) {
+*     if (entry.level === 'error') auditQueue.push(entry);
+*     return entry;
+*   },
+* });
+* ```
+*/
+function usePlugin(plugin) {
+	globalPluginRegistry.register(plugin);
+}
+
 //#endregion
 //#region src/types/index.ts
 const LogLevel = {
@@ -210,10 +307,187 @@ function normalizeError(error) {
 	return new Error(String(error));
 }
 
+//#endregion
+//#region src/utils/otel.ts
+let _otelApi;
+function tryLoadOtelApi() {
+	if (_otelApi !== void 0) return _otelApi;
+	try {
+		_otelApi = __require("@opentelemetry/api");
+		return _otelApi;
+	} catch {
+		_otelApi = null;
+		return null;
+	}
+}
+/**
+* Read the currently active OTel span context (if any) and return its fields
+* in a plain object suitable for spreading into a log entry.
+*
+* Returns `undefined` when:
+* - `@opentelemetry/api` is not installed
+* - No active span exists (root context)
+* - The span context is invalid (all-zeros)
+*/
+function getActiveOtelContext(opts = {}) {
+	const api = tryLoadOtelApi();
+	if (!api) return void 0;
+	const ctx = api.context.active();
+	const sc = api.trace.getSpanContext(ctx);
+	if (!sc || !api.trace.isSpanContextValid(sc)) return void 0;
+	const isSampled = (sc.traceFlags & api.trace.TraceFlags.SAMPLED) === api.trace.TraceFlags.SAMPLED;
+	if (opts.sampledOnly && !isSampled) return void 0;
+	return {
+		traceId: sc.traceId,
+		spanId: sc.spanId,
+		traceFlags: sc.traceFlags,
+		isSampled
+	};
+}
+/**
+* Returns a metadata object with OTel context fields ready to merge into a log call,
+* using the configured field names.
+*
+* Returns `{}` when no active span exists (safe to spread unconditionally).
+*
+* @example
+* ```ts
+* await logger.info('Payment processed', {
+*   ...getOtelMetaFields(),
+*   orderId: 'ord_123',
+* });
+* ```
+*/
+function getOtelMetaFields(opts = {}) {
+	const { traceIdField = "traceId", spanIdField = "spanId", traceFlagsField = "traceFlags" } = opts;
+	const ctx = getActiveOtelContext(opts);
+	if (!ctx) return {};
+	return {
+		[traceIdField]: ctx.traceId,
+		[spanIdField]: ctx.spanId,
+		[traceFlagsField]: ctx.traceFlags
+	};
+}
+let _bridgeOptions = null;
+/**
+* Initialise the global OTel bridge.
+*
+* Once called, logixia's internal log pipeline checks for an active OTel span
+* on **every** log call and automatically merges the span context into the
+* entry's metadata — no per-call wiring needed.
+*
+* Call once at app startup, **after** the OTel SDK has been initialised:
+* ```ts
+* import { initOtelBridge } from 'logixia';
+* initOtelBridge();
+* ```
+*/
+function initOtelBridge(opts = {}) {
+	_bridgeOptions = opts;
+}
+/**
+* @internal
+* Used by the core logger to inject OTel context when the bridge is active.
+* Returns `{}` when the bridge is not initialised or no active span exists.
+*/
+function _getOtelPayloadIfEnabled() {
+	if (!_bridgeOptions) return {};
+	return getOtelMetaFields(_bridgeOptions);
+}
+/**
+* Disable the OTel bridge (useful for tests).
+*/
+function disableOtelBridge() {
+	_bridgeOptions = null;
+}
+
 //#endregion
 //#region src/utils/redact.utils.ts
 const DEFAULT_CENSOR = "[REDACTED]";
 /**
+* Conservative patterns: tokens and secrets that should NEVER appear in logs.
+* Applied when `autoDetect: true` or `autoDetect: 'conservative'`.
+*/
+const PII_CONSERVATIVE_PATTERNS = [
+	/eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]*/g,
+	/Bearer\s+[A-Za-z0-9._~+/-]+=*/gi,
+	/\b(?:sk|pk|api|key|secret|token)-[A-Za-z0-9_-]{16,}/gi,
+	/\bAKIA[0-9A-Z]{16}\b/g,
+	/\b[A-Za-z0-9/+]{40}\b(?=.*aws)/gi
+];
+/**
+* Conservative field-name paths auto-redacted by name regardless of value.
+*/
+const PII_CONSERVATIVE_PATHS = [
+	"**.password",
+	"**.passwd",
+	"**.secret",
+	"**.token",
+	"**.apiKey",
+	"**.api_key",
+	"**.accessToken",
+	"**.access_token",
+	"**.refreshToken",
+	"**.refresh_token",
+	"**.authorization",
+	"**.credentials",
+	"**.privateKey",
+	"**.private_key",
+	"**.clientSecret",
+	"**.client_secret"
+];
+/**
+* Aggressive patterns: also catch personal data that could identify a person.
+* Applied when `autoDetect: 'aggressive'`.
+*/
+const PII_AGGRESSIVE_PATTERNS = [
+	/\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g,
+	/\b\d{3}-?\d{2}-?\d{4}\b/g,
+	/\b(?:\d[ -]?){13,19}\b/g,
+	/\b(?:\+?1[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\b/g,
+	/\b(?:\d{1,3}\.){3}\d{1,3}\b/g
+];
+const PII_AGGRESSIVE_PATHS = [
+	...PII_CONSERVATIVE_PATHS,
+	"**.email",
+	"**.emailAddress",
+	"**.email_address",
+	"**.phone",
+	"**.phoneNumber",
+	"**.phone_number",
+	"**.mobile",
+	"**.ssn",
+	"**.sin",
+	"**.dob",
+	"**.dateOfBirth",
+	"**.date_of_birth",
+	"**.creditCard",
+	"**.credit_card",
+	"**.cardNumber",
+	"**.card_number",
+	"**.cvv",
+	"**.cvc",
+	"**.ipAddress",
+	"**.ip_address"
+];
+/**
+* Build an effective config that merges `autoDetect` PII rules into the
+* explicit `paths` and `patterns` the caller provided.
+*/
+function resolveConfig(config) {
+	const { autoDetect } = config;
+	if (!autoDetect) return config;
+	const aggressive = autoDetect === "aggressive";
+	const extraPaths = aggressive ? PII_AGGRESSIVE_PATHS : PII_CONSERVATIVE_PATHS;
+	const extraPatterns = aggressive ? [...PII_CONSERVATIVE_PATTERNS, ...PII_AGGRESSIVE_PATTERNS] : PII_CONSERVATIVE_PATTERNS;
+	const { paths = [], patterns = [] } = config;
+	return {
+		...config,
+		paths: [...paths, ...extraPaths],
+		patterns: [...patterns, ...extraPatterns]
+	};
+}
+/**
 * Convert a dot-notation path pattern to a RegExp.
 * Supports `*` (one segment) and `**` (zero or more segments).
 *
@@ -285,8 +559,9 @@ function redactObject(obj, config, _currentPath = "") {
 */
 function applyRedaction(payload, config) {
 	if (!payload || !config) return payload;
-	if ((!config.paths || config.paths.length === 0) && (!config.patterns || config.patterns.length === 0)) return payload;
-	return redactObject(payload, config);
+	const resolved$1 = resolveConfig(config);
+	if ((!resolved$1.paths || resolved$1.paths.length === 0) && (!resolved$1.patterns || resolved$1.patterns.length === 0)) return payload;
+	return redactObject(payload, resolved$1);
 }
 function isPlainObject(value) {
 	return value !== null && typeof value === "object" && !Array.isArray(value) && !(value instanceof Date) && !(value instanceof Error) && !(value instanceof RegExp);
@@ -662,11 +937,17 @@ function namespacePatternToRegex(pattern) {
 	const escaped = pattern.split(".").map((s) => s === "*" ? "[^.]+" : s.replace(/[$()*+.?[\\\]^{|}]/g, "\\$&")).join("\\.");
 	return /* @__PURE__ */ new RegExp(`^${escaped}$`);
 }
+/** Max compiled patterns to keep in memory. Oldest entry is evicted when full. */
+const _NS_CACHE_MAX = 1e3;
 const _nsPatternCache = /* @__PURE__ */ new Map();
 function matchesNamespacePattern(ns, pattern) {
 	let re = _nsPatternCache.get(pattern);
 	if (!re) {
 		re = namespacePatternToRegex(pattern);
+		if (_nsPatternCache.size >= _NS_CACHE_MAX) {
+			const firstKey = _nsPatternCache.keys().next().value;
+			if (firstKey !== void 0) _nsPatternCache.delete(firstKey);
+		}
 		_nsPatternCache.set(pattern, re);
 	}
 	return re.test(ns);
@@ -697,6 +978,7 @@ var LogixiaLogger = class LogixiaLogger {
 		this._formattedLevels = /* @__PURE__ */ new Map();
 		this._formattedAppName = "";
 		this._hasRedact = false;
+		this._pluginRegistry = new PluginRegistry();
 		this.config = {
 			appName: "App",
 			environment: "development",
@@ -753,6 +1035,7 @@ var LogixiaLogger = class LogixiaLogger {
 		});
 		this.setupGracefulShutdown();
 		this.createCustomLevelMethods();
+		for (const p of globalPluginRegistry._plugins) this._pluginRegistry.register(p);
 		this._buildPerfCaches();
 	}
 	setupGracefulShutdown() {
@@ -979,6 +1262,29 @@ var LogixiaLogger = class LogixiaLogger {
 		};
 		return childLogger;
 	}
+	/**
+	* Register a plugin on this logger instance.
+	*
+	* @example
+	* ```ts
+	* logger.use({
+	*   name: 'audit',
+	*   onLog(entry) { auditQueue.push(entry); return entry; },
+	* });
+	* ```
+	*/
+	use(plugin) {
+		this._pluginRegistry.register(plugin);
+		return this;
+	}
+	/**
+	* Remove a previously registered plugin by name.
+	* No-op if the plugin is not registered on this instance.
+	*/
+	unuse(pluginName) {
+		this._pluginRegistry.unregister(pluginName);
+		return this;
+	}
 	async flush() {
 		if (this.transportManager) await this.transportManager.flush();
 	}
@@ -1001,6 +1307,7 @@ var LogixiaLogger = class LogixiaLogger {
 			await this.transportManager.close();
 		}
 		(_this$_sampler = this._sampler) === null || _this$_sampler === void 0 || _this$_sampler.destroy();
+		await this._pluginRegistry.runOnShutdown();
 		deregisterFromShutdown(this);
 	}
 	async log(level, message, data) {
@@ -1011,10 +1318,19 @@ var LogixiaLogger = class LogixiaLogger {
 			if (!this._sampler.shouldEmit(level, traceId$1)) return;
 		}
 		const alsContext = LogixiaContext.get();
-		const mergedData = alsContext && Object.keys(alsContext).length > 0 ? {
+		const otelFields = _getOtelPayloadIfEnabled();
+		const hasOtel = Object.keys(otelFields).length > 0;
+		let mergedData;
+		if (alsContext && Object.keys(alsContext).length > 0) mergedData = {
 			...alsContext,
+			...hasOtel ? otelFields : {},
+			...data
+		};
+		else if (hasOtel) mergedData = {
+			...otelFields,
 			...data
-		} : data;
+		};
+		else mergedData = data;
 		const rawPayload = this._hasContextData ? {
 			...this.contextData,
 			...mergedData
@@ -1032,8 +1348,13 @@ var LogixiaLogger = class LogixiaLogger {
 		if (this.context) entry.context = this.context;
 		if (payload !== void 0) entry.payload = payload;
 		if (traceId !== void 0) entry.traceId = traceId;
-		const formattedLog = this.formatLog(entry);
-		await this.output(formattedLog, level, entry);
+		let finalEntry = entry;
+		if (this._pluginRegistry.size > 0) {
+			finalEntry = await this._pluginRegistry.runOnLog(entry);
+			if (finalEntry === null) return;
+		}
+		const formattedLog = this.formatLog(finalEntry);
+		await this.output(formattedLog, level, finalEntry);
 	}
 	/**
 	* Hot-path level check: a single Map lookup + integer compare.
@@ -10521,5 +10842,5 @@ let LogixiaLoggerModule = class LogixiaLoggerModule$1 {
 LogixiaLoggerModule = _LogixiaLoggerModule = __decorate([Module({})], LogixiaLoggerModule);
 
 //#endregion
-export { LogixiaContext as A, redactObject as C, DEFAULT_LOG_COLORS as D, serializeError as E, createFastifyContextHook as M, DEFAULT_LOG_LEVELS as O, applyRedaction as S, normalizeError as T, traceStorage as _, TraceMiddleware as a, registerForShutdown as b, LogixiaLogger as c, createTraceMiddleware as d, extractTraceId as f, setTraceId as g, runWithTraceId as h, WebSocketTraceInterceptor as i, createExpressContextMiddleware as j, LogLevel as k, createLogger as l, getCurrentTraceId as m, LOGIXIA_LOGGER_PREFIX as n, KafkaTraceInterceptor as o, generateTraceId as p, LogixiaLoggerModule as r, LogixiaLoggerService as s, LOGIXIA_LOGGER_CONFIG as t, DEFAULT_TRACE_HEADERS$1 as u, deregisterFromShutdown as v, isError as w, resetShutdownHandlers as x, flushOnExit as y };
-//# sourceMappingURL=logitron-logger.module-2AzkadqZ.mjs.map
+export { isError as A, createExpressContextMiddleware as B, resetShutdownHandlers as C, getActiveOtelContext as D, disableOtelBridge as E, LogLevel as F, PluginRegistry as I, globalPluginRegistry as L, serializeError as M, DEFAULT_LOG_COLORS as N, getOtelMetaFields as O, DEFAULT_LOG_LEVELS as P, usePlugin as R, registerForShutdown as S, redactObject as T, createFastifyContextHook as V, runWithTraceId as _, TraceMiddleware as a, deregisterFromShutdown as b, __decorate as c, createLogger as d, DEFAULT_TRACE_HEADERS$1 as f, getCurrentTraceId as g, generateTraceId as h, WebSocketTraceInterceptor as i, normalizeError as j, initOtelBridge as k, __decorateMetadata as l, extractTraceId as m, LOGIXIA_LOGGER_PREFIX as n, KafkaTraceInterceptor as o, createTraceMiddleware as p, LogixiaLoggerModule as r, LogixiaLoggerService as s, LOGIXIA_LOGGER_CONFIG as t, LogixiaLogger as u, setTraceId as v, applyRedaction as w, flushOnExit as x, traceStorage as y, LogixiaContext as z };
+//# sourceMappingURL=logitron-logger.module-C939PIEV.mjs.map