@amqp-contract/worker 0.9.0 → 0.11.0

package/dist/index.cjs

@@ -92,6 +92,23 @@ async function decompressBuffer(buffer, contentEncoding) {
 //#endregion
 //#region src/worker.ts
 /**
+* Type guard to check if a handler entry is a tuple format [handler, options].
+*/
+function isHandlerTuple(entry) {
+	return Array.isArray(entry) && entry.length === 2;
+}
+/**
+* Type guard to check if a value is a Standard Schema v1 compliant schema.
+*/
+function isStandardSchema(value) {
+	if (typeof value !== "object" || value === null) return false;
+	if (!("~standard" in value)) return false;
+	const standard = value["~standard"];
+	if (typeof standard !== "object" || standard === null) return false;
+	if (!("validate" in standard)) return false;
+	return typeof standard.validate === "function";
+}
+/**
 * Type-safe AMQP worker for consuming messages from RabbitMQ.
 *
 * This class provides automatic message validation, connection management,
@@ -133,16 +150,13 @@ async function decompressBuffer(buffer, contentEncoding) {
 */
 var TypedAmqpWorker = class TypedAmqpWorker {
 	/**
-	* Internal handler type - always safe handlers (`Future<Result>`).
-	* Unsafe handlers are wrapped into safe handlers by defineUnsafeHandler/defineUnsafeHandlers.
+	* Internal handler storage - handlers returning `Future<Result>`.
 	*/
 	actualHandlers;
 	consumerOptions;
-	batchTimers = /* @__PURE__ */ new Map();
 	consumerTags = /* @__PURE__ */ new Set();
-	retryConfig;
 	telemetry;
-	constructor(contract, amqpClient, handlers, logger, retryOptions, telemetry) {
+	constructor(contract, amqpClient, handlers, logger, telemetry) {
 		this.contract = contract;
 		this.amqpClient = amqpClient;
 		this.logger = logger;
@@ -153,19 +167,12 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 		for (const consumerName of Object.keys(handlersRecord)) {
 			const handlerEntry = handlersRecord[consumerName];
 			const typedConsumerName = consumerName;
-			if (Array.isArray(handlerEntry)) {
-				this.actualHandlers[typedConsumerName] = handlerEntry[0];
-				this.consumerOptions[typedConsumerName] = handlerEntry[1];
+			if (isHandlerTuple(handlerEntry)) {
+				const [handler, options] = handlerEntry;
+				this.actualHandlers[typedConsumerName] = handler;
+				this.consumerOptions[typedConsumerName] = options;
 			} else this.actualHandlers[typedConsumerName] = handlerEntry;
 		}
-		if (retryOptions === void 0) this.retryConfig = null;
-		else this.retryConfig = {
-			maxRetries: retryOptions.maxRetries ?? 3,
-			initialDelayMs: retryOptions.initialDelayMs ?? 1e3,
-			maxDelayMs: retryOptions.maxDelayMs ?? 3e4,
-			backoffMultiplier: retryOptions.backoffMultiplier ?? 2,
-			jitter: retryOptions.jitter ?? true
-		};
 	}
 	/**
 	* Create a type-safe AMQP worker from a contract.
@@ -186,18 +193,18 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 	* const worker = await TypedAmqpWorker.create({
 	*   contract: myContract,
 	*   handlers: {
-	*     processOrder: async (msg) => console.log('Order:', msg.orderId)
+	*     processOrder: async ({ payload }) => console.log('Order:', payload.orderId)
 	*   },
 	*   urls: ['amqp://localhost']
 	* }).resultToPromise();
 	* ```
 	*/
-	static create({ contract, handlers, urls, connectionOptions, logger, retry, telemetry }) {
+	static create({ contract, handlers, urls, connectionOptions, logger, telemetry }) {
 		const worker = new TypedAmqpWorker(contract, new _amqp_contract_core.AmqpClient(contract, {
 			urls,
 			connectionOptions
-		}), handlers, logger, retry, telemetry);
-		return worker.waitForConnectionReady().flatMapOk(() => worker.setupWaitQueues()).flatMapOk(() => worker.consumeAll()).mapOk(() => worker);
+		}), handlers, logger, telemetry);
+		return worker.waitForConnectionReady().flatMapOk(() => worker.validateRetryConfiguration()).flatMapOk(() => worker.consumeAll()).mapOk(() => worker);
 	}
 	/**
 	* Close the AMQP channel and connection.
@@ -216,8 +223,6 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 	* ```
 	*/
 	close() {
-		for (const timer of this.batchTimers.values()) clearTimeout(timer);
-		this.batchTimers.clear();
 		return _swan_io_boxed.Future.all(Array.from(this.consumerTags).map((consumerTag) => _swan_io_boxed.Future.fromPromise(this.amqpClient.channel.cancel(consumerTag)).mapErrorToResult((error) => {
 			this.logger?.warn("Failed to cancel consumer during close", {
 				consumerTag,
@@ -229,40 +234,82 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 		}).flatMapOk(() => _swan_io_boxed.Future.fromPromise(this.amqpClient.close())).mapError((error) => new TechnicalError("Failed to close AMQP connection", error)).mapOk(() => void 0);
 	}
 	/**
-	* Set up wait queues for retry mechanism.
-	* Creates and binds wait queues for each consumer queue that has DLX configuration.
+	* Validate retry configuration for all consumers.
+	*
+	* For quorum-native mode, validates that the queue is properly configured.
+	* For TTL-backoff mode, wait queues are created by setupAmqpTopology in the core package.
 	*/
-	setupWaitQueues() {
-		if (this.retryConfig === null) return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Ok(void 0));
-		if (!this.contract.consumers || !this.contract.queues) return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Ok(void 0));
-		const setupTasks = [];
+	validateRetryConfiguration() {
+		if (!this.contract.consumers) return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Ok(void 0));
 		for (const consumerName of Object.keys(this.contract.consumers)) {
 			const consumer = this.contract.consumers[consumerName];
 			if (!consumer) continue;
 			const queue = consumer.queue;
-			const deadLetter = queue.deadLetter;
-			if (!deadLetter) continue;
-			const queueName = queue.name;
-			const waitQueueName = `${queueName}-wait`;
-			const dlxName = deadLetter.exchange.name;
-			const setupTask = _swan_io_boxed.Future.fromPromise(this.amqpClient.channel.addSetup(async (channel) => {
-				await channel.assertQueue(waitQueueName, {
-					durable: queue.durable ?? false,
-					deadLetterExchange: dlxName,
-					deadLetterRoutingKey: queueName
-				});
-				await channel.bindQueue(waitQueueName, dlxName, `${queueName}-wait`);
-				this.logger?.info("Wait queue created and bound", {
+			if ((queue.retry?.mode ?? "ttl-backoff") === "quorum-native") {
+				const validationError = this.validateQuorumNativeConfigForConsumer(String(consumerName), consumer);
+				if (validationError) return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Error(validationError));
+				this.logger?.info("Using quorum-native retry mode", {
 					consumerName: String(consumerName),
-					queueName,
-					waitQueueName,
-					dlxName
+					queueName: queue.name
 				});
-			})).mapError((error) => new TechnicalError(`Failed to setup wait queue for "${String(consumerName)}"`, error));
-			setupTasks.push(setupTask);
+			} else if (queue.deadLetter) this.logger?.info("Using TTL-backoff retry mode", {
+				consumerName: String(consumerName),
+				queueName: queue.name
+			});
+			else this.logger?.warn("Queue has no deadLetter configured - retries will use nack with requeue", {
+				consumerName: String(consumerName),
+				queueName: queue.name
+			});
 		}
-		if (setupTasks.length === 0) return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Ok(void 0));
-		return _swan_io_boxed.Future.all(setupTasks).map(_swan_io_boxed.Result.all).mapOk(() => void 0);
+		return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Ok(void 0));
+	}
+	/**
+	* Get the resolved retry configuration for a consumer's queue.
+	* Reads retry config from the queue definition in the contract.
+	*/
+	getRetryConfigForConsumer(consumer) {
+		const retryOptions = consumer.queue.retry;
+		if (retryOptions?.mode === "quorum-native") return {
+			mode: "quorum-native",
+			maxRetries: 0,
+			initialDelayMs: 0,
+			maxDelayMs: 0,
+			backoffMultiplier: 0,
+			jitter: false
+		};
+		if (retryOptions?.mode === "ttl-backoff") return {
+			mode: "ttl-backoff",
+			maxRetries: retryOptions.maxRetries ?? 3,
+			initialDelayMs: retryOptions.initialDelayMs ?? 1e3,
+			maxDelayMs: retryOptions.maxDelayMs ?? 3e4,
+			backoffMultiplier: retryOptions.backoffMultiplier ?? 2,
+			jitter: retryOptions.jitter ?? true
+		};
+		return {
+			mode: "ttl-backoff",
+			maxRetries: 3,
+			initialDelayMs: 1e3,
+			maxDelayMs: 3e4,
+			backoffMultiplier: 2,
+			jitter: true
+		};
+	}
+	/**
+	* Validate that quorum-native retry mode is properly configured for a specific consumer.
+	*
+	* Requirements for quorum-native mode:
+	* - Consumer queue must be a quorum queue
+	* - Consumer queue must have deliveryLimit configured
+	* - Consumer queue should have DLX configured (warning if not)
+	*
+	* @returns TechnicalError if validation fails, null if valid
+	*/
+	validateQuorumNativeConfigForConsumer(consumerName, consumer) {
+		const queue = consumer.queue;
+		if (queue.type !== "quorum") return new TechnicalError(`Consumer "${consumerName}" uses queue "${queue.name}" with type "${queue.type}". Quorum-native retry mode requires quorum queues.`);
+		if (queue.deliveryLimit === void 0) return new TechnicalError(`Consumer "${consumerName}" uses queue "${queue.name}" without deliveryLimit configured. Quorum-native retry mode requires deliveryLimit to be set on the queue definition.`);
+		if (!queue.deadLetter) this.logger?.warn(`Consumer "${consumerName}" uses queue "${queue.name}" without deadLetter configured. Messages exceeding deliveryLimit will be dropped instead of dead-lettered.`);
+		return null;
 	}
 	/**
 	* Start consuming messages for all consumers
@@ -277,10 +324,6 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 				if (options.prefetch <= 0 || !Number.isInteger(options.prefetch)) return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Error(new TechnicalError(`Invalid prefetch value for "${String(consumerName)}": must be a positive integer`)));
 				maxPrefetch = Math.max(maxPrefetch, options.prefetch);
 			}
-			if (options?.batchSize !== void 0) {
-				const effectivePrefetch = options.prefetch ?? options.batchSize;
-				maxPrefetch = Math.max(maxPrefetch, effectivePrefetch);
-			}
 		}
 		if (maxPrefetch > 0) this.amqpClient.channel.addSetup(async (channel) => {
 			await channel.prefetch(maxPrefetch);
@@ -304,19 +347,11 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 		}
 		const handler = this.actualHandlers[consumerName];
 		if (!handler) return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Error(new TechnicalError(`Handler for "${String(consumerName)}" not provided`)));
-		const options = this.consumerOptions[consumerName] ?? {};
-		if (options.batchSize !== void 0) {
-			if (options.batchSize <= 0 || !Number.isInteger(options.batchSize)) return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Error(new TechnicalError(`Invalid batchSize for "${String(consumerName)}": must be a positive integer`)));
-		}
-		if (options.batchTimeout !== void 0) {
-			if (typeof options.batchTimeout !== "number" || !Number.isFinite(options.batchTimeout) || options.batchTimeout <= 0) return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Error(new TechnicalError(`Invalid batchTimeout for "${String(consumerName)}": must be a positive number`)));
-		}
-		if (options.batchSize !== void 0 && options.batchSize > 0) return this.consumeBatch(consumerName, consumer, options, handler);
-		else return this.consumeSingle(consumerName, consumer, handler);
+		return this.consumeSingle(consumerName, consumer, handler);
 	}
 	/**
 	* Parse and validate a message from AMQP
-	* @returns `Future<Result<validated message, void>>` - Ok with validated message, or Error (already handled with nack)
+	* @returns `Future<Result<consumed message, void>>` - Ok with validated consumed message (payload + headers), or Error (already handled with nack)
 	*/
 	parseAndValidateMessage(msg, consumer, consumerName) {
 		const decompressMessage = _swan_io_boxed.Future.fromPromise(decompressBuffer(msg.content, msg.properties.contentEncoding)).tapError((error) => {
@@ -327,7 +362,7 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 				error
 			});
 			this.amqpClient.channel.nack(msg, false, false);
-		});
+		}).mapError(() => void 0);
 		const parseMessage = (buffer) => {
 			const parseResult = _swan_io_boxed.Result.fromExecution(() => JSON.parse(buffer.toString()));
 			if (parseResult.isError()) {
@@ -341,12 +376,12 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 			}
 			return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Ok(parseResult.value));
 		};
-		const validateMessage = (parsedMessage) => {
+		const validatePayload = (parsedMessage) => {
 			const rawValidation = consumer.message.payload["~standard"].validate(parsedMessage);
-			return _swan_io_boxed.Future.fromPromise(rawValidation instanceof Promise ? rawValidation : Promise.resolve(rawValidation)).mapOkToResult((validationResult) => {
+			return _swan_io_boxed.Future.fromPromise(rawValidation instanceof Promise ? rawValidation : Promise.resolve(rawValidation)).mapError(() => void 0).mapOkToResult((validationResult) => {
 				if (validationResult.issues) {
 					const error = new MessageValidationError(String(consumerName), validationResult.issues);
-					this.logger?.error("Message validation failed", {
+					this.logger?.error("Message payload validation failed", {
 						consumerName: String(consumerName),
 						queueName: consumer.queue.name,
 						error
@@ -357,7 +392,45 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 				return _swan_io_boxed.Result.Ok(validationResult.value);
 			});
 		};
-		return decompressMessage.flatMapOk(parseMessage).flatMapOk(validateMessage);
+		const validateHeaders = () => {
+			const headersSchema = consumer.message.headers;
+			if (!headersSchema) return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Ok(void 0));
+			if (!isStandardSchema(headersSchema)) {
+				const error = new MessageValidationError(String(consumerName), "Invalid headers schema: not a Standard Schema v1 compliant schema");
+				this.logger?.error("Message headers validation failed", {
+					consumerName: String(consumerName),
+					queueName: consumer.queue.name,
+					error
+				});
+				this.amqpClient.channel.nack(msg, false, false);
+				return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Error(void 0));
+			}
+			const validSchema = headersSchema;
+			const rawHeaders = msg.properties.headers ?? {};
+			const rawValidation = validSchema["~standard"].validate(rawHeaders);
+			return _swan_io_boxed.Future.fromPromise(rawValidation instanceof Promise ? rawValidation : Promise.resolve(rawValidation)).mapError(() => void 0).mapOkToResult((validationResult) => {
+				if (validationResult.issues) {
+					const error = new MessageValidationError(String(consumerName), validationResult.issues);
+					this.logger?.error("Message headers validation failed", {
+						consumerName: String(consumerName),
+						queueName: consumer.queue.name,
+						error
+					});
+					this.amqpClient.channel.nack(msg, false, false);
+					return _swan_io_boxed.Result.Error(void 0);
+				}
+				return _swan_io_boxed.Result.Ok(validationResult.value);
+			});
+		};
+		const buildConsumedMessage = (validatedPayload) => {
+			return validateHeaders().mapOk((validatedHeaders) => {
+				return {
+					payload: validatedPayload,
+					headers: validatedHeaders
+				};
+			});
+		};
+		return decompressMessage.flatMapOk(parseMessage).flatMapOk(validatePayload).flatMapOk(buildConsumedMessage);
 	}
 	/**
 	* Consume messages one at a time
@@ -374,7 +447,7 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 			}
 			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).flatMapOk(() => {
+			await this.parseAndValidateMessage(msg, consumer, consumerName).flatMapOk((validatedMessage) => handler(validatedMessage, msg).flatMapOk(() => {
 				this.logger?.info("Message consumed successfully", {
 					consumerName: String(consumerName),
 					queueName
@@ -405,107 +478,21 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 		}).mapError((error) => new TechnicalError(`Failed to start consuming for "${String(consumerName)}"`, error)).mapOk(() => void 0);
 	}
 	/**
-	* Handle batch processing error by applying error handling to all messages.
-	*/
-	handleBatchError(error, currentBatch, consumerName, consumer) {
-		return _swan_io_boxed.Future.all(currentBatch.map((item) => this.handleError(error, item.amqpMessage, consumerName, consumer))).map(_swan_io_boxed.Result.all).mapOk(() => void 0);
-	}
-	/**
-	* Consume messages in batches
-	*/
-	consumeBatch(consumerName, consumer, options, handler) {
-		const batchSize = options.batchSize;
-		const batchTimeout = options.batchTimeout ?? 1e3;
-		const timerKey = String(consumerName);
-		const queueName = consumer.queue.name;
-		let batch = [];
-		let isProcessing = false;
-		const processBatch = () => {
-			if (isProcessing || batch.length === 0) return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Ok(void 0));
-			isProcessing = true;
-			const currentBatch = batch;
-			batch = [];
-			const timer = this.batchTimers.get(timerKey);
-			if (timer) {
-				clearTimeout(timer);
-				this.batchTimers.delete(timerKey);
-			}
-			const messages = currentBatch.map((item) => item.message);
-			const batchCount = currentBatch.length;
-			const startTime = Date.now();
-			const span = (0, _amqp_contract_core.startConsumeSpan)(this.telemetry, queueName, String(consumerName), { "amqp.batch.size": batchCount });
-			this.logger?.info("Processing batch", {
-				consumerName: String(consumerName),
-				queueName,
-				batchSize: batchCount
-			});
-			return handler(messages).flatMapOk(() => {
-				for (const item of currentBatch) this.amqpClient.channel.ack(item.amqpMessage);
-				this.logger?.info("Batch processed successfully", {
-					consumerName: String(consumerName),
-					queueName,
-					batchSize: batchCount
-				});
-				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 batch", {
-					consumerName: String(consumerName),
-					queueName,
-					batchSize: batchCount,
-					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.handleBatchError(handlerError, currentBatch, String(consumerName), consumer);
-			}).tap(() => {
-				isProcessing = false;
-			});
-		};
-		const scheduleBatchProcessing = () => {
-			if (isProcessing) return;
-			const existingTimer = this.batchTimers.get(timerKey);
-			if (existingTimer) clearTimeout(existingTimer);
-			const timer = setTimeout(() => {
-				processBatch().toPromise();
-			}, batchTimeout);
-			this.batchTimers.set(timerKey, timer);
-		};
-		return _swan_io_boxed.Future.fromPromise(this.amqpClient.channel.consume(queueName, async (msg) => {
-			if (msg === null) {
-				this.logger?.warn("Consumer cancelled by server", {
-					consumerName: String(consumerName),
-					queueName
-				});
-				await processBatch().toPromise();
-				return;
-			}
-			const validationResult = await this.parseAndValidateMessage(msg, consumer, consumerName).toPromise();
-			if (validationResult.isError()) return;
-			batch.push({
-				message: validationResult.value,
-				amqpMessage: msg
-			});
-			if (batch.length >= batchSize) {
-				await processBatch().toPromise();
-				if (batch.length > 0 && !this.batchTimers.has(timerKey)) scheduleBatchProcessing();
-			} else if (!this.batchTimers.has(timerKey)) scheduleBatchProcessing();
-		})).tapOk((reply) => {
-			this.consumerTags.add(reply.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:
+	* Flow depends on retry mode:
+	*
+	* **quorum-native mode:**
 	* 1. If NonRetryableError -> send directly to DLQ (no retry)
-	* 2. If no retry config -> legacy behavior (immediate requeue)
-	* 3. If max retries exceeded -> send to DLQ
-	* 4. Otherwise -> publish to wait queue with TTL for 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)
 	*/
 	handleError(error, msg, consumerName, consumer) {
 		if (error instanceof NonRetryableError) {
@@ -517,16 +504,50 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 			this.sendToDLQ(msg, consumer);
 			return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Ok(void 0));
 		}
-		if (this.retryConfig === null) {
-			this.logger?.warn("Error in handler (legacy mode: immediate requeue)", {
-				consumerName,
-				error: error.message
-			});
-			this.amqpClient.channel.nack(msg, false, true);
-			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.channel.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;
-		const config = this.retryConfig;
 		if (retryCount >= config.maxRetries) {
 			this.logger?.error("Max retries exceeded, sending to DLQ", {
 				consumerName,
@@ -537,8 +558,8 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 			this.sendToDLQ(msg, consumer);
 			return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Ok(void 0));
 		}
-		const delayMs = this.calculateRetryDelay(retryCount);
-		this.logger?.warn("Retrying message", {
+		const delayMs = this.calculateRetryDelay(retryCount, config);
+		this.logger?.warn("Retrying message (ttl-backoff mode)", {
 			consumerName,
 			retryCount: retryCount + 1,
 			delayMs,
@@ -549,8 +570,8 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 	/**
 	* Calculate retry delay with exponential backoff and optional jitter.
 	*/
-	calculateRetryDelay(retryCount) {
-		const { initialDelayMs, maxDelayMs, backoffMultiplier, jitter } = this.retryConfig;
+	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);
@@ -672,19 +693,6 @@ function validateHandlers(contract, handlers) {
 	const availableConsumerNames = availableConsumers.length > 0 ? availableConsumers.join(", ") : "none";
 	for (const handlerName of Object.keys(handlers)) if (!consumers || !(handlerName in consumers)) throw new Error(`Consumer "${handlerName}" not found in contract. Available consumers: ${availableConsumerNames}`);
 }
-/**
-* Wrap a Promise-based handler into a Future-based safe handler.
-* This is used internally by defineUnsafeHandler to convert Promise handlers to Future handlers.
-*/
-function wrapUnsafeHandler(handler) {
-	return (input) => {
-		return _swan_io_boxed.Future.fromPromise(handler(input)).mapOkToResult(() => _swan_io_boxed.Result.Ok(void 0)).flatMapError((error) => {
-			if (error instanceof NonRetryableError || error instanceof RetryableError) return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Error(error));
-			const retryableError = new RetryableError(error instanceof Error ? error.message : String(error), error);
-			return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Error(retryableError));
-		});
-	};
-}
 function defineHandler(contract, consumerName, handler, options) {
 	validateConsumerExists(contract, String(consumerName));
 	if (options) return [handler, options];
@@ -708,12 +716,12 @@ function defineHandler(contract, consumerName, handler, options) {
 * import { orderContract } from './contract';
 *
 * const handlers = defineHandlers(orderContract, {
-*   processOrder: (message) =>
-*     Future.fromPromise(processPayment(message))
+*   processOrder: ({ payload }) =>
+*     Future.fromPromise(processPayment(payload))
 *       .mapOk(() => undefined)
 *       .mapError((error) => new RetryableError('Payment failed', error)),
-*   notifyOrder: (message) =>
-*     Future.fromPromise(sendNotification(message))
+*   notifyOrder: ({ payload }) =>
+*     Future.fromPromise(sendNotification(payload))
 *       .mapOk(() => undefined)
 *       .mapError((error) => new RetryableError('Notification failed', error)),
 * });
@@ -723,52 +731,6 @@ function defineHandlers(contract, handlers) {
 	validateHandlers(contract, handlers);
 	return handlers;
 }
-function defineUnsafeHandler(contract, consumerName, handler, options) {
-	validateConsumerExists(contract, String(consumerName));
-	const wrappedHandler = wrapUnsafeHandler(handler);
-	if (options) return [wrappedHandler, options];
-	return wrappedHandler;
-}
-/**
-* Define multiple unsafe handlers for consumers in a contract.
-*
-* @deprecated Use `defineHandlers` instead for explicit error handling with `Future<Result>`.
-*
-* **Warning:** Unsafe handlers use exception-based error handling.
-* Consider migrating to safe handlers for better error control.
-*
-* **Note:** Internally, this function wraps all Promise-based handlers into Future-based
-* safe handlers for consistent processing in the worker.
-*
-* @template TContract - The contract definition type
-* @param contract - The contract definition containing the consumers
-* @param handlers - An object with async handler functions for each consumer
-* @returns A type-safe handlers object that can be used with TypedAmqpWorker
-*
-* @example
-* ```typescript
-* import { defineUnsafeHandlers } from '@amqp-contract/worker';
-*
-* // ⚠️ Consider using defineHandlers for better error handling
-* const handlers = defineUnsafeHandlers(orderContract, {
-*   processOrder: async (message) => {
-*     await processPayment(message);
-*   },
-*   notifyOrder: async (message) => {
-*     await sendNotification(message);
-*   },
-* });
-* ```
-*/
-function defineUnsafeHandlers(contract, handlers) {
-	validateHandlers(contract, handlers);
-	const result = {};
-	for (const [name, entry] of Object.entries(handlers)) if (Array.isArray(entry)) {
-		const [handler, options] = entry;
-		result[name] = [wrapUnsafeHandler(handler), options];
-	} else result[name] = wrapUnsafeHandler(entry);
-	return result;
-}
 
 //#endregion
 exports.MessageValidationError = MessageValidationError;
@@ -777,6 +739,4 @@ exports.RetryableError = RetryableError;
 exports.TechnicalError = TechnicalError;
 exports.TypedAmqpWorker = TypedAmqpWorker;
 exports.defineHandler = defineHandler;
-exports.defineHandlers = defineHandlers;
-exports.defineUnsafeHandler = defineUnsafeHandler;
-exports.defineUnsafeHandlers = defineUnsafeHandlers;
+exports.defineHandlers = defineHandlers;