logixia 1.10.3 → 1.11.0

package/dist/index.js

@@ -1,6 +1,8 @@
 const require_transport_manager = require('./transport.manager-B9LF9uDd.js');
-const require_logitron_logger_module = require('./logitron-logger.module-Dlf5GwJ9.js');
+const require_logitron_logger_module = require('./logitron-logger.module-DHFampon.js');
 require('./search-DoZF3RZj.js');
+let node_async_hooks = require("node:async_hooks");
+node_async_hooks = require_transport_manager.__toESM(node_async_hooks);
 let __nestjs_common = require("@nestjs/common");
 __nestjs_common = require_transport_manager.__toESM(__nestjs_common);
 
@@ -253,7 +255,7 @@ function LogMethod(options = {}) {
 		const reportLogFailure = (phase, err) => {
 			process.stderr.write(`[logixia] @LogMethod(${label}) ${phase} log failed: ${String(err)}\n`);
 		};
-		const emit = (logger$1, phase, message, data) => {
+		const emit$1 = (logger$1, phase, message, data) => {
 			const logFnRaw = logger$1[level];
 			const p = (typeof logFnRaw === "function" ? logFnRaw : logger$1.debug).bind(logger$1)(message, data);
 			if (p && typeof p.catch === "function") p.catch((e) => reportLogFailure(phase, e));
@@ -275,7 +277,7 @@ function LogMethod(options = {}) {
 			const start = Date.now();
 			const entry = { method: label };
 			if (logArgs && args.length > 0) entry["args"] = args;
-			if (logger$1) emit(logger$1, "entry", `→ ${label}`, entry);
+			if (logger$1) emit$1(logger$1, "entry", `→ ${label}`, entry);
 			const buildExit = (result$1) => {
 				const exit = {
 					method: label,
@@ -292,13 +294,13 @@ function LogMethod(options = {}) {
 				throw error;
 			}
 			if (result && typeof result.then === "function") return result.then((resolved) => {
-				if (logger$1) emit(logger$1, "exit", `← ${label}`, buildExit(resolved));
+				if (logger$1) emit$1(logger$1, "exit", `← ${label}`, buildExit(resolved));
 				return resolved;
 			}, (error) => {
 				if (logger$1 && logErrors) emitError(logger$1, error, start);
 				throw error;
 			});
-			if (logger$1) emit(logger$1, "exit", `← ${label}`, buildExit(result));
+			if (logger$1) emit$1(logger$1, "exit", `← ${label}`, buildExit(result));
 			return result;
 		};
 		return descriptor;
@@ -546,6 +548,234 @@ var TextFormatter = class TextFormatter {
 	}
 };
 
+//#endregion
+//#region src/utils/runtime-control.ts
+const DEFAULT_CYCLE = [
+	"error",
+	"warn",
+	"info",
+	"debug",
+	"trace",
+	"verbose"
+];
+/**
+* Register an OS-signal handler that cycles the logger's global level on each
+* signal. Returns a dispose function that removes the listener.
+*
+* Cycling (rather than jumping straight to a fixed level) means a single,
+* memorizable command (`kill -USR2 <pid>`) is enough to ratchet verbosity up
+* while chasing a bug and back down again — no value to remember.
+*/
+function registerLevelSignal(logger$1, options = {}) {
+	const signal = options.signal ?? "SIGUSR2";
+	const cycle = options.cycle && options.cycle.length > 0 ? options.cycle : [...DEFAULT_CYCLE];
+	const handler = () => {
+		const current = logger$1.getLevel();
+		const next = cycle[(cycle.indexOf(current) + 1) % cycle.length];
+		logger$1.setLevel(next);
+		require_transport_manager.internalLog(`runtime level changed via ${signal}: ${current} → ${next}`);
+	};
+	process.on(signal, handler);
+	return () => {
+		process.removeListener(signal, handler);
+	};
+}
+const VALID_LEVELS = new Set([
+	"error",
+	"warn",
+	"info",
+	"debug",
+	"trace",
+	"verbose",
+	"fatal"
+]);
+/**
+* Create an HTTP handler (Node `http`/Express-compatible) that reads and sets
+* the logger's level at runtime.
+*
+*  - `GET`  → `{ level, namespaceLevels }`
+*  - `POST` → body `{ level?, namespaceLevels? }` applies them, returns the new state
+*
+* Custom levels are accepted too: any level the logger already knows passes
+* through. Unknown levels are rejected with 400 so a typo can't silently mute
+* logging. Mount behind your own auth — this intentionally has none.
+*/
+function createLevelControlHandler(logger$1, options = {}) {
+	const allowed = options.allowedLevels && options.allowedLevels.length > 0 ? new Set(options.allowedLevels.map((l) => l.toLowerCase())) : VALID_LEVELS;
+	const snapshot = () => {
+		var _logger$getNamespaceL;
+		return {
+			level: logger$1.getLevel(),
+			namespaceLevels: ((_logger$getNamespaceL = logger$1.getNamespaceLevels) === null || _logger$getNamespaceL === void 0 ? void 0 : _logger$getNamespaceL.call(logger$1)) ?? {}
+		};
+	};
+	const send = (res, status, body) => {
+		var _res$setHeader;
+		res.statusCode = status;
+		(_res$setHeader = res.setHeader) === null || _res$setHeader === void 0 || _res$setHeader.call(res, "Content-Type", "application/json");
+		res.end(JSON.stringify(body));
+	};
+	const applyBody = (res, raw) => {
+		let parsed;
+		try {
+			parsed = raw ? JSON.parse(raw) : {};
+		} catch {
+			send(res, 400, { error: "invalid JSON body" });
+			return;
+		}
+		if (parsed.level !== void 0) {
+			const lvl = String(parsed.level).toLowerCase();
+			if (!allowed.has(lvl)) {
+				send(res, 400, {
+					error: `unknown level "${parsed.level}"`,
+					allowed: [...allowed]
+				});
+				return;
+			}
+			logger$1.setLevel(lvl);
+		}
+		if (parsed.namespaceLevels !== void 0) {
+			if (typeof parsed.namespaceLevels !== "object" || parsed.namespaceLevels === null || Array.isArray(parsed.namespaceLevels)) {
+				send(res, 400, { error: "namespaceLevels must be an object" });
+				return;
+			}
+			const nl = parsed.namespaceLevels;
+			for (const [pat, lvl] of Object.entries(nl)) if (!allowed.has(String(lvl).toLowerCase())) {
+				send(res, 400, { error: `unknown level "${String(lvl)}" for namespace "${pat}"` });
+				return;
+			}
+			if (logger$1.setNamespaceLevels) {
+				const coerced = {};
+				for (const [pat, lvl] of Object.entries(nl)) coerced[pat] = String(lvl).toLowerCase();
+				logger$1.setNamespaceLevels(coerced);
+			} else require_transport_manager.internalWarn("level control: logger does not support setNamespaceLevels — ignored");
+		}
+		send(res, 200, snapshot());
+	};
+	return function levelControlHandler(req, res) {
+		const method = (req.method ?? "GET").toUpperCase();
+		if (method === "GET") {
+			send(res, 200, snapshot());
+			return;
+		}
+		if (method === "POST" || method === "PUT" || method === "PATCH") {
+			const maybeBody = req.body;
+			if (maybeBody !== void 0 && typeof req.on !== "function") {
+				applyBody(res, typeof maybeBody === "string" ? maybeBody : JSON.stringify(maybeBody));
+				return;
+			}
+			if (typeof req.on === "function") {
+				let raw = "";
+				req.on("data", (chunk) => {
+					raw += String(chunk ?? "");
+				});
+				req.on("end", () => applyBody(res, raw));
+				return;
+			}
+			applyBody(res, "");
+			return;
+		}
+		send(res, 405, { error: `method ${method} not allowed` });
+	};
+}
+
+//#endregion
+//#region src/utils/safe-stringify.ts
+/** Build a JSONPath like `$["a"][0]["b"]` for a decycle pointer. */
+function jsonPath(parts) {
+	let path = "$";
+	for (const p of parts) path += typeof p === "number" ? `[${p}]` : `[${JSON.stringify(p)}]`;
+	return path;
+}
+/**
+* Serialize any value to JSON without throwing on circular references or BigInt.
+* Circular refs become `"[Circular]"` (or `{ $ref }` pointers when `decycle`).
+*/
+function safeStringify(value, options = {}) {
+	const { indent, deterministic = false, decycle = false, bigint = "string" } = options;
+	if (decycle) return JSON.stringify(decycleValue(value, bigint), void 0, indent);
+	const seen = /* @__PURE__ */ new WeakSet();
+	const transform = (val) => {
+		if (typeof val === "bigint") return bigint === "number" ? Number(val) : val.toString();
+		if (typeof val === "function") return `[Function: ${val.name || "anonymous"}]`;
+		if (typeof val === "symbol") return val.toString();
+		if (val === null || typeof val !== "object") return val;
+		if (seen.has(val)) return "[Circular]";
+		seen.add(val);
+		let out;
+		if (Array.isArray(val)) out = val.map((item) => transform(item));
+		else if (val instanceof Date) out = val.toISOString();
+		else {
+			const rec = val;
+			const keys = deterministic ? Object.keys(rec).sort() : Object.keys(rec);
+			const obj = {};
+			for (const k of keys) {
+				if (k === "__proto__" || k === "constructor" || k === "prototype") continue;
+				obj[k] = transform(rec[k]);
+			}
+			out = obj;
+		}
+		seen.delete(val);
+		return out;
+	};
+	return JSON.stringify(transform(value), void 0, indent);
+}
+/**
+* Replace repeated object references with round-trippable `{ "$ref": "$..." }`
+* JSONPath pointers (the classic Crockford decycle). Pair with {@link retrocycle}
+* to reconstruct the original shared/circular graph.
+*/
+function decycleValue(value, bigint = "string") {
+	const paths = /* @__PURE__ */ new WeakMap();
+	const walk = (val, path) => {
+		if (typeof val === "bigint") return bigint === "number" ? Number(val) : val.toString();
+		if (val === null || typeof val !== "object") return val;
+		if (val instanceof Date) return val.toISOString();
+		const existing = paths.get(val);
+		if (existing !== void 0) return { $ref: existing };
+		paths.set(val, jsonPath(path));
+		if (Array.isArray(val)) return val.map((item, i) => walk(item, [...path, i]));
+		const rec = val;
+		const obj = {};
+		for (const k of Object.keys(rec)) {
+			if (k === "__proto__" || k === "constructor" || k === "prototype") continue;
+			obj[k] = walk(rec[k], [...path, k]);
+		}
+		return obj;
+	};
+	return walk(value, []);
+}
+/**
+* Inverse of {@link decycleValue}: resolve `{ "$ref": "$..." }` pointers back
+* into the live object graph (mutates and returns the parsed input).
+*/
+function retrocycle(root) {
+	const refRe = /^\$(?:\[(?:\d+|"(?:[^"\\]|\\.)*")\])*$/;
+	const resolve = (path) => {
+		const segs = [];
+		const partRe = /\[(\d+|"(?:[^"\\]|\\.)*")\]/g;
+		let m;
+		while ((m = partRe.exec(path)) !== null) {
+			const raw = m[1];
+			segs.push(raw.startsWith("\"") ? JSON.parse(raw) : Number(raw));
+		}
+		let node = root;
+		for (const s of segs) node = node[s];
+		return node;
+	};
+	const walk = (val) => {
+		if (val === null || typeof val !== "object") return;
+		const rec = val;
+		for (const k of Object.keys(rec)) {
+			const child = rec[k];
+			if (child !== null && typeof child === "object" && typeof child.$ref === "string" && refRe.test(child.$ref)) rec[k] = resolve(child.$ref);
+			else walk(child);
+		}
+	};
+	walk(root);
+	return root;
+}
+
 //#endregion
 //#region src/utils/typed-logger.ts
 /**
@@ -606,6 +836,258 @@ function createTypedLogger(logger$1, schema) {
 	};
 }
 
+//#endregion
+//#region src/wide-events.ts
+const _storage = new node_async_hooks.AsyncLocalStorage();
+/**
+* Merge fields into the wide event for the current async scope. No-op (with no
+* throw) when called outside a `withWideEvent` / middleware scope, so business
+* code can call it unconditionally.
+*/
+function addEventFields(fields) {
+	const state = _storage.getStore();
+	if (!state || state.emitted) return;
+	Object.assign(state.fields, fields);
+}
+/** Set a single field on the current wide event. */
+function setEventField(key, value) {
+	addEventFields({ [key]: value });
+}
+/** Read a shallow copy of the wide event accumulated so far, or undefined. */
+function getEventFields() {
+	const state = _storage.getStore();
+	return state ? { ...state.fields } : void 0;
+}
+function emit(logger$1, state, options, extra) {
+	if (state.emitted) return;
+	state.emitted = true;
+	const level = options.level ?? "info";
+	const message = options.message ?? "request";
+	const durationField = options.durationField ?? "durationMs";
+	const includeTrace = options.includeTrace ?? true;
+	const payload = { ...state.fields };
+	if (extra) Object.assign(payload, extra);
+	payload[durationField] = Date.now() - state.startMs;
+	if (includeTrace) {
+		const traceId = require_logitron_logger_module.getCurrentTraceId();
+		if (traceId !== void 0 && payload["traceId"] === void 0) payload["traceId"] = traceId;
+	}
+	const p = logger$1.logLevel(level, message, payload);
+	if (p && typeof p.catch === "function") p.catch(() => {});
+}
+/**
+* Run `callback` inside a wide-event scope. `addEventFields` calls anywhere in
+* the (async) call tree accumulate onto one event, which is emitted exactly once
+* when the callback settles — on success OR error (the canonical "emit in
+* finally" guarantee). On error, `error` + `errorMessage` fields are added.
+*/
+async function withWideEvent(logger$1, initialFields, callback, options = {}) {
+	const state = {
+		fields: { ...initialFields },
+		startMs: Date.now(),
+		emitted: false
+	};
+	return _storage.run(state, async () => {
+		try {
+			const result = await callback();
+			emit(logger$1, state, options);
+			return result;
+		} catch (error) {
+			emit(logger$1, state, options, {
+				error: true,
+				errorMessage: error instanceof Error ? error.message : String(error)
+			});
+			throw error;
+		}
+	});
+}
+/**
+* Express/Connect middleware that opens a wide-event scope per request and
+* emits ONE canonical event on response `finish`/`close` — even if the handler
+* throws or the client disconnects. Pre-populates method/url/ip; handlers add
+* more via `addEventFields`. The completion event includes `statusCode` and the
+* request duration.
+*/
+function wideEventMiddleware(logger$1, options = {}) {
+	return function logixiaWideEventMiddleware(req, res, next) {
+		var _options$skip, _req$socket, _res$once, _res$once2;
+		if ((_options$skip = options.skip) === null || _options$skip === void 0 ? void 0 : _options$skip.call(options, req)) {
+			next();
+			return;
+		}
+		const state = {
+			fields: {
+				method: req.method,
+				url: req.originalUrl ?? req.url,
+				ip: req.ip ?? ((_req$socket = req.socket) === null || _req$socket === void 0 ? void 0 : _req$socket.remoteAddress),
+				...options.enrich ? options.enrich(req) : {}
+			},
+			startMs: Date.now(),
+			emitted: false
+		};
+		const finalize = () => {
+			emit(logger$1, state, options, { statusCode: res.statusCode ?? 0 });
+		};
+		(_res$once = res.once) === null || _res$once === void 0 || _res$once.call(res, "finish", finalize);
+		(_res$once2 = res.once) === null || _res$once2 === void 0 || _res$once2.call(res, "close", finalize);
+		_storage.run(state, () => next());
+	};
+}
+
+//#endregion
+//#region src/transports/otlp.transport.ts
+/**
+* Map a logixia level name to an OTel SeverityNumber (1–24) and text.
+* Per the OTel logs SDK spec: TRACE=1, DEBUG=5, INFO=9, WARN=13, ERROR=17,
+* FATAL=21. Custom/unknown levels fall back to INFO (9).
+*/
+function toOtelSeverity(level) {
+	switch (level.toLowerCase()) {
+		case "trace": return {
+			number: 1,
+			text: "TRACE"
+		};
+		case "verbose": return {
+			number: 5,
+			text: "DEBUG"
+		};
+		case "debug": return {
+			number: 5,
+			text: "DEBUG"
+		};
+		case "info": return {
+			number: 9,
+			text: "INFO"
+		};
+		case "warn":
+		case "warning": return {
+			number: 13,
+			text: "WARN"
+		};
+		case "error": return {
+			number: 17,
+			text: "ERROR"
+		};
+		case "fatal": return {
+			number: 21,
+			text: "FATAL"
+		};
+		default: return {
+			number: 9,
+			text: "INFO"
+		};
+	}
+}
+/** Coerce a JS value into an OTLP AnyValue. */
+function toAnyValue(value) {
+	if (typeof value === "string") return { stringValue: value };
+	if (typeof value === "boolean") return { boolValue: value };
+	if (typeof value === "number") return Number.isInteger(value) ? { intValue: value } : { doubleValue: value };
+	if (typeof value === "bigint") return { stringValue: value.toString() };
+	if (value === null || value === void 0) return { stringValue: "" };
+	try {
+		return { stringValue: JSON.stringify(value) };
+	} catch {
+		return { stringValue: String(value) };
+	}
+}
+/** Build the OTLP KeyValue attribute list from a flat record. */
+function toAttributes(rec) {
+	return Object.entries(rec).map(([key, value]) => ({
+		key,
+		value: toAnyValue(value)
+	}));
+}
+var OtlpLogTransport = class {
+	constructor(config) {
+		this.name = "otlp";
+		this.batch = [];
+		this.flushTimer = null;
+		this.url = config.url;
+		this.headers = config.headers ?? {};
+		this.batchSize = config.batchSize ?? 100;
+		this.flushIntervalMs = config.flushIntervalMs ?? 5e3;
+		this.level = config.level;
+		this.resourceAttrs = toAttributes({
+			"service.name": config.serviceName ?? "logixia",
+			...config.serviceVersion ? { "service.version": config.serviceVersion } : {},
+			...config.environment ? { "deployment.environment": config.environment } : {},
+			...config.resourceAttributes ?? {}
+		});
+		this.flushTimer = setInterval(() => {
+			this.flush().catch(() => {});
+		}, this.flushIntervalMs);
+		if (this.flushTimer.unref) this.flushTimer.unref();
+	}
+	write(entry) {
+		this.batch.push(entry);
+		if (this.batch.length >= this.batchSize) this.flush().catch(() => {});
+	}
+	/** Convert one entry into an OTLP LogRecord. */
+	toLogRecord(entry) {
+		const sev = toOtelSeverity(entry.level);
+		const tsNanos = String(entry.timestamp.getTime() * 1e6);
+		const attrs = { ...entry.data ?? {} };
+		if (entry.context !== void 0) attrs["context"] = entry.context;
+		if (entry.appName !== void 0) attrs["app.name"] = entry.appName;
+		if (entry.environment !== void 0) attrs["deployment.environment"] = entry.environment;
+		const record = {
+			timeUnixNano: tsNanos,
+			observedTimeUnixNano: tsNanos,
+			severityNumber: sev.number,
+			severityText: sev.text,
+			body: { stringValue: entry.message },
+			attributes: toAttributes(attrs)
+		};
+		if (entry.traceId) record["traceId"] = entry.traceId;
+		return record;
+	}
+	buildPayload(entries) {
+		return JSON.stringify({ resourceLogs: [{
+			resource: { attributes: this.resourceAttrs },
+			scopeLogs: [{
+				scope: { name: "logixia" },
+				logRecords: entries.map((e) => this.toLogRecord(e))
+			}]
+		}] });
+	}
+	async flush() {
+		while (this.batch.length > 0) {
+			const entries = this.batch.splice(0, this.batchSize);
+			try {
+				await this.send(entries);
+			} catch (err) {
+				require_transport_manager.internalError("OtlpLogTransport flush error", err);
+				this.batch.unshift(...entries);
+				return;
+			}
+		}
+	}
+	async send(entries) {
+		if (typeof fetch !== "function") {
+			require_transport_manager.internalWarn("OtlpLogTransport: global fetch unavailable — cannot export logs");
+			return;
+		}
+		const res = await fetch(this.url, {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				...this.headers
+			},
+			body: this.buildPayload(entries)
+		});
+		if (!res.ok) throw new Error(`OTLP export failed: HTTP ${res.status}`);
+	}
+	async close() {
+		if (this.flushTimer) {
+			clearInterval(this.flushTimer);
+			this.flushTimer = null;
+		}
+		for (let attempt = 0; attempt < 3 && this.batch.length > 0; attempt += 1) await this.flush();
+		if (this.batch.length > 0) require_transport_manager.internalError(`OtlpLogTransport closing with ${this.batch.length} undelivered record(s)`);
+	}
+};
+
 //#endregion
 //#region src/metrics.ts
 const DEFAULT_BUCKETS = [
@@ -971,6 +1453,7 @@ Object.defineProperty(exports, 'LogixiaLoggerService', {
   }
 });
 exports.MetricsPlugin = MetricsPlugin;
+exports.OtlpLogTransport = OtlpLogTransport;
 exports.PluginRegistry = require_logitron_logger_module.PluginRegistry;
 exports.TRACE_CONTEXT_KEY = require_logitron_logger_module.TRACE_CONTEXT_KEY;
 exports.TextFormatter = TextFormatter;
@@ -982,14 +1465,17 @@ Object.defineProperty(exports, 'WebSocketTraceInterceptor', {
   }
 });
 exports._setActiveContextKey = require_logitron_logger_module._setActiveContextKey;
+exports.addEventFields = addEventFields;
 exports.applyRedaction = require_logitron_logger_module.applyRedaction;
 exports.createExpressContextMiddleware = require_logitron_logger_module.createExpressContextMiddleware;
 exports.createFastifyContextHook = require_logitron_logger_module.createFastifyContextHook;
+exports.createLevelControlHandler = createLevelControlHandler;
 exports.createLogger = createLogger;
 exports.createLoggerService = createLoggerService;
 exports.createMetricsPlugin = createMetricsPlugin;
 exports.createTraceMiddleware = require_logitron_logger_module.createTraceMiddleware;
 exports.createTypedLogger = createTypedLogger;
+exports.decycleValue = decycleValue;
 exports.defineLogSchema = defineLogSchema;
 exports.deregisterFromShutdown = require_logitron_logger_module.deregisterFromShutdown;
 exports.disableOtelBridge = require_logitron_logger_module.disableOtelBridge;
@@ -999,6 +1485,7 @@ exports.generateRequestId = generateRequestId;
 exports.generateTraceId = generateTraceId;
 exports.getActiveOtelContext = require_logitron_logger_module.getActiveOtelContext;
 exports.getCurrentTraceId = require_logitron_logger_module.getCurrentTraceId;
+exports.getEventFields = getEventFields;
 exports.getOtelMetaFields = require_logitron_logger_module.getOtelMetaFields;
 exports.getTraceContextKey = require_logitron_logger_module.getTraceContextKey;
 exports.globalPluginRegistry = require_logitron_logger_module.globalPluginRegistry;
@@ -1009,10 +1496,17 @@ exports.logger = logger;
 exports.normalizeError = require_logitron_logger_module.normalizeError;
 exports.redactObject = require_logitron_logger_module.redactObject;
 exports.registerForShutdown = require_logitron_logger_module.registerForShutdown;
+exports.registerLevelSignal = registerLevelSignal;
 exports.resetShutdownHandlers = require_logitron_logger_module.resetShutdownHandlers;
+exports.retrocycle = retrocycle;
 exports.runWithTraceId = require_logitron_logger_module.runWithTraceId;
+exports.safeStringify = safeStringify;
 exports.serializeError = require_logitron_logger_module.serializeError;
+exports.setEventField = setEventField;
 exports.setTraceId = require_logitron_logger_module.setTraceId;
+exports.toOtelSeverity = toOtelSeverity;
 exports.traceStorage = require_logitron_logger_module.traceStorage;
 exports.usePlugin = require_logitron_logger_module.usePlugin;
+exports.wideEventMiddleware = wideEventMiddleware;
+exports.withWideEvent = withWideEvent;
 //# sourceMappingURL=index.js.map