@vercube/queue 1.3.0

package/dist/index.mjs

@@ -0,0 +1,1719 @@
+import { _ as resolveBackoff, a as KEY_HEADER, c as PRIORITY_HEADER, d as delay, f as encodePayload, g as readNumericHeader, h as prune, i as JOB_HEADER, l as WILDCARD_JOB, m as normalizeHeaders, n as ATTEMPTS_HEADER, o as MAX_ATTEMPTS, p as generateJobId, r as ATTEMPT_HEADER, s as MAX_BACKOFF_MS, t as QueueStrategy, u as decodePayload, v as QueueError } from "./QueueStrategy-DwLPpfFM.mjs";
+import { n as toQueueError, t as __decorate } from "./decorate-C0p0FnUM.mjs";
+import { BaseDecorator, Container, Destroy, Init, Inject, InjectOptional, createDecorator } from "@vercube/di";
+import { Logger } from "@vercube/logger";
+import { BasePlugin, ValidationProvider } from "@vercube/core";
+import { SpanKind, ValueType, createInstrument } from "@vercube/telemetry/instrument";
+//#region src/Common/Instrument.ts
+/**
+* Traces and counts queue activity.
+*
+* The toolkit comes from `@vercube/telemetry/instrument`, which is the only
+* place in the framework that speaks to OpenTelemetry directly, and it creates
+* no instrument until one is actually used.
+*/
+const instrument = createInstrument("@vercube/queue");
+/** Attribute naming the transport a job travelled through. */
+const QUEUE_STRATEGY = "vercube.queue.strategy";
+/** Attribute naming the queue. */
+const QUEUE_NAME = "vercube.queue.name";
+/** Attribute naming the job. */
+const QUEUE_JOB = "vercube.queue.job";
+/** Attribute carrying the attempt number. */
+const QUEUE_ATTEMPT = "vercube.queue.attempt";
+/** Attribute carrying how an attempt ended. */
+const QUEUE_OUTCOME = "vercube.queue.outcome";
+/**
+* Writes the active trace context into a job's headers.
+*
+* This is what makes a background job part of the trace of the request that
+* queued it: without it, the consumer starts a trace of its own and the two
+* halves of the same operation can never be put back together.
+*
+* Uses the globally registered propagator, so it does nothing until an
+* application installs one.
+*
+* @param headers - Headers the job will carry
+*/
+function injectTraceContext(headers) {
+	instrument.inject(headers);
+}
+/**
+* Reads the trace context a job was published with.
+*
+* @param headers - Headers the job arrived with
+* @returns A context carrying the publishing span as parent
+*/
+function extractTraceContext(headers) {
+	return instrument.extract(headers);
+}
+/**
+* Traces publishing one or more jobs.
+*
+* @param target - Strategy, queue and job the publish is for
+* @param count - How many jobs are being published
+* @param fn - The publish
+* @returns Whatever the publish returned
+*/
+function tracePublish(target, count, fn) {
+	const published = instrument.counter("vercube.queue.published", {
+		description: "Jobs handed to a transport.",
+		unit: "{job}",
+		valueType: ValueType.INT
+	});
+	return instrument.span(`queue.publish ${target.queue}`, {
+		kind: SpanKind.PRODUCER,
+		attributes: {
+			[QUEUE_STRATEGY]: target.strategy,
+			[QUEUE_NAME]: target.queue,
+			[QUEUE_JOB]: target.job,
+			"vercube.queue.batch": count
+		}
+	}, fn).then((value) => {
+		published.add(count, {
+			[QUEUE_NAME]: target.queue,
+			[QUEUE_JOB]: target.job
+		});
+		return value;
+	});
+}
+/**
+* Traces one attempt at a job.
+*
+* The span is parented on the publishing span when the job carries trace
+* context, so the whole operation reads as one trace even though the two halves
+* ran in different processes.
+*
+* @param target - Strategy, queue, job and attempt being processed
+* @param headers - Headers the job arrived with
+* @param fn - The attempt
+* @returns Whatever the attempt returned
+*/
+function traceProcess(target, headers, fn) {
+	return instrument.spanFrom(`queue.process ${target.queue}.${target.job}`, {
+		kind: SpanKind.CONSUMER,
+		attributes: {
+			[QUEUE_STRATEGY]: target.strategy,
+			[QUEUE_NAME]: target.queue,
+			[QUEUE_JOB]: target.job,
+			[QUEUE_ATTEMPT]: target.attempt
+		}
+	}, extractTraceContext(headers), fn);
+}
+/**
+* Counts the outcome of one attempt.
+*
+* @param target - Queue and job the attempt was for
+* @param outcome - How the attempt ended
+*/
+function countOutcome(target, outcome) {
+	instrument.counter("vercube.queue.processed", {
+		description: "Job attempts by outcome.",
+		unit: "{attempt}",
+		valueType: ValueType.INT
+	}).add(1, {
+		[QUEUE_NAME]: target.queue,
+		[QUEUE_JOB]: target.job,
+		[QUEUE_OUTCOME]: outcome
+	});
+	instrument.activeSpan()?.setAttribute(QUEUE_OUTCOME, outcome);
+}
+//#endregion
+//#region src/Utils/Redact.ts
+/**
+* Words whose values are never kept in the inspection buffer. Matched against
+* the words of a key, so `keys` stays visible while `accessKeys` does not.
+*
+* Mirrors the list `@vercube/devtools` redacts config and storage with, on
+* purpose: a payload should never be readable in one panel and hidden in another.
+*/
+const SECRET_WORDS = /* @__PURE__ */ new Set([
+	"token",
+	"secret",
+	"password",
+	"passwd",
+	"pwd",
+	"credential",
+	"privatekey",
+	"apikey",
+	"accesskey",
+	"secretkey",
+	"authorization",
+	"cookie",
+	"dsn",
+	"connectionstring"
+]);
+/** What replaces the value of a key that names a credential. */
+const REDACTED = "<redacted>";
+/**
+* Splits a key into lowercase words on separators, digits and camelCase boundaries.
+*
+* @param key - The key to split.
+* @returns The words the key is built from.
+*/
+function words(key) {
+	return key.replaceAll(/([a-z\d])([A-Z])/g, "$1 $2").replaceAll(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").toLowerCase().split(/[^a-z]+/).filter(Boolean);
+}
+/**
+* @param word - A single lowercase word, or two adjacent words joined.
+* @returns Whether the word names a credential.
+*/
+function isSecretWord(word) {
+	return SECRET_WORDS.has(word) || word.endsWith("s") && SECRET_WORDS.has(word.slice(0, -1));
+}
+/**
+* Tells whether a value stored under this key should be withheld.
+*
+* @param key - The key to judge.
+* @returns True when the key names a credential.
+*/
+function isSecretKey(key) {
+	const parts = words(key);
+	return parts.some((word, index) => isSecretWord(word) || index > 0 && isSecretWord(parts[index - 1] + word));
+}
+/**
+* Copies headers with credential-looking values withheld.
+*
+* @param headers - Headers as received from the transport.
+* @returns Headers safe to keep for inspection.
+*/
+function redactHeaders(headers) {
+	const safe = {};
+	for (const [key, value] of Object.entries(headers)) safe[key] = isSecretKey(key) ? REDACTED : value;
+	return safe;
+}
+/**
+* Renders a payload for inspection: JSON, with credential-looking fields
+* withheld and the result capped.
+*
+* @param payload - The payload to render.
+* @param maxBytes - Largest preview to keep, in bytes.
+* @returns The preview, or a note when the payload cannot be rendered.
+*/
+function previewPayload(payload, maxBytes) {
+	let text;
+	try {
+		text = JSON.stringify(payload, (key, value) => key && isSecretKey(key) ? REDACTED : value, 2) ?? String(payload);
+	} catch {
+		return "<unserializable>";
+	}
+	const size = Buffer.byteLength(text, "utf8");
+	if (size <= maxBytes) return text;
+	return `${text.slice(0, maxBytes)}\n… truncated, ${size} bytes in total`;
+}
+//#endregion
+//#region src/Services/QueueManager.ts
+/** Name a strategy is mounted under when none is given. */
+const DEFAULT_STRATEGY = "default";
+/** Manager-wide settings before anything is configured. */
+const DEFAULTS = {
+	autoStart: true,
+	concurrency: 1,
+	onUnhandled: "ignore",
+	maxEvents: 50,
+	capturePayloads: false,
+	maxPayloadBytes: 4096
+};
+/**
+* Central entry point of the queue module.
+*
+* The manager owns the mounted strategies, the handlers registered by the
+* decorators and everything that has to behave the same across transports:
+* routing a job to its handler, validating payloads, retries, timeouts,
+* lifecycle hooks and the counters the devtools read.
+*
+* @example
+* ```ts
+* container.bind(QueueManager);
+*
+* const queue = container.get(QueueManager);
+* await queue.mount({ strategy: MemoryStrategy });
+*
+* await queue.add({ queue: 'emails', job: 'welcome', payload: { userId: '1' } });
+* ```
+*/
+var QueueManager = class {
+	/** Container instance */
+	gContainer;
+	/** Logger instance */
+	gLogger;
+	/** Validation provider, needed only by handlers declaring a schema */
+	gValidation;
+	/** Mounted strategies, indexed by mount name */
+	fStrategies = /* @__PURE__ */ new Map();
+	/** Registered handlers, indexed by strategy, queue and job name */
+	fRegistrations = /* @__PURE__ */ new Map();
+	/** Registered lifecycle hooks */
+	fHooks = {
+		completed: [],
+		failed: []
+	};
+	/** Running consumers, indexed by strategy and queue */
+	fConsumers = /* @__PURE__ */ new Map();
+	/** Per-queue counters, indexed by strategy and queue */
+	fMetrics = /* @__PURE__ */ new Map();
+	/** Recently processed jobs, newest first */
+	fEvents = [];
+	/** Manager-wide settings */
+	fDefaults = { ...DEFAULTS };
+	/** Whether consumers should be running */
+	fStarted = false;
+	/** Serializes start, stop and mount work so consumers are never started twice */
+	fTail = Promise.resolve();
+	/** Retries waiting for their backoff to elapse */
+	fPendingRetries = /* @__PURE__ */ new Set();
+	/** Listeners following the jobs this manager processes */
+	fListeners = /* @__PURE__ */ new Set();
+	/**
+	* Whether consumers have been started.
+	*
+	* @returns {boolean} True once {@link QueueManager.start} ran
+	*/
+	get started() {
+		return this.fStarted;
+	}
+	/**
+	* Currently configured settings.
+	*
+	* @returns {Required<QueueTypes.Defaults>} A copy of the active settings
+	*/
+	get defaults() {
+		return { ...this.fDefaults };
+	}
+	/**
+	* Sets manager-wide settings. Calling it repeatedly merges into the existing
+	* ones, and settings passed per job or per handler always win.
+	*
+	* @param {QueueTypes.Defaults} defaults - Settings to apply
+	* @returns {void}
+	*/
+	configure(defaults) {
+		for (const [key, value] of Object.entries(defaults)) if (value !== void 0) this.fDefaults[key] = value;
+	}
+	/**
+	* Mounts a strategy under a name. Every other call refers to it by that name,
+	* so a single application can talk to several brokers at once.
+	*
+	* The strategy is resolved through the container, connects on first use, and
+	* starts consuming right away when the manager is already running.
+	*
+	* @template T - Strategy being mounted
+	* @param {QueueTypes.Mount<T>} params - Mount name, strategy class and its init options
+	* @returns {Promise<void>} Resolves once the strategy is mounted
+	*/
+	async mount({ name, strategy, initOptions }) {
+		const mountName = name ?? DEFAULT_STRATEGY;
+		this.fStrategies.set(mountName, {
+			name: mountName,
+			strategy: this.gContainer.resolve(strategy),
+			initOptions
+		});
+		if (this.fStarted) await this.enqueue(() => this.startMount(mountName));
+	}
+	/**
+	* Stops and closes a mounted strategy, and forgets it.
+	* Handlers registered for it stay registered, so mounting it again resumes them.
+	*
+	* @param {string} [name] - Mount name, defaults to `default`
+	* @returns {Promise<void>} Resolves once the strategy is closed
+	*/
+	async unmount(name = DEFAULT_STRATEGY) {
+		const mount = this.fStrategies.get(name);
+		if (!mount) return;
+		this.fStrategies.delete(name);
+		await this.enqueue(async () => {
+			await this.stopConsumers(name);
+			await this.closeStrategy(mount);
+		});
+	}
+	/**
+	* Returns a mounted strategy, for the rare case a transport-specific API is needed.
+	*
+	* @param {string} [name] - Mount name, defaults to `default`
+	* @returns {QueueStrategy<unknown> | undefined} The strategy, or undefined when nothing is mounted under that name
+	*/
+	getStrategy(name = DEFAULT_STRATEGY) {
+		return this.fStrategies.get(name)?.strategy;
+	}
+	/**
+	* Adds a single job to a queue.
+	*
+	* @template TQueue - Queue the job is added to
+	* @template TJob - Name of the job
+	* @param {QueueTypes.AddRequest<TQueue, TJob>} request - Queue, job name, payload and per-job options
+	* @returns {Promise<QueueTypes.JobRef>} Reference to the published job
+	* @throws {QueueError} When no strategy is mounted under the requested name, or the job cannot be published
+	*/
+	async add(request) {
+		const mount = await this.resolveMount(request.strategy, "add");
+		const queue = request.queue;
+		const job = request.job;
+		return tracePublish({
+			strategy: mount.name,
+			queue,
+			job
+		}, 1, async () => {
+			try {
+				const ref = await mount.strategy.publish(this.createPublishRequest(queue, job, request.payload, request.options));
+				this.metricsFor(mount.name, queue).published++;
+				return ref;
+			} catch (error) {
+				throw toQueueError(error, "Failed to publish job", "add", {
+					strategy: mount.name,
+					queue,
+					job
+				});
+			}
+		});
+	}
+	/**
+	* Adds many jobs of the same kind to a queue, using the transport's batch API
+	* when it has one.
+	*
+	* @template TQueue - Queue the jobs are added to
+	* @template TJob - Name of the jobs
+	* @param {QueueTypes.AddManyRequest<TQueue, TJob>} request - Queue, job name, payloads and per-job options
+	* @returns {Promise<QueueTypes.JobRef[]>} References to the published jobs, in the same order
+	* @throws {QueueError} When no strategy is mounted under the requested name, or the jobs cannot be published
+	*/
+	async addMany(request) {
+		if (request.payloads.length === 0) return [];
+		const mount = await this.resolveMount(request.strategy, "addMany");
+		const queue = request.queue;
+		const job = request.job;
+		return tracePublish({
+			strategy: mount.name,
+			queue,
+			job
+		}, request.payloads.length, async () => {
+			try {
+				const refs = await mount.strategy.publishMany(request.payloads.map((payload) => this.createPublishRequest(queue, job, payload, request.options)));
+				this.metricsFor(mount.name, queue).published += refs.length;
+				return refs;
+			} catch (error) {
+				throw toQueueError(error, "Failed to publish jobs", "addMany", {
+					strategy: mount.name,
+					queue,
+					job
+				});
+			}
+		});
+	}
+	/**
+	* Registers a handler for a single job, or for every job the queue has no
+	* other handler for when registered under `*`. The decorators call this, and so
+	* can application code building its consumers dynamically.
+	*
+	* When the manager is already running, the queue starts being consumed right away.
+	*
+	* @param {QueueTypes.Registration} registration - Queue, job name, handler and its options
+	* @returns {void}
+	* @throws {QueueError} When a handler for the same job is already registered
+	*/
+	registerConsumer(registration) {
+		const key = this.consumerKey(registration.strategy, registration.queue, registration.job);
+		const existing = this.fRegistrations.get(key);
+		if (existing) throw new QueueError(`Job "${registration.job}" of queue "${registration.queue}" already has a handler`, "register", void 0, {
+			registered: existing.source,
+			duplicate: registration.source
+		}, false);
+		this.fRegistrations.set(key, registration);
+		this.metricsFor(registration.strategy, registration.queue);
+		if (this.fStarted) this.enqueue(() => this.startQueue(registration.strategy, registration.queue));
+	}
+	/**
+	* Registers a lifecycle hook for a queue.
+	*
+	* @param {'completed' | 'failed'} event - Event to listen for
+	* @param {QueueTypes.HookRegistration} registration - Queue, optional job filter and the hook itself
+	* @returns {void}
+	*/
+	registerHook(event, registration) {
+		this.fHooks[event].push(registration);
+	}
+	/**
+	* Removes a registered handler. The queue stops being consumed once its last
+	* handler is gone.
+	*
+	* @param {Pick<QueueTypes.Registration, 'strategy' | 'queue' | 'job'>} registration - Handler to remove
+	* @returns {void}
+	*/
+	unregisterConsumer(registration) {
+		if (!this.fRegistrations.delete(this.consumerKey(registration.strategy, registration.queue, registration.job))) return;
+		if (![...this.fRegistrations.values()].some((entry) => entry.strategy === registration.strategy && entry.queue === registration.queue)) this.enqueue(() => this.stopQueue(registration.strategy, registration.queue));
+	}
+	/**
+	* Removes a registered lifecycle hook.
+	*
+	* @param {'completed' | 'failed'} event - Event the hook listens for
+	* @param {QueueTypes.HookRegistration} registration - The very registration that was registered
+	* @returns {void}
+	*/
+	unregisterHook(event, registration) {
+		this.fHooks[event] = this.fHooks[event].filter((entry) => entry !== registration);
+	}
+	/**
+	* Connects every mounted strategy and starts consuming every queue that has
+	* a handler. Safe to call more than once, queues already running are left alone.
+	*
+	* @returns {Promise<void>} Resolves once every consumer is running
+	*/
+	async start() {
+		this.fStarted = true;
+		return this.enqueue(async () => {
+			const mounted = [...this.fStrategies.keys()];
+			for (const name of mounted) await this.startMount(name);
+		});
+	}
+	/**
+	* Stops every consumer while keeping the connections open, so the application
+	* can still publish. In-flight jobs are awaited.
+	*
+	* @returns {Promise<void>} Resolves once every consumer is stopped
+	*/
+	async stop() {
+		this.fStarted = false;
+		return this.enqueue(async () => {
+			const mounted = [...this.fStrategies.keys()];
+			for (const name of mounted) await this.stopConsumers(name);
+		});
+	}
+	/**
+	* Stops every consumer and closes every connection.
+	*
+	* @returns {Promise<void>} Resolves once everything is closed
+	*/
+	async close() {
+		this.fStarted = false;
+		return this.enqueue(async () => {
+			for (const [name, mount] of this.fStrategies) {
+				await this.stopConsumers(name);
+				await this.closeStrategy(mount);
+			}
+		});
+	}
+	/**
+	* Waits for the work the manager scheduled in the background: starting or
+	* stopping consumers, and retries waiting for their backoff to elapse.
+	*
+	* @returns {Promise<void>} Resolves once nothing is pending
+	*/
+	async drain() {
+		await this.fTail;
+		while (this.fPendingRetries.size > 0) await Promise.all(this.fPendingRetries);
+	}
+	/**
+	* Reads live counters of a queue straight from the transport.
+	*
+	* @param {object} params - Queue to read and the strategy to read it from
+	* @param {string} params.queue - Queue to read
+	* @param {string} [params.strategy] - Mount name, defaults to `default`
+	* @returns {Promise<QueueTypes.QueueStats>} The counters the transport reports, empty when it reports none
+	*/
+	async stats({ queue, strategy }) {
+		const mount = this.fStrategies.get(strategy ?? DEFAULT_STRATEGY);
+		if (!mount?.strategy.stats) return {};
+		try {
+			return await mount.strategy.stats(queue);
+		} catch (error) {
+			this.gLogger?.warn("Vercube/QueueManager::stats", error);
+			return {};
+		}
+	}
+	/**
+	* Follows every job this manager finishes, as it finishes it.
+	*
+	* The listener is called with the same event that goes into the inspection
+	* buffer, right after the job settled, so a listener sees a queue live instead
+	* of polling it. A listener that throws is reported and kept.
+	*
+	* @param {QueueTypes.JobListener} listener - Called once per processed job
+	* @returns {() => void} Removes the listener again
+	*/
+	subscribe(listener) {
+		this.fListeners.add(listener);
+		return () => {
+			this.fListeners.delete(listener);
+		};
+	}
+	/**
+	* Shows what a queue is holding, without consuming any of it.
+	*
+	* Only transports that can be read without side effects support this, which
+	* they report as the `peek` capability. Everything else returns nothing rather
+	* than perturbing the queue: taking delivery of a message to look at it would
+	* change delivery counts and compete with the running consumer.
+	*
+	* @param {object} params - Queue to look at and how much of it to read
+	* @param {string} params.queue - Queue to look at
+	* @param {string} [params.strategy] - Mount name, defaults to `default`
+	* @param {number} [params.limit] - How many messages to read, defaults to 20
+	* @param {QueueTypes.PeekState[]} [params.states] - States to read, defaults to waiting, delayed and failed
+	* @returns {Promise<QueueTypes.PeekedJob[]>} The messages found, with their payloads rendered
+	* @throws {QueueError} When the transport fails to answer
+	*/
+	async peek({ queue, strategy, limit = 20, states = [
+		"waiting",
+		"delayed",
+		"failed"
+	] }) {
+		const mount = this.fStrategies.get(strategy ?? DEFAULT_STRATEGY);
+		if (!mount?.strategy.peek) return [];
+		return (await mount.strategy.peek({
+			queue,
+			limit: Math.max(1, limit),
+			states
+		})).map(({ payload, headers, ...message }) => ({
+			...message,
+			payload: previewPayload(payload, this.fDefaults.maxPayloadBytes),
+			headers: redactHeaders(headers)
+		}));
+	}
+	/**
+	* Describes what the module currently holds: mounted strategies, registered
+	* handlers, per-queue counters and the last processed jobs. Used by the devtools.
+	*
+	* @returns {QueueTypes.Snapshot} The current state of the queue module
+	*/
+	inspect() {
+		const strategies = [...this.fStrategies.values()].map((mount) => ({
+			name: mount.name,
+			transport: mount.strategy.transport,
+			driver: mount.strategy.constructor?.name ?? "unknown",
+			status: this.statusOf(mount),
+			capabilities: mount.strategy.capabilities,
+			error: mount.error?.message
+		}));
+		const consumers = [...this.fRegistrations.values()].map((registration) => ({
+			strategy: registration.strategy,
+			queue: registration.queue,
+			job: registration.job,
+			source: registration.source,
+			attempts: registration.options.attempts ?? 1,
+			timeout: registration.options.timeout,
+			validated: Boolean(registration.options.schema),
+			running: this.fConsumers.has(this.queueKey(registration.strategy, registration.queue))
+		}));
+		return {
+			started: this.fStarted,
+			strategies,
+			consumers,
+			metrics: [...this.fMetrics.values()].map((metrics) => ({ ...metrics })),
+			events: this.fEvents.map((event) => ({ ...event }))
+		};
+	}
+	/**
+	* Processes a single job: routes it to its handler, validates the payload,
+	* enforces the timeout, runs the lifecycle hooks and applies the retry policy.
+	*
+	* The handler registered for the job name wins, and a handler registered under
+	* `*` picks up whatever is left.
+	*
+	* Rejecting tells the strategy the job failed for good, so it can dead-letter it.
+	*
+	* @param {string} strategy - Mount name the job came from
+	* @param {string} queue - Queue the job came from
+	* @param {QueueTypes.IncomingJob} incoming - The job as received from the transport
+	* @returns {Promise<void>} Resolves when the job may be acknowledged
+	* @throws {Error} When the job failed and the transport has to deal with it
+	*/
+	process(strategy, queue, incoming) {
+		return traceProcess({
+			strategy,
+			queue,
+			job: incoming.job,
+			attempt: incoming.attempt
+		}, incoming.headers, () => this.processJob(strategy, queue, incoming));
+	}
+	/**
+	* Does the work {@link QueueManager.process} traces.
+	*
+	* @param {string} strategy - Mount name the job came from
+	* @param {string} queue - Queue the job came from
+	* @param {QueueTypes.IncomingJob} incoming - The job as received from the transport
+	* @returns {Promise<void>} Resolves when the job may be acknowledged
+	* @throws {Error} When the job failed and the transport has to deal with it
+	*/
+	async processJob(strategy, queue, incoming) {
+		const metrics = this.metricsFor(strategy, queue);
+		const registration = this.fRegistrations.get(this.consumerKey(strategy, queue, incoming.job)) ?? this.fRegistrations.get(this.consumerKey(strategy, queue, "*"));
+		if (!registration) {
+			metrics.unhandled++;
+			this.record({
+				strategy,
+				queue,
+				job: incoming.job,
+				id: incoming.id,
+				attempt: incoming.attempt,
+				status: "unhandled",
+				duration: 0,
+				error: {
+					name: "QueueError",
+					message: `No handler is registered for job "${incoming.job}"`,
+					operation: "process",
+					retryable: false
+				}
+			}, incoming.payload, incoming.headers);
+			this.gLogger?.warn(`Vercube/QueueManager::No handler for job "${incoming.job}" on queue "${queue}"`);
+			countOutcome({
+				queue,
+				job: incoming.job
+			}, "unhandled");
+			if (this.fDefaults.onUnhandled === "fail") throw new QueueError(`No handler registered for job "${incoming.job}"`, "process", void 0, {
+				strategy,
+				queue
+			}, false);
+			return;
+		}
+		const attempts = Math.min(incoming.attempts ?? readNumericHeader(incoming.headers["x-attempts"], registration.options.attempts ?? 1, 50), 50);
+		const context = this.createContext(strategy, queue, incoming, attempts);
+		const started = performance.now();
+		metrics.active++;
+		try {
+			context.payload = await this.validate(registration, incoming.payload, context.job);
+			await this.runHandler(registration, context);
+			metrics.processed++;
+			countOutcome({
+				queue,
+				job: context.job
+			}, "completed");
+			this.record({
+				strategy,
+				queue,
+				job: context.job,
+				id: context.id,
+				attempt: context.attempt,
+				status: "completed",
+				duration: performance.now() - started,
+				source: registration.source
+			});
+			await this.runHooks("completed", registration, context);
+		} catch (error) {
+			await this.handleFailure(error, registration, context, performance.now() - started);
+		} finally {
+			metrics.active--;
+		}
+	}
+	/**
+	* Applies the failure policy of a job: hooks first, then either a retry the
+	* manager schedules itself, or a rejection handing the job back to the transport.
+	*
+	* @param {Error} error - Error the attempt failed with
+	* @param {QueueTypes.Registration} registration - Handler that failed
+	* @param {QueueTypes.JobContext} context - Context of the failed attempt
+	* @param {number} duration - How long the attempt took, in milliseconds
+	* @returns {Promise<void>} Resolves once a retry has been scheduled
+	* @throws {Error} The original error, when the transport has to deal with the failure
+	*/
+	async handleFailure(error, registration, context, duration) {
+		const metrics = this.metricsFor(registration.strategy, registration.queue);
+		metrics.failed++;
+		metrics.lastError = error.message;
+		await this.runHooks("failed", registration, context, error);
+		const mount = this.fStrategies.get(registration.strategy);
+		const canRetry = (!(error instanceof QueueError) || error.retryable) && context.attempt < context.attempts;
+		if (mount?.strategy.capabilities.retries || !canRetry) {
+			countOutcome({
+				queue: registration.queue,
+				job: context.job
+			}, "failed");
+			this.record({
+				strategy: registration.strategy,
+				queue: registration.queue,
+				job: context.job,
+				id: context.id,
+				attempt: context.attempt,
+				status: "failed",
+				duration,
+				error: this.describeFailure(error),
+				source: registration.source
+			}, context.payload, context.headers);
+			throw error;
+		}
+		metrics.retried++;
+		countOutcome({
+			queue: registration.queue,
+			job: context.job
+		}, "retried");
+		this.record({
+			strategy: registration.strategy,
+			queue: registration.queue,
+			job: context.job,
+			id: context.id,
+			attempt: context.attempt,
+			status: "retried",
+			duration,
+			error: this.describeFailure(error),
+			source: registration.source
+		}, context.payload, context.headers);
+		await this.scheduleRetry(registration, context, error);
+	}
+	/**
+	* Publishes the job again for its next attempt, waiting for the backoff first.
+	*
+	* The wait is handed to the transport when it can delay jobs, and kept on a
+	* timer otherwise, so the handler slot is released immediately either way.
+	*
+	* @param {QueueTypes.Registration} registration - Handler that failed
+	* @param {QueueTypes.JobContext} context - Context of the failed attempt
+	* @param {Error} error - Error the attempt failed with, reported when the retry cannot be published
+	* @returns {Promise<void>} Resolves once the retry exists, or once it has been scheduled on a timer
+	* @throws {Error} When the retry could be published right away and the transport refused it
+	*/
+	scheduleRetry(registration, context, error) {
+		const wait = resolveBackoff(registration.options.backoff, context.attempt);
+		const native = this.fStrategies.get(registration.strategy)?.strategy.capabilities.delay ?? false;
+		const headers = {
+			...context.headers,
+			[ATTEMPT_HEADER]: String(context.attempt + 1),
+			[ATTEMPTS_HEADER]: String(context.attempts)
+		};
+		const priority = readNumericHeader(headers[PRIORITY_HEADER], 0);
+		const options = {
+			...native ? { delay: wait } : {},
+			...headers["x-key"] === void 0 ? {} : { key: headers[KEY_HEADER] },
+			...priority === 0 ? {} : { priority }
+		};
+		const publish = () => {
+			const mount = this.fStrategies.get(registration.strategy);
+			return mount ? mount.strategy.publish({
+				queue: registration.queue,
+				job: context.job,
+				payload: context.payload,
+				headers,
+				options
+			}) : Promise.reject(new QueueError(`Strategy "${registration.strategy}" is no longer mounted`, "publish", void 0, {
+				queue: registration.queue,
+				job: context.job
+			}, false));
+		};
+		if (native || wait === 0) return Promise.resolve(publish()).then(() => void 0);
+		const pending = delay(wait).then(publish).then(() => void 0, (publishError) => {
+			this.gLogger?.error("Vercube/QueueManager::Failed to schedule retry", publishError, error);
+			this.record({
+				strategy: registration.strategy,
+				queue: registration.queue,
+				job: context.job,
+				id: context.id,
+				attempt: context.attempt,
+				status: "failed",
+				duration: 0,
+				error: this.describeFailure(publishError),
+				source: registration.source
+			}, context.payload, context.headers);
+			countOutcome({
+				queue: registration.queue,
+				job: context.job
+			}, "lost");
+		});
+		this.fPendingRetries.add(pending);
+		pending.finally(() => this.fPendingRetries.delete(pending));
+		return Promise.resolve();
+	}
+	/**
+	* Runs a handler, failing the attempt when it outlives its timeout.
+	* A timed out handler is not interrupted, it is only stopped being waited for.
+	*
+	* @param {QueueTypes.Registration} registration - Handler to run
+	* @param {QueueTypes.JobContext} context - Context of the attempt
+	* @returns {Promise<void>} Resolves once the handler returned
+	* @throws {QueueError} When the handler outlives its timeout
+	*/
+	async runHandler(registration, context) {
+		const run = Promise.resolve(registration.handler(context.payload, context));
+		const timeout = registration.options.timeout;
+		if (!timeout || timeout <= 0) return run;
+		let timer;
+		run.catch(() => void 0);
+		try {
+			await Promise.race([run, new Promise((_, reject) => {
+				timer = setTimeout(() => {
+					reject(new QueueError(`Job "${registration.job}" timed out after ${timeout}ms`, "timeout", void 0, {
+						queue: registration.queue,
+						id: context.id
+					}));
+				}, timeout);
+			})]);
+		} finally {
+			clearTimeout(timer);
+		}
+	}
+	/**
+	* Validates a payload against the handler's schema, when it declares one.
+	*
+	* @param {QueueTypes.Registration} registration - Handler the payload is meant for
+	* @param {unknown} payload - Payload as received from the transport
+	* @param {string} job - Name of the job being processed, which a wildcard handler does not know upfront
+	* @returns {Promise<unknown>} The validated payload, as returned by the schema
+	* @throws {QueueError} When the payload does not match the schema, or no validation provider is bound
+	*/
+	async validate(registration, payload, job) {
+		const schema = registration.options.schema;
+		if (!schema) return payload;
+		if (!this.gValidation) throw new QueueError("A job declares a schema but no ValidationProvider is bound in the container", "validate", void 0, {
+			queue: registration.queue,
+			job
+		}, false);
+		const result = await this.gValidation.validate(schema, payload);
+		if (result.issues) throw new QueueError(`Payload of job "${job}" failed validation`, "validate", void 0, {
+			queue: registration.queue,
+			issues: result.issues
+		}, false);
+		return result.value;
+	}
+	/**
+	* Runs the hooks registered for a queue. A hook filtered by job name runs for
+	* that job only, unless the filter is `*`. A throwing hook is logged and never
+	* changes the outcome of the job.
+	*
+	* @param {'completed' | 'failed'} event - Event being reported
+	* @param {QueueTypes.Registration} registration - Handler the event belongs to
+	* @param {QueueTypes.JobContext} context - Context of the attempt
+	* @param {Error} [error] - Error of the attempt, for the `failed` event
+	* @returns {Promise<void>} Resolves once every hook settled
+	*/
+	async runHooks(event, registration, context, error) {
+		for (const hook of this.fHooks[event]) {
+			if (hook.strategy !== registration.strategy || hook.queue !== registration.queue) continue;
+			if (hook.job && hook.job !== "*" && hook.job !== context.job) continue;
+			try {
+				await (event === "failed" ? hook.hook(error, context) : hook.hook(context));
+			} catch (hookError) {
+				this.gLogger?.error(`Vercube/QueueManager::Hook ${hook.source} threw`, hookError);
+			}
+		}
+	}
+	/**
+	* Connects a mounted strategy and starts consuming every queue it has handlers for.
+	* Failures are logged and leave the other mounts untouched.
+	*
+	* @param {string} name - Mount name
+	* @returns {Promise<void>} Resolves once the mount is running
+	*/
+	async startMount(name) {
+		const mount = this.fStrategies.get(name);
+		if (!mount) return;
+		try {
+			await this.ensureReady(mount);
+		} catch {
+			return;
+		}
+		const queues = new Set([...this.fRegistrations.values()].filter((entry) => entry.strategy === name).map((entry) => entry.queue));
+		for (const queue of queues) await this.startQueue(name, queue);
+	}
+	/**
+	* Starts consuming a single queue, unless it is already being consumed.
+	*
+	* @param {string} strategy - Mount name
+	* @param {string} queue - Queue to consume
+	* @returns {Promise<void>} Resolves once the consumer is running
+	*/
+	async startQueue(strategy, queue) {
+		const key = this.queueKey(strategy, queue);
+		const mount = this.fStrategies.get(strategy);
+		if (!mount || !this.fStarted) return;
+		const registrations = [...this.fRegistrations.values()].filter((entry) => entry.strategy === strategy && entry.queue === queue);
+		if (registrations.length === 0) return;
+		const concurrency = Math.max(this.fDefaults.concurrency, ...registrations.map((entry) => entry.concurrency ?? 0));
+		const running = this.fConsumers.get(key);
+		if (running) {
+			if (running.concurrency >= concurrency) return;
+			await this.stopQueue(strategy, queue);
+		}
+		try {
+			await this.consumeQueue(mount, queue, concurrency);
+		} catch (error) {
+			this.gLogger?.error(`Vercube/QueueManager::Failed to consume queue "${queue}"`, error);
+			if (!running) return;
+			try {
+				await this.consumeQueue(mount, queue, running.concurrency);
+			} catch (restoreError) {
+				this.gLogger?.error(`Vercube/QueueManager::Failed to restore the consumer of "${queue}"`, restoreError);
+			}
+		}
+	}
+	/**
+	* Starts consuming a queue at a given concurrency and records the handle.
+	*
+	* @param {QueueTypes.MountedStrategy} mount - Mount the queue lives on
+	* @param {string} queue - Queue to consume
+	* @param {number} concurrency - How many jobs the transport may hand over at once
+	* @returns {Promise<void>} Resolves once the transport is delivering
+	* @throws {Error} When the strategy cannot start consuming
+	*/
+	async consumeQueue(mount, queue, concurrency) {
+		await this.ensureReady(mount);
+		const handle = await mount.strategy.consume({
+			queue,
+			concurrency,
+			dispatch: (job) => this.process(mount.name, queue, job)
+		});
+		this.fConsumers.set(this.queueKey(mount.name, queue), {
+			handle,
+			concurrency
+		});
+	}
+	/**
+	* Stops every consumer of a mount.
+	*
+	* @param {string} strategy - Mount name
+	* @returns {Promise<void>} Resolves once every consumer is stopped
+	*/
+	async stopConsumers(strategy) {
+		const running = [...this.fConsumers];
+		for (const [key, consumer] of running) if (key === this.queueKey(strategy, consumer.handle.queue)) await this.stopQueue(strategy, consumer.handle.queue);
+	}
+	/**
+	* Stops the consumer of a single queue, waiting for its in-flight jobs.
+	*
+	* @param {string} strategy - Mount name
+	* @param {string} queue - Queue whose consumer is stopped
+	* @returns {Promise<void>} Resolves once the consumer is stopped
+	*/
+	async stopQueue(strategy, queue) {
+		const key = this.queueKey(strategy, queue);
+		const consumer = this.fConsumers.get(key);
+		if (!consumer) return;
+		try {
+			await consumer.handle.stop();
+		} catch (error) {
+			this.gLogger?.error(`Vercube/QueueManager::Failed to stop consumer of "${queue}"`, error);
+		}
+		this.fConsumers.delete(key);
+	}
+	/**
+	* Closes a strategy, keeping a failure from breaking a shutdown sequence.
+	*
+	* @param {QueueTypes.MountedStrategy} mount - Mount to close
+	* @returns {Promise<void>} Resolves once the strategy is closed
+	*/
+	async closeStrategy(mount) {
+		if (!mount.ready) return;
+		try {
+			await mount.strategy.close();
+		} catch (error) {
+			this.gLogger?.error(`Vercube/QueueManager::Failed to close strategy "${mount.name}"`, error);
+		}
+		mount.ready = void 0;
+	}
+	/**
+	* Initializes a strategy once, reusing the same promise for every later call.
+	*
+	* @param {QueueTypes.MountedStrategy} mount - Mount to initialize
+	* @returns {Promise<void>} Resolves once the strategy is ready
+	* @throws {QueueError} When the strategy cannot be initialized
+	*/
+	async ensureReady(mount) {
+		mount.ready ??= (async () => mount.strategy.initialize(mount.initOptions))().then(() => {
+			mount.error = void 0;
+		}, (error) => {
+			mount.ready = void 0;
+			mount.error = error;
+			this.gLogger?.error(`Vercube/QueueManager::Failed to initialize strategy "${mount.name}"`, error);
+			throw toQueueError(error, `Failed to initialize strategy "${mount.name}"`, "initialize", { strategy: mount.name });
+		});
+		return mount.ready;
+	}
+	/**
+	* Resolves a mount by name and makes sure it is connected.
+	*
+	* @param {string} [name] - Mount name, defaults to `default`
+	* @param {string} operation - Operation asking for the mount, reported in the error
+	* @returns {Promise<QueueTypes.MountedStrategy>} The ready mount
+	* @throws {QueueError} When nothing is mounted under that name, or it cannot connect
+	*/
+	async resolveMount(name, operation) {
+		const mountName = name ?? DEFAULT_STRATEGY;
+		const mount = this.fStrategies.get(mountName);
+		if (!mount) throw new QueueError(`No queue strategy is mounted as "${mountName}"`, operation, void 0, { mounted: [...this.fStrategies.keys()] });
+		await this.ensureReady(mount);
+		return mount;
+	}
+	/**
+	* Builds the transport-facing shape of a job, adding the headers the module
+	* needs to route and retry it.
+	*
+	* @param {string} queue - Queue the job goes to
+	* @param {string} job - Name of the job
+	* @param {unknown} payload - Payload of the job
+	* @param {QueueTypes.JobOptions} [options] - Per-job options
+	* @returns {QueueTypes.PublishRequest} The job as a strategy expects it
+	*/
+	createPublishRequest(queue, job, payload, options = {}) {
+		const headers = {
+			...options.headers,
+			[JOB_HEADER]: job,
+			[ATTEMPT_HEADER]: "1"
+		};
+		if (options.attempts && options.attempts > 1) headers[ATTEMPTS_HEADER] = String(options.attempts);
+		if (options.key !== void 0) headers[KEY_HEADER] = options.key;
+		if (options.priority !== void 0) headers[PRIORITY_HEADER] = String(options.priority);
+		injectTraceContext(headers);
+		return {
+			queue,
+			job,
+			payload,
+			headers,
+			options
+		};
+	}
+	/**
+	* Builds the context a handler and its hooks receive.
+	*
+	* @param {string} strategy - Mount name the job came from
+	* @param {string} queue - Queue the job came from
+	* @param {QueueTypes.IncomingJob} incoming - The job as received from the transport
+	* @param {number} attempts - Total attempts this job may take
+	* @returns {QueueTypes.JobContext} The context of this attempt
+	*/
+	createContext(strategy, queue, incoming, attempts) {
+		const logger = this.gLogger;
+		return {
+			id: incoming.id,
+			job: incoming.job,
+			queue,
+			strategy,
+			attempt: incoming.attempt,
+			attempts,
+			payload: incoming.payload,
+			headers: incoming.headers,
+			raw: incoming.raw,
+			logger: typeof logger?.child === "function" ? logger.child({
+				queue,
+				job: incoming.job,
+				jobId: incoming.id,
+				attempt: incoming.attempt
+			}) : logger,
+			updateProgress: async (progress) => {
+				await incoming.updateProgress?.(progress);
+			}
+		};
+	}
+	/**
+	* Returns the counters of a queue, creating them on first use.
+	*
+	* @param {string} strategy - Mount name
+	* @param {string} queue - Queue name
+	* @returns {QueueTypes.QueueMetrics} The mutable counters of that queue
+	*/
+	metricsFor(strategy, queue) {
+		const key = this.queueKey(strategy, queue);
+		let metrics = this.fMetrics.get(key);
+		if (!metrics) {
+			metrics = {
+				strategy,
+				queue,
+				published: 0,
+				processed: 0,
+				failed: 0,
+				retried: 0,
+				unhandled: 0,
+				active: 0
+			};
+			this.fMetrics.set(key, metrics);
+		}
+		return metrics;
+	}
+	/**
+	* Appends a processed job to the inspection buffer, dropping the oldest entry
+	* once the buffer is full.
+	*
+	* The payload and headers of a failure are kept only while `capturePayloads`
+	* is on, and never for a job that completed: that is where the volume is, and
+	* a job that worked has nothing to diagnose.
+	*
+	* @param {Omit<QueueTypes.JobEvent, 'at'>} event - The processed job
+	* @param {unknown} [payload] - Payload of the attempt, kept when capturing is on
+	* @param {Record<string, string>} [headers] - Headers of the attempt, kept when capturing is on
+	* @returns {void}
+	*/
+	record(event, payload, headers) {
+		const captured = this.fDefaults.capturePayloads && event.status !== "completed" ? {
+			payload: previewPayload(payload, this.fDefaults.maxPayloadBytes),
+			headers: headers ? redactHeaders(headers) : void 0
+		} : {};
+		const recorded = {
+			...event,
+			...captured,
+			at: Date.now()
+		};
+		for (const listener of this.fListeners) try {
+			listener(recorded);
+		} catch (error) {
+			this.gLogger?.error("Vercube/QueueManager::Job listener threw", error);
+		}
+		if (this.fDefaults.maxEvents <= 0) return;
+		this.fEvents.unshift(recorded);
+		if (this.fEvents.length > this.fDefaults.maxEvents) this.fEvents.length = this.fDefaults.maxEvents;
+	}
+	/**
+	* Describes an error for the inspection buffer: its name, message and a capped
+	* stack, plus what this module knows about it when it raised the error itself.
+	*
+	* @param {Error} error - Error the attempt failed with
+	* @returns {QueueTypes.JobFailure} The failure, ready to be inspected
+	*/
+	describeFailure(error) {
+		const failure = {
+			name: error.name || "Error",
+			message: error.message,
+			stack: error.stack?.slice(0, this.fDefaults.maxPayloadBytes)
+		};
+		if (error instanceof QueueError) {
+			failure.operation = error.operation;
+			failure.retryable = error.retryable;
+		}
+		return failure;
+	}
+	/**
+	* Reports the state of a mount for the devtools.
+	*
+	* @param {QueueTypes.MountedStrategy} mount - Mount to describe
+	* @returns {QueueTypes.StrategyStatus} What the mount is currently doing
+	*/
+	statusOf(mount) {
+		if (mount.error) return "error";
+		return mount.ready ? "ready" : "idle";
+	}
+	/**
+	* Runs a piece of lifecycle work after everything scheduled before it, so
+	* consumers are never started or stopped concurrently.
+	*
+	* @param {() => Promise<void>} task - Work to run
+	* @returns {Promise<void>} Resolves once this task ran
+	*/
+	enqueue(task) {
+		const tail = this.fTail.then(task, task);
+		this.fTail = tail.catch(() => void 0);
+		return tail;
+	}
+	/**
+	* Key a handler is registered under.
+	*
+	* @param {string} strategy - Mount name
+	* @param {string} queue - Queue name
+	* @param {string} job - Job name
+	* @returns {string} The registration key
+	*/
+	consumerKey(strategy, queue, job) {
+		return `${strategy}::${queue}::${job}`;
+	}
+	/**
+	* Key a queue is tracked under.
+	*
+	* @param {string} strategy - Mount name
+	* @param {string} queue - Queue name
+	* @returns {string} The queue key
+	*/
+	queueKey(strategy, queue) {
+		return `${strategy}::${queue}`;
+	}
+	/**
+	* Starts the consumers once the container is initialized, so every handler
+	* registered by a decorator is known before the first job is received.
+	*
+	* @returns {void}
+	*/
+	init() {
+		queueMicrotask(() => {
+			if (!this.fDefaults.autoStart) return;
+			this.start().catch((error) => this.gLogger?.error("Vercube/QueueManager::Failed to start", error));
+		});
+	}
+	/**
+	* Closes every connection when the container is torn down.
+	*
+	* @returns {void}
+	*/
+	destroy() {
+		this.close().catch((error) => this.gLogger?.error("Vercube/QueueManager::Failed to close", error));
+	}
+};
+__decorate([Inject(Container)], QueueManager.prototype, "gContainer", void 0);
+__decorate([InjectOptional(Logger)], QueueManager.prototype, "gLogger", void 0);
+__decorate([InjectOptional(ValidationProvider)], QueueManager.prototype, "gValidation", void 0);
+__decorate([Init()], QueueManager.prototype, "init", null);
+__decorate([Destroy()], QueueManager.prototype, "destroy", null);
+//#endregion
+//#region src/Utils/Metadata.ts
+/**
+* Consumer options per decorated prototype.
+*
+* A weak map keeps the options off the class itself, so nothing leaks into the
+* instances the container hands out and subclasses inherit them naturally.
+*/
+const consumers = /* @__PURE__ */ new WeakMap();
+/**
+* Stores the options a `@Consumer()` class was declared with.
+*
+* @param prototype - Prototype of the decorated class.
+* @param options - Options the class was declared with.
+* @returns Nothing.
+*/
+function setConsumerOptions(prototype, options) {
+	consumers.set(prototype, options);
+}
+/**
+* Reads the options of the closest `@Consumer()` class in the prototype chain,
+* so a handler declared on a base class still finds its queue.
+*
+* @param prototype - Prototype to start looking at.
+* @returns The options, or undefined when no class in the chain is a consumer.
+*/
+function getConsumerOptions(prototype) {
+	let current = prototype;
+	while (current) {
+		const options = consumers.get(current);
+		if (options) return options;
+		current = Object.getPrototypeOf(current);
+	}
+}
+//#endregion
+//#region src/Decorators/Job.ts
+/**
+* Registers the decorated method as the handler of a single job.
+* Runs when the container instantiates the consumer class.
+*/
+var JobDecorator = class extends BaseDecorator {
+	/** Queue manager the handler is registered with */
+	gQueueManager;
+	/** Logger instance */
+	gLogger;
+	/** The registration handed to the manager, kept so it can be removed again */
+	fRegistration = null;
+	/**
+	* Registers the handler with the queue manager.
+	*
+	* @returns {void}
+	*/
+	created() {
+		if (!this.gQueueManager) {
+			this.warn("QueueManager is not bound in the container, no job will be consumed");
+			return;
+		}
+		const consumer = getConsumerOptions(this.prototype);
+		if (!consumer) {
+			this.warn(`Unable to find the queue of "${this.propertyName}". Did you use @Consumer()?`);
+			return;
+		}
+		const handler = this.instance[this.propertyName];
+		if (typeof handler !== "function") {
+			this.warn(`"${this.propertyName}" is not a method, @Job() can only decorate methods`);
+			return;
+		}
+		this.fRegistration = {
+			strategy: consumer.strategy ?? "default",
+			queue: consumer.queue,
+			job: this.options.name,
+			handler: handler.bind(this.instance),
+			concurrency: consumer.concurrency,
+			options: {
+				attempts: this.options.options.attempts ?? consumer.attempts,
+				backoff: this.options.options.backoff ?? consumer.backoff,
+				timeout: this.options.options.timeout ?? consumer.timeout,
+				schema: this.options.options.schema ?? consumer.schema
+			},
+			source: `${this.instance?.constructor?.name ?? "anonymous"}.${this.propertyName}`
+		};
+		this.gQueueManager.registerConsumer(this.fRegistration);
+	}
+	/**
+	* Removes the handler again, so rebinding the consumer class does not collide
+	* with the handler its previous instance registered.
+	*
+	* @returns {void}
+	*/
+	destroyed() {
+		if (!this.fRegistration) return;
+		this.gQueueManager?.unregisterConsumer(this.fRegistration);
+		this.fRegistration = null;
+	}
+	/**
+	* Reports a consumer that cannot be wired up.
+	*
+	* @param {string} message - What is wrong
+	* @returns {void}
+	*/
+	warn(message) {
+		const text = `Vercube/Queue::@Job() - ${message}`;
+		if (this.gLogger) {
+			this.gLogger.warn(text);
+			return;
+		}
+		console.warn(text);
+	}
+};
+__decorate([InjectOptional(QueueManager)], JobDecorator.prototype, "gQueueManager", void 0);
+__decorate([InjectOptional(Logger)], JobDecorator.prototype, "gLogger", void 0);
+/**
+* Declares the decorated method as the handler of a job.
+*
+* The method receives the job payload as its first argument and a
+* {@link QueueTypes.JobContext} as its second. Returning marks the job as done,
+* throwing marks the attempt as failed and hands it to the retry policy.
+*
+* Options given here override the defaults of the `@Consumer()` class. To handle
+* everything the queue carries beyond the named jobs, see `@AnyJob()`.
+*
+* @param {string} name - Name of the job, as used when adding it to the queue
+* @param {QueueTypes.HandlerOptions} [options] - Retries, timeout and payload schema of this handler
+* @returns {Function} The method decorator
+*
+* @example
+* ```ts
+* @Consumer({ queue: 'emails' })
+* export class EmailConsumer {
+*   @Job('welcome')
+*   public async welcome(payload: { userId: string }): Promise<void> {
+*     await this.mailer.sendWelcome(payload.userId);
+*   }
+* }
+* ```
+*
+* @example
+* ```ts
+* // three attempts with a growing delay, a validated payload and a hard time limit
+* @Job('digest', {
+*   attempts: 3,
+*   backoff: { type: 'exponential', delay: 1000 },
+*   timeout: 30_000,
+*   schema: DigestSchema,
+* })
+* public async digest(payload: Digest, context: QueueTypes.JobContext<Digest>): Promise<void> {
+*   context.logger?.info(`attempt ${context.attempt} of ${context.attempts}`);
+*   await context.updateProgress(50);
+* }
+* ```
+*/
+function Job(name, options = {}) {
+	return createDecorator(JobDecorator, {
+		name,
+		options
+	});
+}
+//#endregion
+//#region src/Decorators/AnyJob.ts
+/**
+* Declares the decorated method as the handler of every job of the queue that no
+* `@Job()` claims.
+*
+* A handler registered for a job name always wins, so `@AnyJob()` is the fallback
+* rather than a replacement. It is what makes a queue somebody else fills
+* consumable: messages produced outside this module carry no job name, and would
+* otherwise be reported as unhandled.
+*
+* The real job name is on the context, so the handler can still branch on it.
+* Only one `@AnyJob()` per queue is allowed, like any other handler.
+*
+* @param {QueueTypes.HandlerOptions} [options] - Retries, timeout and payload schema of this handler
+* @returns {Function} The method decorator
+*
+* @example
+* ```ts
+* // a queue filled by another application, whose messages carry no job name
+* @Consumer({ queue: 'legacy-events' })
+* export class LegacyConsumer {
+*   @AnyJob({ attempts: 3 })
+*   public async handle(payload: unknown, context: QueueTypes.JobContext): Promise<void> {
+*     await this.gEvents.ingest(payload, context.job);
+*   }
+* }
+* ```
+*
+* @example
+* ```ts
+* // known jobs handled on their own, everything else swept up
+* @Consumer({ queue: 'emails' })
+* export class EmailConsumer {
+*   @Job('welcome')
+*   public async welcome(payload: Welcome): Promise<void> {}
+*
+*   @AnyJob()
+*   public async rest(payload: unknown, context: QueueTypes.JobContext): Promise<void> {
+*     context.logger?.warn(`unrecognised job ${context.job}`);
+*   }
+* }
+* ```
+*/
+function AnyJob(options = {}) {
+	return createDecorator(JobDecorator, {
+		name: "*",
+		options
+	});
+}
+//#endregion
+//#region src/Decorators/Consumer.ts
+/**
+* Declares a class as the consumer of a queue.
+*
+* The class itself does nothing until it is bound in the container: that is when
+* its `@Job()` methods register themselves and the queue starts being consumed.
+* Options declared here become the defaults of every handler in the class.
+*
+* @param {QueueTypes.ConsumerOptions} options - Queue to consume, its concurrency and the handler defaults
+* @returns {Function} The class decorator
+*
+* @example
+* ```ts
+* @Consumer({ queue: 'emails', concurrency: 5 })
+* export class EmailConsumer {
+*   @Job('welcome')
+*   public async welcome(payload: { userId: string }): Promise<void> {
+*     await this.mailer.sendWelcome(payload.userId);
+*   }
+* }
+*
+* // in the container setup
+* container.bind(EmailConsumer);
+* ```
+*
+* @example
+* ```ts
+* // defaults for every handler of the class, overridable per job
+* @Consumer({ queue: 'reports', strategy: 'kafka', attempts: 3, timeout: 30_000 })
+* export class ReportConsumer {}
+* ```
+*/
+function Consumer(options) {
+	return function internalDecorator(target) {
+		setConsumerOptions(target.prototype, options);
+	};
+}
+//#endregion
+//#region src/Decorators/JobHookDecorator.ts
+/**
+* Registers the decorated method as a lifecycle hook of the queue its
+* `@Consumer()` class reads from. Shared by `@OnJobCompleted()` and `@OnJobFailed()`.
+*/
+var JobHookDecorator = class extends BaseDecorator {
+	/** Queue manager the hook is registered with */
+	gQueueManager;
+	/** Logger instance */
+	gLogger;
+	/** The registration handed to the manager, kept so it can be removed again */
+	fRegistration = null;
+	/**
+	* Registers the hook with the queue manager.
+	*
+	* @returns {void}
+	*/
+	created() {
+		const consumer = getConsumerOptions(this.prototype);
+		const hook = this.instance[this.propertyName];
+		if (!this.gQueueManager) {
+			this.warn("QueueManager is not bound in the container, no job hook will run");
+			return;
+		}
+		if (!consumer) {
+			this.warn(`Unable to find the queue of "${this.propertyName}". Did you use @Consumer()?`);
+			return;
+		}
+		if (typeof hook !== "function") {
+			this.warn(`"${this.propertyName}" is not a method, a job hook can only decorate methods`);
+			return;
+		}
+		this.fRegistration = {
+			strategy: consumer.strategy ?? "default",
+			queue: consumer.queue,
+			job: this.options.job,
+			hook: hook.bind(this.instance),
+			source: `${this.instance?.constructor?.name ?? "anonymous"}.${this.propertyName}`
+		};
+		this.gQueueManager.registerHook(this.options.event, this.fRegistration);
+	}
+	/**
+	* Removes the hook again when the container is torn down.
+	*
+	* @returns {void}
+	*/
+	destroyed() {
+		if (!this.fRegistration) return;
+		this.gQueueManager?.unregisterHook(this.options.event, this.fRegistration);
+		this.fRegistration = null;
+	}
+	/**
+	* Reports a hook that cannot be wired up.
+	*
+	* @param {string} message - What is wrong
+	* @returns {void}
+	*/
+	warn(message) {
+		const text = `Vercube/Queue::Job hook - ${message}`;
+		if (this.gLogger) {
+			this.gLogger.warn(text);
+			return;
+		}
+		console.warn(text);
+	}
+};
+__decorate([InjectOptional(QueueManager)], JobHookDecorator.prototype, "gQueueManager", void 0);
+__decorate([InjectOptional(Logger)], JobHookDecorator.prototype, "gLogger", void 0);
+//#endregion
+//#region src/Decorators/OnJobCompleted.ts
+/**
+* Runs the decorated method after a job of the consumer's queue completed.
+*
+* The hook receives the {@link QueueTypes.JobContext} of the finished job. It
+* never changes the outcome of that job: a throwing hook is logged and forgotten.
+*
+* @param {object} [options] - Narrows the hook down to a single job
+* @param {string} [options.job] - Name of the only job to listen for, every job of the queue by default
+* @returns {Function} The method decorator
+*
+* @example
+* ```ts
+* @Consumer({ queue: 'emails' })
+* export class EmailConsumer {
+*   @Job('welcome')
+*   public async welcome(payload: { userId: string }): Promise<void> {}
+*
+*   @OnJobCompleted()
+*   public async sent(context: QueueTypes.JobContext): Promise<void> {
+*     this.metrics.increment(`emails.${context.job}.sent`);
+*   }
+* }
+* ```
+*/
+function OnJobCompleted(options = {}) {
+	const hook = {
+		event: "completed",
+		job: options.job
+	};
+	return createDecorator(JobHookDecorator, hook);
+}
+//#endregion
+//#region src/Decorators/OnJobFailed.ts
+/**
+* Runs the decorated method after an attempt of a job of the consumer's queue threw.
+*
+* The hook receives the error and the {@link QueueTypes.JobContext} of the failed
+* attempt, so it can tell a retry from a final failure by comparing
+* `context.attempt` with `context.attempts`. It never changes the outcome of the
+* job: a throwing hook is logged and forgotten.
+*
+* @param {object} [options] - Narrows the hook down to a single job
+* @param {string} [options.job] - Name of the only job to listen for, every job of the queue by default
+* @returns {Function} The method decorator
+*
+* @example
+* ```ts
+* @Consumer({ queue: 'emails' })
+* export class EmailConsumer {
+*   @Job('welcome', { attempts: 3 })
+*   public async welcome(payload: { userId: string }): Promise<void> {}
+*
+*   @OnJobFailed()
+*   public async failed(error: Error, context: QueueTypes.JobContext): Promise<void> {
+*     if (context.attempt === context.attempts) {
+*       await this.alerts.report(error, context.id);
+*     }
+*   }
+* }
+* ```
+*/
+function OnJobFailed(options = {}) {
+	const hook = {
+		event: "failed",
+		job: options.job
+	};
+	return createDecorator(JobHookDecorator, hook);
+}
+//#endregion
+//#region src/Plugins/QueuePlugin.ts
+/**
+* Queue Plugin for Vercube framework
+*
+* Binds the {@link QueueManager}, mounts the strategies it is given and lets the
+* `@Consumer()` classes bound in the container start consuming once the
+* application is up. Consumer classes themselves stay in your hands: bind them
+* where you bind your controllers.
+*
+* @example
+* ```ts
+* import { defineConfig } from '@vercube/core';
+* import { QueuePlugin } from '@vercube/queue';
+* import { BullMQStrategy } from '@vercube/queue/strategies/BullMQStrategy';
+*
+* export default defineConfig({
+*   plugins: [
+*     [QueuePlugin, {
+*       strategies: [{ strategy: BullMQStrategy, initOptions: { connection: { host: '127.0.0.1', port: 6379 } } }],
+*     }],
+*   ],
+* });
+* ```
+*
+* @example
+* ```ts
+* // a web process that only publishes jobs
+* app.addPlugin(QueuePlugin, {
+*   autoStart: false,
+*   strategies: [{ strategy: MemoryStrategy }],
+* });
+* ```
+*
+* @see {@link https://vercube.dev} for full documentation
+*/
+var QueuePlugin = class extends BasePlugin {
+	/**
+	* The name of the plugin.
+	* @override
+	*/
+	name = "QueuePlugin";
+	/**
+	* Binds the queue manager and mounts every configured strategy.
+	*
+	* Registering the plugin more than once, which happens as soon as it is listed
+	* both in the config and in `app.addPlugin()`, is harmless: the manager is
+	* bound once, settings are merged, and a name that is already mounted is left
+	* alone. Rebinding it would drop the settings and the strategies of whoever
+	* registered first.
+	*
+	* @param {App} app - The application instance
+	* @param {QueueTypes.PluginOptions} [options] - Strategies to mount and manager-wide settings
+	* @returns {Promise<void>} Resolves once every strategy is mounted
+	* @override
+	*/
+	async use(app, options) {
+		if (!app.container.getOptional(QueueManager)) app.container.bind(QueueManager);
+		const manager = app.container.get(QueueManager);
+		const { strategies, ...defaults } = options ?? {};
+		manager.configure(defaults);
+		for (const mount of strategies ?? []) {
+			if (manager.getStrategy(mount.name)) continue;
+			await manager.mount(mount);
+		}
+	}
+};
+//#endregion
+//#region src/Utils/Mount.ts
+/**
+* Type checks a single strategy mount and erases its options, so a list of
+* mounts of different strategies stays checked.
+*
+* `QueueManager.mount()` infers the strategy from its argument and checks
+* `initOptions` against it. A plain array in `QueuePlugin` options cannot do
+* that, since there is no inference site per entry - this helper is that site.
+*
+* @param {QueueTypes.Mount<T>} mount - Mount name, strategy class and its init options
+* @returns {QueueTypes.AnyMount} The very same mount, with its options type erased
+*
+* @example
+* ```ts
+* app.addPlugin(QueuePlugin, {
+*   strategies: [
+*     defineQueueStrategy({ strategy: RabbitMQStrategy, initOptions: { url: 'amqp://localhost' } }),
+*     defineQueueStrategy({
+*       name: 'events',
+*       strategy: KafkaStrategy,
+*       initOptions: { client: { brokers: ['localhost:9092'] }, groupId: 'workers' },
+*     }),
+*   ],
+* });
+* ```
+*/
+function defineQueueStrategy(mount) {
+	return mount;
+}
+//#endregion
+export { ATTEMPTS_HEADER, ATTEMPT_HEADER, AnyJob, Consumer, JOB_HEADER, Job, JobDecorator, KEY_HEADER, MAX_ATTEMPTS, MAX_BACKOFF_MS, OnJobCompleted, OnJobFailed, PRIORITY_HEADER, QueueError, QueueManager, QueuePlugin, QueueStrategy, WILDCARD_JOB, decodePayload, defineQueueStrategy, delay, encodePayload, generateJobId, getConsumerOptions, normalizeHeaders, prune, readNumericHeader, resolveBackoff, setConsumerOptions, toQueueError };