@amqp-contract/core 0.21.0 → 0.23.0

package/dist/index.d.mts

@@ -31,17 +31,32 @@ declare class MessageValidationError extends Error {
 }
 //#endregion
 //#region src/amqp-client.d.ts
+/**
+ * Default time `waitForConnect` will wait for the broker before erroring out.
+ * Defaulting to a finite value (rather than waiting forever) means a fail-fast
+ * developer experience: a misconfigured URL, a down broker, or wrong
+ * credentials surface as a Result.Error within 30 seconds. Pass `null`
+ * explicitly to disable the timeout — `Infinity` and other non-finite values
+ * are also coerced to "no timeout" because Node's `setTimeout` clamps large
+ * delays to ~24.8 days and silently fires near-immediately on `Infinity`.
+ */
+declare const DEFAULT_CONNECT_TIMEOUT_MS = 30000;
 /**
  * Options for creating an AMQP client.
  *
  * @property urls - AMQP broker URL(s). Multiple URLs provide failover support.
  * @property connectionOptions - Optional connection configuration (heartbeat, reconnect settings, etc.).
  * @property channelOptions - Optional channel configuration options.
+ * @property connectTimeoutMs - Maximum time in ms to wait for the channel to
+ *   become ready in `waitForConnect`. Defaults to {@link DEFAULT_CONNECT_TIMEOUT_MS}.
+ *   Pass `null` to disable the timeout entirely (amqp-connection-manager will
+ *   retry indefinitely).
  */
 type AmqpClientOptions = {
   urls: ConnectionUrl[];
   connectionOptions?: AmqpConnectionManagerOptions | undefined;
   channelOptions?: Partial<CreateChannelOpts> | undefined;
+  connectTimeoutMs?: number | null | undefined;
 };
 /**
  * Callback type for consuming messages.
@@ -93,6 +108,8 @@ declare class AmqpClient {
   private readonly channelWrapper;
   private readonly urls;
   private readonly connectionOptions?;
+  /** Resolved timeout in ms; `null` means "wait forever". */
+  private readonly connectTimeoutMs;
   /**
    * Create a new AMQP client instance.
    *
@@ -118,7 +135,19 @@ declare class AmqpClient {
   /**
    * Wait for the channel to be connected and ready.
    *
-   * @returns A Future that resolves when the channel is connected
+   * If `connectTimeoutMs` was provided in the constructor options, the returned
+   * Future resolves to `Result.Error<TechnicalError>` once the timeout elapses.
+   * Without a timeout, this waits forever — amqp-connection-manager retries
+   * connections indefinitely and never errors on its own.
+   *
+   * NOTE: When using `AmqpClient` directly (not via `TypedAmqpClient` /
+   * `TypedAmqpWorker`), the constructor has already incremented the pooled
+   * connection's reference count. Callers must invoke `close()` on the error
+   * path to release the connection — `waitForConnect` does not do this
+   * automatically. The typed factories handle this cleanup for you.
+   *
+   * @returns A Future resolving to `Result.Ok(void)` on connect, or
+   *   `Result.Error(TechnicalError)` on timeout / connection failure.
    */
   waitForConnect(): Future<Result<void, TechnicalError>>;
   /**
@@ -211,85 +240,20 @@ declare class AmqpClient {
 //#endregion
 //#region src/connection-manager.d.ts
 /**
- * Connection manager singleton for sharing AMQP connections across clients.
+ * Number of active pooled connections. Test-only helper — exposed in lieu of
+ * the underlying singleton, which is intentionally not part of the public API
+ * (mutating it from outside the library can break in-flight clients sharing a
+ * connection).
  *
- * This singleton implements connection pooling to avoid creating multiple connections
- * to the same broker, which is a RabbitMQ best practice. Connections are identified
- * by their URLs and connection options, and reference counting ensures connections
- * are only closed when all clients have released them.
+ * @internal
+ */
+declare function _getConnectionCountForTesting(): number;
+/**
+ * Close every pooled connection and clear ref-counts. Test-only helper.
  *
- * @example
- * ```typescript
- * const manager = ConnectionManagerSingleton.getInstance();
- * const connection = manager.getConnection(['amqp://localhost']);
- * // ... use connection ...
- * await manager.releaseConnection(['amqp://localhost']);
- * ```
+ * @internal
  */
-declare class ConnectionManagerSingleton {
-  private static instance;
-  private connections;
-  private refCounts;
-  private constructor();
-  /**
-   * Get the singleton instance of the connection manager.
-   *
-   * @returns The singleton instance
-   */
-  static getInstance(): ConnectionManagerSingleton;
-  /**
-   * Get or create a connection for the given URLs and options.
-   *
-   * If a connection already exists with the same URLs and options, it is reused
-   * and its reference count is incremented. Otherwise, a new connection is created.
-   *
-   * @param urls - AMQP broker URL(s)
-   * @param connectionOptions - Optional connection configuration
-   * @returns The AMQP connection manager instance
-   */
-  getConnection(urls: ConnectionUrl[], connectionOptions?: AmqpConnectionManagerOptions): AmqpConnectionManager;
-  /**
-   * Release a connection reference.
-   *
-   * Decrements the reference count for the connection. If the count reaches zero,
-   * the connection is closed and removed from the pool.
-   *
-   * @param urls - AMQP broker URL(s) used to identify the connection
-   * @param connectionOptions - Optional connection configuration used to identify the connection
-   * @returns A promise that resolves when the connection is released (and closed if necessary)
-   */
-  releaseConnection(urls: ConnectionUrl[], connectionOptions?: AmqpConnectionManagerOptions): Promise<void>;
-  /**
-   * Create a unique key for a connection based on URLs and options.
-   *
-   * The key is deterministic: same URLs and options always produce the same key,
-   * enabling connection reuse.
-   *
-   * @param urls - AMQP broker URL(s)
-   * @param connectionOptions - Optional connection configuration
-   * @returns A unique string key identifying the connection
-   */
-  private createConnectionKey;
-  /**
-   * Serialize connection options to a deterministic string.
-   *
-   * @param options - Connection options to serialize
-   * @returns A JSON string with sorted keys for deterministic comparison
-   */
-  private serializeOptions;
-  /**
-   * Deep sort an object's keys for deterministic serialization.
-   *
-   * @param value - The value to deep sort (can be object, array, or primitive)
-   * @returns The value with all object keys sorted alphabetically
-   */
-  private deepSort;
-  /**
-   * Reset all cached connections (for testing purposes)
-   * @internal
-   */
-  _resetForTesting(): Promise<void>;
-}
+declare function _resetConnectionsForTesting(): Promise<void>;
 //#endregion
 //#region src/logger.d.ts
 /**
@@ -421,6 +385,12 @@ type TelemetryProvider = {
    * Returns undefined if OpenTelemetry is not available.
    */
   getConsumeLatencyHistogram: () => Histogram | undefined;
+  /**
+   * Get a counter for RPC replies that arrive after the caller has gone away
+   * (timeout, cancellation, or unknown correlationId). Returns undefined if
+   * OpenTelemetry is not available.
+   */
+  getLateRpcReplyCounter: () => Counter | undefined;
 };
 /**
  * Default telemetry provider that uses OpenTelemetry API if available.
@@ -452,6 +422,15 @@ declare function recordPublishMetric(provider: TelemetryProvider, exchangeName:
  * Record a consume metric.
  */
 declare function recordConsumeMetric(provider: TelemetryProvider, queueName: string, consumerName: string, success: boolean, durationMs: number): void;
+/**
+ * Record an RPC reply that arrived after the caller stopped waiting.
+ *
+ * @param reason - Why the reply was orphaned. `"unknown-correlation-id"` is
+ *   the typical "caller already timed out" case; `"missing-correlation-id"`
+ *   means the broker delivered a reply with no correlationId at all (a
+ *   protocol violation by the responder).
+ */
+declare function recordLateRpcReply(provider: TelemetryProvider, reason: "unknown-correlation-id" | "missing-correlation-id"): void;
 /**
  * Reset the cached OpenTelemetry API module and instruments.
  * For testing purposes only.
@@ -459,5 +438,5 @@ declare function recordConsumeMetric(provider: TelemetryProvider, queueName: str
  */
 declare function _resetTelemetryCacheForTesting(): void;
 //#endregion
-export { AmqpClient, type AmqpClientOptions, ConnectionManagerSingleton, type ConsumeCallback, type ConsumerOptions, type Logger, type LoggerContext, MessageValidationError, MessagingSemanticConventions, type PublishOptions, TechnicalError, type TelemetryProvider, _resetTelemetryCacheForTesting, defaultTelemetryProvider, endSpanError, endSpanSuccess, recordConsumeMetric, recordPublishMetric, setupAmqpTopology, startConsumeSpan, startPublishSpan };
+export { AmqpClient, type AmqpClientOptions, type ConsumeCallback, type ConsumerOptions, DEFAULT_CONNECT_TIMEOUT_MS, type Logger, type LoggerContext, MessageValidationError, MessagingSemanticConventions, type PublishOptions, TechnicalError, type TelemetryProvider, _getConnectionCountForTesting, _resetConnectionsForTesting, _resetTelemetryCacheForTesting, defaultTelemetryProvider, endSpanError, endSpanSuccess, recordConsumeMetric, recordLateRpcReply, recordPublishMetric, setupAmqpTopology, startConsumeSpan, startPublishSpan };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/errors.ts","../src/amqp-client.ts","../src/connection-manager.ts","../src/logger.ts","../src/setup.ts","../src/telemetry.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/errors.ts","../src/amqp-client.ts","../src/connection-manager.ts","../src/logger.ts","../src/setup.ts","../src/telemetry.ts"],"mappings":"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"}

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { createRequire } from "node:module";
-import { Future } from "@swan-io/boxed";
+import { Future, Result } from "@swan-io/boxed";
 import amqp from "amqp-connection-manager";
 import { extractQueue } from "@amqp-contract/contract";
 //#region \0rolldown/runtime.js
@@ -119,6 +119,14 @@ var ConnectionManagerSingleton = class ConnectionManagerSingleton {
 		return value;
 	}
 	/**
+	* Get the number of active pooled connections.
+	*
+	* @internal
+	*/
+	_getConnectionCountForTesting() {
+		return this.connections.size;
+	}
+	/**
 	* Reset all cached connections (for testing purposes)
 	* @internal
 	*/
@@ -129,6 +137,25 @@ var ConnectionManagerSingleton = class ConnectionManagerSingleton {
 		this.refCounts.clear();
 	}
 };
+/**
+* Number of active pooled connections. Test-only helper — exposed in lieu of
+* the underlying singleton, which is intentionally not part of the public API
+* (mutating it from outside the library can break in-flight clients sharing a
+* connection).
+*
+* @internal
+*/
+function _getConnectionCountForTesting() {
+	return ConnectionManagerSingleton.getInstance()._getConnectionCountForTesting();
+}
+/**
+* Close every pooled connection and clear ref-counts. Test-only helper.
+*
+* @internal
+*/
+function _resetConnectionsForTesting() {
+	return ConnectionManagerSingleton.getInstance()._resetForTesting();
+}
 //#endregion
 //#region src/errors.ts
 /**
@@ -188,13 +215,20 @@ var MessageValidationError = class extends Error {
 * ```
 */
 async function setupAmqpTopology(channel, contract) {
-	const exchangeErrors = (await Promise.allSettled(Object.values(contract.exchanges ?? {}).map((exchange) => channel.assertExchange(exchange.name, exchange.type, {
+	const exchanges = Object.values(contract.exchanges ?? {}).filter((e) => e.name !== "");
+	const exchangeErrors = (await Promise.allSettled(exchanges.map((exchange) => channel.assertExchange(exchange.name, exchange.type, {
 		durable: exchange.durable,
 		autoDelete: exchange.autoDelete,
 		internal: exchange.internal,
 		arguments: exchange.arguments
-	})))).filter((result) => result.status === "rejected");
-	if (exchangeErrors.length > 0) throw new AggregateError(exchangeErrors.map(({ reason }) => reason), "Failed to setup exchanges");
+	})))).map((result, i) => ({
+		result,
+		name: exchanges[i].name
+	})).filter((entry) => entry.result.status === "rejected");
+	if (exchangeErrors.length > 0) {
+		const names = exchangeErrors.map((e) => e.name).join(", ");
+		throw new AggregateError(exchangeErrors.map(({ result }) => result.reason), `Failed to setup exchanges: ${names}`);
+	}
 	for (const queueEntry of Object.values(contract.queues ?? {})) {
 		const queue = extractQueue(queueEntry);
 		if (queue.deadLetter) {
@@ -202,7 +236,8 @@ async function setupAmqpTopology(channel, contract) {
 			if (!Object.values(contract.exchanges ?? {}).some((exchange) => exchange.name === dlxName)) throw new TechnicalError(`Queue "${queue.name}" references dead letter exchange "${dlxName}" which is not declared in the contract. Add the exchange to contract.exchanges to ensure it is created before the queue.`);
 		}
 	}
-	const queueErrors = (await Promise.allSettled(Object.values(contract.queues ?? {}).map((queueEntry) => {
+	const queueEntries = Object.values(contract.queues ?? {});
+	const queueErrors = (await Promise.allSettled(queueEntries.map((queueEntry) => {
 		const queue = extractQueue(queueEntry);
 		const queueArguments = { ...queue.arguments };
 		queueArguments["x-queue-type"] = queue.type;
@@ -221,13 +256,29 @@ async function setupAmqpTopology(channel, contract) {
 			autoDelete: queue.autoDelete,
 			arguments: queueArguments
 		});
-	}))).filter((result) => result.status === "rejected");
-	if (queueErrors.length > 0) throw new AggregateError(queueErrors.map(({ reason }) => reason), "Failed to setup queues");
-	const bindingErrors = (await Promise.allSettled(Object.values(contract.bindings ?? {}).map((binding) => {
+	}))).map((result, i) => ({
+		result,
+		name: extractQueue(queueEntries[i]).name
+	})).filter((entry) => entry.result.status === "rejected");
+	if (queueErrors.length > 0) {
+		const names = queueErrors.map((e) => e.name).join(", ");
+		throw new AggregateError(queueErrors.map(({ result }) => result.reason), `Failed to setup queues: ${names}`);
+	}
+	const bindings = Object.values(contract.bindings ?? {});
+	const bindingErrors = (await Promise.allSettled(bindings.map((binding) => {
 		if (binding.type === "queue") return channel.bindQueue(binding.queue.name, binding.exchange.name, binding.routingKey ?? "", binding.arguments);
 		return channel.bindExchange(binding.destination.name, binding.source.name, binding.routingKey ?? "", binding.arguments);
-	}))).filter((result) => result.status === "rejected");
-	if (bindingErrors.length > 0) throw new AggregateError(bindingErrors.map(({ reason }) => reason), "Failed to setup bindings");
+	}))).map((result, i) => {
+		const binding = bindings[i];
+		return {
+			result,
+			name: binding.type === "queue" ? `${binding.exchange.name} -> ${binding.queue.name}` : `${binding.source.name} -> ${binding.destination.name}`
+		};
+	}).filter((entry) => entry.result.status === "rejected");
+	if (bindingErrors.length > 0) {
+		const names = bindingErrors.map((e) => e.name).join(", ");
+		throw new AggregateError(bindingErrors.map(({ result }) => result.reason), `Failed to setup bindings: ${names}`);
+	}
 }
 //#endregion
 //#region src/amqp-client.ts
@@ -246,6 +297,28 @@ function callSetupFunc(setup, channel) {
 	return setup(channel);
 }
 /**
+* Default time `waitForConnect` will wait for the broker before erroring out.
+* Defaulting to a finite value (rather than waiting forever) means a fail-fast
+* developer experience: a misconfigured URL, a down broker, or wrong
+* credentials surface as a Result.Error within 30 seconds. Pass `null`
+* explicitly to disable the timeout — `Infinity` and other non-finite values
+* are also coerced to "no timeout" because Node's `setTimeout` clamps large
+* delays to ~24.8 days and silently fires near-immediately on `Infinity`.
+*/
+const DEFAULT_CONNECT_TIMEOUT_MS = 3e4;
+/**
+* Normalise the user-supplied connect timeout to either a positive finite
+* number of milliseconds, or `null` (no timeout). `Infinity`, `NaN`, and
+* non-positive values all map to `null` rather than being passed to
+* `setTimeout` — see {@link DEFAULT_CONNECT_TIMEOUT_MS}.
+*/
+function resolveConnectTimeoutMs(input) {
+	if (input === null) return null;
+	if (input === void 0) return DEFAULT_CONNECT_TIMEOUT_MS;
+	if (!Number.isFinite(input) || input <= 0) return null;
+	return input;
+}
+/**
 * AMQP client that manages connections and channels with automatic topology setup.
 *
 * This class handles:
@@ -278,6 +351,8 @@ var AmqpClient = class {
 	channelWrapper;
 	urls;
 	connectionOptions;
+	/** Resolved timeout in ms; `null` means "wait forever". */
+	connectTimeoutMs;
 	/**
 	* Create a new AMQP client instance.
 	*
@@ -293,6 +368,7 @@ var AmqpClient = class {
 		this.contract = contract;
 		this.urls = options.urls;
 		if (options.connectionOptions !== void 0) this.connectionOptions = options.connectionOptions;
+		this.connectTimeoutMs = resolveConnectTimeoutMs(options.connectTimeoutMs);
 		const singleton = ConnectionManagerSingleton.getInstance();
 		this.connection = singleton.getConnection(options.urls, options.connectionOptions);
 		const defaultSetup = (channel) => setupAmqpTopology(channel, this.contract);
@@ -324,10 +400,36 @@ var AmqpClient = class {
 	/**
 	* Wait for the channel to be connected and ready.
 	*
-	* @returns A Future that resolves when the channel is connected
+	* If `connectTimeoutMs` was provided in the constructor options, the returned
+	* Future resolves to `Result.Error<TechnicalError>` once the timeout elapses.
+	* Without a timeout, this waits forever — amqp-connection-manager retries
+	* connections indefinitely and never errors on its own.
+	*
+	* NOTE: When using `AmqpClient` directly (not via `TypedAmqpClient` /
+	* `TypedAmqpWorker`), the constructor has already incremented the pooled
+	* connection's reference count. Callers must invoke `close()` on the error
+	* path to release the connection — `waitForConnect` does not do this
+	* automatically. The typed factories handle this cleanup for you.
+	*
+	* @returns A Future resolving to `Result.Ok(void)` on connect, or
+	*   `Result.Error(TechnicalError)` on timeout / connection failure.
 	*/
 	waitForConnect() {
-		return Future.fromPromise(this.channelWrapper.waitForConnect()).mapError((error) => new TechnicalError("Failed to connect to AMQP broker", error));
+		const connectPromise = this.channelWrapper.waitForConnect();
+		const timeoutMs = this.connectTimeoutMs;
+		const racedPromise = timeoutMs === null ? connectPromise : new Promise((resolve, reject) => {
+			const handle = setTimeout(() => {
+				reject(/* @__PURE__ */ new Error(`Timed out waiting for AMQP connection after ${timeoutMs}ms`));
+			}, timeoutMs);
+			connectPromise.then(() => {
+				clearTimeout(handle);
+				resolve();
+			}, (error) => {
+				clearTimeout(handle);
+				reject(error);
+			});
+		});
+		return Future.fromPromise(racedPromise).mapError((error) => new TechnicalError("Failed to connect to AMQP broker", error));
 	}
 	/**
 	* Publish a message to an exchange.
@@ -426,7 +528,10 @@ var AmqpClient = class {
 	* @returns A Future that resolves when the channel and connection are closed
 	*/
 	close() {
-		return Future.fromPromise(this.channelWrapper.close()).mapError((error) => new TechnicalError("Failed to close channel", error)).flatMapOk(() => Future.fromPromise(ConnectionManagerSingleton.getInstance().releaseConnection(this.urls, this.connectionOptions)).mapError((error) => new TechnicalError("Failed to release connection", error))).mapOk(() => void 0);
+		return Future.fromPromise(this.channelWrapper.close()).mapError((error) => new TechnicalError("Failed to close channel", error)).flatMap((channelResult) => Future.fromPromise(ConnectionManagerSingleton.getInstance().releaseConnection(this.urls, this.connectionOptions)).mapError((error) => new TechnicalError("Failed to release connection", error)).map((releaseResult) => {
+			if (channelResult.isError() && releaseResult.isError()) return Result.Error(new TechnicalError("Failed to close channel and release connection", new AggregateError([channelResult.error, releaseResult.error], "Failed to close channel and release connection")));
+			return channelResult.isError() ? channelResult : releaseResult;
+		}));
 	}
 	/**
 	* Reset connection singleton cache (for testing only)
@@ -444,7 +549,9 @@ var AmqpClient = class {
 * @see https://opentelemetry.io/docs/specs/otel/trace/api/#spankind
 */
 const SpanKind = {
+	/** Producer span represents a message producer */
 	PRODUCER: 3,
+	/** Consumer span represents a message consumer */
 	CONSUMER: 4
 };
 /**
@@ -471,13 +578,27 @@ const MessagingSemanticConventions = {
 * Instrumentation scope name for amqp-contract.
 */
 const INSTRUMENTATION_SCOPE_NAME = "@amqp-contract";
-const INSTRUMENTATION_SCOPE_VERSION = "0.1.0";
+/**
+* Instrumentation scope version, sourced from this package's package.json so
+* the OTel meter version always tracks the released library version. We use
+* `createRequire` rather than a JSON import attribute so the same source builds
+* to ESM, CJS, and runs under bundlers that don't yet understand
+* `import … with { type: "json" }`.
+*/
+const INSTRUMENTATION_SCOPE_VERSION = (() => {
+	try {
+		return createRequire(import.meta.url)("../package.json").version ?? "0.0.0";
+	} catch {
+		return "0.0.0";
+	}
+})();
 let otelApi;
 let cachedTracer;
 let cachedPublishCounter;
 let cachedConsumeCounter;
 let cachedPublishLatencyHistogram;
 let cachedConsumeLatencyHistogram;
+let cachedLateRpcReplyCounter;
 /**
 * Try to load the OpenTelemetry API module.
 * Returns null if the module is not available.
@@ -508,14 +629,16 @@ function getMeterInstruments() {
 		publishCounter: cachedPublishCounter,
 		consumeCounter: cachedConsumeCounter,
 		publishLatencyHistogram: cachedPublishLatencyHistogram,
-		consumeLatencyHistogram: cachedConsumeLatencyHistogram
+		consumeLatencyHistogram: cachedConsumeLatencyHistogram,
+		lateRpcReplyCounter: cachedLateRpcReplyCounter
 	};
 	const api = tryLoadOpenTelemetryApi();
 	if (!api) return {
 		publishCounter: void 0,
 		consumeCounter: void 0,
 		publishLatencyHistogram: void 0,
-		consumeLatencyHistogram: void 0
+		consumeLatencyHistogram: void 0,
+		lateRpcReplyCounter: void 0
 	};
 	const meter = api.metrics.getMeter(INSTRUMENTATION_SCOPE_NAME, INSTRUMENTATION_SCOPE_VERSION);
 	cachedPublishCounter = meter.createCounter("amqp.client.messages.published", {
@@ -534,11 +657,16 @@ function getMeterInstruments() {
 		description: "Duration of message processing operations",
 		unit: "ms"
 	});
+	cachedLateRpcReplyCounter = meter.createCounter("amqp.client.rpc.late_reply", {
+		description: "RPC replies received after the caller stopped waiting (timeout, cancellation, or unknown correlationId)",
+		unit: "{message}"
+	});
 	return {
 		publishCounter: cachedPublishCounter,
 		consumeCounter: cachedConsumeCounter,
 		publishLatencyHistogram: cachedPublishLatencyHistogram,
-		consumeLatencyHistogram: cachedConsumeLatencyHistogram
+		consumeLatencyHistogram: cachedConsumeLatencyHistogram,
+		lateRpcReplyCounter: cachedLateRpcReplyCounter
 	};
 }
 /**
@@ -549,7 +677,8 @@ const defaultTelemetryProvider = {
 	getPublishCounter: () => getMeterInstruments().publishCounter,
 	getConsumeCounter: () => getMeterInstruments().consumeCounter,
 	getPublishLatencyHistogram: () => getMeterInstruments().publishLatencyHistogram,
-	getConsumeLatencyHistogram: () => getMeterInstruments().consumeLatencyHistogram
+	getConsumeLatencyHistogram: () => getMeterInstruments().consumeLatencyHistogram,
+	getLateRpcReplyCounter: () => getMeterInstruments().lateRpcReplyCounter
 };
 /**
 * Create a span for a publish operation.
@@ -647,6 +776,22 @@ function recordConsumeMetric(provider, queueName, consumerName, success, duratio
 	consumeLatencyHistogram?.record(durationMs, attributes);
 }
 /**
+* Record an RPC reply that arrived after the caller stopped waiting.
+*
+* @param reason - Why the reply was orphaned. `"unknown-correlation-id"` is
+*   the typical "caller already timed out" case; `"missing-correlation-id"`
+*   means the broker delivered a reply with no correlationId at all (a
+*   protocol violation by the responder).
+*/
+function recordLateRpcReply(provider, reason) {
+	const counter = provider.getLateRpcReplyCounter();
+	const attributes = {
+		[MessagingSemanticConventions.MESSAGING_SYSTEM]: MessagingSemanticConventions.MESSAGING_SYSTEM_RABBITMQ,
+		reason
+	};
+	counter?.add(1, attributes);
+}
+/**
 * Reset the cached OpenTelemetry API module and instruments.
 * For testing purposes only.
 * @internal
@@ -658,8 +803,9 @@ function _resetTelemetryCacheForTesting() {
 	cachedConsumeCounter = void 0;
 	cachedPublishLatencyHistogram = void 0;
 	cachedConsumeLatencyHistogram = void 0;
+	cachedLateRpcReplyCounter = void 0;
 }
 //#endregion
-export { AmqpClient, ConnectionManagerSingleton, MessageValidationError, MessagingSemanticConventions, TechnicalError, _resetTelemetryCacheForTesting, defaultTelemetryProvider, endSpanError, endSpanSuccess, recordConsumeMetric, recordPublishMetric, setupAmqpTopology, startConsumeSpan, startPublishSpan };
+export { AmqpClient, DEFAULT_CONNECT_TIMEOUT_MS, MessageValidationError, MessagingSemanticConventions, TechnicalError, _getConnectionCountForTesting, _resetConnectionsForTesting, _resetTelemetryCacheForTesting, defaultTelemetryProvider, endSpanError, endSpanSuccess, recordConsumeMetric, recordLateRpcReply, recordPublishMetric, setupAmqpTopology, startConsumeSpan, startPublishSpan };
 
 //# sourceMappingURL=index.mjs.map