@amqp-contract/core 0.7.0 → 0.9.0

package/dist/index.cjs

@@ -30,19 +30,44 @@ amqp_connection_manager = __toESM(amqp_connection_manager);
 
 //#region src/connection-manager.ts
 /**
-* Connection manager singleton for sharing connections across clients
+* Connection manager singleton for sharing AMQP connections across clients.
+*
+* 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.
+*
+* @example
+* ```typescript
+* const manager = ConnectionManagerSingleton.getInstance();
+* const connection = manager.getConnection(['amqp://localhost']);
+* // ... use connection ...
+* await manager.releaseConnection(['amqp://localhost']);
+* ```
 */
 var ConnectionManagerSingleton = class ConnectionManagerSingleton {
 	static instance;
 	connections = /* @__PURE__ */ new Map();
 	refCounts = /* @__PURE__ */ new Map();
 	constructor() {}
+	/**
+	* Get the singleton instance of the connection manager.
+	*
+	* @returns The singleton instance
+	*/
 	static getInstance() {
 		if (!ConnectionManagerSingleton.instance) ConnectionManagerSingleton.instance = new ConnectionManagerSingleton();
 		return ConnectionManagerSingleton.instance;
 	}
 	/**
-	* Get or create a connection for the given URLs and options
+	* 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, connectionOptions) {
 		const key = this.createConnectionKey(urls, connectionOptions);
@@ -55,7 +80,14 @@ var ConnectionManagerSingleton = class ConnectionManagerSingleton {
 		return this.connections.get(key);
 	}
 	/**
-	* Release a connection reference. If no more references exist, close the connection.
+	* 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)
 	*/
 	async releaseConnection(urls, connectionOptions) {
 		const key = this.createConnectionKey(urls, connectionOptions);
@@ -69,13 +101,35 @@ var ConnectionManagerSingleton = class ConnectionManagerSingleton {
 			}
 		} else this.refCounts.set(key, refCount - 1);
 	}
+	/**
+	* 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
+	*/
 	createConnectionKey(urls, connectionOptions) {
 		return `${JSON.stringify(urls)}::${connectionOptions ? this.serializeOptions(connectionOptions) : ""}`;
 	}
+	/**
+	* Serialize connection options to a deterministic string.
+	*
+	* @param options - Connection options to serialize
+	* @returns A JSON string with sorted keys for deterministic comparison
+	*/
 	serializeOptions(options) {
 		const sorted = this.deepSort(options);
 		return JSON.stringify(sorted);
 	}
+	/**
+	* 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
+	*/
 	deepSort(value) {
 		if (Array.isArray(value)) return value.map((item) => this.deepSort(item));
 		if (value !== null && typeof value === "object") {
@@ -102,7 +156,24 @@ var ConnectionManagerSingleton = class ConnectionManagerSingleton {
 //#endregion
 //#region src/setup.ts
 /**
-* Setup AMQP topology (exchanges, queues, and bindings) from a contract definition
+* Setup AMQP topology (exchanges, queues, and bindings) from a contract definition.
+*
+* This function sets up the complete AMQP topology in the correct order:
+* 1. Assert all exchanges defined in the contract
+* 2. Validate dead letter exchanges are declared before referencing them
+* 3. Assert all queues with their configurations (including dead letter settings)
+* 4. Create all bindings (queue-to-exchange and exchange-to-exchange)
+*
+* @param channel - The AMQP channel to use for topology setup
+* @param contract - The contract definition containing the topology specification
+* @throws {AggregateError} If any exchanges, queues, or bindings fail to be created
+* @throws {Error} If a queue references a dead letter exchange not declared in the contract
+*
+* @example
+* ```typescript
+* const channel = await connection.createChannel();
+* await setupAmqpTopology(channel, contract);
+* ```
 */
 async function setupAmqpTopology(channel, contract) {
 	const exchangeErrors = (await Promise.allSettled(Object.values(contract.exchanges ?? {}).map((exchange) => channel.assertExchange(exchange.name, exchange.type, {
@@ -139,11 +210,45 @@ async function setupAmqpTopology(channel, contract) {
 
 //#endregion
 //#region src/amqp-client.ts
+/**
+* AMQP client that manages connections and channels with automatic topology setup.
+*
+* This class handles:
+* - Connection management with automatic reconnection via amqp-connection-manager
+* - Connection pooling and sharing across instances with the same URLs
+* - Automatic AMQP topology setup (exchanges, queues, bindings) from contract
+* - Channel creation with JSON serialization enabled by default
+*
+* @example
+* ```typescript
+* const client = new AmqpClient(contract, {
+*   urls: ['amqp://localhost'],
+*   connectionOptions: { heartbeatIntervalInSeconds: 30 }
+* });
+*
+* // Use the channel to publish messages
+* await client.channel.publish('exchange', 'routingKey', { data: 'value' });
+*
+* // Close when done
+* await client.close();
+* ```
+*/
 var AmqpClient = class {
 	connection;
 	channel;
 	urls;
 	connectionOptions;
+	/**
+	* Create a new AMQP client instance.
+	*
+	* The client will automatically:
+	* - Get or create a shared connection using the singleton pattern
+	* - Set up AMQP topology (exchanges, queues, bindings) from the contract
+	* - Create a channel with JSON serialization enabled
+	*
+	* @param contract - The contract definition specifying the AMQP topology
+	* @param options - Client configuration options
+	*/
 	constructor(contract, options) {
 		this.contract = contract;
 		this.urls = options.urls;
@@ -180,6 +285,16 @@ var AmqpClient = class {
 	getConnection() {
 		return this.connection;
 	}
+	/**
+	* Close the channel and release the connection reference.
+	*
+	* This will:
+	* - Close the channel wrapper
+	* - Decrease the reference count on the shared connection
+	* - Close the connection if this was the last client using it
+	*
+	* @returns A promise that resolves when the channel and connection are closed
+	*/
 	async close() {
 		await this.channel.close();
 		await ConnectionManagerSingleton.getInstance().releaseConnection(this.urls, this.connectionOptions);
@@ -193,7 +308,242 @@ var AmqpClient = class {
 	}
 };
 
+//#endregion
+//#region src/telemetry.ts
+/**
+* SpanKind values from OpenTelemetry.
+* Defined as constants to avoid runtime dependency when types are used.
+* @see https://opentelemetry.io/docs/specs/otel/trace/api/#spankind
+*/
+const SpanKind = {
+	PRODUCER: 3,
+	CONSUMER: 4
+};
+/**
+* Semantic conventions for AMQP messaging following OpenTelemetry standards.
+* @see https://opentelemetry.io/docs/specs/semconv/messaging/messaging-spans/
+*/
+const MessagingSemanticConventions = {
+	MESSAGING_SYSTEM: "messaging.system",
+	MESSAGING_DESTINATION: "messaging.destination.name",
+	MESSAGING_DESTINATION_KIND: "messaging.destination.kind",
+	MESSAGING_OPERATION: "messaging.operation",
+	MESSAGING_MESSAGE_ID: "messaging.message.id",
+	MESSAGING_MESSAGE_PAYLOAD_SIZE: "messaging.message.body.size",
+	MESSAGING_MESSAGE_CONVERSATION_ID: "messaging.message.conversation_id",
+	MESSAGING_RABBITMQ_ROUTING_KEY: "messaging.rabbitmq.destination.routing_key",
+	MESSAGING_RABBITMQ_MESSAGE_DELIVERY_TAG: "messaging.rabbitmq.message.delivery_tag",
+	ERROR_TYPE: "error.type",
+	MESSAGING_SYSTEM_RABBITMQ: "rabbitmq",
+	MESSAGING_DESTINATION_KIND_EXCHANGE: "exchange",
+	MESSAGING_DESTINATION_KIND_QUEUE: "queue",
+	MESSAGING_OPERATION_PUBLISH: "publish",
+	MESSAGING_OPERATION_RECEIVE: "receive",
+	MESSAGING_OPERATION_PROCESS: "process"
+};
+/**
+* Instrumentation scope name for amqp-contract.
+*/
+const INSTRUMENTATION_SCOPE_NAME = "@amqp-contract";
+const INSTRUMENTATION_SCOPE_VERSION = "0.1.0";
+let otelApi;
+let cachedTracer;
+let cachedPublishCounter;
+let cachedConsumeCounter;
+let cachedPublishLatencyHistogram;
+let cachedConsumeLatencyHistogram;
+/**
+* Try to load the OpenTelemetry API module.
+* Returns null if the module is not available.
+*/
+function tryLoadOpenTelemetryApi() {
+	if (otelApi === void 0) try {
+		otelApi = require("@opentelemetry/api");
+	} catch {
+		otelApi = null;
+	}
+	return otelApi;
+}
+/**
+* Get or create a tracer instance.
+*/
+function getTracer() {
+	if (cachedTracer !== void 0) return cachedTracer;
+	const api = tryLoadOpenTelemetryApi();
+	if (!api) return;
+	cachedTracer = api.trace.getTracer(INSTRUMENTATION_SCOPE_NAME, INSTRUMENTATION_SCOPE_VERSION);
+	return cachedTracer;
+}
+/**
+* Get or create a meter and its instruments.
+*/
+function getMeterInstruments() {
+	if (cachedPublishCounter !== void 0) return {
+		publishCounter: cachedPublishCounter,
+		consumeCounter: cachedConsumeCounter,
+		publishLatencyHistogram: cachedPublishLatencyHistogram,
+		consumeLatencyHistogram: cachedConsumeLatencyHistogram
+	};
+	const api = tryLoadOpenTelemetryApi();
+	if (!api) return {
+		publishCounter: void 0,
+		consumeCounter: void 0,
+		publishLatencyHistogram: void 0,
+		consumeLatencyHistogram: void 0
+	};
+	const meter = api.metrics.getMeter(INSTRUMENTATION_SCOPE_NAME, INSTRUMENTATION_SCOPE_VERSION);
+	cachedPublishCounter = meter.createCounter("amqp.client.messages.published", {
+		description: "Number of messages published to AMQP broker",
+		unit: "{message}"
+	});
+	cachedConsumeCounter = meter.createCounter("amqp.worker.messages.consumed", {
+		description: "Number of messages consumed from AMQP broker",
+		unit: "{message}"
+	});
+	cachedPublishLatencyHistogram = meter.createHistogram("amqp.client.publish.duration", {
+		description: "Duration of message publish operations",
+		unit: "ms"
+	});
+	cachedConsumeLatencyHistogram = meter.createHistogram("amqp.worker.process.duration", {
+		description: "Duration of message processing operations",
+		unit: "ms"
+	});
+	return {
+		publishCounter: cachedPublishCounter,
+		consumeCounter: cachedConsumeCounter,
+		publishLatencyHistogram: cachedPublishLatencyHistogram,
+		consumeLatencyHistogram: cachedConsumeLatencyHistogram
+	};
+}
+/**
+* Default telemetry provider that uses OpenTelemetry API if available.
+*/
+const defaultTelemetryProvider = {
+	getTracer,
+	getPublishCounter: () => getMeterInstruments().publishCounter,
+	getConsumeCounter: () => getMeterInstruments().consumeCounter,
+	getPublishLatencyHistogram: () => getMeterInstruments().publishLatencyHistogram,
+	getConsumeLatencyHistogram: () => getMeterInstruments().consumeLatencyHistogram
+};
+/**
+* Create a span for a publish operation.
+* Returns undefined if OpenTelemetry is not available.
+*/
+function startPublishSpan(provider, exchangeName, routingKey, attributes) {
+	const tracer = provider.getTracer();
+	if (!tracer) return;
+	const spanName = `${exchangeName} publish`;
+	return tracer.startSpan(spanName, {
+		kind: SpanKind.PRODUCER,
+		attributes: {
+			[MessagingSemanticConventions.MESSAGING_SYSTEM]: MessagingSemanticConventions.MESSAGING_SYSTEM_RABBITMQ,
+			[MessagingSemanticConventions.MESSAGING_DESTINATION]: exchangeName,
+			[MessagingSemanticConventions.MESSAGING_DESTINATION_KIND]: MessagingSemanticConventions.MESSAGING_DESTINATION_KIND_EXCHANGE,
+			[MessagingSemanticConventions.MESSAGING_OPERATION]: MessagingSemanticConventions.MESSAGING_OPERATION_PUBLISH,
+			...routingKey ? { [MessagingSemanticConventions.MESSAGING_RABBITMQ_ROUTING_KEY]: routingKey } : {},
+			...attributes
+		}
+	});
+}
+/**
+* Create a span for a consume/process operation.
+* Returns undefined if OpenTelemetry is not available.
+*/
+function startConsumeSpan(provider, queueName, consumerName, attributes) {
+	const tracer = provider.getTracer();
+	if (!tracer) return;
+	const spanName = `${queueName} process`;
+	return tracer.startSpan(spanName, {
+		kind: SpanKind.CONSUMER,
+		attributes: {
+			[MessagingSemanticConventions.MESSAGING_SYSTEM]: MessagingSemanticConventions.MESSAGING_SYSTEM_RABBITMQ,
+			[MessagingSemanticConventions.MESSAGING_DESTINATION]: queueName,
+			[MessagingSemanticConventions.MESSAGING_DESTINATION_KIND]: MessagingSemanticConventions.MESSAGING_DESTINATION_KIND_QUEUE,
+			[MessagingSemanticConventions.MESSAGING_OPERATION]: MessagingSemanticConventions.MESSAGING_OPERATION_PROCESS,
+			"amqp.consumer.name": consumerName,
+			...attributes
+		}
+	});
+}
+/**
+* End a span with success status.
+*/
+function endSpanSuccess(span) {
+	if (!span) return;
+	const api = tryLoadOpenTelemetryApi();
+	if (api) span.setStatus({ code: api.SpanStatusCode.OK });
+	span.end();
+}
+/**
+* End a span with error status.
+*/
+function endSpanError(span, error) {
+	if (!span) return;
+	const api = tryLoadOpenTelemetryApi();
+	if (api) {
+		span.setStatus({
+			code: api.SpanStatusCode.ERROR,
+			message: error.message
+		});
+		span.recordException(error);
+		span.setAttribute(MessagingSemanticConventions.ERROR_TYPE, error.name);
+	}
+	span.end();
+}
+/**
+* Record a publish metric.
+*/
+function recordPublishMetric(provider, exchangeName, routingKey, success, durationMs) {
+	const publishCounter = provider.getPublishCounter();
+	const publishLatencyHistogram = provider.getPublishLatencyHistogram();
+	const attributes = {
+		[MessagingSemanticConventions.MESSAGING_SYSTEM]: MessagingSemanticConventions.MESSAGING_SYSTEM_RABBITMQ,
+		[MessagingSemanticConventions.MESSAGING_DESTINATION]: exchangeName,
+		...routingKey ? { [MessagingSemanticConventions.MESSAGING_RABBITMQ_ROUTING_KEY]: routingKey } : {},
+		success
+	};
+	publishCounter?.add(1, attributes);
+	publishLatencyHistogram?.record(durationMs, attributes);
+}
+/**
+* Record a consume metric.
+*/
+function recordConsumeMetric(provider, queueName, consumerName, success, durationMs) {
+	const consumeCounter = provider.getConsumeCounter();
+	const consumeLatencyHistogram = provider.getConsumeLatencyHistogram();
+	const attributes = {
+		[MessagingSemanticConventions.MESSAGING_SYSTEM]: MessagingSemanticConventions.MESSAGING_SYSTEM_RABBITMQ,
+		[MessagingSemanticConventions.MESSAGING_DESTINATION]: queueName,
+		"amqp.consumer.name": consumerName,
+		success
+	};
+	consumeCounter?.add(1, attributes);
+	consumeLatencyHistogram?.record(durationMs, attributes);
+}
+/**
+* Reset the cached OpenTelemetry API module and instruments.
+* For testing purposes only.
+* @internal
+*/
+function _resetTelemetryCacheForTesting() {
+	otelApi = void 0;
+	cachedTracer = void 0;
+	cachedPublishCounter = void 0;
+	cachedConsumeCounter = void 0;
+	cachedPublishLatencyHistogram = void 0;
+	cachedConsumeLatencyHistogram = void 0;
+}
+
 //#endregion
 exports.AmqpClient = AmqpClient;
 exports.ConnectionManagerSingleton = ConnectionManagerSingleton;
-exports.setupAmqpTopology = setupAmqpTopology;
+exports.MessagingSemanticConventions = MessagingSemanticConventions;
+exports._resetTelemetryCacheForTesting = _resetTelemetryCacheForTesting;
+exports.defaultTelemetryProvider = defaultTelemetryProvider;
+exports.endSpanError = endSpanError;
+exports.endSpanSuccess = endSpanSuccess;
+exports.recordConsumeMetric = recordConsumeMetric;
+exports.recordPublishMetric = recordPublishMetric;
+exports.setupAmqpTopology = setupAmqpTopology;
+exports.startConsumeSpan = startConsumeSpan;
+exports.startPublishSpan = startPublishSpan;