@amqp-contract/worker 0.20.0 → 0.22.0

package/dist/index.cjs

@@ -1,10 +1,41 @@
-Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-let _amqp_contract_core = require("@amqp-contract/core");
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let _amqp_contract_contract = require("@amqp-contract/contract");
+let _amqp_contract_core = require("@amqp-contract/core");
 let _swan_io_boxed = require("@swan-io/boxed");
 let node_zlib = require("node:zlib");
 let node_util = require("node:util");
-
+//#region src/decompression.ts
+const gunzipAsync = (0, node_util.promisify)(node_zlib.gunzip);
+const inflateAsync = (0, node_util.promisify)(node_zlib.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 _swan_io_boxed.Future.value(_swan_io_boxed.Result.Ok(buffer));
+	const normalizedEncoding = contentEncoding.toLowerCase();
+	if (!isSupportedEncoding(normalizedEncoding)) return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Error(new _amqp_contract_core.TechnicalError(`Unsupported content-encoding: "${contentEncoding}". Supported encodings are: ${SUPPORTED_ENCODINGS.join(", ")}. Please check your publisher configuration.`)));
+	switch (normalizedEncoding) {
+		case "gzip": return _swan_io_boxed.Future.fromPromise(gunzipAsync(buffer)).mapError((error) => new _amqp_contract_core.TechnicalError("Failed to decompress gzip", error));
+		case "deflate": return _swan_io_boxed.Future.fromPromise(inflateAsync(buffer)).mapError((error) => new _amqp_contract_core.TechnicalError("Failed to decompress deflate", error));
+	}
+}
+//#endregion
 //#region src/errors.ts
 /**
 * Retryable errors - transient failures that may succeed on retry
@@ -165,40 +196,231 @@ function retryable(message, cause) {
 function nonRetryable(message, cause) {
 	return new NonRetryableError(message, cause);
 }
-
 //#endregion
-//#region src/decompression.ts
-const gunzipAsync = (0, node_util.promisify)(node_zlib.gunzip);
-const inflateAsync = (0, node_util.promisify)(node_zlib.inflate);
+//#region src/retry.ts
 /**
-* Supported content encodings for message decompression.
-*/
-const SUPPORTED_ENCODINGS = ["gzip", "deflate"];
-/**
-* Type guard to check if a string is a supported encoding.
+* 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 isSupportedEncoding(encoding) {
-	return SUPPORTED_ENCODINGS.includes(encoding.toLowerCase());
+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 _swan_io_boxed.Future.value(_swan_io_boxed.Result.Ok(void 0));
+	}
+	const config = (0, _amqp_contract_contract.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 _swan_io_boxed.Future.value(_swan_io_boxed.Result.Ok(void 0));
 }
 /**
-* Decompress a buffer based on the content-encoding header.
+* Handle error by requeuing immediately.
 *
-* @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
+* 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.
 *
-* @internal
+* This is simpler than TTL-based retry but provides immediate retries only.
 */
-function decompressBuffer(buffer, contentEncoding) {
-	if (!contentEncoding) return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Ok(buffer));
-	const normalizedEncoding = contentEncoding.toLowerCase();
-	if (!isSupportedEncoding(normalizedEncoding)) return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Error(new _amqp_contract_core.TechnicalError(`Unsupported content-encoding: "${contentEncoding}". Supported encodings are: ${SUPPORTED_ENCODINGS.join(", ")}. Please check your publisher configuration.`)));
-	switch (normalizedEncoding) {
-		case "gzip": return _swan_io_boxed.Future.fromPromise(gunzipAsync(buffer)).mapError((error) => new _amqp_contract_core.TechnicalError("Failed to decompress gzip", error));
-		case "deflate": return _swan_io_boxed.Future.fromPromise(inflateAsync(buffer)).mapError((error) => new _amqp_contract_core.TechnicalError("Failed to decompress deflate", error));
+function handleErrorImmediateRequeue(ctx, error, msg, consumerName, consumer, config) {
+	const queue = (0, _amqp_contract_contract.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 _swan_io_boxed.Future.value(_swan_io_boxed.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 _swan_io_boxed.Future.value(_swan_io_boxed.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 (!(0, _amqp_contract_contract.isQueueWithTtlBackoffInfrastructure)(consumer.queue)) {
+		ctx.logger?.error("Queue does not have TTL-backoff infrastructure", {
+			consumerName,
+			queueName: consumer.queue.name
+		});
+		return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Error(new _amqp_contract_core.TechnicalError("Queue does not have TTL-backoff infrastructure")));
+	}
+	const queueEntry = consumer.queue;
+	const queueName = (0, _amqp_contract_contract.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 _swan_io_boxed.Future.value(_swan_io_boxed.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.
+* Prevents double JSON serialization by converting Buffer to object when possible.
+*/
+function parseMessageContentForRetry(ctx, msg, queueName) {
+	let content = msg.content;
+	if (!msg.properties.contentEncoding) try {
+		content = JSON.parse(msg.content.toString());
+	} catch (err) {
+		ctx.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.
+*/
+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 _swan_io_boxed.Result.Error(new _amqp_contract_core.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 _swan_io_boxed.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 = (0, _amqp_contract_contract.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
 /**
@@ -221,7 +443,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()
@@ -250,31 +472,67 @@ 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;
 	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 ?? _amqp_contract_core.defaultTelemetryProvider;
 		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] = options;
-			} else this.actualHandlers[typedConsumerName] = handlerEntry;
+				this.actualHandlers[typedName] = handler;
+				this.consumerOptions[typedName] = {
+					...this.defaultConsumerOptions,
+					...options
+				};
+			} else {
+				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: (0, _amqp_contract_contract.extractConsumer)(consumerEntry),
+			isRpc: false
+		};
+	}
+	/**
 	* Create a type-safe AMQP worker from a contract.
 	*
 	* Connection management (including automatic reconnection) is handled internally
@@ -299,12 +557,18 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 	* }).resultToPromise();
 	* ```
 	*/
-	static create({ contract, handlers, urls, connectionOptions, logger, telemetry }) {
+	static create({ contract, handlers, urls, connectionOptions, defaultConsumerOptions, logger, telemetry, connectTimeoutMs }) {
 		const worker = new TypedAmqpWorker(contract, new _amqp_contract_core.AmqpClient(contract, {
 			urls,
-			connectionOptions
-		}), handlers, logger, telemetry);
-		return worker.waitForConnectionReady().flatMapOk(() => worker.consumeAll()).mapOk(() => worker);
+			connectionOptions,
+			connectTimeoutMs
+		}), handlers, defaultConsumerOptions ?? {}, logger, telemetry);
+		return worker.waitForConnectionReady().flatMapOk(() => worker.consumeAll()).flatMap((result) => result.match({
+			Ok: () => _swan_io_boxed.Future.value(_swan_io_boxed.Result.Ok(worker)),
+			Error: (error) => worker.close().tapError((closeError) => {
+				logger?.warn("Failed to close worker after setup failure", { error: closeError });
+			}).map(() => _swan_io_boxed.Result.Error(error))
+		}));
 	}
 	/**
 	* Close the AMQP channel and connection.
@@ -334,40 +598,25 @@ 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 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);
-		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 _swan_io_boxed.Future.all(consumerNames.map((name) => this.consume(name))).map(_swan_io_boxed.Result.all).mapOk(() => void 0);
+		const consumerNames = Object.keys(this.contract.consumers ?? {});
+		const rpcNames = Object.keys(this.contract.rpcs ?? {});
+		const allNames = [...consumerNames, ...rpcNames];
+		return _swan_io_boxed.Future.all(allNames.map((name) => this.consume(name))).map(_swan_io_boxed.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 = (0, _amqp_contract_contract.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.
@@ -392,9 +641,10 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 	* @returns Ok with validated message (payload + headers), or Error (message already nacked)
 	*/
 	parseAndValidateMessage(msg, consumer, consumerName) {
+		const queue = (0, _amqp_contract_contract.extractQueue)(consumer.queue);
 		const context = {
 			consumerName: String(consumerName),
-			queueName: consumer.queue.name
+			queueName: queue.name
 		};
 		const nackAndError = (message, error) => {
 			this.logger?.error(message, {
@@ -424,244 +674,119 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 		}).map(_swan_io_boxed.Result.allFromDict);
 	}
 	/**
-	* Consume messages one at a time
-	*/
-	consumeSingle(consumerName, consumer, handler) {
-		const queueName = consumer.queue.name;
-		return this.amqpClient.consume(queueName, async (msg) => {
-			if (msg === null) {
-				this.logger?.warn("Consumer cancelled by server", {
-					consumerName: String(consumerName),
-					queueName
-				});
-				return;
-			}
-			const startTime = Date.now();
-			const span = (0, _amqp_contract_core.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),
-					queueName
-				});
-				this.amqpClient.ack(msg);
-				const durationMs = Date.now() - startTime;
-				(0, _amqp_contract_core.endSpanSuccess)(span);
-				(0, _amqp_contract_core.recordConsumeMetric)(this.telemetry, queueName, String(consumerName), true, durationMs);
-				return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Ok(void 0));
-			}).flatMapError((handlerError) => {
-				this.logger?.error("Error processing message", {
-					consumerName: String(consumerName),
-					queueName,
-					errorType: handlerError.name,
-					error: handlerError.message
-				});
-				const durationMs = Date.now() - startTime;
-				(0, _amqp_contract_core.endSpanError)(span, handlerError);
-				(0, _amqp_contract_core.recordConsumeMetric)(this.telemetry, queueName, String(consumerName), false, durationMs);
-				return this.handleError(handlerError, msg, String(consumerName), consumer);
-			})).tapError(() => {
-				const durationMs = Date.now() - startTime;
-				(0, _amqp_contract_core.endSpanError)(span, /* @__PURE__ */ new Error("Message validation failed"));
-				(0, _amqp_contract_core.recordConsumeMetric)(this.telemetry, queueName, String(consumerName), false, durationMs);
-			}).toPromise();
-		}).tapOk((consumerTag) => {
-			this.consumerTags.add(consumerTag);
-		}).mapError((error) => new _amqp_contract_core.TechnicalError(`Failed to start consuming for "${String(consumerName)}"`, error)).mapOk(() => void 0);
-	}
-	/**
-	* Handle error in message processing with retry logic.
+	* 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.
 	*
-	* Flow depends on retry mode:
-	*
-	* **quorum-native mode:**
-	* 1. If NonRetryableError -> send directly to DLQ (no retry)
-	* 2. Otherwise -> nack with requeue=true (RabbitMQ handles delivery count)
-	*
-	* **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)
+	* Validation errors are surfaced as NonRetryableError (handler returned the
+	* wrong shape — retrying the same input will not fix it). Publish errors are
+	* surfaced as RetryableError so the worker's existing retry logic applies.
 	*/
-	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
+	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?.warn("RPC handler returned a response but the incoming message has no replyTo; dropping response", {
+				rpcName: String(rpcName),
+				queueName
 			});
-			this.sendToDLQ(msg, consumer);
 			return _swan_io_boxed.Future.value(_swan_io_boxed.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);
-	}
-	/**
-	* Handle error using quorum queue's native delivery limit feature.
-	*
-	* 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
-	*
-	* This is simpler than TTL-based retry but provides immediate retries only.
-	*/
-	handleErrorQuorumNative(error, msg, consumerName, consumer) {
-		const queue = 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)", {
-			consumerName,
-			queueName,
-			deliveryCount,
-			deliveryLimit,
-			willDeadLetterOnNextFailure: deliveryCount === deliveryLimit - 1,
-			alreadyExceededLimit: deliveryCount >= deliveryLimit,
-			error: error.message
-		});
-		else this.logger?.warn("Retrying message (quorum-native mode)", {
-			consumerName,
-			queueName,
-			deliveryCount,
-			deliveryLimit,
-			attemptsBeforeDeadLetter,
-			error: error.message
-		});
-		this.amqpClient.nack(msg, false, true);
-		return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Ok(void 0));
-	}
-	/**
-	* Handle error using TTL + wait queue pattern for exponential backoff.
-	*/
-	handleErrorTtlBackoff(error, msg, consumerName, consumer, config) {
-		const retryCount = msg.properties.headers?.["x-retry-count"] ?? 0;
-		if (retryCount >= config.maxRetries) {
-			this.logger?.error("Max retries exceeded, sending to DLQ", {
-				consumerName,
-				retryCount,
-				maxRetries: config.maxRetries,
-				error: error.message
+		if (typeof correlationId !== "string" || correlationId.length === 0) {
+			this.logger?.warn("RPC handler returned a response but the incoming message has no correlationId; dropping response", {
+				rpcName: String(rpcName),
+				queueName,
+				replyTo
 			});
-			this.sendToDLQ(msg, consumer);
 			return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Ok(void 0));
 		}
-		const delayMs = this.calculateRetryDelay(retryCount, config);
-		this.logger?.warn("Retrying message (ttl-backoff mode)", {
-			consumerName,
-			retryCount: retryCount + 1,
-			delayMs,
-			error: error.message
-		});
-		return this.publishForRetry(msg, consumer, retryCount + 1, delayMs, error);
-	}
-	/**
-	* 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
-			});
+		let rawValidation;
+		try {
+			rawValidation = responseSchema["~standard"].validate(response);
+		} catch (error) {
+			return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Error(new NonRetryableError("RPC response schema validation threw", error)));
 		}
-		return content;
+		const validationPromise = rawValidation instanceof Promise ? rawValidation : Promise.resolve(rawValidation);
+		return _swan_io_boxed.Future.fromPromise(validationPromise).mapError((error) => new NonRetryableError("RPC response schema validation threw", error)).mapOkToResult((validation) => {
+			if (validation.issues) return _swan_io_boxed.Result.Error(new NonRetryableError(`RPC response for "${String(rpcName)}" failed schema validation`, new _amqp_contract_core.MessageValidationError(String(rpcName), validation.issues)));
+			return _swan_io_boxed.Result.Ok(validation.value);
+		}).flatMapOk((validatedResponse) => this.amqpClient.publish("", replyTo, validatedResponse, {
+			correlationId,
+			contentType: "application/json"
+		}).mapErrorToResult((error) => _swan_io_boxed.Result.Error(new RetryableError("Failed to publish RPC response", error))).mapOkToResult((published) => published ? _swan_io_boxed.Result.Ok(void 0) : _swan_io_boxed.Result.Error(new RetryableError("Failed to publish RPC response: channel buffer full"))));
 	}
 	/**
-	* 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              │
-	* │                                                                   │
-	* └─────────────────────────────────────────────────────────────────┘
+	* Process a single consumed message: validate, invoke handler, optionally
+	* publish the RPC response, record telemetry, and handle errors.
 	*/
-	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 _swan_io_boxed.Future.value(_swan_io_boxed.Result.Ok(void 0));
-		}
-		const dlxName = deadLetter.exchange.name;
-		const waitRoutingKey = `${queueName}-wait`;
-		this.amqpClient.ack(msg);
-		const content = this.parseMessageContentForRetry(msg, queueName);
-		return this.amqpClient.publish(dlxName, waitRoutingKey, content, {
-			...msg.properties,
-			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()
-			}
-		}).mapOkToResult((published) => {
-			if (!published) {
-				this.logger?.error("Failed to publish message for retry (write buffer full)", {
-					queueName,
-					waitRoutingKey,
-					retryCount: newRetryCount
+	processMessage(msg, view, name, handler) {
+		const { consumer, isRpc, responseSchema } = view;
+		const queueName = (0, _amqp_contract_contract.extractQueue)(consumer.queue).name;
+		const startTime = Date.now();
+		const span = (0, _amqp_contract_core.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).flatMapOk((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
 				});
-				return _swan_io_boxed.Result.Error(new _amqp_contract_core.TechnicalError("Failed to publish message for retry (write buffer full)"));
-			}
-			this.logger?.info("Message published for retry", {
+				this.amqpClient.ack(msg);
+				messageHandled = true;
+				return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Ok(void 0));
+			});
+			this.logger?.info("Message consumed successfully", {
+				consumerName: String(name),
+				queueName
+			});
+			this.amqpClient.ack(msg);
+			messageHandled = true;
+			return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Ok(void 0));
+		}).flatMapError((handlerError) => {
+			this.logger?.error("Error processing message", {
+				consumerName: String(name),
 				queueName,
-				waitRoutingKey,
-				retryCount: newRetryCount,
-				delayMs
+				errorType: handlerError.name,
+				error: handlerError.message
 			});
-			return _swan_io_boxed.Result.Ok(void 0);
+			firstError = handlerError;
+			return handleError({
+				amqpClient: this.amqpClient,
+				logger: this.logger
+			}, handlerError, msg, String(name), consumer);
+		})).map((result) => {
+			const durationMs = Date.now() - startTime;
+			if (messageHandled) {
+				(0, _amqp_contract_core.endSpanSuccess)(span);
+				(0, _amqp_contract_core.recordConsumeMetric)(this.telemetry, queueName, String(name), true, durationMs);
+			} else {
+				(0, _amqp_contract_core.endSpanError)(span, result.isError() ? result.error : firstError ?? /* @__PURE__ */ new Error("Unknown error"));
+				(0, _amqp_contract_core.recordConsumeMetric)(this.telemetry, queueName, String(name), false, durationMs);
+			}
+			return result;
 		});
 	}
 	/**
-	* Send message to dead letter queue.
-	* Nacks the message without requeue, relying on DLX configuration.
+	* Consume messages one at a time.
 	*/
-	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 });
-		this.logger?.info("Sending message to DLQ", {
-			queueName,
-			deliveryTag: msg.fields.deliveryTag
-		});
-		this.amqpClient.nack(msg, false, false);
+	consumeSingle(name, view, handler) {
+		const queueName = (0, _amqp_contract_contract.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;
+			}
+			await this.processMessage(msg, view, name, handler).toPromise();
+		}, this.consumerOptions[name]).tapOk((consumerTag) => {
+			this.consumerTags.add(consumerTag);
+		}).mapError((error) => new _amqp_contract_core.TechnicalError(`Failed to start consuming for "${String(name)}"`, error)).mapOk(() => void 0);
 	}
 };
-
 //#endregion
 //#region src/handlers.ts
 /**
@@ -722,13 +847,12 @@ function defineHandlers(contract, handlers) {
 	validateHandlers(contract, handlers);
 	return handlers;
 }
-
 //#endregion
-Object.defineProperty(exports, 'MessageValidationError', {
-  enumerable: true,
-  get: function () {
-    return _amqp_contract_core.MessageValidationError;
-  }
+Object.defineProperty(exports, "MessageValidationError", {
+	enumerable: true,
+	get: function() {
+		return _amqp_contract_core.MessageValidationError;
+	}
 });
 exports.NonRetryableError = NonRetryableError;
 exports.RetryableError = RetryableError;
@@ -739,4 +863,4 @@ exports.isHandlerError = isHandlerError;
 exports.isNonRetryableError = isNonRetryableError;
 exports.isRetryableError = isRetryableError;
 exports.nonRetryable = nonRetryable;
-exports.retryable = retryable;
+exports.retryable = retryable;