@warlock.js/herald 4.14.0 → 4.16.0

package/CHANGELOG.md

@@ -1,21 +1,42 @@
-# Changelog — @warlock.js/herald
-
-All notable changes to `@warlock.js/herald` 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.
-
-## 4.12.0
-
-### Changed
-
-- Declares its own test runner and pins it to an exact version (`vitest@4.1.10`). The package is its own repository, so a runner resolved from a workspace root it may not be cloned with is a runner it cannot rely on. The pin is exact rather than a range because the version moved underneath the suite mid-development on an unrelated install — a suite whose runner can change without anyone choosing it proves less than it appears to
-
-## 4.2.11
-
-### Changed
-
-- Bumped `@mongez/reinforcements` to 3.3.0
-
-## 4.1.15
-
-- Baseline — per-package changelog tracking starts at this version.
+# Changelog — @warlock.js/herald
+
+All notable changes to `@warlock.js/herald` 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.
+
+## 4.16.0 - 2026-08-18
+
+### Security
+
+- **Poison-message DoS: an `EventConsumer.handle()` that reliably throws was nack+requeued forever**, with no retry cap and no dead-letter escape hatch — a single bad message could pin a consumer in a hot ack/nack loop indefinitely, starving every other message behind it (worse with low prefetch). `prepareConsumerSubscription`'s catch now calls the channel's bounded `ctx.retry()` instead of an unconditional `ctx.nack(true)`, so redelivery is capped and the message is dead-lettered (if configured) or dropped with a loud `log.error` once the cap is hit — never silently, and never forever
+- **Fixed the retry counter never advancing on the automatic (non-explicit) nack path** (`RabbitMQChannel.subscribe`'s catch, used by any direct `channel.subscribe(handler, { retry, deadLetter })` caller whose handler throws instead of calling `ctx.retry()` itself). It read `x-retry-count` from the *original* message's headers and then plain-`nack(msg, false, true)`'d — which redelivers that same original message, so the header a developer's `retry.maxRetries`/`deadLetter` depended on never changed and the configured cap was silently never reached. Both the automatic path and the explicit `ctx.retry()` path now share one bounded-retry routine that republishes with an incremented header, so `maxRetries`/`deadLetter` are honored regardless of which path a handler takes
+- **Broker credentials no longer leak into thrown/logged connection errors.** `username`/`password` are now URI-encoded when building the `amqp://` URL (a reserved character like `@`/`:`/`/` in a generated secret previously produced a malformed URL whose parser error echoed the raw credential back), and any error surfaced from `connect()` — including one that embeds a caller-supplied `uri` with credentials — has `user:pass@` redacted before it's re-thrown, so a connection failure can no longer put a plaintext broker password in front of `console.error`/structured logging/an error tracker
+
+### Dependencies
+
+- Bumped `@mongez/events` to `^2.2.7` (no breaking changes) and `@mongez/reinforcements` to `^4.0.1`. The reinforcements major makes `Random.string/nanoid/id/token/uuid` CSPRNG-backed (WebCrypto) and removes `Random.seed()` support — audited this package's source and tests for `Random.seed(` and for seeded/reproducible use of `Random.*`; none found, so no code changes were needed.
+
+## 4.15.0 - 2026-08-16
+
+### Fixed
+
+- **The RabbitMQ driver's lazy `amqplib` loader was not idempotent under concurrent callers.** It cached the resolved module in a module-level binding but nothing guarded the load itself, so two loads could be in flight at the same time and the last one to settle won the binding. The eager, unawaited `loadAmqplibModule()` call at module scope was one of those callers by construction — it started a load nobody was waiting on, which then raced the awaited call from `connect()`. That eager call has been removed: `connect()` already awaits the loader, so it bought nothing but the race. The loader now memoizes the in-flight promise itself, so the first caller starts the `import()` and every later caller awaits that same one
+- **No user-visible misbehaviour is known in production** — both racing paths resolve the same real `amqplib`, so whichever won, callers got the module they expected. The observable damage was in test isolation: when a test was aborted mid-`await import(...)`, the racing loads could leave the binding holding the real `amqplib` while the test file's `vi.mock("amqplib")` was still active, so every later test in that file silently bypassed the mock and opened a real socket. Proven by instrumentation — the driver held a live `ChannelModel` on `::1:5672` while `import("amqplib")` inside the same test still returned the mock, which is how a green test could be green for the wrong reason
+- **Verified by a timeout sweep, not by a passing suite.** The full suite passed both before and after (13 files / 137 tests), because the fault only surfaces when the first test is starved of time. Running `tests/connect-to-broker.test.ts` at `--testTimeout=3000` and `4000` previously timed out the first test *and* took `wraps a connection failure with the driver name` down with it, failing in ~50 ms with `promise resolved "Broker{…}" instead of rejecting` — the mock was gone. With the loader fixed, that test passes at every timeout even while the first test still times out: starving one test can no longer poison the next
+- **The first test also paid a cold-transform cost inside its own timed body**, since `connectToBroker` dynamically imports the driver, which pulls in `@warlock.js/seal` and `@warlock.js/logger` as raw TS source. That work moved to a `beforeAll` warm-up. This is a test-timing change only and carries none of the correctness weight above — the loader fix stands on its own without it
+
+## 4.12.0
+
+### Changed
+
+- Declares its own test runner and pins it to an exact version (`vitest@4.1.10`). The package is its own repository, so a runner resolved from a workspace root it may not be cloned with is a runner it cannot rely on. The pin is exact rather than a range because the version moved underneath the suite mid-development on an unrelated install — a suite whose runner can change without anyone choosing it proves less than it appears to
+
+## 4.2.11
+
+### Changed
+
+- Bumped `@mongez/reinforcements` to 3.3.0
+
+## 4.1.15
+
+- Baseline — per-package changelog tracking starts at this version.

package/cjs/index.cjs

@@ -17,6 +17,7 @@ var __exportAll = (all, no_symbols) => {
 
 //#endregion
 let node_events = require("node:events");
+let _warlock_js_logger = require("@warlock.js/logger");
 let _warlock_js_seal = require("@warlock.js/seal");
 let node_crypto = require("node:crypto");
 let crypto = require("crypto");
@@ -354,7 +355,7 @@ function prepareConsumerSubscription(Consumer, onError) {
 			});
 			ctx.ack();
 		} catch (error) {
-			ctx.nack(true);
+			await ctx.retry();
 			if (onError) onError(error, Consumer.eventName);
 		}
 	};
@@ -465,6 +466,7 @@ var RabbitMQChannel = class {
 		const { consumerTag } = await this.amqpChannel.consume(this.name, async (msg) => {
 			if (!msg) return;
 			let ackHandled = isFireAndForget;
+			let parsedMessage;
 			try {
 				const content = JSON.parse(msg.content.toString());
 				let payload = content.payload;
@@ -495,6 +497,7 @@ var RabbitMQChannel = class {
 					payload,
 					raw: msg
 				};
+				parsedMessage = message;
 				await handler(message, {
 					ack: async () => {
 						if (!ackHandled) {
@@ -530,31 +533,16 @@ var RabbitMQChannel = class {
 					retry: async (delay) => {
 						if (ackHandled) return;
 						ackHandled = true;
-						const retryCount = (metadata.retryCount || 0) + 1;
-						if (retryCount > (options?.retry?.maxRetries ?? 3)) {
-							if (options?.deadLetter) await this.sendToDeadLetter(message, options.deadLetter.channel);
-							this.amqpChannel.ack(msg);
-							return;
-						}
-						const headers = {
-							...msg.properties.headers,
-							"x-retry-count": retryCount
-						};
-						if (delay) headers["x-delay"] = delay;
-						this.amqpChannel.sendToQueue(this.name, msg.content, {
-							...msg.properties,
-							headers
-						});
-						this.amqpChannel.ack(msg);
+						await this.retryOrGiveUp(msg, metadata.retryCount || 0, options, message, delay);
 					}
 				});
 				if (!ackHandled) this.amqpChannel.ack(msg);
 			} catch (error) {
 				if (ackHandled) return;
-				if (options?.retry) if ((msg.properties.headers?.["x-retry-count"] || 0) < options.retry.maxRetries) this.amqpChannel.nack(msg, false, true);
-				else if (options.deadLetter) this.amqpChannel.nack(msg, false, false);
-				else this.amqpChannel.reject(msg, false);
-				else this.amqpChannel.nack(msg, false, false);
+				if (options?.retry) {
+					const currentRetryCount = msg.properties.headers?.["x-retry-count"] || 0;
+					await this.retryOrGiveUp(msg, currentRetryCount, options, parsedMessage);
+				} else this.amqpChannel.nack(msg, false, false);
 			}
 		}, consumerOptions);
 		const subscription = new RabbitMQSubscription(subscriptionId, this.name, consumerTag, this.amqpChannel);
@@ -593,6 +581,61 @@ var RabbitMQChannel = class {
 		this.amqpChannel.sendToQueue(deadLetterChannel, Buffer.from(content), { persistent: true });
 	}
 	/**
+	* Dead-letter a message whose body couldn't be parsed into a {@link Message}
+	* (e.g. `JSON.parse` itself threw before an envelope existed). Forwards the
+	* raw AMQP bytes/properties as-is rather than re-deriving a payload, so a
+	* malformed message isn't lost.
+	*/
+	sendToDeadLetterRaw(msg, deadLetterChannel) {
+		this.amqpChannel.sendToQueue(deadLetterChannel, msg.content, {
+			...msg.properties,
+			persistent: true
+		});
+	}
+	/**
+	* Bounded retry shared by the explicit `ctx.retry()` call and the automatic
+	* catch when a handler throws without calling it itself — so both paths
+	* honor the same cap instead of the automatic path silently requeueing
+	* forever (see `subscribe()`'s catch block).
+	*
+	* Under the cap: republishes with an incremented `x-retry-count` header —
+	* NOT a plain `nack(msg, false, true)`, which redelivers the original
+	* message untouched and never advances the counter.
+	*
+	* At/over the cap: dead-letters if configured, otherwise drops the message
+	* with a loud `log.error` (never a silent drop) so an operator can see a
+	* poison message was discarded instead of it vanishing without a trace.
+	*/
+	async retryOrGiveUp(msg, currentRetryCount, options, parsedMessage, delay) {
+		const retryCount = currentRetryCount + 1;
+		const maxRetries = options?.retry?.maxRetries ?? 3;
+		if (retryCount > maxRetries) {
+			if (options?.deadLetter) if (parsedMessage) await this.sendToDeadLetter(parsedMessage, options.deadLetter.channel);
+			else this.sendToDeadLetterRaw(msg, options.deadLetter.channel);
+			else {
+				_warlock_js_logger.log.error("herald", "poison-message", `Dropping message on channel "${this.name}" after ${retryCount - 1} failed ${retryCount - 1 === 1 ? "retry" : "retries"} (maxRetries: ${maxRetries}) with no dead-letter channel configured.`, {
+					channel: this.name,
+					retryCount: retryCount - 1,
+					maxRetries
+				});
+				this.amqpChannel.reject(msg, false);
+				return;
+			}
+			this.amqpChannel.ack(msg);
+			return;
+		}
+		const headers = {
+			...msg.properties.headers,
+			"x-retry-count": retryCount
+		};
+		if (delay) headers["x-delay"] = delay;
+		this.amqpChannel.sendToQueue(this.name, msg.content, {
+			...msg.properties,
+			headers
+		});
+		this.amqpChannel.ack(msg);
+	}
+	/**
 	* Request-response pattern
 	*/
 	async request(payload, options) {
@@ -712,13 +755,16 @@ var RabbitMQSubscription = class {
 //#region ../herald/src/drivers/rabbitmq/rabbitmq-driver.ts
 var rabbitmq_driver_exports = /* @__PURE__ */ __exportAll({ RabbitMQDriver: () => RabbitMQDriver });
 /**
-* Cached amqplib module (loaded once, reused)
-*/
-let amqplibModule;
-/**
-* Module availability flag
+* The single amqplib load, shared by every caller.
+*
+* Memoized as a promise rather than as a resolved value so the loader stays
+* idempotent: without it, two callers arriving before the first `import()`
+* settles would each start their own load and the last writer would win, so a
+* caller could end up observing a module instance it never awaited.
+*
+* Resolves to `undefined` when amqplib is not installed.
 */
-let isModuleExists = null;
+let amqplibModulePromise;
 /**
 * Installation instructions for amqplib
 */
@@ -735,17 +781,26 @@ Or manually:
   yarn add amqplib
 `.trim();
 /**
-* Load amqplib module
+* Strip `user:password@` credentials from any `amqp(s)://` URL embedded in a
+* string. The connection URL carries plaintext broker credentials, and
+* amqplib/Node's URL parser commonly echoes the offending URL verbatim in a
+* malformed-URL error (e.g. an unencoded `@`/`:` in the password) — applied
+* to every error `connect()` surfaces so a credential never reaches whatever
+* the host app does with a thrown connection error (console.error,
+* structured logging, an error tracker).
 */
-async function loadAmqplibModule() {
-	try {
-		amqplibModule = await import("amqplib");
-		isModuleExists = true;
-	} catch {
-		isModuleExists = false;
-	}
+function redactAmqpCredentials(message) {
+	return message.replace(/(amqps?:\/\/)[^/@\s]+@/gi, "$1****:****@");
+}
+/**
+* Load amqplib, reusing the single shared load for every caller.
+*
+* @returns The amqplib module, or `undefined` when it is not installed.
+*/
+function loadAmqplibModule() {
+	if (!amqplibModulePromise) amqplibModulePromise = import("amqplib").catch(() => void 0);
+	return amqplibModulePromise;
 }
-loadAmqplibModule();
 /**
 * RabbitMQ Driver
 *
@@ -828,11 +883,8 @@ var RabbitMQDriver = class {
 	* Connect to RabbitMQ
 	*/
 	async connect() {
-		if (isModuleExists === false) throw new Error(`amqplib is not installed.\n\n${AMQPLIB_INSTALL_INSTRUCTIONS}`);
-		if (isModuleExists === null) {
-			await loadAmqplibModule();
-			if (!isModuleExists) throw new Error(`amqplib is not installed.\n\n${AMQPLIB_INSTALL_INSTRUCTIONS}`);
-		}
+		const amqplib = await loadAmqplibModule();
+		if (!amqplib) throw new Error(`amqplib is not installed.\n\n${AMQPLIB_INSTALL_INSTRUCTIONS}`);
 		try {
 			const url = this.buildConnectionUrl();
 			const connectOptions = {
@@ -840,7 +892,7 @@ var RabbitMQDriver = class {
 				timeout: this.options.connectionTimeout,
 				...this.options.clientOptions
 			};
-			this.connection = await amqplibModule.connect(url, connectOptions);
+			this.connection = await amqplib.connect(url, connectOptions);
 			this.amqpChannel = await this.connection.createChannel();
 			if (this.options.prefetch) await this.amqpChannel.prefetch(this.options.prefetch);
 			this._isConnected = true;
@@ -857,7 +909,8 @@ var RabbitMQDriver = class {
 			});
 		} catch (error) {
 			this._isConnected = false;
-			throw new Error(`Failed to connect to RabbitMQ: ${error instanceof Error ? error.message : String(error)}`);
+			const message = error instanceof Error ? error.message : String(error);
+			throw new Error(`Failed to connect to RabbitMQ: ${redactAmqpCredentials(message)}`);
 		}
 	}
 	/**
@@ -869,7 +922,7 @@ var RabbitMQDriver = class {
 		const host = this.options.host ?? "localhost";
 		const port = this.options.port ?? 5672;
 		const vhost = this.options.vhost ?? "/";
-		return `${protocol}://${this.options.username ?? "guest"}:${this.options.password ?? "guest"}@${host}:${port}/${encodeURIComponent(vhost)}`;
+		return `${protocol}://${encodeURIComponent(this.options.username ?? "guest")}:${encodeURIComponent(this.options.password ?? "guest")}@${host}:${port}/${encodeURIComponent(vhost)}`;
 	}
 	/**
 	* Handle reconnection