@vercube/queue 1.3.0

package/dist/Strategies/RabbitMQStrategy.mjs

@@ -0,0 +1,388 @@
+import { f as encodePayload, g as readNumericHeader, m as normalizeHeaders, p as generateJobId, r as ATTEMPT_HEADER, 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 { InjectOptional } from "@vercube/di";
+import { Logger } from "@vercube/logger";
+import { connect } from "amqplib";
+//#region src/Strategies/RabbitMQStrategy.ts
+/**
+* RabbitMQ backed queue implementation.
+*
+* Jobs are plain AMQP messages: the job name travels in the message `type`
+* property, the module's bookkeeping in the headers, and the payload as JSON.
+* RabbitMQ has no notion of attempts or delays, so the manager owns them - which
+* also means a job that has run out of attempts is nacked without requeue, and
+* ends up wherever the queue's dead letter exchange points.
+*
+* @example
+* ```ts
+* await queueManager.mount({
+*   strategy: RabbitMQStrategy,
+*   initOptions: { url: 'amqp://localhost' },
+* });
+* ```
+*
+* @example
+* ```ts
+* // a queue that dead-letters what it cannot process
+* await queueManager.mount({
+*   strategy: RabbitMQStrategy,
+*   initOptions: {
+*     url: 'amqp://localhost',
+*     queueOptions: { durable: true, deadLetterExchange: 'failed' },
+*   },
+* });
+* ```
+*/
+var RabbitMQStrategy = class extends QueueStrategy {
+	/** Transport this strategy talks to. */
+	transport = "rabbitmq";
+	/** Logger instance */
+	gLogger;
+	/** Options the strategy was initialized with */
+	fOptions = null;
+	/** The connection, recovering on its own unless recovery was turned off */
+	fConnection = null;
+	/** Channel every publish goes through */
+	fPublishChannel = null;
+	/** Running consumers, indexed by queue name */
+	fConsumers = /* @__PURE__ */ new Map();
+	/**
+	* Queues the application asked to consume, indexed by queue name.
+	*
+	* Kept apart from {@link RabbitMQStrategy.fConsumers}, which holds the live
+	* channels: those belong to one connection and are thrown away when it is
+	* replaced, while what should be consumed does not change with a reconnect.
+	*/
+	fRequests = /* @__PURE__ */ new Map();
+	/**
+	* Bumped on every connection. A consumer that finishes starting after its
+	* connection was replaced belongs to a dead one and is discarded.
+	*/
+	fGeneration = 0;
+	/** Queues already asserted on the current connection */
+	fAsserted = /* @__PURE__ */ new Set();
+	/**
+	* RabbitMQ carries priorities and message counts, while attempts and delays
+	* are left to the manager.
+	*
+	* @returns {QueueTypes.Capabilities} What this strategy supports
+	*/
+	get capabilities() {
+		return {
+			retries: false,
+			delay: false,
+			priority: true,
+			progress: false,
+			stats: true,
+			peek: false
+		};
+	}
+	/**
+	* Opens the connection to the broker.
+	*
+	* @param {RabbitMQStrategyOptions} options - Broker to connect to and the defaults to use
+	* @returns {Promise<void>} Resolves once the connection is open
+	* @throws {QueueError} When no broker is given, or the connection cannot be opened
+	*/
+	async initialize(options) {
+		if (!options?.url) throw new QueueError("RabbitMQ needs a broker url", "initialize", void 0, void 0, false);
+		this.fOptions = options;
+		const recovery = options.recovery ?? true;
+		try {
+			this.fConnection = await (recovery ? connect(options.url, {
+				...options.socketOptions,
+				recovery: recovery === true ? {} : recovery
+			}) : connect(options.url, options.socketOptions));
+		} catch (error) {
+			throw toQueueError(error, "Failed to connect to RabbitMQ", "initialize");
+		}
+		this.fConnection.on("error", (error) => {
+			this.gLogger?.error("Vercube/RabbitMQStrategy::Connection failed", error);
+		});
+		this.fConnection.on("connect", () => {
+			this.fAsserted.clear();
+			this.fPublishChannel = null;
+			this.fConsumers.clear();
+			this.fGeneration++;
+			for (const request of this.fRequests.values()) this.resume(request, this.fGeneration);
+		});
+	}
+	/**
+	* Sends a job to a queue.
+	*
+	* @param {QueueTypes.PublishRequest} request - Job to publish
+	* @returns {Promise<QueueTypes.JobRef>} Reference to the published job
+	* @throws {QueueError} When the job cannot be sent
+	*/
+	async publish(request) {
+		const options = this.requireOptions("publish");
+		try {
+			const channel = await this.publishChannel();
+			await this.assertQueue(channel, request.queue);
+			const id = request.options.jobId ?? generateJobId();
+			if (!channel.sendToQueue(request.queue, encodePayload(request.payload), {
+				persistent: true,
+				...options.publishOptions,
+				headers: request.headers,
+				type: request.job,
+				messageId: id,
+				priority: request.options.priority,
+				correlationId: request.options.key
+			})) await new Promise((resolve, reject) => {
+				const drained = () => settle();
+				const failed = (channelError) => settle(channelError);
+				const closed = () => settle(/* @__PURE__ */ new Error("The channel closed before the job was flushed"));
+				const settle = (error) => {
+					channel.removeListener("drain", drained);
+					channel.removeListener("error", failed);
+					channel.removeListener("close", closed);
+					if (error) reject(error);
+					else resolve();
+				};
+				channel.once("drain", drained);
+				channel.once("error", failed);
+				channel.once("close", closed);
+			});
+			return {
+				id,
+				queue: request.queue,
+				job: request.job,
+				strategy: this.transport
+			};
+		} catch (error) {
+			throw toQueueError(error, "Failed to send job to RabbitMQ", "publish", {
+				queue: request.queue,
+				job: request.job
+			});
+		}
+	}
+	/**
+	* Starts consuming a queue on its own channel, so its prefetch is its own.
+	*
+	* A job whose dispatch rejects is nacked without requeue: the manager has
+	* already decided it is not worth another attempt.
+	*
+	* @param {QueueTypes.ConsumeRequest} request - Queue to consume, its concurrency and the dispatch callback
+	* @returns {Promise<QueueTypes.ConsumerHandle>} Handle used to stop the consumer again
+	* @throws {QueueError} When the consumer cannot be started
+	*/
+	async consume(request) {
+		const generation = this.fGeneration;
+		this.fRequests.set(request.queue, request);
+		try {
+			await this.startConsumer(request, generation);
+		} catch (error) {
+			if (generation !== this.fGeneration) return {
+				queue: request.queue,
+				stop: () => this.stopConsumer(request.queue)
+			};
+			this.fRequests.delete(request.queue);
+			throw toQueueError(error, "Failed to consume RabbitMQ queue", "consume", { queue: request.queue });
+		}
+		return {
+			queue: request.queue,
+			stop: () => this.stopConsumer(request.queue)
+		};
+	}
+	/**
+	* Opens a channel for a queue and starts delivering its messages.
+	*
+	* @param {QueueTypes.ConsumeRequest} request - Queue to consume, its concurrency and the dispatch callback
+	* @param {number} generation - Connection this consumer is being started for
+	* @returns {Promise<boolean>} Whether the consumer was installed, false when it was no longer wanted
+	* @throws {Error} When the channel or the consumer cannot be created
+	*/
+	async startConsumer(request, generation) {
+		const options = this.requireOptions("consume");
+		const channel = await this.requireConnection("consume").createChannel();
+		try {
+			await this.assertQueue(channel, request.queue);
+			await channel.prefetch(options.prefetch ?? Math.max(1, request.concurrency));
+			const reply = await channel.consume(request.queue, (message) => {
+				if (!message) {
+					this.gLogger?.warn(`Vercube/RabbitMQStrategy::Consumer of "${request.queue}" was cancelled by the broker`);
+					return;
+				}
+				this.handle(request, message);
+			});
+			if (generation !== this.fGeneration || !this.fRequests.has(request.queue)) {
+				await channel.close().catch(() => void 0);
+				return false;
+			}
+			this.fConsumers.set(request.queue, {
+				channel,
+				tag: reply.consumerTag,
+				active: 0,
+				stopping: false
+			});
+			return true;
+		} catch (error) {
+			await channel.close().catch(() => void 0);
+			throw error;
+		}
+	}
+	/**
+	* Starts a consumer again on a recovered connection.
+	*
+	* Failing here is reported rather than thrown: nothing is waiting on a
+	* recovery, and a queue that cannot be consumed again has to be visible.
+	*
+	* @param {QueueTypes.ConsumeRequest} request - What the consumer was started with
+	* @param {number} generation - Connection being recovered onto
+	* @returns {Promise<void>} Resolves once the consumer is running again, or once the failure was reported
+	*/
+	async resume(request, generation) {
+		try {
+			await this.startConsumer(request, generation);
+		} catch (error) {
+			this.gLogger?.error(`Vercube/RabbitMQStrategy::Failed to consume "${request.queue}" again after a recovery`, error);
+		}
+	}
+	/**
+	* Reads how many messages are waiting on a queue.
+	*
+	* @param {string} queue - Queue to read
+	* @returns {Promise<QueueTypes.QueueStats>} Counters of that queue
+	* @throws {QueueError} When the queue cannot be inspected
+	*/
+	async stats(queue) {
+		const connection = this.requireConnection("stats");
+		let channel = null;
+		try {
+			channel = await connection.createChannel();
+			const info = await channel.checkQueue(queue);
+			const consumer = this.fConsumers.get(queue);
+			return {
+				waiting: info.messageCount,
+				active: consumer?.active ?? 0
+			};
+		} catch (error) {
+			throw toQueueError(error, "Failed to inspect RabbitMQ queue", "stats", { queue });
+		} finally {
+			await channel?.close().catch(() => void 0);
+		}
+	}
+	/**
+	* Stops every consumer and closes the connection.
+	*
+	* @returns {Promise<void>} Resolves once the connection is closed
+	*/
+	async close() {
+		const consuming = /* @__PURE__ */ new Set([...this.fConsumers.keys(), ...this.fRequests.keys()]);
+		for (const queue of consuming) await this.stopConsumer(queue);
+		const channel = this.fPublishChannel;
+		const connection = this.fConnection;
+		this.fPublishChannel = null;
+		this.fConnection = null;
+		this.fAsserted.clear();
+		try {
+			await channel?.close();
+			await connection?.close();
+		} catch (error) {
+			this.gLogger?.warn("Vercube/RabbitMQStrategy::Failed to close the connection", error);
+		}
+	}
+	/**
+	* Runs a single delivery and acknowledges it according to the outcome.
+	*
+	* @param {QueueTypes.ConsumeRequest} request - The consumer the message belongs to
+	* @param {ConsumeMessage} message - The delivery
+	* @returns {Promise<void>} Resolves once the message has been settled
+	*/
+	async handle(request, message) {
+		const consumer = this.fConsumers.get(request.queue);
+		const headers = normalizeHeaders(message.properties.headers);
+		if (consumer) consumer.active++;
+		try {
+			await request.dispatch({
+				id: message.properties.messageId ?? generateJobId(),
+				job: message.properties.type ?? headers["x-job"] ?? "unknown",
+				payload: decodePayload(message.content),
+				headers,
+				attempt: readNumericHeader(headers[ATTEMPT_HEADER], 1),
+				raw: message
+			});
+			consumer?.channel.ack(message);
+		} catch {
+			consumer?.channel.nack(message, false, false);
+		} finally {
+			if (consumer) consumer.active--;
+		}
+	}
+	/**
+	* Cancels a consumer, waits for its in-flight messages and closes its channel.
+	*
+	* @param {string} queue - Queue whose consumer is stopped
+	* @returns {Promise<void>} Resolves once the channel is closed
+	*/
+	async stopConsumer(queue) {
+		this.fRequests.delete(queue);
+		const consumer = this.fConsumers.get(queue);
+		if (!consumer || consumer.stopping) return;
+		consumer.stopping = true;
+		this.fConsumers.delete(queue);
+		try {
+			await consumer.channel.cancel(consumer.tag);
+			while (consumer.active > 0) await new Promise((resolve) => setTimeout(resolve, 10));
+			await consumer.channel.close();
+		} catch (error) {
+			this.gLogger?.warn(`Vercube/RabbitMQStrategy::Failed to stop the consumer of "${queue}"`, error);
+		}
+	}
+	/**
+	* Returns the channel every publish goes through, opening it on first use and
+	* after a reconnection.
+	*
+	* @returns {Promise<Channel>} The publish channel
+	* @throws {QueueError} When the strategy is not connected
+	*/
+	async publishChannel() {
+		if (!this.fPublishChannel) {
+			this.fPublishChannel = await this.requireConnection("publish").createChannel();
+			this.fPublishChannel.on("error", (error) => {
+				this.gLogger?.error("Vercube/RabbitMQStrategy::Publish channel failed", error);
+			});
+		}
+		return this.fPublishChannel;
+	}
+	/**
+	* Declares a queue once per connection.
+	*
+	* @param {Channel} channel - Channel to declare it on
+	* @param {string} queue - Queue to declare
+	* @returns {Promise<void>} Resolves once the queue exists
+	*/
+	async assertQueue(channel, queue) {
+		if (this.fAsserted.has(queue)) return;
+		await channel.assertQueue(queue, {
+			durable: true,
+			...this.fOptions?.queueOptions
+		});
+		this.fAsserted.add(queue);
+	}
+	/**
+	* Returns the options the strategy was initialized with.
+	*
+	* @param {string} operation - Operation asking for them, reported in the error
+	* @returns {RabbitMQStrategyOptions} The options
+	* @throws {QueueError} When the strategy has not been initialized
+	*/
+	requireOptions(operation) {
+		if (!this.fOptions) throw new QueueError("RabbitMQ strategy is not initialized", operation, void 0, void 0, false);
+		return this.fOptions;
+	}
+	/**
+	* Returns the open connection.
+	*
+	* @param {string} operation - Operation asking for it, reported in the error
+	* @returns {ChannelModel | RecoveringChannelModel} The connection
+	* @throws {QueueError} When the strategy is not connected
+	*/
+	requireConnection(operation) {
+		if (!this.fConnection) throw new QueueError("RabbitMQ strategy is not connected", operation, void 0, void 0, false);
+		return this.fConnection;
+	}
+};
+__decorate([InjectOptional(Logger)], RabbitMQStrategy.prototype, "gLogger", void 0);
+//#endregion
+export { RabbitMQStrategy };

package/dist/decorate-C0p0FnUM.mjs

@@ -0,0 +1,25 @@
+import { v as QueueError } from "./QueueStrategy-DwLPpfFM.mjs";
+//#region src/Utils/Errors.ts
+/**
+* Turns any thrown value into a {@link QueueError}, leaving queue errors alone so
+* their operation and `retryable` flag survive.
+*
+* @param error - The value that was thrown.
+* @param message - Message of the resulting error.
+* @param operation - Queue operation that failed.
+* @param metadata - Additional non-sensitive context.
+* @returns The error to throw.
+*/
+function toQueueError(error, message, operation, metadata) {
+	return error instanceof QueueError ? error : new QueueError(message, operation, error, metadata);
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.150.0/helpers/esm/decorate.js
+function __decorate(decorators, target, key, desc) {
+	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+//#endregion
+export { toQueueError as n, __decorate as t };