@amqp-contract/worker 0.21.0 → 0.23.0

package/dist/index.mjs

@@ -196,6 +196,240 @@ function nonRetryable(message, cause) {
 	return new NonRetryableError(message, cause);
 }
 //#endregion
+//#region src/retry.ts
+/**
+* Handle error in message processing with retry logic.
+*
+* Flow depends on retry mode:
+*
+* **immediate-requeue mode:**
+* 1. If NonRetryableError -> send directly to DLQ (no retry)
+* 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
+*
+* **none mode (no retry config):**
+* 1. send directly to DLQ (no retry)
+*/
+function handleError(ctx, error, msg, consumerName, consumer) {
+	if (error instanceof NonRetryableError) {
+		ctx.logger?.error("Non-retryable error, sending to DLQ immediately", {
+			consumerName,
+			errorType: error.name,
+			error: error.message
+		});
+		sendToDLQ(ctx, msg, consumer);
+		return Future.value(Result.Ok(void 0));
+	}
+	const config = extractQueue(consumer.queue).retry;
+	if (config.mode === "immediate-requeue") return handleErrorImmediateRequeue(ctx, error, msg, consumerName, consumer, config);
+	if (config.mode === "ttl-backoff") return handleErrorTtlBackoff(ctx, error, msg, consumerName, consumer, config);
+	ctx.logger?.warn("Retry disabled (none mode), sending to DLQ", {
+		consumerName,
+		error: error.message
+	});
+	sendToDLQ(ctx, msg, consumer);
+	return Future.value(Result.Ok(void 0));
+}
+/**
+* Handle error by requeuing immediately.
+*
+* 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.
+*/
+function handleErrorImmediateRequeue(ctx, error, msg, consumerName, consumer, config) {
+	const queue = extractQueue(consumer.queue);
+	const queueName = queue.name;
+	const retryCount = queue.type === "quorum" ? msg.properties.headers?.["x-delivery-count"] ?? 0 : msg.properties.headers?.["x-retry-count"] ?? 0;
+	if (retryCount >= config.maxRetries) {
+		ctx.logger?.error("Max retries exceeded, sending to DLQ (immediate-requeue mode)", {
+			consumerName,
+			queueName,
+			retryCount,
+			maxRetries: config.maxRetries,
+			error: error.message
+		});
+		sendToDLQ(ctx, msg, consumer);
+		return Future.value(Result.Ok(void 0));
+	}
+	ctx.logger?.warn("Retrying message (immediate-requeue mode)", {
+		consumerName,
+		queueName,
+		retryCount,
+		maxRetries: config.maxRetries,
+		error: error.message
+	});
+	if (queue.type === "quorum") {
+		ctx.amqpClient.nack(msg, false, true);
+		return Future.value(Result.Ok(void 0));
+	} else return publishForRetry(ctx, {
+		msg,
+		exchange: msg.fields.exchange,
+		routingKey: msg.fields.routingKey,
+		queueName,
+		error
+	});
+}
+/**
+* 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             │
+* │                                                                 │
+* └─────────────────────────────────────────────────────────────────┘
+*/
+function handleErrorTtlBackoff(ctx, error, msg, consumerName, consumer, config) {
+	if (!isQueueWithTtlBackoffInfrastructure(consumer.queue)) {
+		ctx.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) {
+		ctx.logger?.error("Max retries exceeded, sending to DLQ (ttl-backoff mode)", {
+			consumerName,
+			queueName,
+			retryCount,
+			maxRetries: config.maxRetries,
+			error: error.message
+		});
+		sendToDLQ(ctx, msg, consumer);
+		return Future.value(Result.Ok(void 0));
+	}
+	const delayMs = calculateRetryDelay(retryCount, config);
+	ctx.logger?.warn("Retrying message (ttl-backoff mode)", {
+		consumerName,
+		queueName,
+		retryCount: retryCount + 1,
+		maxRetries: config.maxRetries,
+		delayMs,
+		error: error.message
+	});
+	return publishForRetry(ctx, {
+		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.
+*/
+function calculateRetryDelay(retryCount, config) {
+	const { initialDelayMs, maxDelayMs, backoffMultiplier, jitter } = config;
+	let delay = Math.min(initialDelayMs * Math.pow(backoffMultiplier, retryCount), maxDelayMs);
+	if (jitter) delay = delay * (.5 + Math.random() * .5);
+	return Math.floor(delay);
+}
+/**
+* Parse message content for republishing.
+*
+* The channel is configured with `json: true`, so values published as plain
+* objects are encoded once at publish time. Re-publishing the raw `Buffer`
+* would then trigger a *second* JSON.stringify (turning the bytes into a
+* stringified base64 blob), so for JSON payloads we must round-trip back to
+* the parsed value. For any other content type — or when the message is
+* compressed — we pass the bytes through untouched, since re-parsing would
+* either fail or silently corrupt binary data.
+*/
+function parseMessageContentForRetry(ctx, msg, queueName) {
+	if (msg.properties.contentEncoding) return msg.content;
+	const contentType = msg.properties.contentType;
+	if (!(contentType === void 0 || contentType === "application/json" || contentType.startsWith("application/json;") || contentType.endsWith("+json"))) return msg.content;
+	try {
+		return JSON.parse(msg.content.toString());
+	} catch (err) {
+		ctx.logger?.warn("Failed to parse JSON message for retry, using original buffer", {
+			queueName,
+			error: err
+		});
+		return msg.content;
+	}
+}
+/**
+* Publish message with an incremented x-retry-count header and optional TTL.
+*/
+function publishForRetry(ctx, { msg, exchange, routingKey, queueName, waitQueueName, delayMs, error }) {
+	const newRetryCount = (msg.properties.headers?.["x-retry-count"] ?? 0) + 1;
+	ctx.amqpClient.ack(msg);
+	const content = parseMessageContentForRetry(ctx, msg, queueName);
+	return ctx.amqpClient.publish(exchange, routingKey, content, {
+		...msg.properties,
+		...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(),
+			...waitQueueName !== void 0 ? {
+				"x-wait-queue": waitQueueName,
+				"x-retry-queue": queueName
+			} : {}
+		}
+	}).mapOkToResult((published) => {
+		if (!published) {
+			ctx.logger?.error("Failed to publish message for retry (write buffer full)", {
+				queueName,
+				retryCount: newRetryCount,
+				...delayMs !== void 0 ? { delayMs } : {}
+			});
+			return Result.Error(new TechnicalError("Failed to publish message for retry (write buffer full)"));
+		}
+		ctx.logger?.info("Message published for retry", {
+			queueName,
+			retryCount: newRetryCount,
+			...delayMs !== void 0 ? { delayMs } : {}
+		});
+		return Result.Ok(void 0);
+	});
+}
+/**
+* Send message to dead letter queue.
+* Nacks the message without requeue, relying on DLX configuration.
+*/
+function sendToDLQ(ctx, msg, consumer) {
+	const queue = extractQueue(consumer.queue);
+	const queueName = queue.name;
+	if (!(queue.deadLetter !== void 0)) ctx.logger?.warn("Queue does not have DLX configured - message will be lost on nack", { queueName });
+	ctx.logger?.info("Sending message to DLQ", {
+		queueName,
+		deliveryTag: msg.fields.deliveryTag
+	});
+	ctx.amqpClient.nack(msg, false, false);
+}
+//#endregion
 //#region src/worker.ts
 /**
 * Type guard to check if a handler entry is a tuple format [handler, options].
@@ -246,7 +480,10 @@ function isHandlerTuple(entry) {
 */
 var TypedAmqpWorker = class TypedAmqpWorker {
 	/**
-	* Internal handler storage - handlers returning `Future<Result>`.
+	* Internal handler storage. Keyed by handler name (consumer or RPC); the
+	* stored function signature is widened so the dispatch loop can call it
+	* uniformly. The actual handler is type-checked at the worker's public API
+	* boundary via `WorkerInferHandlers<TContract>`.
 	*/
 	actualHandlers;
 	consumerOptions;
@@ -261,23 +498,49 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 		this.actualHandlers = {};
 		this.consumerOptions = {};
 		const handlersRecord = handlers;
-		for (const consumerName of Object.keys(handlersRecord)) {
-			const handlerEntry = handlersRecord[consumerName];
-			const typedConsumerName = consumerName;
+		for (const handlerName of Object.keys(handlersRecord)) {
+			const handlerEntry = handlersRecord[handlerName];
+			const typedName = handlerName;
 			if (isHandlerTuple(handlerEntry)) {
 				const [handler, options] = handlerEntry;
-				this.actualHandlers[typedConsumerName] = handler;
-				this.consumerOptions[typedConsumerName] = {
+				this.actualHandlers[typedName] = handler;
+				this.consumerOptions[typedName] = {
 					...this.defaultConsumerOptions,
 					...options
 				};
 			} else {
-				this.actualHandlers[typedConsumerName] = handlerEntry;
-				this.consumerOptions[typedConsumerName] = this.defaultConsumerOptions;
+				this.actualHandlers[typedName] = handlerEntry;
+				this.consumerOptions[typedName] = this.defaultConsumerOptions;
 			}
 		}
 	}
 	/**
+	* Build a `ConsumerDefinition`-shaped view for a handler name, regardless
+	* of whether it came from `contract.consumers` or `contract.rpcs`. The
+	* dispatch path treats both uniformly; the returned `isRpc` flag (and the
+	* accompanying `responseSchema`) tells `processMessage` whether to validate
+	* the handler return value and publish a reply.
+	*/
+	resolveConsumerView(name) {
+		const rpcs = this.contract.rpcs;
+		if (rpcs && Object.hasOwn(rpcs, name)) {
+			const rpc = rpcs[name];
+			return {
+				consumer: {
+					queue: rpc.queue,
+					message: rpc.request
+				},
+				isRpc: true,
+				responseSchema: rpc.response.payload
+			};
+		}
+		const consumerEntry = this.contract.consumers[name];
+		return {
+			consumer: extractConsumer(consumerEntry),
+			isRpc: false
+		};
+	}
+	/**
 	* Create a type-safe AMQP worker from a contract.
 	*
 	* Connection management (including automatic reconnection) is handled internally
@@ -302,12 +565,18 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 	* }).resultToPromise();
 	* ```
 	*/
-	static create({ contract, handlers, urls, connectionOptions, defaultConsumerOptions, logger, telemetry }) {
+	static create({ contract, handlers, urls, connectionOptions, defaultConsumerOptions, logger, telemetry, connectTimeoutMs }) {
 		const worker = new TypedAmqpWorker(contract, new AmqpClient(contract, {
 			urls,
-			connectionOptions
+			connectionOptions,
+			connectTimeoutMs
 		}), handlers, defaultConsumerOptions ?? {}, logger, telemetry);
-		return worker.waitForConnectionReady().flatMapOk(() => worker.consumeAll()).mapOk(() => worker);
+		return worker.waitForConnectionReady().flatMapOk(() => worker.consumeAll()).flatMap((result) => result.match({
+			Ok: () => Future.value(Result.Ok(worker)),
+			Error: (error) => worker.close().tapError((closeError) => {
+				logger?.warn("Failed to close worker after setup failure", { error: closeError });
+			}).map(() => Result.Error(error))
+		}));
 	}
 	/**
 	* Close the AMQP channel and connection.
@@ -337,356 +606,202 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 		}).flatMapOk(() => this.amqpClient.close()).mapOk(() => void 0);
 	}
 	/**
-	* Get the retry configuration for a consumer's queue.
-	* Defaults are applied in the contract's defineQueue, so we just return the config.
-	*/
-	getRetryConfigForConsumer(consumer) {
-		return extractQueue(consumer.queue).retry;
-	}
-	/**
-	* Start consuming messages for all consumers.
-	* TypeScript guarantees consumers exist (handlers require matching consumers).
+	* Start consuming for every entry in `contract.consumers` and `contract.rpcs`.
 	*/
 	consumeAll() {
-		const consumers = this.contract.consumers;
-		const consumerNames = Object.keys(consumers);
-		return Future.all(consumerNames.map((name) => this.consume(name))).map(Result.all).mapOk(() => void 0);
+		const consumerNames = Object.keys(this.contract.consumers ?? {});
+		const rpcNames = Object.keys(this.contract.rpcs ?? {});
+		const allNames = [...consumerNames, ...rpcNames];
+		return Future.all(allNames.map((name) => this.consume(name))).map(Result.all).mapOk(() => void 0);
 	}
 	waitForConnectionReady() {
 		return this.amqpClient.waitForConnect();
 	}
 	/**
-	* Start consuming messages for a specific consumer.
-	* TypeScript guarantees consumer and handler exist for valid consumer names.
+	* Start consuming messages for a specific handler — either a `consumers`
+	* entry (regular event/command consumer) or an `rpcs` entry (RPC server).
 	*/
-	consume(consumerName) {
-		const consumerEntry = this.contract.consumers[consumerName];
-		const consumer = extractConsumer(consumerEntry);
-		const handler = this.actualHandlers[consumerName];
-		return this.consumeSingle(consumerName, consumer, handler);
+	consume(name) {
+		const view = this.resolveConsumerView(name);
+		const handler = this.actualHandlers[name];
+		return this.consumeSingle(name, view, handler);
 	}
 	/**
-	* Validate data against a Standard Schema and handle errors.
+	* Validate data against a Standard Schema. No side effects; the caller is
+	* responsible for ack/nack based on the Result.
 	*/
-	validateSchema(schema, data, context, msg) {
+	validateSchema(schema, data, context) {
 		const rawValidation = schema["~standard"].validate(data);
 		const validationPromise = rawValidation instanceof Promise ? rawValidation : Promise.resolve(rawValidation);
 		return Future.fromPromise(validationPromise).mapError((error) => new TechnicalError(`Error validating ${context.field}`, error)).mapOkToResult((result) => {
 			if (result.issues) return Result.Error(new TechnicalError(`${context.field} validation failed`, new MessageValidationError(context.consumerName, result.issues)));
 			return Result.Ok(result.value);
-		}).tapError((error) => {
-			this.logger?.error(`${context.field} validation failed`, {
-				consumerName: context.consumerName,
-				queueName: context.queueName,
-				error
-			});
-			this.amqpClient.nack(msg, false, false);
 		});
 	}
 	/**
-	* Parse and validate a message from AMQP.
-	* @returns Ok with validated message (payload + headers), or Error (message already nacked)
+	* Parse and validate a message from AMQP. Pure: returns the validated payload
+	* and headers, or an error. The dispatch path in {@link processMessage} routes
+	* validation/parse errors directly to the DLQ (single nack) — they never enter
+	* the retry pipeline because retrying an unparseable or schema-violating
+	* payload cannot succeed.
 	*/
 	parseAndValidateMessage(msg, consumer, consumerName) {
-		const queue = extractQueue(consumer.queue);
-		const context = {
-			consumerName: String(consumerName),
-			queueName: queue.name
-		};
-		const nackAndError = (message, error) => {
-			this.logger?.error(message, {
-				...context,
-				error
-			});
-			this.amqpClient.nack(msg, false, false);
-			return new TechnicalError(message, error);
-		};
-		const parsePayload = decompressBuffer(msg.content, msg.properties.contentEncoding).tapError((error) => {
-			this.logger?.error("Failed to decompress message", {
-				...context,
-				error
-			});
-			this.amqpClient.nack(msg, false, false);
-		}).mapOkToResult((buffer) => Result.fromExecution(() => JSON.parse(buffer.toString())).mapError((error) => nackAndError("Failed to parse JSON", error))).flatMapOk((parsed) => this.validateSchema(consumer.message.payload, parsed, {
+		const context = { consumerName: String(consumerName) };
+		const parsePayload = decompressBuffer(msg.content, msg.properties.contentEncoding).mapErrorToResult((error) => Result.Error(new TechnicalError("Failed to decompress message", error))).mapOkToResult((buffer) => Result.fromExecution(() => JSON.parse(buffer.toString())).mapError((error) => new TechnicalError("Failed to parse JSON", error))).flatMapOk((parsed) => this.validateSchema(consumer.message.payload, parsed, {
 			...context,
 			field: "payload"
-		}, msg));
+		}));
 		const parseHeaders = consumer.message.headers ? this.validateSchema(consumer.message.headers, msg.properties.headers ?? {}, {
 			...context,
 			field: "headers"
-		}, msg) : Future.value(Result.Ok(void 0));
+		}) : Future.value(Result.Ok(void 0));
 		return Future.allFromDict({
 			payload: parsePayload,
 			headers: parseHeaders
 		}).map(Result.allFromDict);
 	}
 	/**
-	* Consume messages one at a time
+	* Validate an RPC handler's response and publish it back to the caller's reply
+	* queue with the same `correlationId`. Published via the AMQP default exchange
+	* with `routingKey = msg.properties.replyTo`, which works for both
+	* `amq.rabbitmq.reply-to` and any anonymous queue declared by the caller.
+	*
+	* Failure semantics:
+	* - **Missing replyTo / correlationId**: NonRetryableError. The caller is
+	*   already lost; retrying the original message cannot recover the reply
+	*   path. The poison message lands in DLQ for inspection rather than being
+	*   silently ack'd (which would mask a contract violation).
+	* - **Schema validation failure**: NonRetryableError — the handler returned
+	*   the wrong shape; retrying the same input will not fix it.
+	* - **Publish failure**: NonRetryableError. The caller has already timed out
+	*   (or will shortly), so retrying the message wastes the queue's retry
+	*   budget on a reply that no one is waiting for. The message is logged and
+	*   DLQ'd; the original work is treated as completed for the purpose of the
+	*   inbox.
+	*/
+	publishRpcResponse(msg, queueName, rpcName, responseSchema, response) {
+		const replyTo = msg.properties.replyTo;
+		const correlationId = msg.properties.correlationId;
+		if (typeof replyTo !== "string" || replyTo.length === 0) {
+			this.logger?.error("RPC handler returned a response but the incoming message has no replyTo", {
+				rpcName: String(rpcName),
+				queueName
+			});
+			return Future.value(Result.Error(new NonRetryableError(`RPC "${String(rpcName)}" received a message without replyTo; cannot deliver response`)));
+		}
+		if (typeof correlationId !== "string" || correlationId.length === 0) {
+			this.logger?.error("RPC handler returned a response but the incoming message has no correlationId", {
+				rpcName: String(rpcName),
+				queueName,
+				replyTo
+			});
+			return Future.value(Result.Error(new NonRetryableError(`RPC "${String(rpcName)}" received a message without correlationId; cannot deliver response`)));
+		}
+		let rawValidation;
+		try {
+			rawValidation = responseSchema["~standard"].validate(response);
+		} catch (error) {
+			return Future.value(Result.Error(new NonRetryableError("RPC response schema validation threw", error)));
+		}
+		const validationPromise = rawValidation instanceof Promise ? rawValidation : Promise.resolve(rawValidation);
+		return Future.fromPromise(validationPromise).mapError((error) => new NonRetryableError("RPC response schema validation threw", error)).mapOkToResult((validation) => {
+			if (validation.issues) return Result.Error(new NonRetryableError(`RPC response for "${String(rpcName)}" failed schema validation`, new MessageValidationError(String(rpcName), validation.issues)));
+			return Result.Ok(validation.value);
+		}).flatMapOk((validatedResponse) => this.amqpClient.publish("", replyTo, validatedResponse, {
+			correlationId,
+			contentType: "application/json"
+		}).mapErrorToResult((error) => Result.Error(new NonRetryableError("Failed to publish RPC response", error))).mapOkToResult((published) => published ? Result.Ok(void 0) : Result.Error(new NonRetryableError("Failed to publish RPC response: channel buffer full"))));
+	}
+	/**
+	* Process a single consumed message: validate, invoke handler, optionally
+	* publish the RPC response, record telemetry, and handle errors.
 	*/
-	consumeSingle(consumerName, consumer, handler) {
+	processMessage(msg, view, name, handler) {
+		const { consumer, isRpc, responseSchema } = view;
 		const queueName = extractQueue(consumer.queue).name;
-		return this.amqpClient.consume(queueName, async (msg) => {
-			if (msg === null) {
-				this.logger?.warn("Consumer cancelled by server", {
-					consumerName: String(consumerName),
-					queueName
+		const startTime = Date.now();
+		const span = startConsumeSpan(this.telemetry, queueName, String(name), { "messaging.rabbitmq.message.delivery_tag": msg.fields.deliveryTag });
+		let messageHandled = false;
+		let firstError;
+		return this.parseAndValidateMessage(msg, consumer, name).flatMap((parseResult) => parseResult.match({
+			Ok: (validatedMessage) => handler(validatedMessage, msg).flatMapOk((handlerResponse) => {
+				if (isRpc && responseSchema) return this.publishRpcResponse(msg, queueName, name, responseSchema, handlerResponse).flatMapOk(() => {
+					this.logger?.info("Message consumed successfully", {
+						consumerName: String(name),
+						queueName
+					});
+					this.amqpClient.ack(msg);
+					messageHandled = true;
+					return Future.value(Result.Ok(void 0));
 				});
-				return;
-			}
-			const startTime = Date.now();
-			const span = startConsumeSpan(this.telemetry, queueName, String(consumerName), { "messaging.rabbitmq.message.delivery_tag": msg.fields.deliveryTag });
-			await this.parseAndValidateMessage(msg, consumer, consumerName).flatMapOk((validatedMessage) => handler(validatedMessage, msg).flatMapOk(() => {
 				this.logger?.info("Message consumed successfully", {
-					consumerName: String(consumerName),
+					consumerName: String(name),
 					queueName
 				});
 				this.amqpClient.ack(msg);
-				const durationMs = Date.now() - startTime;
-				endSpanSuccess(span);
-				recordConsumeMetric(this.telemetry, queueName, String(consumerName), true, durationMs);
+				messageHandled = true;
 				return Future.value(Result.Ok(void 0));
 			}).flatMapError((handlerError) => {
 				this.logger?.error("Error processing message", {
-					consumerName: String(consumerName),
+					consumerName: String(name),
 					queueName,
 					errorType: handlerError.name,
 					error: handlerError.message
 				});
-				const durationMs = Date.now() - startTime;
-				endSpanError(span, handlerError);
-				recordConsumeMetric(this.telemetry, queueName, String(consumerName), false, durationMs);
-				return this.handleError(handlerError, msg, String(consumerName), consumer);
-			})).tapError(() => {
-				const durationMs = Date.now() - startTime;
-				endSpanError(span, /* @__PURE__ */ new Error("Message validation failed"));
-				recordConsumeMetric(this.telemetry, queueName, String(consumerName), false, durationMs);
-			}).toPromise();
-		}, this.consumerOptions[consumerName]).tapOk((consumerTag) => {
-			this.consumerTags.add(consumerTag);
-		}).mapError((error) => new TechnicalError(`Failed to start consuming for "${String(consumerName)}"`, error)).mapOk(() => void 0);
-	}
-	/**
-	* Handle error in message processing with retry logic.
-	*
-	* Flow depends on retry mode:
-	*
-	* **immediate-requeue mode:**
-	* 1. If NonRetryableError -> send directly to DLQ (no retry)
-	* 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
-	*
-	* **none mode (no retry config):**
-	* 1. send directly to DLQ (no retry)
-	*/
-	handleError(error, msg, consumerName, consumer) {
-		if (error instanceof NonRetryableError) {
-			this.logger?.error("Non-retryable error, sending to DLQ immediately", {
-				consumerName,
-				errorType: error.name,
-				error: error.message
-			});
-			this.sendToDLQ(msg, consumer);
-			return Future.value(Result.Ok(void 0));
-		}
-		const config = this.getRetryConfigForConsumer(consumer);
-		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 by requeuing immediately.
-	*
-	* 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.
-	*/
-	handleErrorImmediateRequeue(error, msg, consumerName, consumer, config) {
-		const queue = extractQueue(consumer.queue);
-		const queueName = queue.name;
-		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,
-			retryCount,
-			maxRetries: config.maxRetries,
-			error: error.message
-		});
-		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,
-			error
-		});
-	}
-	/**
-	* 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 (ttl-backoff mode)", {
-				consumerName,
-				queueName,
-				retryCount,
-				maxRetries: config.maxRetries,
-				error: error.message
-			});
-			this.sendToDLQ(msg, consumer);
-			return Future.value(Result.Ok(void 0));
-		}
-		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,
-			exchange: queueEntry.waitExchange.name,
-			routingKey: msg.fields.routingKey,
-			waitQueueName: queueEntry.waitQueue.name,
-			queueName,
-			delayMs,
-			error
+				firstError = handlerError;
+				return handleError({
+					amqpClient: this.amqpClient,
+					logger: this.logger
+				}, handlerError, msg, String(name), consumer);
+			}),
+			Error: (parseError) => {
+				firstError = parseError;
+				this.logger?.error("Failed to parse/validate message; sending to DLQ", {
+					consumerName: String(name),
+					queueName,
+					error: parseError
+				});
+				this.amqpClient.nack(msg, false, false);
+				return Future.value(Result.Error(parseError));
+			}
+		})).map((result) => {
+			const durationMs = Date.now() - startTime;
+			if (messageHandled) {
+				endSpanSuccess(span);
+				recordConsumeMetric(this.telemetry, queueName, String(name), true, durationMs);
+			} else {
+				endSpanError(span, result.isError() ? result.error : firstError ?? /* @__PURE__ */ new Error("Unknown error"));
+				recordConsumeMetric(this.telemetry, queueName, String(name), false, durationMs);
+			}
+			return result;
 		});
 	}
 	/**
-	* Calculate retry delay with exponential backoff and optional jitter.
-	*/
-	calculateRetryDelay(retryCount, config) {
-		const { initialDelayMs, maxDelayMs, backoffMultiplier, jitter } = config;
-		let delay = Math.min(initialDelayMs * Math.pow(backoffMultiplier, retryCount), maxDelayMs);
-		if (jitter) delay = delay * (.5 + Math.random() * .5);
-		return Math.floor(delay);
-	}
-	/**
-	* Parse message content for republishing.
-	* Prevents double JSON serialization by converting Buffer to object when possible.
-	*/
-	parseMessageContentForRetry(msg, queueName) {
-		let content = msg.content;
-		if (!msg.properties.contentEncoding) try {
-			content = JSON.parse(msg.content.toString());
-		} catch (err) {
-			this.logger?.warn("Failed to parse message for retry, using original buffer", {
-				queueName,
-				error: err
-			});
-		}
-		return content;
-	}
-	/**
-	* Publish message with an incremented x-retry-count header and optional TTL.
+	* Consume messages one at a time.
 	*/
-	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(exchange, routingKey, content, {
-			...msg.properties,
-			...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(),
-				...waitQueueName !== void 0 ? {
-					"x-wait-queue": waitQueueName,
-					"x-retry-queue": queueName
-				} : {}
+	consumeSingle(name, view, handler) {
+		const queueName = extractQueue(view.consumer.queue).name;
+		return this.amqpClient.consume(queueName, async (msg) => {
+			if (msg === null) {
+				this.logger?.warn("Consumer cancelled by server", {
+					consumerName: String(name),
+					queueName
+				});
+				return;
 			}
-		}).mapOkToResult((published) => {
-			if (!published) {
-				this.logger?.error("Failed to publish message for retry (write buffer full)", {
+			try {
+				await this.processMessage(msg, view, name, handler).toPromise();
+			} catch (error) {
+				this.logger?.error("Uncaught error in consume callback; nacking message", {
+					consumerName: String(name),
 					queueName,
-					retryCount: newRetryCount,
-					...delayMs !== void 0 ? { delayMs } : {}
+					error
 				});
-				return Result.Error(new TechnicalError("Failed to publish message for retry (write buffer full)"));
+				this.amqpClient.nack(msg, false, false);
 			}
-			this.logger?.info("Message published for retry", {
-				queueName,
-				retryCount: newRetryCount,
-				...delayMs !== void 0 ? { delayMs } : {}
-			});
-			return Result.Ok(void 0);
-		});
-	}
-	/**
-	* Send message to dead letter queue.
-	* Nacks the message without requeue, relying on DLX configuration.
-	*/
-	sendToDLQ(msg, consumer) {
-		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
-		});
-		this.amqpClient.nack(msg, false, false);
+		}, this.consumerOptions[name]).tapOk((consumerTag) => {
+			this.consumerTags.add(consumerTag);
+		}).mapError((error) => new TechnicalError(`Failed to start consuming for "${String(name)}"`, error)).mapOk(() => void 0);
 	}
 };
 //#endregion