@warlock.js/logger 5.29.0 → 5.30.0

package/CHANGELOG.md

@@ -4,6 +4,31 @@ All notable changes to `@warlock.js/logger` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
+## 5.30.0 - 2026-10-16
+
+### Upgrading
+
+- **BREAKING (types):** `log.info/warn/error/debug/success/fatal/log/assert` and the function `timer()` returns now return the logger synchronously instead of `Promise<this>`. Remove `await` before log calls (it is harmless but pointless) and any `.then()` chained on one; code that needs the write to finish calls `await log.flush()`.
+
+### Changed
+
+- Logging is fire-and-forget: level methods no longer return a promise, so `@typescript-eslint/no-floating-promises` no longer flags every call site (WR-019).
+- `log.flush()` drains every channel concurrently: each waits for its own in-flight async deliveries (including entries logged while the flush runs), then runs its `flush()`, so a hung network channel no longer holds up the file channel.
+- `log.flush({ timeout })` is bounded: it resolves after `timeout` ms (default 5000, `DEFAULT_FLUSH_TIMEOUT_MS`; `Infinity` waits without a limit) and reports each channel still draining to the channel error handler. Before, one delivery that never settled made `flush()` (and a graceful shutdown awaiting it) wait forever.
+- `maskEmailsInText` cuts text longer than `MASK_EMAILS_MAX_LENGTH` (16,384 characters) and marks the cut, so masking a huge cache key or message has a bounded cost.
+
+### Added
+
+- `log.onChannelError(handler)` / `configure({ onChannelError })` and the `ChannelErrorHandler` type: receives a channel's sync throw or async rejection from `log()`, a redaction that threw, or a timed-out `flush()`. Default: one stderr line. The handler may be async; a rejection is swallowed.
+- `maskEmail(address)` and `maskEmailsInText(text)`: mask email addresses (`m***@example.com`) inside message strings and cache keys, which key-based redaction cannot reach. Core's mail logs and the cache drivers' key logs use them (FW-04).
+
+### Fixed
+
+- A channel whose `log()` rejected became an unhandled rejection (looping through `captureAnyUnhandledRejection`), and one that threw synchronously stopped delivery to the channels after it; both are now isolated and reported to the channel error handler.
+- A redaction that threw (a `censor` function that fails on an unexpected value) threw at the call site and skipped the remaining channels. A channel's own redaction failure is now isolated like any channel failure; a logger-wide one drops the entry (it is never delivered unredacted) and is reported to the channel error handler.
+- An async `onChannelError` handler that rejected became an unhandled rejection.
+- **Security:** `maskEmailsInText` backtracked quadratically on long runs of address-like characters with no domain (about 11 s on 75 KB), and it runs on cache keys built from request input. Its pattern is now bounded and linear. It also masks addresses with letters from any script (`jöhn@exämple.de`), and `maskEmail` no longer keeps half of a surrogate pair.
+
 ## 5.29.0 - 2026-10-01
 
 ### Changed

package/README.md

@@ -28,8 +28,8 @@ log.setChannels([
   new FileLog({ chunk: "daily" }),
 ]);
 
-await log.info("users", "register", "New user created");
-await log.error("payments", "charge", new Error("Card declined"));
+log.info("users", "register", "New user created");
+log.error("payments", "charge", new Error("Card declined"));
 ```
 
 The logger starts with no channels — nothing is printed or written until you register at least one.
@@ -39,15 +39,15 @@ The logger starts with no channels — nothing is printed or written until you r
 Every call carries three pieces of context. Modules and actions become searchable keys in file and JSON channels:
 
 ```ts
-await log.info("auth", "login", "User signed in");
-await log.warn("api", "rateLimitApproaching", "80% of quota used");
-await log.success("payments", "captured", "Payment of $49.99 captured");
+log.info("auth", "login", "User signed in");
+log.warn("api", "rateLimitApproaching", "80% of quota used");
+log.success("payments", "captured", "Payment of $49.99 captured");
 ```
 
 Pass an object instead of positional args when you need `context` metadata:
 
 ```ts
-await log.error({
+log.error({
   module: "orders",
   action: "checkout",
   message: "Card declined",

package/cjs/index.cjs

@@ -39,7 +39,7 @@ path = __toESM(path, 1);
 let safe_stable_stringify = require("safe-stable-stringify");
 let _mongez_reinforcements = require("@mongez/reinforcements");
 
-//#region ../logger/src/log-channel.ts
+//#region ../../packages/logger/src/log-channel.ts
 var LogChannel = class {
 	/**
 	* Constructor
@@ -112,7 +112,7 @@ var LogChannel = class {
 };
 
 //#endregion
-//#region ../logger/src/channels/console-log.ts
+//#region ../../packages/logger/src/channels/console-log.ts
 /**
 * The longest level name (`success`) sets the tag column width. Padding every
 * level name to this width keeps the timestamp / module / action columns
@@ -195,7 +195,7 @@ var ConsoleLog = class extends LogChannel {
 };
 
 //#endregion
-//#region ../logger/src/channels/file-log.ts
+//#region ../../packages/logger/src/channels/file-log.ts
 var FileLog = class extends LogChannel {
 	constructor(..._args) {
 		super(..._args);
@@ -467,7 +467,7 @@ var FileLog = class extends LogChannel {
 };
 
 //#endregion
-//#region ../logger/src/utils/safe-json-stringify.ts
+//#region ../../packages/logger/src/utils/safe-json-stringify.ts
 /**
 * Replacer that surfaces Error data — `name`, `message`, and `stack` are
 * non-enumerable on `Error`, so neither default JSON serialization nor an
@@ -498,7 +498,7 @@ function safeJsonStringify(value, space) {
 }
 
 //#endregion
-//#region ../logger/src/channels/json-file-log.ts
+//#region ../../packages/logger/src/channels/json-file-log.ts
 var JSONFileLog = class extends FileLog {
 	constructor(..._args) {
 		super(..._args);
@@ -626,7 +626,7 @@ var JSONFileLog = class extends FileLog {
 };
 
 //#endregion
-//#region ../logger/src/channels/sentry-log.ts
+//#region ../../packages/logger/src/channels/sentry-log.ts
 let Sentry;
 let isModuleExists = null;
 let loadingPromise;
@@ -823,7 +823,7 @@ var SentryLog = class extends LogChannel {
 };
 
 //#endregion
-//#region ../logger/src/redact/default-keys.ts
+//#region ../../packages/logger/src/redact/default-keys.ts
 /**
 * Built-in secret-key denylist — the redaction floor that applies with no
 * configuration at all.
@@ -937,7 +937,7 @@ const DEFAULT_REDACT_KEYS = [
 const DEFAULT_REDACT_KEY_SET = new Set(DEFAULT_REDACT_KEYS.map(normalizeRedactKey));
 
 //#endregion
-//#region ../logger/src/redact/redact.ts
+//#region ../../packages/logger/src/redact/redact.ts
 const DEFAULT_CENSOR = "[REDACTED]";
 /**
 * Values we copy by reference rather than walking. Expanding these with
@@ -1201,7 +1201,75 @@ function mergeRedact(base, extra) {
 }
 
 //#endregion
-//#region ../logger/src/utils/clear-message.ts
+//#region ../../packages/logger/src/redact/mask-email.ts
+/**
+* Email addresses inside free text: a local part and a dotted domain, letters
+* and digits from any script (`jöhn@exämple.de`). Kept deliberately simple (no
+* quoted local parts, no IP-literal domains, no percent-encoded `@`): it masks
+* the addresses that show up in log messages and cache keys, not every string
+* RFC 5322 allows.
+*
+* Every repetition is bounded (local part 64, label 63, at most 12 labels), so
+* matching stays linear in the input length. Cache keys and messages are often
+* built from request input; an unbounded pattern backtracks quadratically on a
+* long run of address-like characters with no domain.
+*/
+const EMAIL_IN_TEXT = /[\p{L}\p{N}._%+-]{1,64}@[\p{L}\p{N}-]{1,63}(?:\.[\p{L}\p{N}-]{1,63}){0,10}\.\p{L}{2,63}/gu;
+/**
+* Longest text {@link maskEmailsInText} scans. Anything past it is cut off and
+* replaced by a marker, so a huge cache key or message cannot cost more than a
+* bounded amount of time per log line, and nothing past the cut can leak.
+*/
+const MASK_EMAILS_MAX_LENGTH = 16384;
+/**
+* Mask one email address, keeping its first character and its domain:
+* `member@example.com` → `m***@example.com`. A value without an `@` is
+* returned as `***`.
+*
+* Key-based redaction cannot reach an address that sits inside a message
+* string or a cache key; mask it before it is logged.
+*
+* @example
+* log.info("mail", "send", `Sending mail to: ${maskEmail(to)}`);
+*/
+function maskEmail(address) {
+	const at = address.lastIndexOf("@");
+	if (at <= 0) return "***";
+	return `${String.fromCodePoint(address.codePointAt(0))}***${address.slice(at)}`;
+}
+/**
+* Mask every email address the pattern above recognises in a piece of text
+* with {@link maskEmail}. Text longer than {@link MASK_EMAILS_MAX_LENGTH}
+* characters is truncated first (the cut is marked).
+*
+* Dots are valid in the local part of an address, so a dotted prefix that
+* runs into the address is masked with it: in a cache key such as
+* `email.member@example.com` the whole `email.member` reads as the local part.
+*
+* Not recognised (left as they are): quoted local parts (`"john doe"@x.com`),
+* IP-literal domains (`user@[127.0.0.1]`) and percent-encoded addresses
+* (`user%40example.com`).
+*
+* @example
+* maskEmailsInText("sent to member@example.com") // "sent to m***@example.com"
+* maskEmailsInText("email.member@example.com") // "e***@example.com"
+*/
+function maskEmailsInText(text) {
+	let scanned = text;
+	let marker = "";
+	if (scanned.length > 16384) {
+		let cut = MASK_EMAILS_MAX_LENGTH;
+		const last = scanned.charCodeAt(cut - 1);
+		if (last >= 55296 && last <= 56319) cut -= 1;
+		marker = `…[${scanned.length - cut} chars truncated]`;
+		scanned = scanned.slice(0, cut);
+	}
+	if (!scanned.includes("@")) return scanned + marker;
+	return scanned.replace(EMAIL_IN_TEXT, (match) => maskEmail(match)) + marker;
+}
+
+//#endregion
+//#region ../../packages/logger/src/utils/clear-message.ts
 /**
 * Clear message from any terminal codes
 */
@@ -1211,7 +1279,7 @@ function clearMessage(message) {
 }
 
 //#endregion
-//#region ../logger/src/logger.ts
+//#region ../../packages/logger/src/logger.ts
 const SIGNAL_EVENTS = new Set([
 	"SIGINT",
 	"SIGTERM",
@@ -1239,6 +1307,8 @@ var Logger = class {
 		this.channels = [];
 		this.id = "logger-" + _mongez_reinforcements.Random.string(32);
 		this.autoFlushHandlers = /* @__PURE__ */ new Map();
+		this.pendingDeliveries = /* @__PURE__ */ new Map();
+		this.channelErrorHandler = reportChannelError;
 	}
 	/**
 	* Add a new channel
@@ -1255,6 +1325,21 @@ var Logger = class {
 		if (config.autoFlushOn) this.enableAutoFlush(config.autoFlushOn);
 		if (config.minLevel !== void 0) this.setMinLevel(config.minLevel);
 		if (config.redact !== void 0) this.setRedact(config.redact);
+		if (config.onChannelError) this.onChannelError(config.onChannelError);
+		return this;
+	}
+	/**
+	* Handle a channel's delivery failure. Logging is fire-and-forget, so a
+	* channel that throws or rejects never reaches the call site and never
+	* becomes an unhandled rejection; it goes to this handler instead. The
+	* default writes one line to stderr. The handler must not log through this
+	* logger (a failing channel would loop).
+	*
+	* @example
+	* log.onChannelError((error, channel) => metrics.increment(`log.${channel.name}.failed`));
+	*/
+	onChannelError(handler) {
+		this.channelErrorHandler = handler;
 		return this;
 	}
 	/**
@@ -1332,21 +1417,62 @@ var Logger = class {
 	* — each channel sees its own shallow clone so one channel cannot observe
 	* another's mutations (e.g. a later terminal channel still sees the original
 	* colored message).
+	*
+	* Synchronous and fire-and-forget: it returns the logger, not a promise.
+	* Async channel deliveries are tracked and awaited by {@link flush}; a
+	* channel that throws or rejects is isolated from the others and reported
+	* to {@link onChannelError}.
 	*/
-	async log(data) {
+	log(data) {
 		if (this.minLevel && LEVEL_RANK[data.type] < LEVEL_RANK[this.minLevel]) return this;
-		const baseEntry = applyRedact(data, this.redactConfig);
-		for (const channel of this.channels) {
+		let baseEntry;
+		try {
+			baseEntry = applyRedact(data, this.redactConfig);
+		} catch (error) {
+			for (const channel of this.channels) this.reportChannelError(error, channel, redactionFailedEntry(data));
+			return this;
+		}
+		for (const channel of this.channels) this.deliver(channel, data, baseEntry);
+		return this;
+	}
+	/**
+	* Prepare and hand one entry to one channel, isolating its failure (a
+	* channel redaction that throws included) and tracking an async delivery
+	* until it settles.
+	*/
+	deliver(channel, data, baseEntry) {
+		let payload = baseEntry;
+		let result;
+		try {
 			const channelRedact = channel.getRedactConfig?.();
-			const effectiveRedact = channelRedact ? mergeRedact(this.redactConfig, channelRedact) : void 0;
-			let payload = effectiveRedact ? applyRedact(data, effectiveRedact) : baseEntry;
+			if (channelRedact) payload = applyRedact(data, mergeRedact(this.redactConfig, channelRedact));
 			if (channel.terminal === false) payload = {
 				...payload,
 				message: clearMessage(payload.message)
 			};
-			channel.log(payload);
+			result = channel.log(payload);
+		} catch (error) {
+			this.reportChannelError(error, channel, payload);
+			return;
 		}
-		return this;
+		if (!result || typeof result.then !== "function") return;
+		let pending = this.pendingDeliveries.get(channel);
+		if (!pending) {
+			pending = /* @__PURE__ */ new Set();
+			this.pendingDeliveries.set(channel, pending);
+		}
+		const tracked = pending;
+		const delivery = Promise.resolve(result).catch((error) => this.reportChannelError(error, channel, payload)).finally(() => {
+			tracked.delete(delivery);
+			if (tracked.size === 0 && this.pendingDeliveries.get(channel) === tracked) this.pendingDeliveries.delete(channel);
+		});
+		tracked.add(delivery);
+	}
+	reportChannelError(error, channel, entry) {
+		try {
+			const outcome = this.channelErrorHandler(error, channel, entry);
+			if (outcome && typeof outcome.then === "function") outcome.then(void 0, () => {});
+		} catch {}
 	}
 	/**
 	* Make debug log
@@ -1442,7 +1568,9 @@ var Logger = class {
 		for (const channel of this.channels) if (channel.flushSync) channel.flushSync();
 	}
 	/**
-	* Asynchronously drain every channel that implements `flush()`.
+	* Wait for every in-flight async delivery, then drain every channel that
+	* implements `flush()` — bounded by `timeout` (default
+	* {@link DEFAULT_FLUSH_TIMEOUT_MS}).
 	*
 	* Unlike {@link flushSync}, this awaits each channel's async I/O — the
 	* correct call for a graceful shutdown that can afford to wait
@@ -1450,24 +1578,68 @@ var Logger = class {
 	* `process.exit`). A channel whose delivery is async (a network transport,
 	* an async disk write) implements `flush()`, not `flushSync()`.
 	*
-	* Channels are isolated: a channel whose flush rejects can neither prevent
-	* the others from draining nor escape as an unhandled rejection. Channels
-	* without `flush()` are skipped.
+	* Channels drain concurrently and independently: each waits for its own
+	* pending deliveries (including ones logged while the flush runs), then
+	* runs its `flush()`. A channel whose delivery hangs therefore cannot hold
+	* up another channel's drain, and a channel whose flush rejects can neither
+	* stop the others nor escape as an unhandled rejection. When `timeout`
+	* elapses, `flush()` resolves anyway and each channel still draining is
+	* reported to {@link onChannelError}. Channels without `flush()` only wait
+	* for their deliveries.
 	*
 	* @example
 	* async function shutdown() {
 	*   await httpServer.close();
-	*   await log.flush();
+	*   await log.flush({ timeout: 3000 });
 	*   process.exit(0);
 	* }
 	*/
-	async flush() {
-		await Promise.allSettled(this.channels.map(async (channel) => {
-			if (!channel.flush) return;
+	async flush(options = {}) {
+		const timeout = options.timeout ?? 5e3;
+		const draining = new Set(this.channels);
+		for (const channel of this.pendingDeliveries.keys()) draining.add(channel);
+		const unfinished = new Set(draining);
+		const drains = [...draining].map(async (channel) => {
 			try {
-				await channel.flush();
-			} catch {}
-		}));
+				await this.drainChannel(channel);
+			} catch {} finally {
+				unfinished.delete(channel);
+			}
+		});
+		const settled = Promise.allSettled(drains).then(() => false);
+		if (!Number.isFinite(timeout)) {
+			await settled;
+			return;
+		}
+		let resolveTimeout;
+		const timeoutReached = new Promise((resolve) => {
+			resolveTimeout = resolve;
+		});
+		const timer = setTimeout(() => resolveTimeout(true), Math.max(0, timeout));
+		timer.unref?.();
+		const timedOut = await Promise.race([settled, timeoutReached]);
+		clearTimeout(timer);
+		if (!timedOut) return;
+		for (const channel of unfinished) this.reportChannelError(/* @__PURE__ */ new Error(`flush timed out after ${timeout}ms; entries still in flight may be lost`), channel, {
+			type: "warn",
+			module: "logger",
+			action: "flush",
+			message: "flush timed out"
+		});
+	}
+	/**
+	* Wait until the channel has no delivery in flight, run its `flush()`, and
+	* repeat while that flush let new deliveries in.
+	*/
+	async drainChannel(channel) {
+		do {
+			let pending = this.pendingDeliveries.get(channel);
+			while (pending && pending.size > 0) {
+				await Promise.allSettled([...pending]);
+				pending = this.pendingDeliveries.get(channel);
+			}
+			if (channel.flush) await channel.flush();
+		} while ((this.pendingDeliveries.get(channel)?.size ?? 0) > 0);
 	}
 	/**
 	* Register one process-level handler per event that calls `flushSync()`
@@ -1513,6 +1685,34 @@ var Logger = class {
 	}
 };
 /**
+* Default `timeout` of {@link Logger.flush}: long enough for a healthy network
+* channel, short enough that a hung one cannot eat a shutdown budget.
+*/
+const DEFAULT_FLUSH_TIMEOUT_MS = 5e3;
+/**
+* What the error handler receives when the logger-wide redaction itself
+* failed: the entry's identity only, never the unredacted message or context.
+*/
+function redactionFailedEntry(data) {
+	return {
+		type: data.type,
+		module: data.module,
+		action: data.action,
+		message: "[entry dropped: redaction failed]"
+	};
+}
+/**
+* Default {@link ChannelErrorHandler}: one stderr line per failure. Written
+* directly to the stream, never through a logger, so a broken channel cannot
+* recurse.
+*/
+function reportChannelError(error, channel) {
+	const reason = error instanceof Error ? error.message : String(error);
+	try {
+		process.stderr.write(`[@warlock.js/logger] channel "${channel.name}" failed to log: ${reason}\n`);
+	} catch {}
+}
+/**
 * The package singleton. Use this for everyday logging — `log.info(...)`,
 * `log.error(...)`, `log.configure(...)`. Custom logger instances can be
 * created by instantiating `Logger` directly.
@@ -1529,7 +1729,7 @@ var Logger = class {
 const log = new Logger();
 
 //#endregion
-//#region ../logger/src/utils/capture-unhandled-errors.ts
+//#region ../../packages/logger/src/utils/capture-unhandled-errors.ts
 /**
 * Best-effort budget (ms) for draining async channels (file, Sentry, …) before
 * the forced exit. Bounded so a single stuck channel can't hang the process —
@@ -1579,17 +1779,21 @@ function captureAnyUnhandledRejection(options = {}) {
 
 //#endregion
 exports.ConsoleLog = ConsoleLog;
+exports.DEFAULT_FLUSH_TIMEOUT_MS = DEFAULT_FLUSH_TIMEOUT_MS;
 exports.DEFAULT_REDACT_KEYS = DEFAULT_REDACT_KEYS;
 exports.DEFAULT_REDACT_KEY_SET = DEFAULT_REDACT_KEY_SET;
 exports.FileLog = FileLog;
 exports.JSONFileLog = JSONFileLog;
 exports.LogChannel = LogChannel;
 exports.Logger = Logger;
+exports.MASK_EMAILS_MAX_LENGTH = MASK_EMAILS_MAX_LENGTH;
 exports.SentryLog = SentryLog;
 exports.applyRedact = applyRedact;
 exports.captureAnyUnhandledRejection = captureAnyUnhandledRejection;
 exports.clearMessage = clearMessage;
 exports.log = log;
+exports.maskEmail = maskEmail;
+exports.maskEmailsInText = maskEmailsInText;
 exports.mergeRedact = mergeRedact;
 exports.normalizeRedactKey = normalizeRedactKey;
 exports.resolveRedactKeys = resolveRedactKeys;