@znight/messaging 0.0.0-stage → 0.1.0

package/dist/index.mjs

@@ -0,0 +1,870 @@
+import { _ as consumerError, a as sleep, c as attemptFromHeaders, d as AttemptsExhaustedError, f as MessageDecodeError, g as brokerUnavailableError, h as NonRetryableError, i as isPositiveInteger, l as headerRecord, m as NoHandlerError, n as Semaphore, p as MessageValidationError, r as errorMessage, s as MessagingHeaders, u as messageHeader, v as isNonRetryable } from "./async-CFh_bvex.mjs";
+import { a as bodyToText, i as bodyToBytes, n as JSON_CONTENT_TYPE, o as jsonCodec, r as TEXT_CONTENT_TYPE, s as mediaType, t as BINARY_CONTENT_TYPE } from "./codec-Dku-NXXU.mjs";
+import { randomUUID } from "node:crypto";
+import { displayName, resolveOptions } from "@znight/core";
+// src/broker.ts
+/**
+* Publishes messages. Inject it in any provider (it is a singleton external provided by
+* `MessagingPlugin`):
+*
+* ```ts
+* @Injectable()
+* export class OrderService {
+*   constructor(private readonly broker: MessageBroker) {}
+*
+*   async place(order: Order) {
+*     await this.broker.publish('orders', order, { type: 'order.placed', key: order.customerId })
+*   }
+* }
+* ```
+*
+* `publish()` resolves once the broker confirmed the message (publisher confirms, SQS response,
+* Kafka acknowledgement). It is usable from `onBootstrap` of the messaging plugin until the
+* application is disposed (including providers' `onStart` / `onStop`).
+*/
+var MessageBroker = class {};
+const HEADER_NAME = /^[\x21-\x7e]+$/;
+/** The {@link MessageBroker} registered by `MessagingPlugin` (internal). */
+var DriverMessageBroker = class extends MessageBroker {
+	#driver;
+	#codec;
+	#hooks;
+	#closed = false;
+	/** Connects the broker to the driver (plugin `onBootstrap`). */
+	bind(driver, codec, hooks) {
+		this.#driver = driver;
+		this.#codec = codec;
+		this.#hooks = hooks;
+		this.#closed = false;
+	}
+	/** Rejects further publications (plugin `onDispose`). */
+	unbind() {
+		this.#closed = true;
+	}
+	async publish(queue, payload, options = {}) {
+		const driver = this.#driver;
+		const codec = this.#codec;
+		if (driver === void 0 || codec === void 0) throw brokerUnavailableError(`MessageBroker.publish('${queue}'): the messaging plugin is not bootstrapped yet (publish from onStart or later)`);
+		if (this.#closed) throw brokerUnavailableError(`MessageBroker.publish('${queue}'): the messaging plugin has been disposed`);
+		const message = this.#prepare(queue, payload, options, codec, driver);
+		const hooks = this.#hooks;
+		const wrapped = hooks?.hasWrappers("messaging:publish") ?? false;
+		const observed = hooks?.hasListeners("messaging:publish") ?? false;
+		if (hooks === void 0 || !wrapped && !observed) {
+			await driver.publish(queue, message.outbound());
+			return { id: message.id };
+		}
+		const event = {
+			queue,
+			type: options.type,
+			messageId: message.id,
+			headers: message.headers,
+			startTime: performance.now()
+		};
+		const send = async () => {
+			try {
+				await driver.publish(queue, message.outbound());
+			} catch (error) {
+				event.error = error;
+				throw error;
+			}
+		};
+		try {
+			if (wrapped) await hooks.run("messaging:publish", event, send);
+			else await send();
+		} finally {
+			if (observed) hooks.emit("messaging:publish", event);
+		}
+		return { id: message.id };
+	}
+	#prepare(queue, payload, options, codec, driver) {
+		if (typeof queue !== "string" || queue === "") throw new TypeError(`[znight] MessageBroker.publish(): the queue must be a non-empty string, got ${String(queue)}`);
+		const delayMs = options.delay ?? 0;
+		if (typeof delayMs !== "number" || !Number.isFinite(delayMs) || delayMs < 0) throw new TypeError(`[znight] MessageBroker.publish('${queue}'): "delay" must be a number of milliseconds >= 0`);
+		if (delayMs > driver.capabilities.maxPublishDelayMs) throw new RangeError(driver.capabilities.maxPublishDelayMs === 0 ? `[znight] MessageBroker.publish('${queue}'): the ${driver.name} driver does not support delayed publishing` : `[znight] MessageBroker.publish('${queue}'): the ${driver.name} driver supports delays up to ${driver.capabilities.maxPublishDelayMs} ms (got ${delayMs})`);
+		const headers = headerRecord();
+		if (options.headers !== void 0) for (const [name, value] of Object.entries(options.headers)) {
+			if (!HEADER_NAME.test(name)) throw new TypeError(`[znight] MessageBroker.publish('${queue}'): invalid header name "${name}"`);
+			if (typeof value !== "string") throw new TypeError(`[znight] MessageBroker.publish('${queue}'): header "${name}" must be a string`);
+			headers[name] = value;
+		}
+		const id = options.id ?? randomUUID();
+		const encoded = codec.encode(payload, options.contentType);
+		const timestamp = Date.now();
+		return {
+			id,
+			headers,
+			outbound: () => ({
+				id,
+				type: options.type,
+				key: options.key,
+				headers: { ...headers },
+				body: encoded.body,
+				contentType: encoded.contentType,
+				timestamp,
+				delayMs
+			})
+		};
+	}
+};
+// src/decorators.ts
+function marker() {}
+const classMarker = marker;
+const methodMarker = marker;
+const parameterMarker = marker;
+const errorHandlerMarker = marker;
+function Consumer(_queueOrOptions) {
+	return classMarker;
+}
+/**
+* Declares a message handler. With `type` (static), it handles the messages of that type (exact
+* match, or a pattern where `*` matches any sequence: `'order.*'`); without type it is the consumer's
+* default handler (messages without type, or whose type no other handler matches). A message no
+* handler matches is dead-lettered (reason `no-handler`).
+*/
+function OnMessage(_type) {
+	return methodMarker;
+}
+/**
+* Retry policy of a handler (static options). `attempts` counts the first delivery:
+* `{ attempts: 3 }` means one delivery plus two retries. Without `@Retry`, the plugin's
+* `defaults.retry` applies (3 attempts, exponential from 1 s).
+*/
+function Retry(_options) {
+	return methodMarker;
+}
+/**
+* Declares the consumer's error handler, called once a message will not be retried anymore (last
+* attempt failed, `NonRetryableError`, invalid payload, no matching handler). Returning `'ack'`
+* acknowledges the message; returning anything else (or throwing) dead-letters it.
+*
+* ```ts
+* @OnError()
+* onError(error: unknown, message: InboundMessage) {
+*   if (message.type?.startsWith('legacy.')) return 'ack'
+* }
+* ```
+*/
+function OnError() {
+	return errorHandlerMarker;
+}
+/**
+* Injects the message payload. With a Standard Schema (Zod, Valibot...), the payload is validated and
+* the parameter receives the schema output; an invalid payload is dead-lettered without retry
+* (reason `validation`). The schema is a _value_ argument (inline, or an exported binding).
+*/
+function Message(_schema) {
+	return parameterMarker;
+}
+/** Injects all the message headers, or the value of one header (`string | undefined`). `name` is static. */
+function Headers(_name) {
+	return parameterMarker;
+}
+/** Injects the {@link InboundMessage} (id, type, attempt, headers, raw message, abort signal...). */
+function Ctx() {
+	return parameterMarker;
+}
+// src/retry.ts
+/** Default base delay of a retry policy, in milliseconds. */
+const DEFAULT_RETRY_DELAY_MS = 1e3;
+/** Default backoff strategy. */
+const DEFAULT_BACKOFF = "exponential";
+/** Policy applied to handlers without `@Retry` when the plugin sets no `defaults.retry`. */
+const DEFAULT_RETRY_POLICY = Object.freeze({
+	attempts: 3,
+	backoff: "exponential",
+	delay: DEFAULT_RETRY_DELAY_MS,
+	maxDelay: 3e4
+});
+/** The policy of `retry: false` / `{ attempts: 1 }`. */
+const NO_RETRY_POLICY = Object.freeze({
+	attempts: 1,
+	backoff: "fixed",
+	delay: 0
+});
+const MAX_ATTEMPTS = 1e4;
+/**
+* Validates retry options and fills defaults.
+*
+* @throws ZnightError ZNIGHT011 for invalid values (`where` names the handler in the message).
+*/
+function normalizeRetry(options, where = "@Retry()") {
+	if (options === null || typeof options !== "object") throw consumerError(`${where}: retry options must be an object, got ${String(options)}`);
+	const { attempts, backoff = DEFAULT_BACKOFF, delay = DEFAULT_RETRY_DELAY_MS, maxDelay } = options;
+	if (!Number.isInteger(attempts) || attempts < 1 || attempts > MAX_ATTEMPTS) throw consumerError(`${where}: "attempts" must be an integer between 1 and ${MAX_ATTEMPTS}, got ${String(attempts)}`, ["attempts counts the first delivery: { attempts: 3 } means 1 delivery + 2 retries"]);
+	if (backoff !== "fixed" && backoff !== "exponential") throw consumerError(`${where}: "backoff" must be 'fixed' or 'exponential', got ${String(backoff)}`);
+	if (!isDuration(delay)) throw consumerError(`${where}: "delay" must be a finite number of milliseconds >= 0, got ${String(delay)}`);
+	if (maxDelay !== void 0 && (!isDuration(maxDelay) || maxDelay < delay)) throw consumerError(`${where}: "maxDelay" must be a finite number of milliseconds >= delay (${delay}), got ${String(maxDelay)}`);
+	return maxDelay === void 0 ? {
+		attempts,
+		backoff,
+		delay
+	} : {
+		attempts,
+		backoff,
+		delay,
+		maxDelay
+	};
+}
+function isDuration(value) {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+/**
+* Delay before the next attempt once `attempt` (1-based) failed: `delay` for `fixed`,
+* `delay * 2^(attempt - 1)` capped by `maxDelay` for `exponential`.
+*/
+function computeRetryDelay(policy, attempt) {
+	if (policy.backoff === "fixed") return policy.delay;
+	const exponent = Math.max(0, attempt - 1);
+	const raw = policy.delay * 2 ** exponent;
+	return Math.min(raw, policy.maxDelay ?? Number.MAX_SAFE_INTEGER);
+}
+/** Every delay the policy may request (one per retry), in attempt order. */
+function retryDelays(policy) {
+	const delays = [];
+	for (let attempt = 1; attempt < policy.attempts; attempt++) delays.push(computeRetryDelay(policy, attempt));
+	return delays;
+}
+/** Whether a delay is waited in-process (`true`) or delegated to the broker (`false`). */
+function isInProcessDelay(delayMs, capabilities) {
+	return delayMs <= capabilities.maxInProcessDelayMs;
+}
+/**
+* Checks that the driver can honour every delay of `policy`.
+*
+* @throws ZnightError ZNIGHT011 naming `where` and the offending delay.
+*/
+function assertRetrySupported(policy, capabilities, driver, where) {
+	for (const delay of new Set(retryDelays(policy))) {
+		if (isInProcessDelay(delay, capabilities)) continue;
+		if (capabilities.nativeDelay && delay <= capabilities.maxNativeDelayMs) continue;
+		const limits = capabilities.nativeDelay ? `in-process delays up to ${capabilities.maxInProcessDelayMs} ms and native delays up to ${capabilities.maxNativeDelayMs} ms` : `in-process delays up to ${capabilities.maxInProcessDelayMs} ms and no native delay`;
+		throw consumerError(`${where}: the ${driver} driver cannot wait ${delay} ms between attempts (it supports ${limits})`, ["Lower \"delay\"/\"maxDelay\" of the retry policy", "Or raise the driver budget (e.g. maxInProcessDelayMs) if holding messages that long is acceptable"]);
+	}
+}
+// src/consumers.ts
+/** Normalizes `defaults.retry` of the plugin. */
+function defaultRetryPolicy(retry) {
+	if (retry === void 0) return DEFAULT_RETRY_POLICY;
+	if (retry === false) return NO_RETRY_POLICY;
+	return normalizeRetry(retry, "MessagingPlugin defaults.retry");
+}
+/**
+* Validates `metadata.extensions.messaging` against the container and the driver capabilities.
+*
+* @throws ZnightError ZNIGHT011 describing the first invalid consumer.
+*/
+function prepareConsumers(metadata, container, driver, defaults) {
+	if (metadata === void 0) return [];
+	if (metadata === null || typeof metadata !== "object" || !Array.isArray(metadata.consumers)) throw consumerError("Invalid messaging metadata: \"consumers\" must be an array", ["Regenerate the metadata with the @znight/messaging compiler extension"]);
+	const byQueue = /* @__PURE__ */ new Map();
+	const prepared = [];
+	for (const definition of metadata.consumers) {
+		const consumer = prepareConsumer(definition, container, driver, defaults);
+		const previous = byQueue.get(consumer.queue);
+		if (previous !== void 0) throw consumerError(`${previous} and ${consumer.name} both consume "${consumer.queue}"`, ["A queue is consumed by a single @Consumer class: merge the handlers, or route by type with @OnMessage(type)"]);
+		byQueue.set(consumer.queue, consumer.name);
+		prepared.push(consumer);
+	}
+	return prepared;
+}
+function prepareConsumer(definition, container, driver, defaults) {
+	if (definition === null || typeof definition !== "object" || typeof definition.token !== "string" || definition.token === "") throw consumerError("Invalid consumer definition: missing provider token");
+	const token = definition.token;
+	const name = displayName(token);
+	if (typeof definition.queue !== "string" || definition.queue === "") throw consumerError(`@Consumer ${name}: the queue must be a non-empty string`);
+	if (!container.has(token)) throw consumerError(`@Consumer ${name}: no provider is registered for ${token}`, ["Regenerate the metadata: the consumer class must be a compiled provider"]);
+	const { concurrency: rawConcurrency, deadLetter, ...driverOptions } = definition.options ?? {};
+	const concurrency = rawConcurrency ?? defaults.concurrency;
+	if (!isPositiveInteger(concurrency)) throw consumerError(`@Consumer ${name}: "concurrency" must be a positive integer, got ${String(concurrency)}`);
+	if (deadLetter !== void 0 && deadLetter !== false && (typeof deadLetter !== "string" || deadLetter === "")) throw consumerError(`@Consumer ${name}: "deadLetter" must be a queue name or false, got ${String(deadLetter)}`);
+	if (deadLetter === definition.queue) throw consumerError(`@Consumer ${name}: the dead-letter queue cannot be the consumed queue "${definition.queue}"`);
+	const handlers = definition.handlers;
+	if (!Array.isArray(handlers) || handlers.length === 0) throw consumerError(`@Consumer ${name} has no @OnMessage handler`, ["Decorate at least one method with @OnMessage()"]);
+	const exact = /* @__PURE__ */ new Map();
+	const patterns = [];
+	let fallback;
+	let maxAttempts = 1;
+	const nativeDelays = /* @__PURE__ */ new Set();
+	for (const handlerDefinition of handlers) {
+		const handler = prepareHandler(handlerDefinition, name, driver, defaults.retry);
+		maxAttempts = Math.max(maxAttempts, handler.policy.attempts);
+		for (const delay of retryDelays(handler.policy)) if (!isInProcessDelay(delay, driver.capabilities)) nativeDelays.add(delay);
+		const type = handlerDefinition.type;
+		if (type === void 0) {
+			if (fallback !== void 0) throw consumerError(`@Consumer ${name}: ${fallback.method}() and ${handler.method}() are both default @OnMessage() handlers`, ["Give one of them a message type: @OnMessage(\"order.created\")"]);
+			fallback = handler;
+		} else if (type.includes("*")) {
+			if (patterns.some((entry) => entry.handler.definition.type === type)) throw duplicateType(name, type);
+			patterns.push({
+				regex: patternToRegExp(type),
+				handler
+			});
+		} else {
+			if (exact.has(type)) throw duplicateType(name, type);
+			exact.set(type, handler);
+		}
+	}
+	const errorHandler = definition.errorHandler;
+	if (errorHandler !== void 0) {
+		if (typeof errorHandler !== "string" || errorHandler === "") throw consumerError(`@Consumer ${name}: invalid @OnError method name ${String(errorHandler)}`);
+		const providers = container.metadata.providers;
+		const prototype = (Object.hasOwn(providers, token) ? providers[token] : void 0)?.class?.prototype;
+		if (prototype !== void 0 && typeof prototype[errorHandler] !== "function") throw consumerError(`@Consumer ${name}: the @OnError method ${errorHandler}() does not exist`);
+	}
+	return {
+		definition,
+		token,
+		name,
+		queue: definition.queue,
+		concurrency,
+		deadLetterQueue: resolveDeadLetter(definition.queue, deadLetter, defaults.deadLetter, driver),
+		errorHandler,
+		maxAttempts,
+		retryDelays: [...nativeDelays].sort((a, b) => a - b),
+		driverOptions,
+		select(type) {
+			if (type === void 0) return fallback;
+			const handler = exact.get(type);
+			if (handler !== void 0) return handler;
+			for (const entry of patterns) if (entry.regex.test(type)) return entry.handler;
+			return fallback;
+		}
+	};
+}
+function prepareHandler(definition, consumer, driver, defaultPolicy) {
+	if (definition === null || typeof definition !== "object" || typeof definition.method !== "string" || definition.method === "") throw consumerError(`@Consumer ${consumer}: invalid @OnMessage handler definition`);
+	const where = `${consumer}.${definition.method}()`;
+	if (typeof definition.invoke !== "function") throw consumerError(`${where}: the handler has no invoker`, ["Regenerate the metadata"]);
+	if (definition.type !== void 0 && (typeof definition.type !== "string" || definition.type === "")) throw consumerError(`${where}: the @OnMessage type must be a non-empty string`);
+	const policy = definition.retry === void 0 ? defaultPolicy : normalizeRetry(definition.retry, `@Retry on ${where}`);
+	assertRetrySupported(policy, driver.capabilities, driver.name, definition.retry === void 0 ? `${where} (default retry policy)` : `@Retry on ${where}`);
+	return {
+		definition,
+		method: definition.method,
+		policy
+	};
+}
+function duplicateType(consumer, type) {
+	return consumerError(`@Consumer ${consumer}: several @OnMessage handlers for type "${type}"`);
+}
+/** `order.*` → `/^order\..*$/`: `*` matches any sequence of characters. */
+function patternToRegExp(pattern) {
+	const source = pattern.split("*").map((part) => part.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join(".*");
+	return new RegExp(`^${source}$`, "s");
+}
+function resolveDeadLetter(queue, option, defaults, driver) {
+	if (option === false) return void 0;
+	if (typeof option === "string") return option;
+	if (defaults === false) return void 0;
+	const name = defaults === void 0 ? driver.deadLetterName(queue) : defaults(queue);
+	if (typeof name !== "string" || name === "" || name === queue) throw consumerError(`Invalid dead-letter queue name for "${queue}": ${String(name)}`);
+	return name;
+}
+// src/tokens.ts
+/** Tokens of the externals provided by `MessagingPlugin` (declared in the package manifest). */
+const MessagingTokens = Object.freeze({
+	MessageBroker: "@znight/messaging#MessageBroker",
+	InboundMessage: "@znight/messaging#InboundMessage"
+});
+// src/runtime.ts
+/** Runs the deliveries of one consumer. */
+var ConsumerRuntime = class {
+	consumer;
+	#services;
+	#slots;
+	#abort = new AbortController();
+	#inflight = /* @__PURE__ */ new Set();
+	#subscription;
+	#state = "created";
+	constructor(consumer, services) {
+		this.consumer = consumer;
+		this.#services = services;
+		this.#slots = new Semaphore(consumer.concurrency);
+	}
+	get state() {
+		return this.#state;
+	}
+	/** Deliveries currently handled (including those waiting for a slot or an in-process retry delay). */
+	get inFlight() {
+		return this.#inflight.size;
+	}
+	/** Subscribes to the queue. */
+	async start() {
+		if (this.#state !== "created") throw new Error(`[znight] Consumer ${this.consumer.name} was already started`);
+		this.#state = "starting";
+		const { consumer } = this;
+		try {
+			this.#subscription = await this.#services.driver.subscribe(consumer.queue, (delivery) => this.handle(delivery), {
+				consumer: consumer.name,
+				concurrency: consumer.concurrency,
+				deadLetterQueue: consumer.deadLetterQueue,
+				maxAttempts: consumer.maxAttempts,
+				retryDelays: consumer.retryDelays,
+				options: consumer.driverOptions
+			});
+		} catch (error) {
+			this.#state = "stopped";
+			throw error;
+		}
+		this.#state = "running";
+	}
+	/**
+	* Graceful stop: stops receiving, aborts in-process retry delays (those messages are released to
+	* the broker), awaits the in-flight handlers, then closes the subscription. Never throws.
+	*/
+	async stop() {
+		if (this.#state === "stopping" || this.#state === "stopped") return;
+		this.#state = "stopping";
+		this.#abort.abort();
+		const subscription = this.#subscription;
+		if (subscription !== void 0) try {
+			await subscription.cancel();
+		} catch (error) {
+			this.#services.logger.error(`Consumer ${this.consumer.name}: failed to cancel the subscription`, { err: error });
+		}
+		while (this.#inflight.size > 0) await Promise.allSettled([...this.#inflight]);
+		if (subscription !== void 0) try {
+			await subscription.close();
+		} catch (error) {
+			this.#services.logger.error(`Consumer ${this.consumer.name}: failed to close the subscription`, { err: error });
+		}
+		this.#state = "stopped";
+	}
+	/** Handles one delivery (the driver's `DeliveryHandler`). Never rejects. */
+	handle(delivery) {
+		const promise = this.#handle(delivery);
+		this.#inflight.add(promise);
+		const done = () => {
+			this.#inflight.delete(promise);
+		};
+		promise.then(done, done);
+		return promise;
+	}
+	async #handle(delivery) {
+		const signal = this.#abort.signal;
+		if (signal.aborted) return this.#release(delivery);
+		try {
+			await this.#slots.acquire(signal);
+		} catch {
+			return this.#release(delivery);
+		}
+		try {
+			await this.#process(delivery);
+		} catch (error) {
+			this.#services.logger.error(`Consumer ${this.consumer.name}: unexpected delivery failure`, { err: error });
+			await this.#release(delivery);
+		} finally {
+			this.#slots.release();
+		}
+	}
+	async #process(delivery) {
+		const { container, hooks, codec, driver } = this.#services;
+		const { consumer } = this;
+		const handler = consumer.select(delivery.type);
+		let payload;
+		let decodeError;
+		try {
+			payload = codec.decode(delivery.body, delivery.contentType);
+		} catch (error) {
+			decodeError = isNonRetryable(error) ? error : new MessageDecodeError(`Cannot decode the message body: ${errorMessage(error)}`, { cause: error });
+		}
+		const message = {
+			id: delivery.id,
+			queue: consumer.queue,
+			type: delivery.type,
+			payload,
+			headers: delivery.headers,
+			key: delivery.key,
+			attempt: delivery.attempt,
+			maxAttempts: handler?.policy.attempts ?? 1,
+			redelivered: delivery.redelivered,
+			timestamp: delivery.timestamp,
+			receivedAt: Date.now(),
+			contentType: delivery.contentType,
+			body: delivery.body,
+			driver: driver.name,
+			raw: delivery.raw,
+			signal: this.#abort.signal
+		};
+		const event = {
+			queue: consumer.queue,
+			type: delivery.type,
+			messageId: delivery.id,
+			attempt: delivery.attempt,
+			headers: delivery.headers,
+			consumer: consumer.name,
+			handler: handler?.method,
+			message,
+			startTime: performance.now()
+		};
+		const context = {
+			delivery,
+			message,
+			handler,
+			event,
+			decodeError,
+			executed: false,
+			followup: void 0
+		};
+		let failure = /* @__PURE__ */ new Error("A messaging:message hook wrapper did not call next()");
+		try {
+			await container.runInScope(() => hooks.run("messaging:message", event, () => this.#execute(context)), [[MessagingTokens.InboundMessage, message]]);
+		} catch (error) {
+			failure = error;
+			if (context.executed) this.#services.logger.error(`Consumer ${consumer.name}: error after handling message ${delivery.id}`, {
+				err: error,
+				queue: consumer.queue
+			});
+		}
+		if (!context.executed) await this.#failure(context, failure, false);
+		if (hooks.hasListeners("messaging:message")) hooks.emit("messaging:message", event);
+		await this.#followup(context);
+	}
+	/** Runs inside the request scope and the hooks: handler, then settlement. Never throws. */
+	async #execute(context) {
+		if (context.executed) return;
+		context.executed = true;
+		const { handler, message } = context;
+		if (context.decodeError !== void 0) return this.#failure(context, context.decodeError, true);
+		if (handler === void 0) return this.#terminal(context, new NoHandlerError(this.consumer.name, message.type), "no-handler", true);
+		if (message.attempt > message.maxAttempts) return this.#terminal(context, new AttemptsExhaustedError(message.attempt, message.maxAttempts), "max-attempts", false);
+		try {
+			const instance = this.#services.container.get(this.consumer.token);
+			await handler.definition.invoke(instance, message);
+		} catch (error) {
+			return this.#failure(context, error, true);
+		}
+		return this.#ack(context);
+	}
+	/** A failed attempt: retry while attempts remain, dead-letter otherwise. */
+	#failure(context, error, withErrorHandler) {
+		if (isNonRetryable(error)) return this.#terminal(context, error, reasonOf(error), withErrorHandler);
+		if (context.message.attempt < context.message.maxAttempts) return this.#retry(context, error);
+		return this.#terminal(context, error, "max-attempts", withErrorHandler);
+	}
+	async #retry(context, error) {
+		const { message, delivery, event } = context;
+		const policy = context.handler?.policy;
+		const delayMs = policy === void 0 ? 0 : computeRetryDelay(policy, message.attempt);
+		event.outcome = "retry";
+		event.error = error;
+		this.#services.logger.warn(`Consumer ${this.consumer.name}: attempt ${message.attempt}/${message.maxAttempts} of message ${message.id} failed, retrying in ${delayMs} ms`, {
+			queue: message.queue,
+			messageId: message.id,
+			type: message.type,
+			...this.#errorContext(error)
+		});
+		if (isInProcessDelay(delayMs, this.#services.driver.capabilities)) {
+			context.followup = {
+				kind: "retry",
+				delayMs,
+				error
+			};
+			return;
+		}
+		try {
+			await delivery.retry({
+				attempt: message.attempt + 1,
+				delayMs,
+				error
+			});
+		} catch (retryError) {
+			this.#services.logger.error(`Consumer ${this.consumer.name}: failed to schedule the retry of message ${message.id}`, {
+				err: retryError,
+				queue: message.queue
+			});
+			context.followup = { kind: "requeue" };
+		}
+	}
+	/** No more attempts: `@OnError` may acknowledge, otherwise the message is dead-lettered. */
+	async #terminal(context, error, reason, withErrorHandler) {
+		context.event.error = error;
+		const method = this.consumer.errorHandler;
+		if (withErrorHandler && method !== void 0) try {
+			if (await this.#services.container.get(this.consumer.token)[method]?.(error, context.message) === "ack") return this.#ack(context);
+		} catch (handlerError) {
+			this.#services.logger.error(`Consumer ${this.consumer.name}: @OnError ${method}() failed`, {
+				err: handlerError,
+				queue: context.message.queue,
+				messageId: context.message.id
+			});
+		}
+		return this.#deadLetter(context, error, reason);
+	}
+	async #deadLetter(context, error, reason) {
+		const { message, delivery, event } = context;
+		const queue = this.consumer.deadLetterQueue;
+		event.outcome = "dead-letter";
+		try {
+			await delivery.deadLetter({
+				queue,
+				reason,
+				error,
+				attempt: message.attempt
+			});
+		} catch (deadLetterError) {
+			event.outcome = "retry";
+			event.error = deadLetterError;
+			this.#services.logger.error(`Consumer ${this.consumer.name}: failed to dead-letter message ${message.id}, it will be redelivered`, {
+				err: deadLetterError,
+				cause: error,
+				queue: message.queue,
+				deadLetterQueue: queue
+			});
+			context.followup = { kind: "requeue" };
+			return;
+		}
+		this.#services.logger.error(queue === void 0 ? `Consumer ${this.consumer.name}: message ${message.id} rejected (${reason})` : `Consumer ${this.consumer.name}: message ${message.id} dead-lettered to ${queue} (${reason})`, {
+			queue: message.queue,
+			messageId: message.id,
+			type: message.type,
+			attempt: message.attempt,
+			reason,
+			...this.#errorContext(error)
+		});
+	}
+	/**
+	* The error of a failed delivery in the retry / dead-letter log entries: the error itself (with its
+	* stack), or only its message when a `messaging:message` wrapper is installed. Such a wrapper (the
+	* ObservabilityPlugin delivery log) writes its own entry for the delivery with the error: the stack
+	* is logged once. Settlement failures always log their error.
+	*/
+	#errorContext(error) {
+		return this.#services.hooks.hasWrappers("messaging:message") ? { error: errorMessage(error) } : { err: error };
+	}
+	async #ack(context) {
+		context.event.outcome = "ack";
+		try {
+			await context.delivery.ack();
+		} catch (error) {
+			this.#services.logger.warn(`Consumer ${this.consumer.name}: failed to acknowledge message ${context.message.id}, the broker will redeliver it`, {
+				err: error,
+				queue: context.message.queue
+			});
+		}
+	}
+	/** Work done after the scope closed: in-process retry delays and requeues. */
+	async #followup(context) {
+		const followup = context.followup;
+		if (followup === void 0) return;
+		const { delivery, message } = context;
+		if (followup.kind === "retry") {
+			try {
+				await sleep(followup.delayMs, this.#abort.signal);
+			} catch {
+				return this.#release(delivery);
+			}
+			try {
+				await delivery.retry({
+					attempt: message.attempt + 1,
+					delayMs: 0,
+					error: followup.error
+				});
+				return;
+			} catch (error) {
+				this.#services.logger.error(`Consumer ${this.consumer.name}: failed to redeliver message ${message.id}`, {
+					err: error,
+					queue: message.queue
+				});
+			}
+		}
+		try {
+			await sleep(this.#services.requeueDelayMs, this.#abort.signal);
+		} catch {}
+		return this.#release(delivery);
+	}
+	async #release(delivery) {
+		try {
+			await delivery.release();
+		} catch (error) {
+			this.#services.logger.error(`Consumer ${this.consumer.name}: failed to release message ${delivery.id}, the broker will redeliver it`, {
+				err: error,
+				queue: this.consumer.queue
+			});
+		}
+	}
+};
+function reasonOf(error) {
+	if (error instanceof MessageValidationError) return "validation";
+	if (error instanceof MessageDecodeError) return "decode";
+	if (error instanceof NoHandlerError) return "no-handler";
+	if (error instanceof AttemptsExhaustedError) return "max-attempts";
+	return "non-retryable";
+}
+// src/plugin.ts
+const DEFAULT_REQUEUE_DELAY_MS = 1e3;
+/** Period of the keep-alive timer (it never does anything: it only keeps the event loop alive). */
+const KEEP_ALIVE_INTERVAL_MS = 2 ** 30;
+/**
+* Message consumers and publishing.
+*
+* ```ts
+* import { MessagingPlugin } from '@znight/messaging'
+* import { rabbitmq } from '@znight/messaging/rabbitmq'
+*
+* const app = await Application.create({
+*   metadata: __ZNIGHT_METADATA__,
+*   plugins: [MessagingPlugin.configure({ driver: rabbitmq({ url: 'amqp://localhost' }) })],
+* })
+* ```
+*
+* Options may be computed from the container (evaluated in `onBootstrap`):
+* `MessagingPlugin.configure(c => ({ driver: rabbitmq({ url: c.get(AmqpConfig).url }) }))`.
+*/
+const MessagingPlugin = Object.freeze({ configure(options) {
+	return createPlugin(options);
+} });
+function createPlugin(rawOptions) {
+	const broker = new DriverMessageBroker();
+	let driver;
+	let connected = false;
+	let consume = true;
+	let runtimes = [];
+	/**
+	* Keeps the process alive while consumers run: they are its ingress, and some drivers hold no
+	* handle of their own (the memory driver only uses microtasks and short timers), so a process
+	* without other handle would exit right after `app.start()`, without graceful shutdown.
+	*/
+	let keepAlive;
+	const stopKeepAlive = () => {
+		if (keepAlive !== void 0) clearInterval(keepAlive);
+		keepAlive = void 0;
+	};
+	return {
+		name: "messaging",
+		broker,
+		get driver() {
+			return driver;
+		},
+		consumers() {
+			return runtimes.map((runtime) => ({
+				consumer: runtime.consumer.name,
+				queue: runtime.consumer.queue,
+				state: runtime.state,
+				concurrency: runtime.consumer.concurrency,
+				inFlight: runtime.inFlight,
+				deadLetterQueue: runtime.consumer.deadLetterQueue
+			}));
+		},
+		register(ctx) {
+			ctx.container.registerExternal({
+				token: MessagingTokens.InboundMessage,
+				scope: "request",
+				providedBy: "MessagingPlugin"
+			});
+			ctx.container.registerValue(MessagingTokens.MessageBroker, broker);
+		},
+		async onBootstrap(ctx) {
+			const options = validateOptions(resolveOptions(rawOptions, ctx.container));
+			driver = options.driver;
+			consume = options.consume ?? true;
+			const defaults = options.defaults ?? {};
+			const consumerDefaults = {
+				retry: defaultRetryPolicy(defaults.retry),
+				concurrency: defaults.concurrency ?? 1,
+				deadLetter: defaults.deadLetter
+			};
+			const prepared = prepareConsumers(ctx.metadata.extensions?.messaging, ctx.container, driver, consumerDefaults);
+			const codec = options.codec ?? jsonCodec;
+			connected = true;
+			await driver.connect({ logger: ctx.logger });
+			broker.bind(driver, codec, ctx.hooks);
+			const services = {
+				container: ctx.container,
+				hooks: ctx.hooks,
+				logger: ctx.logger,
+				codec,
+				driver,
+				requeueDelayMs: defaults.requeueDelay ?? DEFAULT_REQUEUE_DELAY_MS
+			};
+			runtimes = prepared.map((consumer) => new ConsumerRuntime(consumer, services));
+		},
+		async onStart(ctx) {
+			if (!consume || runtimes.length === 0) return;
+			const failure = (await Promise.allSettled(runtimes.map((runtime) => runtime.start()))).find((result) => result.status === "rejected");
+			if (failure !== void 0) {
+				await Promise.all(runtimes.map((runtime) => runtime.stop()));
+				throw failure.reason;
+			}
+			keepAlive ??= setInterval(() => void 0, KEEP_ALIVE_INTERVAL_MS);
+			ctx.logger.info(`Messaging: ${runtimes.length} consumer(s) subscribed with the ${driver?.name} driver`, { queues: runtimes.map((runtime) => runtime.consumer.queue) });
+		},
+		async onStop() {
+			try {
+				await Promise.all(runtimes.map((runtime) => runtime.stop()));
+			} finally {
+				stopKeepAlive();
+			}
+		},
+		async onDispose() {
+			stopKeepAlive();
+			broker.unbind();
+			if (driver !== void 0 && connected) {
+				connected = false;
+				await driver.close();
+			}
+		}
+	};
+}
+function validateOptions(options) {
+	if (options === null || typeof options !== "object") throw consumerError("MessagingPlugin.configure(): options must be an object");
+	const driver = options.driver;
+	if (driver === void 0 || driver === null || typeof driver.connect !== "function" || typeof driver.subscribe !== "function" || typeof driver.publish !== "function" || typeof driver.close !== "function" || typeof driver.deadLetterName !== "function" || typeof driver.capabilities !== "object") throw consumerError("MessagingPlugin.configure(): \"driver\" must be a messaging driver", ["Use rabbitmq() from '@znight/messaging/rabbitmq', sqs(), kafka() or memory() from their subpaths"]);
+	const defaults = options.defaults;
+	if (defaults?.concurrency !== void 0 && !isPositiveInteger(defaults.concurrency)) throw consumerError(`MessagingPlugin defaults.concurrency must be a positive integer, got ${String(defaults.concurrency)}`);
+	if (defaults?.requeueDelay !== void 0 && !(Number.isFinite(defaults.requeueDelay) && defaults.requeueDelay >= 0)) throw consumerError(`MessagingPlugin defaults.requeueDelay must be a number of milliseconds >= 0, got ${String(defaults.requeueDelay)}`);
+	if (defaults?.deadLetter !== void 0 && defaults.deadLetter !== false && typeof defaults.deadLetter !== "function") throw consumerError("MessagingPlugin defaults.deadLetter must be a function (queue => name) or false");
+	return options;
+}
+// src/standard-schema.ts
+/** Whether `value` looks like a Standard Schema v1 (has a `~standard.validate` function). */
+function isStandardSchema(value) {
+	if (value === null || typeof value !== "object" && typeof value !== "function") return false;
+	const props = value["~standard"];
+	return props !== null && typeof props === "object" && typeof props.validate === "function";
+}
+// src/validation.ts
+/**
+* Validates `value` with a Standard Schema (Zod, Valibot, ArkType...) and returns the schema
+* **output** (defaults and transforms applied). On failure it throws a {@link MessageValidationError},
+* a `NonRetryableError`: the message is dead-lettered without further attempts.
+*
+* Returns synchronously when the schema validates synchronously, a promise otherwise. Called by the
+* code generated for `@Message(schema)` parameters:
+*
+* ```ts
+* invoke: async (c, m) => c.handle(await validateMessage(OrderCreated, m.payload))
+* ```
+*
+* @param label Describes the value in the error message. Default: `'message payload'`.
+*/
+function validateMessage(schema, value, label = "message payload") {
+	if (!isStandardSchema(schema)) throw new TypeError(`[znight] validateMessage(): the schema of the ${label} is not a Standard Schema v1`);
+	const result = schema["~standard"].validate(value);
+	if (isPromiseLike(result)) return Promise.resolve(result).then((settled) => unwrap(settled, label));
+	return unwrap(result, label);
+}
+function unwrap(result, label) {
+	if (result.issues === void 0) return result.value;
+	throw new MessageValidationError(label, result.issues.map(toIssue));
+}
+function toIssue(issue) {
+	return {
+		path: formatPath(issue.path),
+		message: String(issue.message)
+	};
+}
+function formatPath(path) {
+	if (path === void 0 || path.length === 0) return "";
+	return path.map((segment) => String(isSegment(segment) ? segment.key : segment)).join(".");
+}
+function isPromiseLike(value) {
+	return typeof value?.then === "function";
+}
+function isSegment(segment) {
+	return typeof segment === "object" && segment !== null && "key" in segment;
+}
+export { AttemptsExhaustedError, BINARY_CONTENT_TYPE, Consumer, Ctx, DEFAULT_BACKOFF, DEFAULT_RETRY_DELAY_MS, DEFAULT_RETRY_POLICY, Headers, JSON_CONTENT_TYPE, Message, MessageBroker, MessageDecodeError, MessageValidationError, MessagingHeaders, MessagingPlugin, MessagingTokens, NoHandlerError, NonRetryableError, OnError, OnMessage, Retry, TEXT_CONTENT_TYPE, attemptFromHeaders, bodyToBytes, bodyToText, computeRetryDelay, isNonRetryable, isStandardSchema, jsonCodec, mediaType, messageHeader, normalizeRetry, validateMessage };
+
+//# sourceMappingURL=index.mjs.map