@amqp-contract/worker 0.20.0 → 0.21.0

package/dist/index.mjs

@@ -1,9 +1,40 @@
+import { extractConsumer, extractQueue, isQueueWithTtlBackoffInfrastructure } from "@amqp-contract/contract";
 import { AmqpClient, MessageValidationError, TechnicalError, defaultTelemetryProvider, endSpanError, endSpanSuccess, recordConsumeMetric, startConsumeSpan } from "@amqp-contract/core";
-import { extractConsumer } from "@amqp-contract/contract";
 import { Future, Result } from "@swan-io/boxed";
 import { gunzip, inflate } from "node:zlib";
 import { promisify } from "node:util";
-
+//#region src/decompression.ts
+const gunzipAsync = promisify(gunzip);
+const inflateAsync = promisify(inflate);
+/**
+* Supported content encodings for message decompression.
+*/
+const SUPPORTED_ENCODINGS = ["gzip", "deflate"];
+/**
+* Type guard to check if a string is a supported encoding.
+*/
+function isSupportedEncoding(encoding) {
+	return SUPPORTED_ENCODINGS.includes(encoding.toLowerCase());
+}
+/**
+* Decompress a buffer based on the content-encoding header.
+*
+* @param buffer - The buffer to decompress
+* @param contentEncoding - The content-encoding header value (e.g., 'gzip', 'deflate')
+* @returns A Future with the decompressed buffer or a TechnicalError
+*
+* @internal
+*/
+function decompressBuffer(buffer, contentEncoding) {
+	if (!contentEncoding) return Future.value(Result.Ok(buffer));
+	const normalizedEncoding = contentEncoding.toLowerCase();
+	if (!isSupportedEncoding(normalizedEncoding)) return Future.value(Result.Error(new TechnicalError(`Unsupported content-encoding: "${contentEncoding}". Supported encodings are: ${SUPPORTED_ENCODINGS.join(", ")}. Please check your publisher configuration.`)));
+	switch (normalizedEncoding) {
+		case "gzip": return Future.fromPromise(gunzipAsync(buffer)).mapError((error) => new TechnicalError("Failed to decompress gzip", error));
+		case "deflate": return Future.fromPromise(inflateAsync(buffer)).mapError((error) => new TechnicalError("Failed to decompress deflate", error));
+	}
+}
+//#endregion
 //#region src/errors.ts
 /**
 * Retryable errors - transient failures that may succeed on retry
@@ -164,40 +195,6 @@ function retryable(message, cause) {
 function nonRetryable(message, cause) {
 	return new NonRetryableError(message, cause);
 }
-
-//#endregion
-//#region src/decompression.ts
-const gunzipAsync = promisify(gunzip);
-const inflateAsync = promisify(inflate);
-/**
-* Supported content encodings for message decompression.
-*/
-const SUPPORTED_ENCODINGS = ["gzip", "deflate"];
-/**
-* Type guard to check if a string is a supported encoding.
-*/
-function isSupportedEncoding(encoding) {
-	return SUPPORTED_ENCODINGS.includes(encoding.toLowerCase());
-}
-/**
-* Decompress a buffer based on the content-encoding header.
-*
-* @param buffer - The buffer to decompress
-* @param contentEncoding - The content-encoding header value (e.g., 'gzip', 'deflate')
-* @returns A Future with the decompressed buffer or a TechnicalError
-*
-* @internal
-*/
-function decompressBuffer(buffer, contentEncoding) {
-	if (!contentEncoding) return Future.value(Result.Ok(buffer));
-	const normalizedEncoding = contentEncoding.toLowerCase();
-	if (!isSupportedEncoding(normalizedEncoding)) return Future.value(Result.Error(new TechnicalError(`Unsupported content-encoding: "${contentEncoding}". Supported encodings are: ${SUPPORTED_ENCODINGS.join(", ")}. Please check your publisher configuration.`)));
-	switch (normalizedEncoding) {
-		case "gzip": return Future.fromPromise(gunzipAsync(buffer)).mapError((error) => new TechnicalError("Failed to decompress gzip", error));
-		case "deflate": return Future.fromPromise(inflateAsync(buffer)).mapError((error) => new TechnicalError("Failed to decompress deflate", error));
-	}
-}
-
 //#endregion
 //#region src/worker.ts
 /**
@@ -220,7 +217,7 @@ function isHandlerTuple(entry) {
 * import { defineQueue, defineMessage, defineContract, defineConsumer } from '@amqp-contract/contract';
 * import { z } from 'zod';
 *
-* const orderQueue = defineQueue('order-processing', { durable: true });
+* const orderQueue = defineQueue('order-processing');
 * const orderMessage = defineMessage(z.object({
 *   orderId: z.string(),
 *   amount: z.number()
@@ -255,9 +252,10 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 	consumerOptions;
 	consumerTags = /* @__PURE__ */ new Set();
 	telemetry;
-	constructor(contract, amqpClient, handlers, logger, telemetry) {
+	constructor(contract, amqpClient, handlers, defaultConsumerOptions, logger, telemetry) {
 		this.contract = contract;
 		this.amqpClient = amqpClient;
+		this.defaultConsumerOptions = defaultConsumerOptions;
 		this.logger = logger;
 		this.telemetry = telemetry ?? defaultTelemetryProvider;
 		this.actualHandlers = {};
@@ -269,8 +267,14 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 			if (isHandlerTuple(handlerEntry)) {
 				const [handler, options] = handlerEntry;
 				this.actualHandlers[typedConsumerName] = handler;
-				this.consumerOptions[typedConsumerName] = options;
-			} else this.actualHandlers[typedConsumerName] = handlerEntry;
+				this.consumerOptions[typedConsumerName] = {
+					...this.defaultConsumerOptions,
+					...options
+				};
+			} else {
+				this.actualHandlers[typedConsumerName] = handlerEntry;
+				this.consumerOptions[typedConsumerName] = this.defaultConsumerOptions;
+			}
 		}
 	}
 	/**
@@ -298,11 +302,11 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 	* }).resultToPromise();
 	* ```
 	*/
-	static create({ contract, handlers, urls, connectionOptions, logger, telemetry }) {
+	static create({ contract, handlers, urls, connectionOptions, defaultConsumerOptions, logger, telemetry }) {
 		const worker = new TypedAmqpWorker(contract, new AmqpClient(contract, {
 			urls,
 			connectionOptions
-		}), handlers, logger, telemetry);
+		}), handlers, defaultConsumerOptions ?? {}, logger, telemetry);
 		return worker.waitForConnectionReady().flatMapOk(() => worker.consumeAll()).mapOk(() => worker);
 	}
 	/**
@@ -337,7 +341,7 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 	* Defaults are applied in the contract's defineQueue, so we just return the config.
 	*/
 	getRetryConfigForConsumer(consumer) {
-		return consumer.queue.retry;
+		return extractQueue(consumer.queue).retry;
 	}
 	/**
 	* Start consuming messages for all consumers.
@@ -346,13 +350,6 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 	consumeAll() {
 		const consumers = this.contract.consumers;
 		const consumerNames = Object.keys(consumers);
-		const maxPrefetch = consumerNames.reduce((max, name) => {
-			const prefetch = this.consumerOptions[name]?.prefetch;
-			return prefetch ? Math.max(max, prefetch) : max;
-		}, 0);
-		if (maxPrefetch > 0) this.amqpClient.addSetup(async (channel) => {
-			await channel.prefetch(maxPrefetch);
-		});
 		return Future.all(consumerNames.map((name) => this.consume(name))).map(Result.all).mapOk(() => void 0);
 	}
 	waitForConnectionReady() {
@@ -391,9 +388,10 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 	* @returns Ok with validated message (payload + headers), or Error (message already nacked)
 	*/
 	parseAndValidateMessage(msg, consumer, consumerName) {
+		const queue = extractQueue(consumer.queue);
 		const context = {
 			consumerName: String(consumerName),
-			queueName: consumer.queue.name
+			queueName: queue.name
 		};
 		const nackAndError = (message, error) => {
 			this.logger?.error(message, {
@@ -426,7 +424,7 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 	* Consume messages one at a time
 	*/
 	consumeSingle(consumerName, consumer, handler) {
-		const queueName = consumer.queue.name;
+		const queueName = extractQueue(consumer.queue).name;
 		return this.amqpClient.consume(queueName, async (msg) => {
 			if (msg === null) {
 				this.logger?.warn("Consumer cancelled by server", {
@@ -463,7 +461,7 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 				endSpanError(span, /* @__PURE__ */ new Error("Message validation failed"));
 				recordConsumeMetric(this.telemetry, queueName, String(consumerName), false, durationMs);
 			}).toPromise();
-		}).tapOk((consumerTag) => {
+		}, this.consumerOptions[consumerName]).tapOk((consumerTag) => {
 			this.consumerTags.add(consumerTag);
 		}).mapError((error) => new TechnicalError(`Failed to start consuming for "${String(consumerName)}"`, error)).mapOk(() => void 0);
 	}
@@ -472,17 +470,18 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 	*
 	* Flow depends on retry mode:
 	*
-	* **quorum-native mode:**
+	* **immediate-requeue mode:**
 	* 1. If NonRetryableError -> send directly to DLQ (no retry)
-	* 2. Otherwise -> nack with requeue=true (RabbitMQ handles delivery count)
+	* 2. If max retries exceeded -> send to DLQ
+	* 3. Otherwise -> requeue immediately for retry
 	*
 	* **ttl-backoff mode:**
 	* 1. If NonRetryableError -> send directly to DLQ (no retry)
 	* 2. If max retries exceeded -> send to DLQ
 	* 3. Otherwise -> publish to wait queue with TTL for retry
 	*
-	* **Legacy mode (no retry config):**
-	* 1. nack with requeue=true (immediate requeue)
+	* **none mode (no retry config):**
+	* 1. send directly to DLQ (no retry)
 	*/
 	handleError(error, msg, consumerName, consumer) {
 		if (error instanceof NonRetryableError) {
@@ -495,52 +494,98 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 			return Future.value(Result.Ok(void 0));
 		}
 		const config = this.getRetryConfigForConsumer(consumer);
-		if (config.mode === "quorum-native") return this.handleErrorQuorumNative(error, msg, consumerName, consumer);
-		return this.handleErrorTtlBackoff(error, msg, consumerName, consumer, config);
+		if (config.mode === "immediate-requeue") return this.handleErrorImmediateRequeue(error, msg, consumerName, consumer, config);
+		if (config.mode === "ttl-backoff") return this.handleErrorTtlBackoff(error, msg, consumerName, consumer, config);
+		this.logger?.warn("Retry disabled (none mode), sending to DLQ", {
+			consumerName,
+			error: error.message
+		});
+		this.sendToDLQ(msg, consumer);
+		return Future.value(Result.Ok(void 0));
 	}
 	/**
-	* Handle error using quorum queue's native delivery limit feature.
+	* Handle error by requeuing immediately.
 	*
-	* Simply requeues the message with nack(requeue=true). RabbitMQ automatically:
-	* - Increments x-delivery-count header
-	* - Dead-letters the message when count exceeds x-delivery-limit
+	* For quorum queues, messages are requeued with `nack(requeue=true)`, and the worker tracks delivery count via the native RabbitMQ `x-delivery-count` header.
+	* For classic queues, messages are re-published on the same queue, and the worker tracks delivery count via a custom `x-retry-count` header.
+	* When the count exceeds `maxRetries`, the message is automatically dead-lettered (if DLX is configured) or dropped.
 	*
 	* This is simpler than TTL-based retry but provides immediate retries only.
 	*/
-	handleErrorQuorumNative(error, msg, consumerName, consumer) {
-		const queue = consumer.queue;
+	handleErrorImmediateRequeue(error, msg, consumerName, consumer, config) {
+		const queue = extractQueue(consumer.queue);
 		const queueName = queue.name;
-		const deliveryCount = msg.properties.headers?.["x-delivery-count"] ?? 0;
-		const deliveryLimit = queue.type === "quorum" ? queue.deliveryLimit : void 0;
-		const attemptsBeforeDeadLetter = deliveryLimit !== void 0 ? Math.max(0, deliveryLimit - deliveryCount - 1) : "unknown";
-		if (deliveryLimit !== void 0 && deliveryCount >= deliveryLimit - 1) this.logger?.warn("Message at final delivery attempt (quorum-native mode)", {
+		const retryCount = queue.type === "quorum" ? msg.properties.headers?.["x-delivery-count"] ?? 0 : msg.properties.headers?.["x-retry-count"] ?? 0;
+		if (retryCount >= config.maxRetries) {
+			this.logger?.error("Max retries exceeded, sending to DLQ (immediate-requeue mode)", {
+				consumerName,
+				queueName,
+				retryCount,
+				maxRetries: config.maxRetries,
+				error: error.message
+			});
+			this.sendToDLQ(msg, consumer);
+			return Future.value(Result.Ok(void 0));
+		}
+		this.logger?.warn("Retrying message (immediate-requeue mode)", {
 			consumerName,
 			queueName,
-			deliveryCount,
-			deliveryLimit,
-			willDeadLetterOnNextFailure: deliveryCount === deliveryLimit - 1,
-			alreadyExceededLimit: deliveryCount >= deliveryLimit,
+			retryCount,
+			maxRetries: config.maxRetries,
 			error: error.message
 		});
-		else this.logger?.warn("Retrying message (quorum-native mode)", {
-			consumerName,
+		if (queue.type === "quorum") {
+			this.amqpClient.nack(msg, false, true);
+			return Future.value(Result.Ok(void 0));
+		} else return this.publishForRetry({
+			msg,
+			exchange: msg.fields.exchange,
+			routingKey: msg.fields.routingKey,
 			queueName,
-			deliveryCount,
-			deliveryLimit,
-			attemptsBeforeDeadLetter,
-			error: error.message
+			error
 		});
-		this.amqpClient.nack(msg, false, true);
-		return Future.value(Result.Ok(void 0));
 	}
 	/**
 	* Handle error using TTL + wait queue pattern for exponential backoff.
+	*
+	* ┌─────────────────────────────────────────────────────────────────┐
+	* │ Retry Flow (Native RabbitMQ TTL + Wait queue pattern)           │
+	* ├─────────────────────────────────────────────────────────────────┤
+	* │                                                                 │
+	* │ 1. Handler throws any Error                                     │
+	* │    ↓                                                            │
+	* │ 2. Worker publishes to wait exchange                            |
+	* |    (with header `x-wait-queue` set to the wait queue name)      │
+	* │    ↓                                                            │
+	* │ 3. Wait exchange routes to wait queue                           │
+	* │    (with expiration: calculated backoff delay)                  │
+	* │    ↓                                                            │
+	* │ 4. Message waits in queue until TTL expires                     │
+	* │    ↓                                                            │
+	* │ 5. Expired message dead-lettered to retry exchange              |
+	* |    (with header `x-retry-queue` set to the main queue name)     │
+	* │    ↓                                                            │
+	* │ 6. Retry exchange routes back to main queue → RETRY             │
+	* │    ↓                                                            │
+	* │ 7. If retries exhausted: nack without requeue → DLQ             │
+	* │                                                                 │
+	* └─────────────────────────────────────────────────────────────────┘
 	*/
 	handleErrorTtlBackoff(error, msg, consumerName, consumer, config) {
+		if (!isQueueWithTtlBackoffInfrastructure(consumer.queue)) {
+			this.logger?.error("Queue does not have TTL-backoff infrastructure", {
+				consumerName,
+				queueName: consumer.queue.name
+			});
+			return Future.value(Result.Error(new TechnicalError("Queue does not have TTL-backoff infrastructure")));
+		}
+		const queueEntry = consumer.queue;
+		const queueName = extractQueue(queueEntry).name;
 		const retryCount = msg.properties.headers?.["x-retry-count"] ?? 0;
 		if (retryCount >= config.maxRetries) {
-			this.logger?.error("Max retries exceeded, sending to DLQ", {
+			this.logger?.error("Max retries exceeded, sending to DLQ (ttl-backoff mode)", {
 				consumerName,
+				queueName,
 				retryCount,
 				maxRetries: config.maxRetries,
 				error: error.message
@@ -551,11 +596,21 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 		const delayMs = this.calculateRetryDelay(retryCount, config);
 		this.logger?.warn("Retrying message (ttl-backoff mode)", {
 			consumerName,
+			queueName,
 			retryCount: retryCount + 1,
+			maxRetries: config.maxRetries,
 			delayMs,
 			error: error.message
 		});
-		return this.publishForRetry(msg, consumer, retryCount + 1, delayMs, error);
+		return this.publishForRetry({
+			msg,
+			exchange: queueEntry.waitExchange.name,
+			routingKey: msg.fields.routingKey,
+			waitQueueName: queueEntry.waitQueue.name,
+			queueName,
+			delayMs,
+			error
+		});
 	}
 	/**
 	* Calculate retry delay with exponential backoff and optional jitter.
@@ -583,65 +638,38 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 		return content;
 	}
 	/**
-	* Publish message to wait queue for retry after TTL expires.
-	*
-	* ┌─────────────────────────────────────────────────────────────────┐
-	* │ Retry Flow (Native RabbitMQ TTL + DLX Pattern)                   │
-	* ├─────────────────────────────────────────────────────────────────┤
-	* │                                                                   │
-	* │ 1. Handler throws any Error                                      │
-	* │    ↓                                                              │
-	* │ 2. Worker publishes to DLX with routing key: {queue}-wait        │
-	* │    ↓                                                              │
-	* │ 3. DLX routes to wait queue: {queue}-wait                        │
-	* │    (with expiration: calculated backoff delay)                   │
-	* │    ↓                                                              │
-	* │ 4. Message waits in queue until TTL expires                      │
-	* │    ↓                                                              │
-	* │ 5. Expired message dead-lettered to DLX                          │
-	* │    (with routing key: {queue})                                   │
-	* │    ↓                                                              │
-	* │ 6. DLX routes back to main queue → RETRY                         │
-	* │    ↓                                                              │
-	* │ 7. If retries exhausted: nack without requeue → DLQ              │
-	* │                                                                   │
-	* └─────────────────────────────────────────────────────────────────┘
+	* Publish message with an incremented x-retry-count header and optional TTL.
 	*/
-	publishForRetry(msg, consumer, newRetryCount, delayMs, error) {
-		const queueName = consumer.queue.name;
-		const deadLetter = consumer.queue.deadLetter;
-		if (!deadLetter) {
-			this.logger?.warn("Cannot retry: queue does not have DLX configured, falling back to nack with requeue", { queueName });
-			this.amqpClient.nack(msg, false, true);
-			return Future.value(Result.Ok(void 0));
-		}
-		const dlxName = deadLetter.exchange.name;
-		const waitRoutingKey = `${queueName}-wait`;
+	publishForRetry({ msg, exchange, routingKey, queueName, waitQueueName, delayMs, error }) {
+		const newRetryCount = (msg.properties.headers?.["x-retry-count"] ?? 0) + 1;
 		this.amqpClient.ack(msg);
 		const content = this.parseMessageContentForRetry(msg, queueName);
-		return this.amqpClient.publish(dlxName, waitRoutingKey, content, {
+		return this.amqpClient.publish(exchange, routingKey, content, {
 			...msg.properties,
-			expiration: delayMs.toString(),
+			...delayMs !== void 0 ? { expiration: delayMs.toString() } : {},
 			headers: {
 				...msg.properties.headers,
 				"x-retry-count": newRetryCount,
 				"x-last-error": error.message,
-				"x-first-failure-timestamp": msg.properties.headers?.["x-first-failure-timestamp"] ?? Date.now()
+				"x-first-failure-timestamp": msg.properties.headers?.["x-first-failure-timestamp"] ?? Date.now(),
+				...waitQueueName !== void 0 ? {
+					"x-wait-queue": waitQueueName,
+					"x-retry-queue": queueName
+				} : {}
 			}
 		}).mapOkToResult((published) => {
 			if (!published) {
 				this.logger?.error("Failed to publish message for retry (write buffer full)", {
 					queueName,
-					waitRoutingKey,
-					retryCount: newRetryCount
+					retryCount: newRetryCount,
+					...delayMs !== void 0 ? { delayMs } : {}
 				});
 				return Result.Error(new TechnicalError("Failed to publish message for retry (write buffer full)"));
 			}
 			this.logger?.info("Message published for retry", {
 				queueName,
-				waitRoutingKey,
 				retryCount: newRetryCount,
-				delayMs
+				...delayMs !== void 0 ? { delayMs } : {}
 			});
 			return Result.Ok(void 0);
 		});
@@ -651,8 +679,9 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 	* Nacks the message without requeue, relying on DLX configuration.
 	*/
 	sendToDLQ(msg, consumer) {
-		const queueName = consumer.queue.name;
-		if (!(consumer.queue.deadLetter !== void 0)) this.logger?.warn("Queue does not have DLX configured - message will be lost on nack", { queueName });
+		const queue = extractQueue(consumer.queue);
+		const queueName = queue.name;
+		if (!(queue.deadLetter !== void 0)) this.logger?.warn("Queue does not have DLX configured - message will be lost on nack", { queueName });
 		this.logger?.info("Sending message to DLQ", {
 			queueName,
 			deliveryTag: msg.fields.deliveryTag
@@ -660,7 +689,6 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 		this.amqpClient.nack(msg, false, false);
 	}
 };
-
 //#endregion
 //#region src/handlers.ts
 /**
@@ -721,7 +749,7 @@ function defineHandlers(contract, handlers) {
 	validateHandlers(contract, handlers);
 	return handlers;
 }
-
 //#endregion
 export { MessageValidationError, NonRetryableError, RetryableError, TypedAmqpWorker, defineHandler, defineHandlers, isHandlerError, isNonRetryableError, isRetryableError, nonRetryable, retryable };
+
 //# sourceMappingURL=index.mjs.map