@fedify/amqp 2.0.0-dev.237 → 2.0.0-dev.279

package/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/amqp",
-  "version": "2.0.0-dev.237+7f2bb1de",
+  "version": "2.0.0-dev.279+ce1bdc22",
   "license": "MIT",
   "exports": {
     ".": "./src/mod.ts",
@@ -18,7 +18,8 @@
   ],
   "publish": {
     "exclude": [
-      "**/*.test.ts"
+      "**/*.test.ts",
+      "tsdown.config.ts"
     ]
   },
   "tasks": {

package/dist/mod.d.cts

@@ -1,2 +1,2 @@
-import { AmqpMessageQueue, AmqpMessageQueueOptions } from "./mq.cjs";
-export { AmqpMessageQueue, AmqpMessageQueueOptions };
+import { AmqpMessageQueue, AmqpMessageQueueOptions, AmqpOrderingOptions } from "./mq.cjs";
+export { AmqpMessageQueue, AmqpMessageQueueOptions, AmqpOrderingOptions };

package/dist/mod.d.ts

@@ -1,2 +1,2 @@
-import { AmqpMessageQueue, AmqpMessageQueueOptions } from "./mq.js";
-export { AmqpMessageQueue, AmqpMessageQueueOptions };
+import { AmqpMessageQueue, AmqpMessageQueueOptions, AmqpOrderingOptions } from "./mq.js";
+export { AmqpMessageQueue, AmqpMessageQueueOptions, AmqpOrderingOptions };

package/dist/mq.cjs

@@ -23,6 +23,8 @@ var AmqpMessageQueue = class {
 	#delayedQueuePrefix;
 	#durable;
 	#senderChannel;
+	#ordering;
+	#orderingPrepared = false;
 	nativeRetrial;
 	/**
 	* Creates a new `AmqpMessageQueue`.
@@ -35,30 +37,85 @@ var AmqpMessageQueue = class {
 		this.#delayedQueuePrefix = options.delayedQueuePrefix ?? "fedify_delayed_";
 		this.#durable = options.durable ?? true;
 		this.nativeRetrial = options.nativeRetrial ?? false;
+		if (options.ordering != null) this.#ordering = {
+			exchange: options.ordering.exchange ?? "fedify_ordering",
+			queuePrefix: options.ordering.queuePrefix ?? "fedify_ordering_",
+			partitions: options.ordering.partitions ?? 4
+		};
 	}
 	async #prepareQueue(channel) {
 		await channel.assertQueue(this.#queue, { durable: this.#durable });
 	}
+	#getOrderingQueueName(partition) {
+		return `${this.#ordering.queuePrefix}${partition}`;
+	}
+	async #prepareOrdering(channel) {
+		if (this.#ordering == null || this.#orderingPrepared) return;
+		await channel.assertExchange(this.#ordering.exchange, "x-consistent-hash", { durable: this.#durable });
+		for (let i = 0; i < this.#ordering.partitions; i++) {
+			const queueName = this.#getOrderingQueueName(i);
+			await channel.assertQueue(queueName, {
+				durable: this.#durable,
+				arguments: { "x-single-active-consumer": true }
+			});
+			await channel.bindQueue(queueName, this.#ordering.exchange, "1");
+		}
+		this.#orderingPrepared = true;
+	}
 	async #getSenderChannel() {
 		if (this.#senderChannel != null) return this.#senderChannel;
 		const channel = await this.#connection.createChannel();
 		this.#senderChannel = channel;
-		this.#prepareQueue(channel);
+		await this.#prepareQueue(channel);
+		await this.#prepareOrdering(channel);
 		return channel;
 	}
+	/**
+	* Enqueues a message to be processed.
+	*
+	* When an `orderingKey` is provided without a `delay`, the message is routed
+	* through the consistent hash exchange, ensuring messages with the same
+	* ordering key are processed by the same consumer in FIFO order.
+	*
+	* When both `orderingKey` and `delay` are provided, the message is first
+	* placed in a delay queue, then routed to the consistent hash exchange
+	* after the delay expires.  This ensures ordering is preserved even for
+	* delayed messages.
+	*
+	* @param message The message to enqueue.
+	* @param options The options for enqueueing the message.
+	*/
 	async enqueue(message, options) {
 		const channel = await this.#getSenderChannel();
 		const delay = options?.delay?.total("millisecond");
+		const orderingKey = options?.orderingKey;
+		if (orderingKey != null && this.#ordering != null && (delay == null || delay <= 0)) {
+			channel.publish(this.#ordering.exchange, orderingKey, node_buffer.Buffer.from(JSON.stringify(message), "utf-8"), {
+				persistent: this.#durable,
+				contentType: "application/json"
+			});
+			return;
+		}
 		let queue;
+		let deadLetterExchange;
+		let deadLetterRoutingKey;
 		if (delay == null || delay <= 0) queue = this.#queue;
 		else {
 			const delayStr = delay.toLocaleString("en", { useGrouping: false });
-			queue = this.#delayedQueuePrefix + delayStr;
+			if (orderingKey != null && this.#ordering != null) {
+				queue = `${this.#delayedQueuePrefix}ordering_${delayStr}`;
+				deadLetterExchange = this.#ordering.exchange;
+				deadLetterRoutingKey = orderingKey;
+			} else {
+				queue = this.#delayedQueuePrefix + delayStr;
+				deadLetterExchange = "";
+				deadLetterRoutingKey = this.#queue;
+			}
 			await channel.assertQueue(queue, {
 				autoDelete: true,
 				durable: this.#durable,
-				deadLetterExchange: "",
-				deadLetterRoutingKey: this.#queue,
+				deadLetterExchange,
+				deadLetterRoutingKey,
 				messageTtl: delay
 			});
 		}
@@ -67,19 +124,52 @@ var AmqpMessageQueue = class {
 			contentType: "application/json"
 		});
 	}
+	/**
+	* Enqueues multiple messages to be processed.
+	*
+	* When an `orderingKey` is provided without a `delay`, the messages are
+	* routed through the consistent hash exchange, ensuring messages with the
+	* same ordering key are processed by the same consumer in FIFO order.
+	*
+	* When both `orderingKey` and `delay` are provided, the messages are first
+	* placed in a delay queue, then routed to the consistent hash exchange
+	* after the delay expires.  This ensures ordering is preserved even for
+	* delayed messages.
+	*
+	* @param messages The messages to enqueue.
+	* @param options The options for enqueueing the messages.
+	*/
 	async enqueueMany(messages, options) {
 		const channel = await this.#getSenderChannel();
 		const delay = options?.delay?.total("millisecond");
+		const orderingKey = options?.orderingKey;
+		if (orderingKey != null && this.#ordering != null && (delay == null || delay <= 0)) {
+			for (const message of messages) channel.publish(this.#ordering.exchange, orderingKey, node_buffer.Buffer.from(JSON.stringify(message), "utf-8"), {
+				persistent: this.#durable,
+				contentType: "application/json"
+			});
+			return;
+		}
 		let queue;
+		let deadLetterExchange;
+		let deadLetterRoutingKey;
 		if (delay == null || delay <= 0) queue = this.#queue;
 		else {
 			const delayStr = delay.toLocaleString("en", { useGrouping: false });
-			queue = this.#delayedQueuePrefix + delayStr;
+			if (orderingKey != null && this.#ordering != null) {
+				queue = `${this.#delayedQueuePrefix}ordering_${delayStr}`;
+				deadLetterExchange = this.#ordering.exchange;
+				deadLetterRoutingKey = orderingKey;
+			} else {
+				queue = this.#delayedQueuePrefix + delayStr;
+				deadLetterExchange = "";
+				deadLetterRoutingKey = this.#queue;
+			}
 			await channel.assertQueue(queue, {
 				autoDelete: true,
 				durable: this.#durable,
-				deadLetterExchange: "",
-				deadLetterRoutingKey: this.#queue,
+				deadLetterExchange,
+				deadLetterRoutingKey,
 				messageTtl: delay
 			});
 		}
@@ -91,8 +181,9 @@ var AmqpMessageQueue = class {
 	async listen(handler, options = {}) {
 		const channel = await this.#connection.createChannel();
 		await this.#prepareQueue(channel);
+		await this.#prepareOrdering(channel);
 		await channel.prefetch(1);
-		const reply = await channel.consume(this.#queue, (msg) => {
+		const messageHandler = (msg) => {
 			if (msg == null) return;
 			const message = JSON.parse(msg.content.toString("utf-8"));
 			try {
@@ -105,13 +196,21 @@ var AmqpMessageQueue = class {
 			} finally {
 				if (!this.nativeRetrial) channel.ack(msg);
 			}
-		}, { noAck: false });
+		};
+		const consumerTags = [];
+		const reply = await channel.consume(this.#queue, messageHandler, { noAck: false });
+		consumerTags.push(reply.consumerTag);
+		if (this.#ordering != null) for (let i = 0; i < this.#ordering.partitions; i++) {
+			const queueName = this.#getOrderingQueueName(i);
+			const orderingReply = await channel.consume(queueName, messageHandler, { noAck: false });
+			consumerTags.push(orderingReply.consumerTag);
+		}
 		return await new Promise((resolve) => {
 			if (options.signal?.aborted) resolve();
-			options.signal?.addEventListener("abort", () => {
-				channel.cancel(reply.consumerTag).then(() => {
-					channel.close().then(() => resolve());
-				});
+			options.signal?.addEventListener("abort", async () => {
+				for (const tag of consumerTags) await channel.cancel(tag);
+				await channel.close();
+				resolve();
 			});
 		});
 	}

package/dist/mq.d.cts

@@ -3,6 +3,39 @@ import { ChannelModel } from "amqplib";
 
 //#region src/mq.d.ts
 
+/**
+ * Options for ordering key support in {@link AmqpMessageQueue}.
+ *
+ * Ordering key support requires the `rabbitmq_consistent_hash_exchange`
+ * plugin to be enabled on the RabbitMQ server.  You can enable it by running:
+ *
+ * ```sh
+ * rabbitmq-plugins enable rabbitmq_consistent_hash_exchange
+ * ```
+ *
+ * @since 2.0.0
+ */
+interface AmqpOrderingOptions {
+  /**
+   * The name of the consistent hash exchange to use for ordering.
+   * Defaults to `"fedify_ordering"`.
+   * @default `"fedify_ordering"`
+   */
+  readonly exchange?: string;
+  /**
+   * The prefix to use for ordering queues.
+   * Defaults to `"fedify_ordering_"`.
+   * @default `"fedify_ordering_"`
+   */
+  readonly queuePrefix?: string;
+  /**
+   * The number of partitions (queues) to use for ordering.
+   * More partitions allow better parallelism for different ordering keys.
+   * Defaults to `4`.
+   * @default `4`
+   */
+  readonly partitions?: number;
+}
 /**
  * Options for {@link AmqpMessageQueue}.
  */
@@ -39,6 +72,22 @@ interface AmqpMessageQueueOptions {
    * @since 0.3.0
    */
   readonly nativeRetrial?: boolean;
+  /**
+   * Options for ordering key support.  If provided, the message queue will
+   * support the `orderingKey` option in {@link MessageQueueEnqueueOptions}.
+   * Messages with the same ordering key will be processed in order,
+   * while messages with different ordering keys can be processed in parallel.
+   *
+   * This feature requires the `rabbitmq_consistent_hash_exchange` plugin
+   * to be enabled on the RabbitMQ server.  See {@link AmqpOrderingOptions}
+   * for more details.
+   *
+   * If not provided, ordering key support is disabled and any `orderingKey`
+   * option passed to `enqueue()` will be ignored.
+   *
+   * @since 0.4.0
+   */
+  readonly ordering?: AmqpOrderingOptions;
 }
 /**
  * A message queue that uses AMQP.
@@ -64,9 +113,39 @@ declare class AmqpMessageQueue implements MessageQueue {
    * @param options Options for the message queue.
    */
   constructor(connection: ChannelModel, options?: AmqpMessageQueueOptions);
+  /**
+   * Enqueues a message to be processed.
+   *
+   * When an `orderingKey` is provided without a `delay`, the message is routed
+   * through the consistent hash exchange, ensuring messages with the same
+   * ordering key are processed by the same consumer in FIFO order.
+   *
+   * When both `orderingKey` and `delay` are provided, the message is first
+   * placed in a delay queue, then routed to the consistent hash exchange
+   * after the delay expires.  This ensures ordering is preserved even for
+   * delayed messages.
+   *
+   * @param message The message to enqueue.
+   * @param options The options for enqueueing the message.
+   */
   enqueue(message: any, options?: MessageQueueEnqueueOptions): Promise<void>;
+  /**
+   * Enqueues multiple messages to be processed.
+   *
+   * When an `orderingKey` is provided without a `delay`, the messages are
+   * routed through the consistent hash exchange, ensuring messages with the
+   * same ordering key are processed by the same consumer in FIFO order.
+   *
+   * When both `orderingKey` and `delay` are provided, the messages are first
+   * placed in a delay queue, then routed to the consistent hash exchange
+   * after the delay expires.  This ensures ordering is preserved even for
+   * delayed messages.
+   *
+   * @param messages The messages to enqueue.
+   * @param options The options for enqueueing the messages.
+   */
   enqueueMany(messages: readonly any[], options?: MessageQueueEnqueueOptions): Promise<void>;
   listen(handler: (message: any) => void | Promise<void>, options?: MessageQueueListenOptions): Promise<void>;
 }
 //#endregion
-export { AmqpMessageQueue, AmqpMessageQueueOptions };
+export { AmqpMessageQueue, AmqpMessageQueueOptions, AmqpOrderingOptions };

package/dist/mq.d.ts

@@ -3,6 +3,39 @@ import { ChannelModel } from "amqplib";
 
 //#region src/mq.d.ts
 
+/**
+ * Options for ordering key support in {@link AmqpMessageQueue}.
+ *
+ * Ordering key support requires the `rabbitmq_consistent_hash_exchange`
+ * plugin to be enabled on the RabbitMQ server.  You can enable it by running:
+ *
+ * ```sh
+ * rabbitmq-plugins enable rabbitmq_consistent_hash_exchange
+ * ```
+ *
+ * @since 2.0.0
+ */
+interface AmqpOrderingOptions {
+  /**
+   * The name of the consistent hash exchange to use for ordering.
+   * Defaults to `"fedify_ordering"`.
+   * @default `"fedify_ordering"`
+   */
+  readonly exchange?: string;
+  /**
+   * The prefix to use for ordering queues.
+   * Defaults to `"fedify_ordering_"`.
+   * @default `"fedify_ordering_"`
+   */
+  readonly queuePrefix?: string;
+  /**
+   * The number of partitions (queues) to use for ordering.
+   * More partitions allow better parallelism for different ordering keys.
+   * Defaults to `4`.
+   * @default `4`
+   */
+  readonly partitions?: number;
+}
 /**
  * Options for {@link AmqpMessageQueue}.
  */
@@ -39,6 +72,22 @@ interface AmqpMessageQueueOptions {
    * @since 0.3.0
    */
   readonly nativeRetrial?: boolean;
+  /**
+   * Options for ordering key support.  If provided, the message queue will
+   * support the `orderingKey` option in {@link MessageQueueEnqueueOptions}.
+   * Messages with the same ordering key will be processed in order,
+   * while messages with different ordering keys can be processed in parallel.
+   *
+   * This feature requires the `rabbitmq_consistent_hash_exchange` plugin
+   * to be enabled on the RabbitMQ server.  See {@link AmqpOrderingOptions}
+   * for more details.
+   *
+   * If not provided, ordering key support is disabled and any `orderingKey`
+   * option passed to `enqueue()` will be ignored.
+   *
+   * @since 0.4.0
+   */
+  readonly ordering?: AmqpOrderingOptions;
 }
 /**
  * A message queue that uses AMQP.
@@ -64,9 +113,39 @@ declare class AmqpMessageQueue implements MessageQueue {
    * @param options Options for the message queue.
    */
   constructor(connection: ChannelModel, options?: AmqpMessageQueueOptions);
+  /**
+   * Enqueues a message to be processed.
+   *
+   * When an `orderingKey` is provided without a `delay`, the message is routed
+   * through the consistent hash exchange, ensuring messages with the same
+   * ordering key are processed by the same consumer in FIFO order.
+   *
+   * When both `orderingKey` and `delay` are provided, the message is first
+   * placed in a delay queue, then routed to the consistent hash exchange
+   * after the delay expires.  This ensures ordering is preserved even for
+   * delayed messages.
+   *
+   * @param message The message to enqueue.
+   * @param options The options for enqueueing the message.
+   */
   enqueue(message: any, options?: MessageQueueEnqueueOptions): Promise<void>;
+  /**
+   * Enqueues multiple messages to be processed.
+   *
+   * When an `orderingKey` is provided without a `delay`, the messages are
+   * routed through the consistent hash exchange, ensuring messages with the
+   * same ordering key are processed by the same consumer in FIFO order.
+   *
+   * When both `orderingKey` and `delay` are provided, the messages are first
+   * placed in a delay queue, then routed to the consistent hash exchange
+   * after the delay expires.  This ensures ordering is preserved even for
+   * delayed messages.
+   *
+   * @param messages The messages to enqueue.
+   * @param options The options for enqueueing the messages.
+   */
   enqueueMany(messages: readonly any[], options?: MessageQueueEnqueueOptions): Promise<void>;
   listen(handler: (message: any) => void | Promise<void>, options?: MessageQueueListenOptions): Promise<void>;
 }
 //#endregion
-export { AmqpMessageQueue, AmqpMessageQueueOptions };
+export { AmqpMessageQueue, AmqpMessageQueueOptions, AmqpOrderingOptions };

package/dist/mq.js

@@ -22,6 +22,8 @@ var AmqpMessageQueue = class {
 	#delayedQueuePrefix;
 	#durable;
 	#senderChannel;
+	#ordering;
+	#orderingPrepared = false;
 	nativeRetrial;
 	/**
 	* Creates a new `AmqpMessageQueue`.
@@ -34,30 +36,85 @@ var AmqpMessageQueue = class {
 		this.#delayedQueuePrefix = options.delayedQueuePrefix ?? "fedify_delayed_";
 		this.#durable = options.durable ?? true;
 		this.nativeRetrial = options.nativeRetrial ?? false;
+		if (options.ordering != null) this.#ordering = {
+			exchange: options.ordering.exchange ?? "fedify_ordering",
+			queuePrefix: options.ordering.queuePrefix ?? "fedify_ordering_",
+			partitions: options.ordering.partitions ?? 4
+		};
 	}
 	async #prepareQueue(channel) {
 		await channel.assertQueue(this.#queue, { durable: this.#durable });
 	}
+	#getOrderingQueueName(partition) {
+		return `${this.#ordering.queuePrefix}${partition}`;
+	}
+	async #prepareOrdering(channel) {
+		if (this.#ordering == null || this.#orderingPrepared) return;
+		await channel.assertExchange(this.#ordering.exchange, "x-consistent-hash", { durable: this.#durable });
+		for (let i = 0; i < this.#ordering.partitions; i++) {
+			const queueName = this.#getOrderingQueueName(i);
+			await channel.assertQueue(queueName, {
+				durable: this.#durable,
+				arguments: { "x-single-active-consumer": true }
+			});
+			await channel.bindQueue(queueName, this.#ordering.exchange, "1");
+		}
+		this.#orderingPrepared = true;
+	}
 	async #getSenderChannel() {
 		if (this.#senderChannel != null) return this.#senderChannel;
 		const channel = await this.#connection.createChannel();
 		this.#senderChannel = channel;
-		this.#prepareQueue(channel);
+		await this.#prepareQueue(channel);
+		await this.#prepareOrdering(channel);
 		return channel;
 	}
+	/**
+	* Enqueues a message to be processed.
+	*
+	* When an `orderingKey` is provided without a `delay`, the message is routed
+	* through the consistent hash exchange, ensuring messages with the same
+	* ordering key are processed by the same consumer in FIFO order.
+	*
+	* When both `orderingKey` and `delay` are provided, the message is first
+	* placed in a delay queue, then routed to the consistent hash exchange
+	* after the delay expires.  This ensures ordering is preserved even for
+	* delayed messages.
+	*
+	* @param message The message to enqueue.
+	* @param options The options for enqueueing the message.
+	*/
 	async enqueue(message, options) {
 		const channel = await this.#getSenderChannel();
 		const delay = options?.delay?.total("millisecond");
+		const orderingKey = options?.orderingKey;
+		if (orderingKey != null && this.#ordering != null && (delay == null || delay <= 0)) {
+			channel.publish(this.#ordering.exchange, orderingKey, Buffer.from(JSON.stringify(message), "utf-8"), {
+				persistent: this.#durable,
+				contentType: "application/json"
+			});
+			return;
+		}
 		let queue;
+		let deadLetterExchange;
+		let deadLetterRoutingKey;
 		if (delay == null || delay <= 0) queue = this.#queue;
 		else {
 			const delayStr = delay.toLocaleString("en", { useGrouping: false });
-			queue = this.#delayedQueuePrefix + delayStr;
+			if (orderingKey != null && this.#ordering != null) {
+				queue = `${this.#delayedQueuePrefix}ordering_${delayStr}`;
+				deadLetterExchange = this.#ordering.exchange;
+				deadLetterRoutingKey = orderingKey;
+			} else {
+				queue = this.#delayedQueuePrefix + delayStr;
+				deadLetterExchange = "";
+				deadLetterRoutingKey = this.#queue;
+			}
 			await channel.assertQueue(queue, {
 				autoDelete: true,
 				durable: this.#durable,
-				deadLetterExchange: "",
-				deadLetterRoutingKey: this.#queue,
+				deadLetterExchange,
+				deadLetterRoutingKey,
 				messageTtl: delay
 			});
 		}
@@ -66,19 +123,52 @@ var AmqpMessageQueue = class {
 			contentType: "application/json"
 		});
 	}
+	/**
+	* Enqueues multiple messages to be processed.
+	*
+	* When an `orderingKey` is provided without a `delay`, the messages are
+	* routed through the consistent hash exchange, ensuring messages with the
+	* same ordering key are processed by the same consumer in FIFO order.
+	*
+	* When both `orderingKey` and `delay` are provided, the messages are first
+	* placed in a delay queue, then routed to the consistent hash exchange
+	* after the delay expires.  This ensures ordering is preserved even for
+	* delayed messages.
+	*
+	* @param messages The messages to enqueue.
+	* @param options The options for enqueueing the messages.
+	*/
 	async enqueueMany(messages, options) {
 		const channel = await this.#getSenderChannel();
 		const delay = options?.delay?.total("millisecond");
+		const orderingKey = options?.orderingKey;
+		if (orderingKey != null && this.#ordering != null && (delay == null || delay <= 0)) {
+			for (const message of messages) channel.publish(this.#ordering.exchange, orderingKey, Buffer.from(JSON.stringify(message), "utf-8"), {
+				persistent: this.#durable,
+				contentType: "application/json"
+			});
+			return;
+		}
 		let queue;
+		let deadLetterExchange;
+		let deadLetterRoutingKey;
 		if (delay == null || delay <= 0) queue = this.#queue;
 		else {
 			const delayStr = delay.toLocaleString("en", { useGrouping: false });
-			queue = this.#delayedQueuePrefix + delayStr;
+			if (orderingKey != null && this.#ordering != null) {
+				queue = `${this.#delayedQueuePrefix}ordering_${delayStr}`;
+				deadLetterExchange = this.#ordering.exchange;
+				deadLetterRoutingKey = orderingKey;
+			} else {
+				queue = this.#delayedQueuePrefix + delayStr;
+				deadLetterExchange = "";
+				deadLetterRoutingKey = this.#queue;
+			}
 			await channel.assertQueue(queue, {
 				autoDelete: true,
 				durable: this.#durable,
-				deadLetterExchange: "",
-				deadLetterRoutingKey: this.#queue,
+				deadLetterExchange,
+				deadLetterRoutingKey,
 				messageTtl: delay
 			});
 		}
@@ -90,8 +180,9 @@ var AmqpMessageQueue = class {
 	async listen(handler, options = {}) {
 		const channel = await this.#connection.createChannel();
 		await this.#prepareQueue(channel);
+		await this.#prepareOrdering(channel);
 		await channel.prefetch(1);
-		const reply = await channel.consume(this.#queue, (msg) => {
+		const messageHandler = (msg) => {
 			if (msg == null) return;
 			const message = JSON.parse(msg.content.toString("utf-8"));
 			try {
@@ -104,13 +195,21 @@ var AmqpMessageQueue = class {
 			} finally {
 				if (!this.nativeRetrial) channel.ack(msg);
 			}
-		}, { noAck: false });
+		};
+		const consumerTags = [];
+		const reply = await channel.consume(this.#queue, messageHandler, { noAck: false });
+		consumerTags.push(reply.consumerTag);
+		if (this.#ordering != null) for (let i = 0; i < this.#ordering.partitions; i++) {
+			const queueName = this.#getOrderingQueueName(i);
+			const orderingReply = await channel.consume(queueName, messageHandler, { noAck: false });
+			consumerTags.push(orderingReply.consumerTag);
+		}
 		return await new Promise((resolve) => {
 			if (options.signal?.aborted) resolve();
-			options.signal?.addEventListener("abort", () => {
-				channel.cancel(reply.consumerTag).then(() => {
-					channel.close().then(() => resolve());
-				});
+			options.signal?.addEventListener("abort", async () => {
+				for (const tag of consumerTags) await channel.cancel(tag);
+				await channel.close();
+				resolve();
 			});
 		});
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/amqp",
-  "version": "2.0.0-dev.237+7f2bb1de",
+  "version": "2.0.0-dev.279+ce1bdc22",
   "description": "AMQP/RabbitMQ driver for Fedify",
   "keywords": [
     "fedify",
@@ -55,7 +55,7 @@
   },
   "peerDependencies": {
     "amqplib": "^0.10.9",
-    "@fedify/fedify": "^2.0.0-dev.237+7f2bb1de"
+    "@fedify/fedify": "^2.0.0-dev.279+ce1bdc22"
   },
   "devDependencies": {
     "@alinea/suite": "^0.6.3",
@@ -65,13 +65,16 @@
     "@types/amqplib": "^0.10.7",
     "tsdown": "^0.12.9",
     "typescript": "^5.9.3",
-    "@fedify/testing": "^2.0.0-dev.237+7f2bb1de"
+    "@fedify/testing": "^2.0.0-dev.279+ce1bdc22"
   },
   "scripts": {
-    "build": "tsdown",
-    "prepublish": "tsdown",
-    "test": "tsdown && node --experimental-transform-types --test",
-    "test:bun": "tsdown && bun test --timeout 15000",
+    "build:self": "tsdown",
+    "build": "pnpm --filter @fedify/amqp... run build:self",
+    "prepublish": "pnpm build",
+    "pretest": "pnpm build",
+    "test": "node --experimental-transform-types --test",
+    "pretest:bun": "pnpm build",
+    "test:bun": "bun test --timeout 15000",
     "test:deno": "deno task test",
     "test-all": "tsdown && node --experimental-transform-types --test && bun test --timeout 15000 && deno task test"
   }

package/src/mq.test.ts

@@ -37,6 +37,47 @@ test(
     ),
 );
 
+// Test with ordering key support (requires rabbitmq_consistent_hash_exchange plugin)
+const orderingConnections: ChannelModel[] = [];
+const orderingQueue = getRandomKey("ordering_queue");
+const orderingDelayedQueuePrefix = getRandomKey("ordering_delayed") + "_";
+const orderingExchange = getRandomKey("ordering_exchange");
+const orderingQueuePrefix = getRandomKey("ordering_partition") + "_";
+
+// Only run ordering key tests if AMQP_ORDERING_TEST env var is set
+// (requires rabbitmq_consistent_hash_exchange plugin to be enabled)
+const orderingTest = process.env.AMQP_ORDERING_TEST
+  ? test
+  : suite(import.meta).skip;
+
+orderingTest(
+  "AmqpMessageQueue [ordering]",
+  { sanitizeOps: false, sanitizeExit: false, sanitizeResources: false },
+  () =>
+    testMessageQueue(
+      async () => {
+        const conn = await getConnection();
+        orderingConnections.push(conn);
+        return new AmqpMessageQueue(conn, {
+          queue: orderingQueue,
+          delayedQueuePrefix: orderingDelayedQueuePrefix,
+          ordering: {
+            exchange: orderingExchange,
+            queuePrefix: orderingQueuePrefix,
+            partitions: 4,
+          },
+        });
+      },
+      async ({ controller }) => {
+        controller.abort();
+        for (const conn of orderingConnections) {
+          await conn.close();
+        }
+      },
+      { testOrderingKey: true },
+    ),
+);
+
 test(
   "AmqpMessageQueue [nativeRetrial: false]",
   { sanitizeOps: false, sanitizeExit: false, sanitizeResources: false },

package/src/mq.ts

@@ -4,9 +4,45 @@ import type {
   MessageQueueListenOptions,
 } from "@fedify/fedify";
 // @deno-types="npm:@types/amqplib@^0.10.7"
-import type { Channel, ChannelModel } from "amqplib";
+import type { Channel, ChannelModel, ConsumeMessage } from "amqplib";
 import { Buffer } from "node:buffer";
 
+/**
+ * Options for ordering key support in {@link AmqpMessageQueue}.
+ *
+ * Ordering key support requires the `rabbitmq_consistent_hash_exchange`
+ * plugin to be enabled on the RabbitMQ server.  You can enable it by running:
+ *
+ * ```sh
+ * rabbitmq-plugins enable rabbitmq_consistent_hash_exchange
+ * ```
+ *
+ * @since 2.0.0
+ */
+export interface AmqpOrderingOptions {
+  /**
+   * The name of the consistent hash exchange to use for ordering.
+   * Defaults to `"fedify_ordering"`.
+   * @default `"fedify_ordering"`
+   */
+  readonly exchange?: string;
+
+  /**
+   * The prefix to use for ordering queues.
+   * Defaults to `"fedify_ordering_"`.
+   * @default `"fedify_ordering_"`
+   */
+  readonly queuePrefix?: string;
+
+  /**
+   * The number of partitions (queues) to use for ordering.
+   * More partitions allow better parallelism for different ordering keys.
+   * Defaults to `4`.
+   * @default `4`
+   */
+  readonly partitions?: number;
+}
+
 /**
  * Options for {@link AmqpMessageQueue}.
  */
@@ -46,6 +82,23 @@ export interface AmqpMessageQueueOptions {
    * @since 0.3.0
    */
   readonly nativeRetrial?: boolean;
+
+  /**
+   * Options for ordering key support.  If provided, the message queue will
+   * support the `orderingKey` option in {@link MessageQueueEnqueueOptions}.
+   * Messages with the same ordering key will be processed in order,
+   * while messages with different ordering keys can be processed in parallel.
+   *
+   * This feature requires the `rabbitmq_consistent_hash_exchange` plugin
+   * to be enabled on the RabbitMQ server.  See {@link AmqpOrderingOptions}
+   * for more details.
+   *
+   * If not provided, ordering key support is disabled and any `orderingKey`
+   * option passed to `enqueue()` will be ignored.
+   *
+   * @since 0.4.0
+   */
+  readonly ordering?: AmqpOrderingOptions;
 }
 
 /**
@@ -69,6 +122,12 @@ export class AmqpMessageQueue implements MessageQueue {
   #delayedQueuePrefix: string;
   #durable: boolean;
   #senderChannel?: Channel;
+  #ordering?: {
+    exchange: string;
+    queuePrefix: string;
+    partitions: number;
+  };
+  #orderingPrepared: boolean = false;
 
   readonly nativeRetrial: boolean;
 
@@ -86,6 +145,13 @@ export class AmqpMessageQueue implements MessageQueue {
     this.#delayedQueuePrefix = options.delayedQueuePrefix ?? "fedify_delayed_";
     this.#durable = options.durable ?? true;
     this.nativeRetrial = options.nativeRetrial ?? false;
+    if (options.ordering != null) {
+      this.#ordering = {
+        exchange: options.ordering.exchange ?? "fedify_ordering",
+        queuePrefix: options.ordering.queuePrefix ?? "fedify_ordering_",
+        partitions: options.ordering.partitions ?? 4,
+      };
+    }
   }
 
   async #prepareQueue(channel: Channel): Promise<void> {
@@ -94,14 +160,55 @@ export class AmqpMessageQueue implements MessageQueue {
     });
   }
 
+  #getOrderingQueueName(partition: number): string {
+    return `${this.#ordering!.queuePrefix}${partition}`;
+  }
+
+  async #prepareOrdering(channel: Channel): Promise<void> {
+    if (this.#ordering == null || this.#orderingPrepared) return;
+    // Declare the consistent hash exchange
+    await channel.assertExchange(this.#ordering.exchange, "x-consistent-hash", {
+      durable: this.#durable,
+    });
+    // Declare and bind ordering queues with Single Active Consumer
+    for (let i = 0; i < this.#ordering.partitions; i++) {
+      const queueName = this.#getOrderingQueueName(i);
+      await channel.assertQueue(queueName, {
+        durable: this.#durable,
+        arguments: {
+          "x-single-active-consumer": true,
+        },
+      });
+      // Bind with weight "1" (equal distribution)
+      await channel.bindQueue(queueName, this.#ordering.exchange, "1");
+    }
+    this.#orderingPrepared = true;
+  }
+
   async #getSenderChannel(): Promise<Channel> {
     if (this.#senderChannel != null) return this.#senderChannel;
     const channel = await this.#connection.createChannel();
     this.#senderChannel = channel;
-    this.#prepareQueue(channel);
+    await this.#prepareQueue(channel);
+    await this.#prepareOrdering(channel);
     return channel;
   }
 
+  /**
+   * Enqueues a message to be processed.
+   *
+   * When an `orderingKey` is provided without a `delay`, the message is routed
+   * through the consistent hash exchange, ensuring messages with the same
+   * ordering key are processed by the same consumer in FIFO order.
+   *
+   * When both `orderingKey` and `delay` are provided, the message is first
+   * placed in a delay queue, then routed to the consistent hash exchange
+   * after the delay expires.  This ensures ordering is preserved even for
+   * delayed messages.
+   *
+   * @param message The message to enqueue.
+   * @param options The options for enqueueing the message.
+   */
   async enqueue(
     // deno-lint-ignore no-explicit-any
     message: any,
@@ -109,17 +216,51 @@ export class AmqpMessageQueue implements MessageQueue {
   ): Promise<void> {
     const channel = await this.#getSenderChannel();
     const delay = options?.delay?.total("millisecond");
+    const orderingKey = options?.orderingKey;
+
+    // If ordering key is provided and ordering is enabled, use consistent hash
+    // Treat delay <= 0 the same as no delay for routing purposes
+    if (
+      orderingKey != null &&
+      this.#ordering != null &&
+      (delay == null || delay <= 0)
+    ) {
+      channel.publish(
+        this.#ordering.exchange,
+        orderingKey, // routing key = ordering key
+        Buffer.from(JSON.stringify(message), "utf-8"),
+        {
+          persistent: this.#durable,
+          contentType: "application/json",
+        },
+      );
+      return;
+    }
+
+    // For delayed messages or messages without ordering key, use direct queue
     let queue: string;
+    let deadLetterExchange: string | undefined;
+    let deadLetterRoutingKey: string | undefined;
+
     if (delay == null || delay <= 0) {
       queue = this.#queue;
     } else {
       const delayStr = delay.toLocaleString("en", { useGrouping: false });
-      queue = this.#delayedQueuePrefix + delayStr;
+      // For delayed messages with ordering key, route to ordering exchange
+      if (orderingKey != null && this.#ordering != null) {
+        queue = `${this.#delayedQueuePrefix}ordering_${delayStr}`;
+        deadLetterExchange = this.#ordering.exchange;
+        deadLetterRoutingKey = orderingKey;
+      } else {
+        queue = this.#delayedQueuePrefix + delayStr;
+        deadLetterExchange = "";
+        deadLetterRoutingKey = this.#queue;
+      }
       await channel.assertQueue(queue, {
         autoDelete: true,
         durable: this.#durable,
-        deadLetterExchange: "",
-        deadLetterRoutingKey: this.#queue,
+        deadLetterExchange,
+        deadLetterRoutingKey,
         messageTtl: delay,
       });
     }
@@ -133,6 +274,21 @@ export class AmqpMessageQueue implements MessageQueue {
     );
   }
 
+  /**
+   * Enqueues multiple messages to be processed.
+   *
+   * When an `orderingKey` is provided without a `delay`, the messages are
+   * routed through the consistent hash exchange, ensuring messages with the
+   * same ordering key are processed by the same consumer in FIFO order.
+   *
+   * When both `orderingKey` and `delay` are provided, the messages are first
+   * placed in a delay queue, then routed to the consistent hash exchange
+   * after the delay expires.  This ensures ordering is preserved even for
+   * delayed messages.
+   *
+   * @param messages The messages to enqueue.
+   * @param options The options for enqueueing the messages.
+   */
   async enqueueMany(
     // deno-lint-ignore no-explicit-any
     messages: readonly any[],
@@ -140,17 +296,53 @@ export class AmqpMessageQueue implements MessageQueue {
   ): Promise<void> {
     const channel = await this.#getSenderChannel();
     const delay = options?.delay?.total("millisecond");
+    const orderingKey = options?.orderingKey;
+
+    // If ordering key is provided and ordering is enabled, use consistent hash
+    // Treat delay <= 0 the same as no delay for routing purposes
+    if (
+      orderingKey != null &&
+      this.#ordering != null &&
+      (delay == null || delay <= 0)
+    ) {
+      for (const message of messages) {
+        channel.publish(
+          this.#ordering.exchange,
+          orderingKey, // routing key = ordering key
+          Buffer.from(JSON.stringify(message), "utf-8"),
+          {
+            persistent: this.#durable,
+            contentType: "application/json",
+          },
+        );
+      }
+      return;
+    }
+
+    // For delayed messages or messages without ordering key, use direct queue
     let queue: string;
+    let deadLetterExchange: string | undefined;
+    let deadLetterRoutingKey: string | undefined;
+
     if (delay == null || delay <= 0) {
       queue = this.#queue;
     } else {
       const delayStr = delay.toLocaleString("en", { useGrouping: false });
-      queue = this.#delayedQueuePrefix + delayStr;
+      // For delayed messages with ordering key, route to ordering exchange
+      if (orderingKey != null && this.#ordering != null) {
+        queue = `${this.#delayedQueuePrefix}ordering_${delayStr}`;
+        deadLetterExchange = this.#ordering.exchange;
+        deadLetterRoutingKey = orderingKey;
+      } else {
+        queue = this.#delayedQueuePrefix + delayStr;
+        deadLetterExchange = "";
+        deadLetterRoutingKey = this.#queue;
+      }
       await channel.assertQueue(queue, {
         autoDelete: true,
         durable: this.#durable,
-        deadLetterExchange: "",
-        deadLetterRoutingKey: this.#queue,
+        deadLetterExchange,
+        deadLetterRoutingKey,
         messageTtl: delay,
       });
     }
@@ -174,8 +366,10 @@ export class AmqpMessageQueue implements MessageQueue {
   ): Promise<void> {
     const channel = await this.#connection.createChannel();
     await this.#prepareQueue(channel);
+    await this.#prepareOrdering(channel);
     await channel.prefetch(1);
-    const reply = await channel.consume(this.#queue, (msg) => {
+
+    const messageHandler = (msg: ConsumeMessage | null) => {
       if (msg == null) return;
       const message = JSON.parse(msg.content.toString("utf-8"));
       try {
@@ -200,15 +394,37 @@ export class AmqpMessageQueue implements MessageQueue {
           channel.ack(msg);
         }
       }
-    }, {
+    };
+
+    // Consume from main queue
+    const consumerTags: string[] = [];
+    const reply = await channel.consume(this.#queue, messageHandler, {
       noAck: false,
     });
+    consumerTags.push(reply.consumerTag);
+
+    // Also consume from ordering queues if ordering is enabled
+    if (this.#ordering != null) {
+      for (let i = 0; i < this.#ordering.partitions; i++) {
+        const queueName = this.#getOrderingQueueName(i);
+        const orderingReply = await channel.consume(
+          queueName,
+          messageHandler,
+          { noAck: false },
+        );
+        consumerTags.push(orderingReply.consumerTag);
+      }
+    }
+
     return await new Promise((resolve) => {
       if (options.signal?.aborted) resolve();
-      options.signal?.addEventListener("abort", () => {
-        channel.cancel(reply.consumerTag).then(() => {
-          channel.close().then(() => resolve());
-        });
+      options.signal?.addEventListener("abort", async () => {
+        // Cancel all consumers
+        for (const tag of consumerTags) {
+          await channel.cancel(tag);
+        }
+        await channel.close();
+        resolve();
       });
     });
   }