@linagora/rabbitmq-client 0.4.0 → 0.5.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { R as RabbitMQClientOptions, a as RabbitMQMessage, P as PublishOptions, b as RabbitMQMessageHandler, S as SubscribeOptions, I as ILogger } from './types-D29GyoZX.cjs';
-export { c as RabbitMQHooks, d as RabbitMQMessageProperties, e as RabbitMQSubscription } from './types-D29GyoZX.cjs';
+import { R as RabbitMQClientOptions, a as RabbitMQMessage, P as PublishOptions, b as RabbitMQMessageHandler, S as SubscribeOptions, I as ILogger } from './types-Cjg-65Ef.cjs';
+export { c as RabbitMQBinding, d as RabbitMQHooks, e as RabbitMQMessageProperties, f as RabbitMQSubscription } from './types-Cjg-65Ef.cjs';
 
 /** A `mandatory` publish the broker could route to no queue. */
 declare class UnroutableMessageError extends Error {
@@ -7,6 +7,12 @@ declare class UnroutableMessageError extends Error {
     readonly routingKey: string;
     constructor(exchange: string, routingKey: string);
 }
+/** Thrown by a handler to send its message to the DLQ at once, without retrying. */
+declare class DeadLetterError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
 /**
  * Production-grade RabbitMQ client with confirm channels, automatic DLQ
  * infrastructure, reconnection with subscription restoration, and
@@ -24,6 +30,7 @@ declare class RabbitMQClient {
     private connection;
     private channel;
     private connected;
+    private closing;
     private subscriptions;
     private readonly options;
     private readonly logger;
@@ -34,6 +41,7 @@ declare class RabbitMQClient {
     private returnWaiters;
     private consumerTags;
     private subscriptionSemaphores;
+    private retryWakers;
     private inflightCount;
     private drainResolve;
     constructor(options: RabbitMQClientOptions);
@@ -78,6 +86,7 @@ declare class RabbitMQClient {
      */
     unsubscribe(queue: string): Promise<void>;
     private setupSubscription;
+    private checkExchanges;
     /**
      * Gates a delivered message on the subscription's concurrency semaphore, then
      * processes it. A message counts as in-flight from delivery until its handler
@@ -104,6 +113,10 @@ declare class RabbitMQClient {
     /** Invokes a hook callback, swallowing errors so hooks never break message flow. */
     private callHook;
     private sleep;
+    private retryDelayFor;
+    private wakeRetries;
+    /** Also cut short by a reconnect, via wakeRetries(). */
+    private sleepUntilClose;
 }
 
 /**
@@ -122,4 +135,4 @@ declare const defaultLogger: ILogger;
  */
 declare const silentLogger: ILogger;
 
-export { ILogger, PublishOptions, RabbitMQClient, RabbitMQClientOptions, RabbitMQMessage, RabbitMQMessageHandler, SubscribeOptions, UnroutableMessageError, defaultLogger, silentLogger };
+export { DeadLetterError, ILogger, PublishOptions, RabbitMQClient, RabbitMQClientOptions, RabbitMQMessage, RabbitMQMessageHandler, SubscribeOptions, UnroutableMessageError, defaultLogger, silentLogger };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { R as RabbitMQClientOptions, a as RabbitMQMessage, P as PublishOptions, b as RabbitMQMessageHandler, S as SubscribeOptions, I as ILogger } from './types-D29GyoZX.js';
-export { c as RabbitMQHooks, d as RabbitMQMessageProperties, e as RabbitMQSubscription } from './types-D29GyoZX.js';
+import { R as RabbitMQClientOptions, a as RabbitMQMessage, P as PublishOptions, b as RabbitMQMessageHandler, S as SubscribeOptions, I as ILogger } from './types-Cjg-65Ef.js';
+export { c as RabbitMQBinding, d as RabbitMQHooks, e as RabbitMQMessageProperties, f as RabbitMQSubscription } from './types-Cjg-65Ef.js';
 
 /** A `mandatory` publish the broker could route to no queue. */
 declare class UnroutableMessageError extends Error {
@@ -7,6 +7,12 @@ declare class UnroutableMessageError extends Error {
     readonly routingKey: string;
     constructor(exchange: string, routingKey: string);
 }
+/** Thrown by a handler to send its message to the DLQ at once, without retrying. */
+declare class DeadLetterError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
 /**
  * Production-grade RabbitMQ client with confirm channels, automatic DLQ
  * infrastructure, reconnection with subscription restoration, and
@@ -24,6 +30,7 @@ declare class RabbitMQClient {
     private connection;
     private channel;
     private connected;
+    private closing;
     private subscriptions;
     private readonly options;
     private readonly logger;
@@ -34,6 +41,7 @@ declare class RabbitMQClient {
     private returnWaiters;
     private consumerTags;
     private subscriptionSemaphores;
+    private retryWakers;
     private inflightCount;
     private drainResolve;
     constructor(options: RabbitMQClientOptions);
@@ -78,6 +86,7 @@ declare class RabbitMQClient {
      */
     unsubscribe(queue: string): Promise<void>;
     private setupSubscription;
+    private checkExchanges;
     /**
      * Gates a delivered message on the subscription's concurrency semaphore, then
      * processes it. A message counts as in-flight from delivery until its handler
@@ -104,6 +113,10 @@ declare class RabbitMQClient {
     /** Invokes a hook callback, swallowing errors so hooks never break message flow. */
     private callHook;
     private sleep;
+    private retryDelayFor;
+    private wakeRetries;
+    /** Also cut short by a reconnect, via wakeRetries(). */
+    private sleepUntilClose;
 }
 
 /**
@@ -122,4 +135,4 @@ declare const defaultLogger: ILogger;
  */
 declare const silentLogger: ILogger;
 
-export { ILogger, PublishOptions, RabbitMQClient, RabbitMQClientOptions, RabbitMQMessage, RabbitMQMessageHandler, SubscribeOptions, UnroutableMessageError, defaultLogger, silentLogger };
+export { DeadLetterError, ILogger, PublishOptions, RabbitMQClient, RabbitMQClientOptions, RabbitMQMessage, RabbitMQMessageHandler, SubscribeOptions, UnroutableMessageError, defaultLogger, silentLogger };

package/dist/index.js

@@ -89,6 +89,9 @@ var DEFAULTS = {
   prefetch: DEFAULT_PREFETCH,
   closeTimeout: 5e3
 };
+function backoff(baseDelay, attempt, maxDelay) {
+  return Math.min(baseDelay * Math.pow(2, attempt - 1), maxDelay);
+}
 var UnroutableMessageError = class extends Error {
   constructor(exchange, routingKey) {
     super(`No queue is bound to receive ${exchange || "(default exchange)"}/${routingKey}`);
@@ -99,10 +102,17 @@ var UnroutableMessageError = class extends Error {
   exchange;
   routingKey;
 };
+var DeadLetterError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "DeadLetterError";
+  }
+};
 var RabbitMQClient = class {
   connection = null;
   channel = null;
   connected = false;
+  closing = false;
   subscriptions = [];
   options;
   logger;
@@ -118,6 +128,7 @@ var RabbitMQClient = class {
   // connection drops keep holding their permits, and the new consumer cannot
   // exceed the ceiling while the old pipeline drains. `null` = no limit.
   subscriptionSemaphores = /* @__PURE__ */ new Map();
+  retryWakers = /* @__PURE__ */ new Set();
   inflightCount = 0;
   drainResolve = null;
   constructor(options) {
@@ -162,34 +173,43 @@ var RabbitMQClient = class {
   async doConnect(maxAttempts) {
     this.assertedExchanges.clear();
     this.consumerTags.clear();
+    this.connection?.close().catch(() => void 0);
+    this.connection = null;
     let attempts = 0;
-    while (!this.connected) {
+    while (!this.connected && !this.closing) {
       try {
-        this.connection = await amqp.connect(this.options.url);
+        const connection = await amqp.connect(this.options.url);
+        this.connection = connection;
         this.logger.info("Connected to server");
-        this.channel = await this.connection.createConfirmChannel();
+        const channel = await connection.createConfirmChannel();
+        this.channel = channel;
+        this.wakeRetries();
         const returnWaiters = /* @__PURE__ */ new Set();
         this.returnWaiters = returnWaiters;
-        this.channel.on("return", (msg) => {
+        channel.on("return", (msg) => {
           for (const waiter of returnWaiters) waiter(msg);
         });
         this.logger.info("Confirm channel created");
-        await this.channel.prefetch(this.options.prefetch);
+        await channel.prefetch(this.options.prefetch);
         this.logger.info("Channel prefetch set", { prefetch: this.options.prefetch });
-        this.connection.on("error", (error) => {
+        connection.on("error", (error) => {
+          if (connection !== this.connection) return;
           this.connected = false;
           this.logger.error("Connection error", { error });
         });
-        this.connection.on("close", () => {
+        connection.on("close", () => {
+          if (connection !== this.connection) return;
           this.connected = false;
           this.logger.warn("Connection closed");
           this.reconnectWithRetry();
         });
-        this.channel.on("error", (error) => {
+        channel.on("error", (error) => {
+          if (channel !== this.channel) return;
           this.logger.error("Channel error", { error });
           this.handleChannelFailure();
         });
-        this.channel.on("close", () => {
+        channel.on("close", () => {
+          if (channel !== this.channel) return;
           this.logger.warn("Channel closed");
           this.handleChannelFailure();
         });
@@ -213,6 +233,9 @@ var RabbitMQClient = class {
         await this.sleep(this.options.connectionRetryDelay);
       }
     }
+    if (!this.connected) {
+      throw new Error("RabbitMQ client closed while connecting");
+    }
   }
   handleChannelFailure() {
     if (this.connected) {
@@ -299,10 +322,7 @@ var RabbitMQClient = class {
             `Failed to publish to ${exchange || "(default exchange)"}/${routingKey} after ${attempts} attempts: ${error instanceof Error ? error.message : String(error)}`
           );
         }
-        const retryDelay = Math.min(
-          baseDelay * Math.pow(2, attempts - 1),
-          MAX_PUBLISH_RETRY_DELAY_MS
-        );
+        const retryDelay = backoff(baseDelay, attempts, MAX_PUBLISH_RETRY_DELAY_MS);
         this.logger.warn("Publish attempt failed, retrying", { error, exchange, routingKey, attempt: attempts, maxAttempts, retryDelayMs: retryDelay });
         await this.sleep(retryDelay);
       }
@@ -315,13 +335,19 @@ var RabbitMQClient = class {
    * `init()` / reconnect cycle.
    */
   async close(clearSubscriptions = true) {
+    this.closing = true;
     try {
+      await Promise.allSettled([this.initializationPromise, this.reconnectionPromise]);
+      this.wakeRetries();
       if (this.inflightCount > 0) {
         this.logger.info("Waiting for in-flight messages to drain", { inflightCount: this.inflightCount });
         await this.waitForDrain(this.options.closeTimeout);
       }
-      await this.channel?.close();
-      await this.connection?.close();
+      try {
+        await this.channel?.close();
+      } finally {
+        await this.connection?.close();
+      }
       this.connection = null;
       this.channel = null;
       this.connected = false;
@@ -337,9 +363,12 @@ var RabbitMQClient = class {
     } catch (error) {
       this.logger.error("Error closing connection", { error });
       throw error;
+    } finally {
+      this.closing = false;
     }
   }
   async reconnectWithRetry() {
+    if (this.closing) return;
     if (this.reconnectionPromise) {
       return this.reconnectionPromise;
     }
@@ -349,6 +378,8 @@ var RabbitMQClient = class {
     this.reconnectionPromise.catch(() => void 0);
     try {
       await this.reconnectionPromise;
+    } catch (error) {
+      if (!this.closing) throw error;
     } finally {
       this.reconnectionPromise = null;
     }
@@ -400,13 +431,19 @@ var RabbitMQClient = class {
     }
     const sub = { exchange, routingKey, queue, handler, options };
     const existingIndex = this.subscriptions.findIndex((s) => s.queue === queue);
+    const previous = existingIndex === -1 ? void 0 : this.subscriptions[existingIndex];
     if (existingIndex === -1) {
       this.subscriptions.push(sub);
     } else {
       this.subscriptions[existingIndex] = sub;
       this.subscriptionSemaphores.delete(queue);
     }
-    await this.setupSubscription(sub);
+    try {
+      await this.setupSubscription(sub);
+    } catch (error) {
+      this.subscriptions = previous ? this.subscriptions.map((s) => s === sub ? previous : s) : this.subscriptions.filter((s) => s !== sub);
+      throw error;
+    }
   }
   /**
    * Cancels a queue subscription and removes it from the restoration list.
@@ -427,16 +464,22 @@ var RabbitMQClient = class {
     }
     const channel = this.channel;
     const { exchange, routingKey, queue, handler, options } = sub;
-    const dlxExchange = `${exchange}.dlx`;
+    const dlxExchange = options?.deadLetterExchange ?? `${exchange}.dlx`;
     const dlqQueue = `${queue}.dlq`;
     const dlqRoutingKey = `${routingKey}.dead`;
+    const bindings = [{ exchange, routingKey }, ...options?.bindings ?? []];
     await channel.assertExchange(dlxExchange, "topic", { durable: true });
     await channel.assertQueue(dlqQueue, { durable: true });
     await channel.bindQueue(dlqQueue, dlxExchange, dlqRoutingKey);
-    if (!this.assertedExchanges.has(exchange)) {
-      await channel.assertExchange(exchange, "topic", { durable: true });
-      this.assertedExchanges.add(exchange);
+    const missing = bindings.map((b) => b.exchange).filter((name) => !this.assertedExchanges.has(name));
+    if (options?.passiveExchanges && missing.length > 0) {
+      await this.checkExchanges(missing);
+    } else {
+      for (const name of missing) {
+        await channel.assertExchange(name, "topic", { durable: true });
+      }
     }
+    for (const name of missing) this.assertedExchanges.add(name);
     const queueType = options?.queueArguments?.["x-queue-type"] ?? "quorum";
     const queueArgs = {
       "x-queue-type": queueType,
@@ -451,7 +494,9 @@ var RabbitMQClient = class {
       deadLetterRoutingKey: dlqRoutingKey,
       arguments: { ...queueArgs, ...options?.queueArguments }
     });
-    await channel.bindQueue(queue, exchange, routingKey);
+    for (const binding of bindings) {
+      await channel.bindQueue(queue, binding.exchange, binding.routingKey);
+    }
     if (!this.subscriptionSemaphores.has(queue)) {
       const concurrency = options?.concurrency ?? this.options.concurrency;
       this.subscriptionSemaphores.set(queue, concurrency > 0 ? new Semaphore(concurrency) : null);
@@ -461,13 +506,29 @@ var RabbitMQClient = class {
       queue,
       (message) => {
         if (message) {
-          this.dispatch(message, handler, semaphore, channel);
+          this.dispatch(message, handler, semaphore, channel, options);
         }
       },
       { noAck: false }
     );
     this.consumerTags.set(queue, consumerTag);
-    this.logger.info("Subscribed to queue", { exchange, routingKey, queue });
+    this.logger.info("Subscribed to queue", { queue, bindings });
+  }
+  // A failed check closes the channel it ran on, so it runs on a throwaway one
+  // rather than take down the shared channel and every consumer on it.
+  async checkExchanges(exchanges) {
+    if (!this.connection) {
+      throw new Error("Connection not available");
+    }
+    const probe = await this.connection.createChannel();
+    probe.on("error", () => void 0);
+    try {
+      for (const name of exchanges) {
+        await probe.checkExchange(name);
+      }
+    } finally {
+      await probe.close().catch(() => void 0);
+    }
   }
   /**
    * Gates a delivered message on the subscription's concurrency semaphore, then
@@ -475,10 +536,10 @@ var RabbitMQClient = class {
    * settles (including time spent waiting for a permit), so graceful `close()`
    * drains queued messages as well as actively-processing ones.
    */
-  dispatch(message, handler, semaphore, channel) {
+  dispatch(message, handler, semaphore, channel, options) {
     this.inflightCount++;
     const acquire = semaphore ? semaphore.acquire() : Promise.resolve();
-    acquire.then(() => this.handleWithRetry(message, handler, channel)).catch((error) => {
+    acquire.then(() => this.handleWithRetry(message, handler, channel, options)).catch((error) => {
       this.logger.error("Unhandled error in message handler", { error });
     }).finally(() => {
       semaphore?.release();
@@ -488,7 +549,7 @@ var RabbitMQClient = class {
       }
     });
   }
-  async handleWithRetry(message, handler, channel) {
+  async handleWithRetry(message, handler, channel, options) {
     if (channel !== this.channel) {
       this.logger.warn("Skipping message from a superseded channel; it will be redelivered");
       return;
@@ -516,26 +577,41 @@ var RabbitMQClient = class {
     }
     this.logger.debug("Message received, processing", { exchange, routingKey, payload: content });
     const properties = {
+      exchange,
+      routingKey,
       headers: message.properties.headers ?? {},
       timestamp: message.properties.timestamp,
       messageId: message.properties.messageId,
       correlationId: message.properties.correlationId
     };
-    while (attempts < this.options.maxRetries) {
+    const maxRetries = options?.maxRetries ?? this.options.maxRetries;
+    while (attempts < maxRetries) {
       try {
         await handler(content, properties);
       } catch (error) {
         attempts++;
+        if (error instanceof Error && error.name === "DeadLetterError") {
+          const duration3 = Date.now() - startTime;
+          this.logger.warn("Handler dead-lettered the message", { error: error.message, exchange, routingKey });
+          if (this.settle(channel, message, "nack")) {
+            this.callHook(this.hooks.onMessageDlq, { exchange, routingKey, duration: duration3, reason: "dead_letter_error" });
+          }
+          return;
+        }
         this.logger.error("Handler failed", {
           error: error instanceof Error ? error.message : error,
           stack: error instanceof Error ? error.stack : void 0,
           exchange,
           routingKey,
           attempt: attempts,
-          maxRetries: this.options.maxRetries
+          maxRetries
         });
-        if (attempts < this.options.maxRetries) {
-          await this.sleep(this.options.retryDelay);
+        if (attempts < maxRetries) {
+          await this.sleepUntilClose(this.retryDelayFor(attempts, options));
+          if (this.closing || channel !== this.channel) {
+            this.logger.warn("Stopped retrying a message on close or reconnect; it will be redelivered", { exchange, routingKey });
+            return;
+          }
         }
         continue;
       }
@@ -547,7 +623,7 @@ var RabbitMQClient = class {
       return;
     }
     const duration = Date.now() - startTime;
-    this.logger.error("Message failed after max retries, sending to DLQ", { exchange, routingKey, maxRetries: this.options.maxRetries, duration });
+    this.logger.error("Message failed after max retries, sending to DLQ", { exchange, routingKey, maxRetries, duration });
     if (this.settle(channel, message, "nack")) {
       this.callHook(this.hooks.onMessageDlq, { exchange, routingKey, duration, reason: "max_retries_exhausted" });
     }
@@ -628,8 +704,30 @@ var RabbitMQClient = class {
   sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
   }
+  retryDelayFor(attempts, options) {
+    const { retryDelay } = this.options;
+    if (options?.maxRetryDelay === void 0) return retryDelay;
+    return backoff(retryDelay, attempts, options.maxRetryDelay);
+  }
+  wakeRetries() {
+    for (const wake of [...this.retryWakers]) wake();
+  }
+  /** Also cut short by a reconnect, via wakeRetries(). */
+  sleepUntilClose(ms) {
+    if (this.closing) return Promise.resolve();
+    return new Promise((resolve) => {
+      const wake = () => {
+        clearTimeout(timer);
+        this.retryWakers.delete(wake);
+        resolve();
+      };
+      const timer = setTimeout(wake, ms);
+      this.retryWakers.add(wake);
+    });
+  }
 };
 export {
+  DeadLetterError,
   RabbitMQClient,
   UnroutableMessageError,
   defaultLogger,