@amqp-contract/contract 0.20.0 → 0.22.0

package/dist/index.cjs

@@ -1,5 +1,4 @@
-Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 //#region src/builder/exchange.ts
 /**
 * Define an AMQP exchange.
@@ -9,19 +8,23 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 * type safety.
 *
 * @param name - The name of the exchange
-* @param type - The type of exchange: "fanout", "direct", or "topic"
 * @param options - Optional exchange configuration
+* @param options.type - Exchange type (one of "topic", "direct", "fanout", "headers") (default: "topic")
+* @param options.durable - If true, the exchange survives broker restarts (default: true)
+* @param options.autoDelete - If true, the exchange is deleted when no queues are bound
+* @param options.internal - If true, the exchange cannot be directly published to
+* @param options.arguments - Additional AMQP arguments for the exchange
 * @returns An exchange definition
 * @internal
 */
-function defineExchange(name, type, options) {
+function defineExchange(name, options) {
 	return {
 		name,
-		type,
+		type: options?.type ?? "topic",
+		durable: true,
 		...options
 	};
 }
-
 //#endregion
 //#region src/builder/message.ts
 /**
@@ -65,25 +68,64 @@ function defineMessage(payload, options) {
 		...options
 	};
 }
-
 //#endregion
 //#region src/builder/queue-utils.ts
 /**
-* Type guard to check if a queue entry is a QueueWithTtlBackoffInfrastructure.
+* Extract the plain QueueDefinition from a QueueEntry.
 * @internal
 */
-function isQueueWithTtlBackoffInfrastructure$1(entry) {
-	return typeof entry === "object" && entry !== null && "__brand" in entry && entry.__brand === "QueueWithTtlBackoffInfrastructure";
+function extractQueueFromEntry(entry) {
+	if (isQueueWithTtlBackoffInfrastructure(entry)) return entry.queue;
+	return entry;
 }
 /**
 * Extract the plain QueueDefinition from a QueueEntry.
-* @internal
+*
+* **Why this function exists:**
+* When you configure a queue with TTL-backoff retry,
+* `defineQueue` returns a wrapper object that includes
+* the main queue, wait queue, headers exchanges, and bindings. This function extracts the underlying
+* queue definition so you can access properties like `name`, `type`, etc.
+*
+* **When to use:**
+* - When you need to access queue properties (name, type, etc.)
+* - When passing a queue to functions that expect a plain QueueDefinition
+* - Works safely on both plain queues and infrastructure wrappers
+*
+* **How it works:**
+* - If the entry is a `QueueWithTtlBackoffInfrastructure`, returns `entry.queue`
+* - Otherwise, returns the entry as-is (it's already a plain QueueDefinition)
+*
+* @param entry - The queue entry (either plain QueueDefinition or QueueWithTtlBackoffInfrastructure)
+* @returns The plain QueueDefinition
+*
+* @example
+* ```typescript
+* import { defineQueue, extractQueue } from '@amqp-contract/contract';
+*
+* // TTL-backoff queue returns a wrapper
+* const orderQueue = defineQueue('orders', {
+*   retry: { mode: 'ttl-backoff', maxRetries: 3 },
+* });
+*
+* // Use extractQueue to access the queue name
+* const queueName = extractQueue(orderQueue).name; // 'orders'
+*
+* // Also works safely on plain queues
+* const plainQueue = defineQueue('simple', { type: 'quorum', retry: { mode: 'immediate-requeue' } });
+* const plainName = extractQueue(plainQueue).name; // 'simple'
+*
+* // Access other properties
+* const queueDef = extractQueue(orderQueue);
+* console.log(queueDef.name);       // 'orders'
+* console.log(queueDef.type);       // 'quorum'
+* ```
+*
+* @see isQueueWithTtlBackoffInfrastructure - Type guard to check if extraction is needed
 */
-function extractQueueFromEntry(entry) {
-	if (isQueueWithTtlBackoffInfrastructure$1(entry)) return entry.queue;
-	return entry;
+function extractQueue(entry) {
+	return extractQueueFromEntry(entry);
 }
-
 //#endregion
 //#region src/builder/binding.ts
 /**
@@ -98,8 +140,8 @@ function extractQueueFromEntry(entry) {
 * @internal
 */
 function defineQueueBinding(queue, exchange, options) {
-	const queueDef = extractQueueFromEntry(queue);
-	if (exchange.type === "fanout") return {
+	const queueDef = extractQueue(queue);
+	if (exchange.type === "fanout" || exchange.type === "headers") return {
 		type: "queue",
 		queue: queueDef,
 		exchange,
@@ -119,7 +161,7 @@ function defineQueueBinding(queue, exchange, options) {
 * @internal
 */
 function defineQueueBindingInternal(queue, exchange, options) {
-	if (exchange.type === "fanout") return defineQueueBinding(queue, exchange, options);
+	if (exchange.type === "fanout" || exchange.type === "headers") return defineQueueBinding(queue, exchange, options);
 	return defineQueueBinding(queue, exchange, options);
 }
 /**
@@ -134,7 +176,7 @@ function defineQueueBindingInternal(queue, exchange, options) {
 * @internal
 */
 function defineExchangeBinding(destination, source, options) {
-	if (source.type === "fanout") return {
+	if (source.type === "fanout" || source.type === "headers") return {
 		type: "exchange",
 		source,
 		destination,
@@ -148,27 +190,12 @@ function defineExchangeBinding(destination, source, options) {
 		...options?.arguments && { arguments: options.arguments }
 	};
 }
-
 //#endregion
-//#region src/builder/queue.ts
-/**
-* Resolve TTL-backoff retry options with defaults applied.
-* @internal
-*/
-function resolveTtlBackoffOptions(options) {
-	return {
-		mode: "ttl-backoff",
-		maxRetries: options?.maxRetries ?? 3,
-		initialDelayMs: options?.initialDelayMs ?? 1e3,
-		maxDelayMs: options?.maxDelayMs ?? 3e4,
-		backoffMultiplier: options?.backoffMultiplier ?? 2,
-		jitter: options?.jitter ?? true
-	};
-}
+//#region src/builder/ttl-backoff.ts
 /**
 * Type guard to check if a queue entry is a QueueWithTtlBackoffInfrastructure.
 *
-* When you configure a queue with TTL-backoff retry and a dead letter exchange,
+* When you configure a queue with TTL-backoff retry,
 * `defineQueue` returns a `QueueWithTtlBackoffInfrastructure` instead of a plain
 * `QueueDefinition`. This type guard helps you distinguish between the two.
 *
@@ -185,12 +212,11 @@ function resolveTtlBackoffOptions(options) {
 * @example
 * ```typescript
 * const queue = defineQueue('orders', {
-*   deadLetter: { exchange: dlx },
 *   retry: { mode: 'ttl-backoff' },
 * });
 *
 * if (isQueueWithTtlBackoffInfrastructure(queue)) {
-*   // queue has .queue, .waitQueue, .waitQueueBinding, .mainQueueRetryBinding
+*   // queue has .queue, .waitQueue, .waitQueueBinding, .retryQueueBinding, .waitExchange, .retryExchange
 *   console.log('Wait queue:', queue.waitQueue.name);
 * } else {
 *   // queue is a plain QueueDefinition
@@ -199,256 +225,161 @@ function resolveTtlBackoffOptions(options) {
 * ```
 */
 function isQueueWithTtlBackoffInfrastructure(entry) {
-	return isQueueWithTtlBackoffInfrastructure$1(entry);
+	return typeof entry === "object" && entry !== null && "__brand" in entry && entry.__brand === "QueueWithTtlBackoffInfrastructure";
 }
 /**
-* Extract the plain QueueDefinition from a QueueEntry.
-*
-* **Why this function exists:**
-* When you configure a queue with TTL-backoff retry and a dead letter exchange,
-* `defineQueue` (or `defineTtlBackoffQueue`) returns a wrapper object that includes
-* the main queue, wait queue, and bindings. This function extracts the underlying
-* queue definition so you can access properties like `name`, `type`, etc.
+* Wrap a queue definition with TTL-backoff retry infrastructure.
+*/
+function wrapWithTtlBackoffInfrastructure(queue) {
+	return {
+		__brand: "QueueWithTtlBackoffInfrastructure",
+		queue,
+		...createTtlBackoffInfrastructure(queue)
+	};
+}
+/**
+* Create TTL-backoff retry infrastructure for a queue.
 *
-* **When to use:**
-* - When you need to access queue properties (name, type, deadLetter, etc.)
-* - When passing a queue to functions that expect a plain QueueDefinition
-* - Works safely on both plain queues and infrastructure wrappers
+* This builder helper generates the wait queue, exchanges, and bindings needed for TTL-backoff retry.
+* The generated infrastructure can be spread into a contract definition.
 *
-* **How it works:**
-* - If the entry is a `QueueWithTtlBackoffInfrastructure`, returns `entry.queue`
-* - Otherwise, returns the entry as-is (it's already a plain QueueDefinition)
+* TTL-backoff retry works by:
+* 1. Failed messages are sent to the wait exchange with header `x-wait-queue` set to the wait queue name
+* 2. The wait queue receives these messages and holds them for a TTL period
+* 3. After TTL expires, messages are dead-lettered back to the retry exchange with header `x-retry-queue` set to the main queue name
+* 4. The main queue receives the retried message via its binding to the retry exchange
 *
-* @param entry - The queue entry (either plain QueueDefinition or QueueWithTtlBackoffInfrastructure)
-* @returns The plain QueueDefinition
+* @param queue - The main queue definition
+* @param options - Optional configuration for the wait queue
+* @returns TTL-backoff retry infrastructure containing wait queue and bindings
+* @throws {Error} If the queue does not have retry mode set to `ttl-backoff`
 *
 * @example
 * ```typescript
-* import { defineQueue, defineTtlBackoffQueue, extractQueue } from '@amqp-contract/contract';
-*
-* // TTL-backoff queue returns a wrapper
-* const orderQueue = defineTtlBackoffQueue('orders', {
-*   deadLetter: { exchange: dlx },
-*   maxRetries: 3,
+* const orderQueue = defineQueue('order-processing', {
+*   type: 'quorum',
+*   retry: {
+*     mode: 'ttl-backoff',
+*     maxRetries: 5,
+*     initialDelayMs: 1000,
+*   },
 * });
 *
-* // Use extractQueue to access the queue name
-* const queueName = extractQueue(orderQueue).name; // 'orders'
-*
-* // Also works safely on plain queues
-* const plainQueue = defineQueue('simple', { type: 'quorum', retry: { mode: 'quorum-native' } });
-* const plainName = extractQueue(plainQueue).name; // 'simple'
-*
-* // Access other properties
-* const queueDef = extractQueue(orderQueue);
-* console.log(queueDef.name);       // 'orders'
-* console.log(queueDef.type);       // 'quorum'
-* console.log(queueDef.deadLetter); // { exchange: dlx, ... }
+* // Infrastructure is auto-extracted when using defineContract:
+* const contract = defineContract({
+*   publishers: { ... },
+*   consumers: { processOrder: defineEventConsumer(event, orderQueue) },
+* });
+* // contract.queues includes the wait queue, contract.exchanges includes retry exchanges, contract.bindings includes retry bindings
 * ```
-*
-* @see isQueueWithTtlBackoffInfrastructure - Type guard to check if extraction is needed
-* @see defineTtlBackoffQueue - Creates queues with TTL-backoff infrastructure
 */
-function extractQueue(entry) {
-	return extractQueueFromEntry(entry);
+function createTtlBackoffInfrastructure(queue) {
+	if (queue.retry.mode !== "ttl-backoff") throw new Error(`Queue ${queue.name} does not have ttl-backoff retry mode. Infrastructure can only be created for queues with ttl-backoff retry.`);
+	const waitExchange = defineExchange(queue.retry.waitExchangeName, { type: "headers" });
+	const retryExchange = defineExchange(queue.retry.retryExchangeName, { type: "headers" });
+	const baseWaitQueue = {
+		name: queue.retry.waitQueueName,
+		deadLetter: { exchange: retryExchange },
+		retry: { mode: "none" }
+	};
+	const waitQueue = queue.type === "quorum" ? {
+		...baseWaitQueue,
+		type: queue.type,
+		durable: true
+	} : {
+		...baseWaitQueue,
+		type: queue.type,
+		durable: queue.durable
+	};
+	return {
+		waitQueue,
+		waitExchange,
+		retryExchange,
+		waitQueueBinding: defineQueueBindingInternal(waitQueue, waitExchange, { arguments: {
+			"x-match": "all",
+			"x-wait-queue": waitQueue.name
+		} }),
+		retryQueueBinding: defineQueueBindingInternal(queue, retryExchange, { arguments: {
+			"x-match": "all",
+			"x-retry-queue": queue.name
+		} })
+	};
 }
+//#endregion
+//#region src/builder/queue.ts
 /**
-* Create TTL-backoff retry infrastructure (wait queue + bindings) for a queue.
+* Resolve immediate-requeue retry options with defaults.
 * @internal
 */
-function createTtlBackoffInfrastructure(queue) {
-	if (!queue.deadLetter) throw new Error(`Queue "${queue.name}" does not have a dead letter exchange configured. TTL-backoff retry requires deadLetter to be set on the queue.`);
-	const dlx = queue.deadLetter.exchange;
-	const waitQueueName = `${queue.name}-wait`;
-	const waitQueue = {
-		name: waitQueueName,
-		type: "quorum",
-		durable: queue.durable ?? true,
-		deadLetter: {
-			exchange: dlx,
-			routingKey: queue.name
-		},
-		retry: resolveTtlBackoffOptions(void 0)
-	};
+function resolveImmediateRequeueOptions(options) {
 	return {
-		waitQueue,
-		waitQueueBinding: defineQueueBindingInternal(waitQueue, dlx, { routingKey: waitQueueName }),
-		mainQueueRetryBinding: defineQueueBindingInternal(queue, dlx, { routingKey: queue.name })
+		mode: "immediate-requeue",
+		maxRetries: options?.maxRetries ?? 3
 	};
 }
 /**
-* Wrap a queue definition with TTL-backoff retry infrastructure.
+* Resolve TTL-backoff retry options with defaults.
 * @internal
 */
-function wrapWithTtlBackoffInfrastructure(queue) {
-	const infra = createTtlBackoffInfrastructure(queue);
+function resolveTtlBackoffOptions(queueName, options) {
 	return {
-		__brand: "QueueWithTtlBackoffInfrastructure",
-		queue,
-		deadLetter: queue.deadLetter,
-		...infra
+		mode: "ttl-backoff",
+		maxRetries: options?.maxRetries ?? 3,
+		initialDelayMs: options?.initialDelayMs ?? 1e3,
+		maxDelayMs: options?.maxDelayMs ?? 3e4,
+		backoffMultiplier: options?.backoffMultiplier ?? 2,
+		jitter: options?.jitter ?? true,
+		waitQueueName: options?.waitQueueName ?? `${queueName}-wait`,
+		waitExchangeName: options?.waitExchangeName ?? "wait-exchange",
+		retryExchangeName: options?.retryExchangeName ?? "retry-exchange"
 	};
 }
 function defineQueue(name, options) {
 	const opts = options ?? {};
 	const type = opts.type ?? "quorum";
-	const baseProps = { name };
-	if (opts.durable !== void 0) baseProps.durable = opts.durable;
-	if (opts.autoDelete !== void 0) baseProps.autoDelete = opts.autoDelete;
-	if (opts.deadLetter !== void 0) baseProps.deadLetter = opts.deadLetter;
-	if (opts.arguments !== void 0) baseProps.arguments = opts.arguments;
+	const durable = opts.durable ?? true;
+	const baseProps = {
+		name,
+		...opts.deadLetter !== void 0 && { deadLetter: opts.deadLetter },
+		...opts.arguments !== void 0 && { arguments: opts.arguments }
+	};
+	const classicProps = {
+		...opts.exclusive !== void 0 && { exclusive: opts.exclusive },
+		...opts.autoDelete !== void 0 && { autoDelete: opts.autoDelete },
+		...opts.maxPriority !== void 0 && { maxPriority: opts.maxPriority }
+	};
 	if (type === "quorum") {
-		const quorumOpts = opts;
-		const inputRetry = quorumOpts.retry ?? { mode: "ttl-backoff" };
-		if (inputRetry.mode === "quorum-native") {
-			if (quorumOpts.deliveryLimit === void 0) throw new Error(`Queue "${name}" uses quorum-native retry mode but deliveryLimit is not configured. Quorum-native retry requires deliveryLimit to be set.`);
-		}
-		const retry = inputRetry.mode === "quorum-native" ? inputRetry : resolveTtlBackoffOptions(inputRetry);
-		const queueDefinition = {
-			...baseProps,
-			type: "quorum",
-			retry
-		};
-		if (quorumOpts.deliveryLimit !== void 0) {
-			if (quorumOpts.deliveryLimit < 1 || !Number.isInteger(quorumOpts.deliveryLimit)) throw new Error(`Invalid deliveryLimit: ${quorumOpts.deliveryLimit}. Must be a positive integer.`);
-			queueDefinition.deliveryLimit = quorumOpts.deliveryLimit;
+		if (opts.durable === false) throw new Error("Non-durable queues are not supported with quorum type.");
+		if (opts.exclusive !== void 0) throw new Error("Exclusive queues are not supported with quorum type.");
+		if (opts.autoDelete !== void 0) throw new Error("Auto-deleting queues are not supported with quorum type.");
+		if (opts.maxPriority !== void 0) throw new Error("Priority queues are not supported with quorum type.");
+	} else if (opts.maxPriority !== void 0) {
+		if (opts.maxPriority < 1 || opts.maxPriority > 255) throw new Error(`Invalid maxPriority: ${opts.maxPriority}. Must be between 1 and 255. Recommended range: 1-10.`);
+	}
+	const inputRetry = opts.retry ?? { mode: "none" };
+	if (inputRetry.mode === "immediate-requeue" || inputRetry.mode === "ttl-backoff") {
+		if (inputRetry.maxRetries !== void 0) {
+			if (inputRetry.maxRetries < 1 || !Number.isInteger(inputRetry.maxRetries)) throw new Error(`Queue "${name}" uses ${inputRetry.mode} retry mode with invalid maxRetries: ${inputRetry.maxRetries}. Must be a positive integer.`);
 		}
-		if (retry.mode === "ttl-backoff" && queueDefinition.deadLetter) return wrapWithTtlBackoffInfrastructure(queueDefinition);
-		return queueDefinition;
 	}
-	const classicOpts = opts;
-	if (classicOpts.retry?.mode === "quorum-native") throw new Error(`Queue "${name}" uses quorum-native retry mode but is a classic queue. Quorum-native retry requires quorum queues (type: "quorum").`);
-	const retry = resolveTtlBackoffOptions(classicOpts.retry);
-	const queueDefinition = {
+	const retry = inputRetry.mode === "immediate-requeue" ? resolveImmediateRequeueOptions(inputRetry) : inputRetry.mode === "ttl-backoff" ? resolveTtlBackoffOptions(name, inputRetry) : inputRetry;
+	const baseQueueDefinition = {
 		...baseProps,
-		type: "classic",
 		retry
 	};
-	if (classicOpts.exclusive !== void 0) queueDefinition.exclusive = classicOpts.exclusive;
-	if (classicOpts.maxPriority !== void 0) {
-		if (classicOpts.maxPriority < 1 || classicOpts.maxPriority > 255) throw new Error(`Invalid maxPriority: ${classicOpts.maxPriority}. Must be between 1 and 255. Recommended range: 1-10.`);
-		queueDefinition.arguments = {
-			...queueDefinition.arguments,
-			"x-max-priority": classicOpts.maxPriority
-		};
-	}
-	if (retry.mode === "ttl-backoff" && queueDefinition.deadLetter) return wrapWithTtlBackoffInfrastructure(queueDefinition);
-	return queueDefinition;
-}
-/**
-* Create a quorum queue with quorum-native retry.
-*
-* This is a simplified helper that enforces best practices:
-* - Uses quorum queues (recommended for most use cases)
-* - Requires dead letter exchange for failed message handling
-* - Uses quorum-native retry mode (simpler than TTL-backoff)
-*
-* **When to use:**
-* - You want simple, immediate retries without exponential backoff
-* - You don't need configurable delays between retries
-* - You want the simplest retry configuration
-*
-* @param name - The queue name
-* @param options - Configuration options
-* @returns A quorum queue definition with quorum-native retry
-*
-* @example
-* ```typescript
-* const dlx = defineExchange('orders-dlx', 'direct', { durable: true });
-*
-* const orderQueue = defineQuorumQueue('order-processing', {
-*   deadLetter: { exchange: dlx },
-*   deliveryLimit: 3, // Retry up to 3 times
-* });
-*
-* // Use in a contract — exchanges, queues, and bindings are auto-extracted
-* const contract = defineContract({
-*   publishers: { ... },
-*   consumers: { processOrder: defineEventConsumer(event, orderQueue) },
-* });
-* ```
-*
-* @see defineQueue - For full queue configuration options
-* @see defineTtlBackoffQueue - For queues with exponential backoff retry
-*/
-function defineQuorumQueue(name, options) {
-	const { deadLetter, deliveryLimit, autoDelete, arguments: args } = options;
-	const queueOptions = {
-		type: "quorum",
-		deadLetter,
-		deliveryLimit,
-		retry: { mode: "quorum-native" }
-	};
-	if (autoDelete !== void 0) queueOptions.autoDelete = autoDelete;
-	if (args !== void 0) queueOptions.arguments = args;
-	return defineQueue(name, queueOptions);
-}
-/**
-* Create a queue with TTL-backoff retry (exponential backoff).
-*
-* This is a simplified helper that enforces best practices:
-* - Uses quorum queues (recommended for most use cases)
-* - Requires dead letter exchange for retry routing
-* - Uses TTL-backoff retry mode with configurable delays
-* - Automatically generates wait queue and bindings
-*
-* **When to use:**
-* - You need exponential backoff between retries
-* - You want configurable delays (initial delay, max delay, jitter)
-* - You're processing messages that may need time before retry
-*
-* **Returns:** A `QueueWithTtlBackoffInfrastructure` object that includes the
-* main queue, wait queue, and bindings. Pass this directly to `defineContract`
-* and it will be expanded automatically.
-*
-* @param name - The queue name
-* @param options - Configuration options
-* @returns A queue with TTL-backoff infrastructure
-*
-* @example
-* ```typescript
-* const dlx = defineExchange('orders-dlx', 'direct', { durable: true });
-*
-* const orderQueue = defineTtlBackoffQueue('order-processing', {
-*   deadLetter: { exchange: dlx },
-*   maxRetries: 5,
-*   initialDelayMs: 1000,  // Start with 1s delay
-*   maxDelayMs: 30000,     // Cap at 30s
-* });
-*
-* // Use in a contract — wait queue, bindings, and DLX are auto-extracted
-* const contract = defineContract({
-*   publishers: { ... },
-*   consumers: { processOrder: defineEventConsumer(event, extractQueue(orderQueue)) },
-* });
-*
-* // To access the underlying queue definition (e.g., for the queue name):
-* import { extractQueue } from '@amqp-contract/contract';
-* const queueName = extractQueue(orderQueue).name;
-* ```
-*
-* @see defineQueue - For full queue configuration options
-* @see defineQuorumQueue - For queues with quorum-native retry (simpler, immediate retries)
-* @see extractQueue - To access the underlying queue definition
-*/
-function defineTtlBackoffQueue(name, options) {
-	const { deadLetter, maxRetries, initialDelayMs, maxDelayMs, backoffMultiplier, jitter, autoDelete, arguments: args } = options;
-	const retryOptions = { mode: "ttl-backoff" };
-	if (maxRetries !== void 0) retryOptions.maxRetries = maxRetries;
-	if (initialDelayMs !== void 0) retryOptions.initialDelayMs = initialDelayMs;
-	if (maxDelayMs !== void 0) retryOptions.maxDelayMs = maxDelayMs;
-	if (backoffMultiplier !== void 0) retryOptions.backoffMultiplier = backoffMultiplier;
-	if (jitter !== void 0) retryOptions.jitter = jitter;
-	const queueOptions = {
-		type: "quorum",
-		deadLetter,
-		retry: retryOptions
+	const queueDefinition = type === "quorum" ? {
+		...baseQueueDefinition,
+		type,
+		durable: true
+	} : {
+		...baseQueueDefinition,
+		...classicProps,
+		type,
+		durable
 	};
-	if (autoDelete !== void 0) queueOptions.autoDelete = autoDelete;
-	if (args !== void 0) queueOptions.arguments = args;
-	return defineQueue(name, queueOptions);
+	if (retry.mode === "ttl-backoff") return wrapWithTtlBackoffInfrastructure(queueDefinition);
+	return queueDefinition;
 }
-
 //#endregion
 //#region src/builder/publisher.ts
 /**
@@ -463,7 +394,7 @@ function defineTtlBackoffQueue(name, options) {
 * @internal
 */
 function definePublisher(exchange, message, options) {
-	if (exchange.type === "fanout") return {
+	if (exchange.type === "fanout" || exchange.type === "headers") return {
 		exchange,
 		message
 	};
@@ -479,10 +410,9 @@ function definePublisher(exchange, message, options) {
 * @internal
 */
 function definePublisherInternal(exchange, message, options) {
-	if (exchange.type === "fanout") return definePublisher(exchange, message, options);
+	if (exchange.type === "fanout" || exchange.type === "headers") return definePublisher(exchange, message, options);
 	return definePublisher(exchange, message, options);
 }
-
 //#endregion
 //#region src/builder/consumer.ts
 /**
@@ -562,7 +492,7 @@ function extractConsumer(entry) {
 * ```typescript
 * import { z } from 'zod';
 *
-* const orderQueue = defineQueue('order-processing', { durable: true });
+* const orderQueue = defineQueue('order-processing');
 * const orderMessage = defineMessage(
 *   z.object({
 *     orderId: z.string().uuid(),
@@ -591,12 +521,72 @@ function extractConsumer(entry) {
 */
 function defineConsumer(queue, message, options) {
 	return {
-		queue: extractQueue(queue),
+		queue,
 		message,
 		...options
 	};
 }
-
+//#endregion
+//#region src/builder/command.ts
+/**
+* Implementation of defineCommandConsumer.
+* @internal
+*/
+function defineCommandConsumer(queue, exchange, message, options) {
+	return {
+		__brand: "CommandConsumerConfig",
+		consumer: defineConsumer(queue, message),
+		binding: defineQueueBindingInternal(queue, exchange, options),
+		exchange,
+		queue,
+		message,
+		routingKey: options?.routingKey
+	};
+}
+/**
+* Implementation of defineCommandPublisher.
+* @internal
+*/
+function defineCommandPublisher(commandConsumer, options) {
+	const { exchange: targetExchange, message, routingKey: consumerRoutingKey } = commandConsumer;
+	const publisherRoutingKey = options?.routingKey ?? consumerRoutingKey;
+	const bridgeExchange = options?.bridgeExchange;
+	if (bridgeExchange) {
+		const publisherOptions = {};
+		if (publisherRoutingKey !== void 0) publisherOptions.routingKey = publisherRoutingKey;
+		const publisher = definePublisherInternal(bridgeExchange, message, publisherOptions);
+		const e2eBindingOptions = {};
+		if (publisherRoutingKey !== void 0) e2eBindingOptions.routingKey = publisherRoutingKey;
+		return {
+			__brand: "BridgedPublisherConfig",
+			publisher,
+			exchangeBinding: bridgeExchange.type === "fanout" || bridgeExchange.type === "headers" ? defineExchangeBinding(targetExchange, bridgeExchange) : defineExchangeBinding(targetExchange, bridgeExchange, e2eBindingOptions),
+			bridgeExchange,
+			targetExchange
+		};
+	}
+	const publisherOptions = {};
+	if (publisherRoutingKey !== void 0) publisherOptions.routingKey = publisherRoutingKey;
+	return definePublisherInternal(targetExchange, message, publisherOptions);
+}
+/**
+* Type guard to check if a value is a CommandConsumerConfig.
+*
+* @param value - The value to check
+* @returns True if the value is a CommandConsumerConfig
+*/
+function isCommandConsumerConfig(value) {
+	return typeof value === "object" && value !== null && "__brand" in value && value.__brand === "CommandConsumerConfig";
+}
+/**
+* Type guard to check if a value is a BridgedPublisherConfig.
+*
+* @param value - The value to check
+* @returns True if the value is a BridgedPublisherConfig
+*/
+function isBridgedPublisherConfig(value) {
+	return typeof value === "object" && value !== null && "__brand" in value && value.__brand === "BridgedPublisherConfig";
+}
 //#endregion
 //#region src/builder/event.ts
 /**
@@ -630,27 +620,23 @@ function defineEventConsumer(eventPublisher, queue, options) {
 		const consumer = defineConsumer(queue, message);
 		const exchangeBindingOptions = {};
 		if (bindingRoutingKey !== void 0) exchangeBindingOptions.routingKey = bindingRoutingKey;
-		const e2eBinding = sourceExchange.type === "fanout" ? defineExchangeBinding(bridgeExchange, sourceExchange) : defineExchangeBinding(bridgeExchange, sourceExchange, exchangeBindingOptions);
 		return {
 			__brand: "EventConsumerResult",
 			consumer,
 			binding,
 			exchange: sourceExchange,
-			queue: consumer.queue,
-			deadLetterExchange: consumer.queue.deadLetter?.exchange,
-			exchangeBinding: e2eBinding,
+			queue,
+			exchangeBinding: sourceExchange.type === "fanout" || sourceExchange.type === "headers" ? defineExchangeBinding(bridgeExchange, sourceExchange) : defineExchangeBinding(bridgeExchange, sourceExchange, exchangeBindingOptions),
 			bridgeExchange
 		};
 	}
 	const binding = defineQueueBindingInternal(queue, sourceExchange, bindingOptions);
-	const consumer = defineConsumer(queue, message);
 	return {
 		__brand: "EventConsumerResult",
-		consumer,
+		consumer: defineConsumer(queue, message),
 		binding,
 		exchange: sourceExchange,
-		queue: consumer.queue,
-		deadLetterExchange: consumer.queue.deadLetter?.exchange,
+		queue,
 		exchangeBinding: void 0,
 		bridgeExchange: void 0
 	};
@@ -673,71 +659,6 @@ function isEventPublisherConfig(value) {
 function isEventConsumerResult(value) {
 	return typeof value === "object" && value !== null && "__brand" in value && value.__brand === "EventConsumerResult";
 }
-
-//#endregion
-//#region src/builder/command.ts
-/**
-* Implementation of defineCommandConsumer.
-* @internal
-*/
-function defineCommandConsumer(queue, exchange, message, options) {
-	const consumer = defineConsumer(queue, message);
-	return {
-		__brand: "CommandConsumerConfig",
-		consumer,
-		binding: defineQueueBindingInternal(queue, exchange, options),
-		exchange,
-		queue: consumer.queue,
-		deadLetterExchange: consumer.queue.deadLetter?.exchange,
-		message,
-		routingKey: options?.routingKey
-	};
-}
-/**
-* Implementation of defineCommandPublisher.
-* @internal
-*/
-function defineCommandPublisher(commandConsumer, options) {
-	const { exchange: targetExchange, message, routingKey: consumerRoutingKey } = commandConsumer;
-	const publisherRoutingKey = options?.routingKey ?? consumerRoutingKey;
-	const bridgeExchange = options?.bridgeExchange;
-	if (bridgeExchange) {
-		const publisherOptions = {};
-		if (publisherRoutingKey !== void 0) publisherOptions.routingKey = publisherRoutingKey;
-		const publisher = definePublisherInternal(bridgeExchange, message, publisherOptions);
-		const e2eBindingOptions = {};
-		if (publisherRoutingKey !== void 0) e2eBindingOptions.routingKey = publisherRoutingKey;
-		return {
-			__brand: "BridgedPublisherConfig",
-			publisher,
-			exchangeBinding: bridgeExchange.type === "fanout" ? defineExchangeBinding(targetExchange, bridgeExchange) : defineExchangeBinding(targetExchange, bridgeExchange, e2eBindingOptions),
-			bridgeExchange,
-			targetExchange
-		};
-	}
-	const publisherOptions = {};
-	if (publisherRoutingKey !== void 0) publisherOptions.routingKey = publisherRoutingKey;
-	return definePublisherInternal(targetExchange, message, publisherOptions);
-}
-/**
-* Type guard to check if a value is a CommandConsumerConfig.
-*
-* @param value - The value to check
-* @returns True if the value is a CommandConsumerConfig
-*/
-function isCommandConsumerConfig(value) {
-	return typeof value === "object" && value !== null && "__brand" in value && value.__brand === "CommandConsumerConfig";
-}
-/**
-* Type guard to check if a value is a BridgedPublisherConfig.
-*
-* @param value - The value to check
-* @returns True if the value is a BridgedPublisherConfig
-*/
-function isBridgedPublisherConfig(value) {
-	return typeof value === "object" && value !== null && "__brand" in value && value.__brand === "BridgedPublisherConfig";
-}
-
 //#endregion
 //#region src/builder/contract.ts
 /**
@@ -769,12 +690,11 @@ function isBridgedPublisherConfig(value) {
 * import { z } from 'zod';
 *
 * // Define resources
-* const ordersExchange = defineExchange('orders', 'topic', { durable: true });
-* const dlx = defineExchange('orders-dlx', 'direct', { durable: true });
+* const ordersExchange = defineExchange('orders');
+* const dlx = defineExchange('orders-dlx', { type: 'direct' });
 * const orderQueue = defineQueue('order-processing', {
 *   deadLetter: { exchange: dlx },
-*   retry: { mode: 'quorum-native' },
-*   deliveryLimit: 3,
+*   retry: { mode: 'immediate-requeue', maxRetries: 3 },
 * });
 * const orderMessage = defineMessage(
 *   z.object({
@@ -807,13 +727,18 @@ function isBridgedPublisherConfig(value) {
 * ```
 */
 function defineContract(definition) {
-	const { publishers: inputPublishers, consumers: inputConsumers } = definition;
+	const { publishers: inputPublishers, consumers: inputConsumers, rpcs: inputRpcs } = definition;
+	if (inputConsumers && inputRpcs) {
+		const collisions = Object.keys(inputConsumers).filter((name) => Object.hasOwn(inputRpcs, name));
+		if (collisions.length > 0) throw new Error(`defineContract: name collision between consumers and rpcs — keys must be disjoint. Conflicting names: ${collisions.join(", ")}`);
+	}
 	const result = {
 		exchanges: {},
 		queues: {},
 		bindings: {},
 		publishers: {},
-		consumers: {}
+		consumers: {},
+		rpcs: {}
 	};
 	if (inputPublishers && Object.keys(inputPublishers).length > 0) {
 		const processedPublishers = {};
@@ -853,9 +778,10 @@ function defineContract(definition) {
 			processedConsumers[name] = entry.consumer;
 			consumerBindings[`${name}Binding`] = entry.binding;
 			const queueEntry = entry.consumer.queue;
-			queues[queueEntry.name] = queueEntry;
+			const queueDef = extractQueue(queueEntry);
+			queues[queueDef.name] = queueEntry;
 			exchanges[entry.binding.exchange.name] = entry.binding.exchange;
-			if (queueEntry.deadLetter?.exchange) exchanges[queueEntry.deadLetter.exchange.name] = queueEntry.deadLetter.exchange;
+			if (queueDef.deadLetter?.exchange) exchanges[queueDef.deadLetter.exchange.name] = queueDef.deadLetter.exchange;
 			if (entry.exchangeBinding) consumerBindings[`${name}ExchangeBinding`] = entry.exchangeBinding;
 			if (entry.bridgeExchange) exchanges[entry.bridgeExchange.name] = entry.bridgeExchange;
 			if (entry.exchange) exchanges[entry.exchange.name] = entry.exchange;
@@ -863,22 +789,24 @@ function defineContract(definition) {
 			processedConsumers[name] = entry.consumer;
 			consumerBindings[`${name}Binding`] = entry.binding;
 			const queueEntry = entry.consumer.queue;
-			queues[queueEntry.name] = queueEntry;
+			const queueDef = extractQueue(queueEntry);
+			queues[queueDef.name] = queueEntry;
 			exchanges[entry.exchange.name] = entry.exchange;
-			if (queueEntry.deadLetter?.exchange) exchanges[queueEntry.deadLetter.exchange.name] = queueEntry.deadLetter.exchange;
+			if (queueDef.deadLetter?.exchange) exchanges[queueDef.deadLetter.exchange.name] = queueDef.deadLetter.exchange;
 		} else {
 			const consumer = entry;
 			processedConsumers[name] = consumer;
 			const queueEntry = consumer.queue;
-			queues[queueEntry.name] = queueEntry;
-			if (queueEntry.deadLetter?.exchange) exchanges[queueEntry.deadLetter.exchange.name] = queueEntry.deadLetter.exchange;
+			const queueDef = extractQueue(queueEntry);
+			queues[queueDef.name] = queueEntry;
+			if (queueDef.deadLetter?.exchange) exchanges[queueDef.deadLetter.exchange.name] = queueDef.deadLetter.exchange;
 		}
-		for (const queue of Object.values(queues)) if (queue.retry?.mode === "ttl-backoff" && queue.deadLetter) {
-			const infra = createTtlBackoffInfrastructure(queue);
-			queues[infra.waitQueue.name] = infra.waitQueue;
-			consumerBindings[`${queue.name}WaitBinding`] = infra.waitQueueBinding;
-			consumerBindings[`${queue.name}RetryBinding`] = infra.mainQueueRetryBinding;
-			exchanges[queue.deadLetter.exchange.name] = queue.deadLetter.exchange;
+		for (const queueEntry of Object.values(queues)) if (isQueueWithTtlBackoffInfrastructure(queueEntry)) {
+			queues[queueEntry.waitQueue.name] = queueEntry.waitQueue;
+			consumerBindings[`${queueEntry.queue.name}WaitBinding`] = queueEntry.waitQueueBinding;
+			consumerBindings[`${queueEntry.queue.name}RetryBinding`] = queueEntry.retryQueueBinding;
+			exchanges[queueEntry.waitExchange.name] = queueEntry.waitExchange;
+			exchanges[queueEntry.retryExchange.name] = queueEntry.retryExchange;
 		}
 		result.consumers = processedConsumers;
 		result.bindings = {
@@ -894,59 +822,75 @@ function defineContract(definition) {
 			...exchanges
 		};
 	}
+	if (inputRpcs && Object.keys(inputRpcs).length > 0) {
+		const processedRpcs = {};
+		const rpcQueues = {};
+		const rpcExchanges = {};
+		for (const [name, rpc] of Object.entries(inputRpcs)) {
+			processedRpcs[name] = rpc;
+			const queueDef = extractQueue(rpc.queue);
+			rpcQueues[queueDef.name] = rpc.queue;
+			if (queueDef.deadLetter?.exchange) rpcExchanges[queueDef.deadLetter.exchange.name] = queueDef.deadLetter.exchange;
+		}
+		result.rpcs = processedRpcs;
+		result.queues = {
+			...result.queues,
+			...rpcQueues
+		};
+		result.exchanges = {
+			...result.exchanges,
+			...rpcExchanges
+		};
+	}
 	return result;
 }
-
 //#endregion
-//#region src/builder/ttl-backoff.ts
+//#region src/builder/rpc.ts
 /**
-* Create TTL-backoff retry infrastructure for a queue.
+* Define an RPC operation: a request/response pair flowing over a request
+* queue with replies routed back via RabbitMQ direct reply-to.
 *
-* This builder helper generates the wait queue and bindings needed for TTL-backoff retry.
-* The generated infrastructure can be spread into a contract definition.
+* RPC is bidirectional on both ends — the worker handler consumes the request
+* and produces the response; `client.call(name, request, options)` publishes
+* the request and awaits the typed response. Both sides share the same
+* definition, so request and response schemas cannot drift between them.
 *
-* TTL-backoff retry works by:
-* 1. Failed messages are sent to the DLX with routing key `{queueName}-wait`
-* 2. The wait queue receives these messages and holds them for a TTL period
-* 3. After TTL expires, messages are dead-lettered back to the DLX with routing key `{queueName}`
-* 4. The main queue receives the retried message via its binding to the DLX
+* Plug the result into `defineContract({ rpcs: { name: ... } })`. RPCs do not
+* appear in `publishers` or `consumers`.
 *
-* @param queue - The main queue definition (must have deadLetter configured)
-* @param options - Optional configuration for the wait queue
-* @param options.waitQueueDurable - Whether the wait queue should be durable (default: same as main queue)
-* @returns TTL-backoff retry infrastructure containing wait queue and bindings
-* @throws {Error} If the queue does not have a dead letter exchange configured
+* @param queue - The queue that receives RPC requests. The queue name is
+*   used as the routing key on the AMQP default direct exchange.
+* @param messages.request - Schema validated against incoming request payloads
+*   (server side) and outgoing requests (client side).
+* @param messages.response - Schema validated against handler return values
+*   (server side) and incoming replies (client side).
 *
 * @example
 * ```typescript
-* const dlx = defineExchange('orders-dlx', 'direct', { durable: true });
-* const orderQueue = defineQueue('order-processing', {
-*   type: 'quorum',
-*   deadLetter: { exchange: dlx },
-*   retry: {
-*     mode: 'ttl-backoff',
-*     maxRetries: 5,
-*     initialDelayMs: 1000,
-*   },
-* });
+* import { defineQueue, defineMessage, defineRpc, defineContract } from '@amqp-contract/contract';
+* import { z } from 'zod';
 *
-* // Infrastructure is auto-extracted when using defineContract:
-* const contract = defineContract({
-*   publishers: { ... },
-*   consumers: { processOrder: defineEventConsumer(event, extractQueue(orderQueue)) },
+* const calculate = defineRpc(defineQueue('rpc.calculate'), {
+*   request: defineMessage(z.object({ a: z.number(), b: z.number() })),
+*   response: defineMessage(z.object({ sum: z.number() })),
 * });
-* // contract.queues includes the wait queue, contract.bindings includes retry bindings
 *
-* // Or generate manually for advanced use cases:
-* const retryInfra = defineTtlBackoffRetryInfrastructure(orderQueue);
+* const contract = defineContract({ rpcs: { calculate } });
+*
+* // Server (worker): handler returns the typed response
+* //   handlers: { calculate: ({ payload }) => Future.value(Result.Ok({ sum: payload.a + payload.b })) }
+*
+* // Client: typed call with required timeout
+* //   const result = await client.call('calculate', { a: 1, b: 2 }, { timeoutMs: 5_000 }).toPromise();
 * ```
 */
-function defineTtlBackoffRetryInfrastructure(queueEntry, options) {
-	const infra = createTtlBackoffInfrastructure(extractQueue(queueEntry));
-	if (options?.waitQueueDurable !== void 0) infra.waitQueue.durable = options.waitQueueDurable;
-	return infra;
+function defineRpc(queue, messages) {
+	return {
+		queue,
+		request: messages.request,
+		response: messages.response
+	};
 }
-
 //#endregion
 exports.defineCommandConsumer = defineCommandConsumer;
 exports.defineCommandPublisher = defineCommandPublisher;
@@ -960,13 +904,11 @@ exports.defineMessage = defineMessage;
 exports.definePublisher = definePublisher;
 exports.defineQueue = defineQueue;
 exports.defineQueueBinding = defineQueueBinding;
-exports.defineQuorumQueue = defineQuorumQueue;
-exports.defineTtlBackoffQueue = defineTtlBackoffQueue;
-exports.defineTtlBackoffRetryInfrastructure = defineTtlBackoffRetryInfrastructure;
+exports.defineRpc = defineRpc;
 exports.extractConsumer = extractConsumer;
 exports.extractQueue = extractQueue;
 exports.isBridgedPublisherConfig = isBridgedPublisherConfig;
 exports.isCommandConsumerConfig = isCommandConsumerConfig;
 exports.isEventConsumerResult = isEventConsumerResult;
 exports.isEventPublisherConfig = isEventPublisherConfig;
-exports.isQueueWithTtlBackoffInfrastructure = isQueueWithTtlBackoffInfrastructure;
+exports.isQueueWithTtlBackoffInfrastructure = isQueueWithTtlBackoffInfrastructure;