@amqp-contract/worker 0.21.0 → 0.22.0

package/dist/index.mjs

@@ -196,6 +196,231 @@ 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.
+* 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 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 +471,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 +489,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 +556,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,33 +597,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 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.
@@ -421,272 +673,117 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 		}).map(Result.allFromDict);
 	}
 	/**
-	* Consume messages one at a time
-	*/
-	consumeSingle(consumerName, consumer, handler) {
-		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
-				});
-				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),
-					queueName
-				});
-				this.amqpClient.ack(msg);
-				const durationMs = Date.now() - startTime;
-				endSpanSuccess(span);
-				recordConsumeMetric(this.telemetry, queueName, String(consumerName), true, durationMs);
-				return Future.value(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;
-				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:
+	* 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.
 	*
-	* **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)
+	* 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 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,
+		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,
-				retryCount,
-				maxRetries: config.maxRetries,
-				error: error.message
+				replyTo
 			});
-			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
-		});
+		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 RetryableError("Failed to publish RPC response", error))).mapOkToResult((published) => published ? Result.Ok(void 0) : Result.Error(new RetryableError("Failed to publish RPC response: channel buffer full"))));
 	}
 	/**
-	* 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             │
-	* │                                                                 │
-	* └─────────────────────────────────────────────────────────────────┘
+	* Process a single consumed message: validate, invoke handler, optionally
+	* publish the RPC response, record telemetry, and handle errors.
 	*/
-	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
+	processMessage(msg, view, name, handler) {
+		const { consumer, isRpc, responseSchema } = view;
+		const queueName = extractQueue(consumer.queue).name;
+		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).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
+				});
+				this.amqpClient.ack(msg);
+				messageHandled = true;
+				return Future.value(Result.Ok(void 0));
 			});
-			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.logger?.info("Message consumed successfully", {
+				consumerName: String(name),
+				queueName
 			});
-			this.sendToDLQ(msg, consumer);
+			this.amqpClient.ack(msg);
+			messageHandled = true;
 			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
-		});
-	}
-	/**
-	* 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", {
+		}).flatMapError((handlerError) => {
+			this.logger?.error("Error processing message", {
+				consumerName: String(name),
 				queueName,
-				error: err
+				errorType: handlerError.name,
+				error: handlerError.message
 			});
-		}
-		return content;
-	}
-	/**
-	* Publish message with an incremented x-retry-count header and optional TTL.
-	*/
-	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
-				} : {}
-			}
-		}).mapOkToResult((published) => {
-			if (!published) {
-				this.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)"));
+			firstError = handlerError;
+			return handleError({
+				amqpClient: this.amqpClient,
+				logger: this.logger
+			}, handlerError, msg, String(name), consumer);
+		})).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);
 			}
-			this.logger?.info("Message published for retry", {
-				queueName,
-				retryCount: newRetryCount,
-				...delayMs !== void 0 ? { delayMs } : {}
-			});
-			return Result.Ok(void 0);
+			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 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);
+	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;
+			}
+			await this.processMessage(msg, view, name, handler).toPromise();
+		}, 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