@linagora/rabbitmq-client 0.1.0

package/README.md

@@ -0,0 +1,161 @@
+# @linagora/rabbitmq-client
+
+An opinionated RabbitMQ client for Node.js that handles the boilerplate you'd otherwise copy-paste between services: confirm channels, dead letter queues, exponential backoff on publish, and automatic reconnection that restores your subscriptions.
+
+## Install
+
+```bash
+npm install @linagora/rabbitmq-client
+```
+
+## Quick start
+
+```typescript
+import { RabbitMQClient } from '@linagora/rabbitmq-client'
+
+const client = new RabbitMQClient({ url: 'amqp://localhost' })
+await client.init()
+
+await client.publish('auth', 'user.created', { userId: '123' })
+
+await client.subscribe('auth', 'user.created', 'my-service.user-created', async (msg) => {
+  // your logic here
+})
+
+await client.close()
+```
+
+## Configuration
+
+Only `url` is required. Everything else has defaults.
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `url` | -- | AMQP connection string |
+| `maxRetries` | `3` | How many times to retry a failed handler before sending the message to DLQ |
+| `retryDelay` | `1000` | Milliseconds between handler retries |
+| `connectionRetryDelay` | `5000` | Milliseconds between reconnection attempts |
+| `initMaxAttempts` | `5` | Connection attempts on startup before giving up |
+| `publishMaxAttempts` | `5` | Publish retries (exponential backoff, capped at 60s) |
+| `prefetch` | `10` | Channel prefetch count |
+| `closeTimeout` | `5000` | Milliseconds to wait for in-flight messages when closing |
+| `logger` | -- | Parent [pino](https://github.com/pinojs/pino) instance (the library creates its own if omitted) |
+| `hooks` | -- | Observability callbacks (see [Hooks](#hooks)) |
+
+## How it works
+
+### Publishing
+
+Publishes go through a confirm channel, so you know the broker accepted the message. If something goes wrong, the client retries with exponential backoff and forces a new channel on each attempt to avoid retrying on a silently dead connection. Exchange assertions are cached per connection to avoid unnecessary AMQP round-trips on the hot path.
+
+### Subscribing
+
+Each call to `subscribe` wires up the DLQ plumbing for you:
+
+- A dead letter exchange (`<exchange>.dlx`)
+- A dead letter queue (`<queue>.dlq`)
+- A dead letter routing key (`<routingKey>.dead`)
+
+The main queue is created as a quorum queue with `at-least-once` delivery and `reject-publish` overflow. Messages are manually acknowledged.
+
+You can override the default queue arguments by passing a fifth argument:
+
+```typescript
+await client.subscribe('events', 'order.placed', 'order-queue', handler, {
+  queueArguments: { 'x-queue-type': 'classic', 'x-max-length': 10_000 },
+})
+```
+
+Custom arguments are merged with the DLQ wiring defaults, so you can swap the queue type or add a max-length without losing dead-letter routing.
+
+### Unsubscribing
+
+Cancel a consumer and remove it from the auto-restoration list:
+
+```typescript
+await client.unsubscribe('order-queue')
+```
+
+After unsubscribing, the queue will not be re-subscribed on reconnection.
+
+### Message handling
+
+Incoming messages are JSON-parsed first. If that fails, the message goes straight to the DLQ (no point retrying garbage). Otherwise, your handler runs up to `maxRetries` times. Success means ack, final failure means nack to the DLQ.
+
+### Reconnection
+
+If the connection or channel drops, the client reconnects and re-subscribes to everything automatically. Multiple reconnection triggers (e.g. connection close + channel close firing at the same time) are collapsed into a single attempt.
+
+### Graceful shutdown
+
+`close()` waits for in-flight message handlers to finish before tearing down the channel, up to `closeTimeout` milliseconds. If handlers don't drain in time, the client closes anyway and logs a warning.
+
+```typescript
+// wait for handlers to finish, then close
+await client.close()
+
+// close but keep subscriptions for a later init()
+await client.close(false)
+```
+
+### Health check
+
+`checkHealth()` creates and immediately deletes a temporary queue. Useful for Kubernetes readiness probes.
+
+```typescript
+const healthy = await client.checkHealth()
+```
+
+## Hooks
+
+Optional callbacks for wiring metrics, tracing, or alerting. Hook errors are swallowed so they never break message flow.
+
+```typescript
+const client = new RabbitMQClient({
+  url: 'amqp://localhost',
+  hooks: {
+    onPublish({ exchange, routingKey, attempts }) {
+      metrics.increment('rabbitmq.publish', { exchange })
+    },
+    onMessageProcessed({ exchange, routingKey, duration, attempts }) {
+      metrics.histogram('rabbitmq.handler.duration', duration)
+    },
+    onMessageDlq({ exchange, routingKey, duration, reason }) {
+      alerting.warn(`Message sent to DLQ: ${reason}`)
+    },
+    onReconnect({ subscriptionsRestored, subscriptionsFailed }) {
+      metrics.increment('rabbitmq.reconnect')
+    },
+  },
+})
+```
+
+| Hook | Fires when |
+|------|-----------|
+| `onPublish` | A message is confirmed by the broker |
+| `onMessageProcessed` | A handler completes successfully (includes duration and retry count) |
+| `onMessageDlq` | A message is nacked to the DLQ — reason is `'invalid_json'` or `'max_retries_exhausted'` |
+| `onReconnect` | The client reconnects and re-establishes subscriptions |
+
+## Test helpers
+
+The `@linagora/rabbitmq-client/testing` entrypoint provides mocks that don't depend on any test framework.
+
+```typescript
+import { createMockAmqplib } from '@linagora/rabbitmq-client/testing'
+
+const { mockConnection, amqpMock } = createMockAmqplib()
+
+// check what was published
+mockConnection.channel.getPublishedMessages()
+
+// feed a message into a consumer
+mockConnection.channel.simulateMessage({ userId: '123' })
+
+// simulate a broker going down
+mockConnection.simulateClose()
+```
+
+## License
+
+AGPL-3.0

package/dist/index.cjs

@@ -0,0 +1,509 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  RabbitMQClient: () => RabbitMQClient
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/client.ts
+var import_amqplib = __toESM(require("amqplib"), 1);
+
+// src/logger.ts
+var import_pino = __toESM(require("pino"), 1);
+var createLogger = (parent) => {
+  if (parent) {
+    return parent.child({ service: "rabbitmq-client" });
+  }
+  return (0, import_pino.default)({ name: "rabbitmq-client" });
+};
+
+// src/client.ts
+var DEFAULT_PREFETCH = 10;
+var MAX_PUBLISH_RETRY_DELAY_MS = 6e4;
+var DEFAULTS = {
+  maxRetries: 3,
+  retryDelay: 1e3,
+  connectionRetryDelay: 5e3,
+  initMaxAttempts: 5,
+  publishMaxAttempts: 5,
+  prefetch: DEFAULT_PREFETCH,
+  closeTimeout: 5e3
+};
+var RabbitMQClient = class {
+  connection = null;
+  channel = null;
+  connected = false;
+  subscriptions = [];
+  options;
+  logger;
+  hooks;
+  initializationPromise = null;
+  reconnectionPromise = null;
+  assertedExchanges = /* @__PURE__ */ new Set();
+  consumerTags = /* @__PURE__ */ new Map();
+  inflightCount = 0;
+  drainResolve = null;
+  constructor(options) {
+    this.options = {
+      url: options.url,
+      maxRetries: options.maxRetries ?? DEFAULTS.maxRetries,
+      retryDelay: options.retryDelay ?? DEFAULTS.retryDelay,
+      connectionRetryDelay: options.connectionRetryDelay ?? DEFAULTS.connectionRetryDelay,
+      initMaxAttempts: options.initMaxAttempts ?? DEFAULTS.initMaxAttempts,
+      publishMaxAttempts: options.publishMaxAttempts ?? DEFAULTS.publishMaxAttempts,
+      prefetch: options.prefetch ?? DEFAULTS.prefetch,
+      closeTimeout: options.closeTimeout ?? DEFAULTS.closeTimeout
+    };
+    this.logger = createLogger(options.logger);
+    this.hooks = options.hooks ?? {};
+  }
+  /**
+   * Opens a connection and creates a confirm channel. Retries up to
+   * `initMaxAttempts` times, then throws. Idempotent and safe to call
+   * concurrently — duplicate calls share the same in-flight promise.
+   */
+  async init() {
+    if (this.connection && this.connected) {
+      return;
+    }
+    if (this.initializationPromise) {
+      return this.initializationPromise;
+    }
+    this.initializationPromise = this.doConnect(this.options.initMaxAttempts);
+    this.initializationPromise.catch(() => void 0);
+    try {
+      await this.initializationPromise;
+    } finally {
+      this.initializationPromise = null;
+    }
+  }
+  async doConnect(maxAttempts) {
+    this.assertedExchanges.clear();
+    this.consumerTags.clear();
+    let attempts = 0;
+    while (!this.connected) {
+      try {
+        this.connection = await import_amqplib.default.connect(this.options.url);
+        this.logger.info("Connected to server");
+        this.channel = await this.connection.createConfirmChannel();
+        this.logger.info("Confirm channel created");
+        await this.channel.prefetch(this.options.prefetch);
+        this.logger.info({ prefetch: this.options.prefetch }, "Channel prefetch set");
+        this.connection.on("error", (error) => {
+          this.connected = false;
+          this.logger.error({ error }, "Connection error");
+        });
+        this.connection.on("close", () => {
+          this.connected = false;
+          this.logger.warn("Connection closed");
+          this.reconnectWithRetry();
+        });
+        this.channel.on("error", (error) => {
+          this.logger.error({ error }, "Channel error");
+          this.handleChannelFailure();
+        });
+        this.channel.on("close", () => {
+          this.logger.warn("Channel closed");
+          this.handleChannelFailure();
+        });
+        this.connected = true;
+        this.logger.info("Client initialized successfully");
+      } catch (error) {
+        attempts++;
+        this.connected = false;
+        if (maxAttempts !== void 0 && attempts >= maxAttempts) {
+          this.logger.error({ error, attempts, maxAttempts }, "Connection failed after maximum attempts");
+          throw new Error(
+            `Failed to connect to RabbitMQ after ${attempts} attempts. Check RABBITMQ_URL configuration and RabbitMQ server availability.`
+          );
+        }
+        this.logger.warn(
+          {
+            error,
+            attempt: attempts,
+            maxAttempts: maxAttempts ?? "unlimited",
+            retryDelayMs: this.options.connectionRetryDelay
+          },
+          "Connection attempt failed, retrying..."
+        );
+        await this.sleep(this.options.connectionRetryDelay);
+      }
+    }
+  }
+  handleChannelFailure() {
+    if (this.connected) {
+      this.connected = false;
+      this.reconnectWithRetry();
+    }
+  }
+  /**
+   * Returns whether the client currently has an active connection and channel.
+   */
+  isConnected() {
+    return this.connected;
+  }
+  /**
+   * Publishes a JSON message to a topic exchange with publisher confirms.
+   * Retries with exponential backoff (capped at 60 s), forcing a reconnect
+   * on each failure. Throws after `publishMaxAttempts` exhausted.
+   */
+  async publish(exchange, routingKey, message, options) {
+    let attempts = 0;
+    const maxAttempts = options?.maxAttempts ?? this.options.publishMaxAttempts;
+    const baseDelay = this.options.connectionRetryDelay;
+    const content = Buffer.from(JSON.stringify(message));
+    while (attempts < maxAttempts) {
+      try {
+        if (!this.connected) {
+          await this.reconnectWithRetry();
+        }
+        if (!this.channel) {
+          throw new Error("Channel not available");
+        }
+        if (!this.assertedExchanges.has(exchange)) {
+          await this.channel.assertExchange(exchange, "topic", { durable: true });
+          this.assertedExchanges.add(exchange);
+        }
+        this.channel.publish(exchange, routingKey, content, {
+          persistent: true
+        });
+        await this.channel.waitForConfirms();
+        if (attempts > 0) {
+          this.logger.info({ exchange, routingKey, messageSize: content.length, attempts }, "Published message after retries");
+        } else {
+          this.logger.info({ exchange, routingKey, messageSize: content.length }, "Published message");
+        }
+        this.logger.debug({ exchange, routingKey, payload: message }, "Published message payload");
+        this.callHook(this.hooks.onPublish, { exchange, routingKey, attempts: attempts + 1 });
+        return;
+      } catch (error) {
+        attempts++;
+        this.connected = false;
+        if (attempts >= maxAttempts) {
+          this.logger.error(
+            { error, exchange, routingKey, attempts, maxAttempts },
+            "Publish failed after max attempts"
+          );
+          throw new Error(
+            `Failed to publish to ${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
+        );
+        this.logger.warn(
+          { error, exchange, routingKey, attempt: attempts, maxAttempts, retryDelayMs: retryDelay },
+          "Publish attempt failed, retrying"
+        );
+        await this.sleep(retryDelay);
+      }
+    }
+  }
+  /**
+   * Gracefully shuts down the client. Waits up to `closeTimeout` ms for
+   * in-flight message handlers to finish before closing the channel and
+   * connection. Pass `false` to preserve subscriptions for a later
+   * `init()` / reconnect cycle.
+   */
+  async close(clearSubscriptions = true) {
+    try {
+      if (this.inflightCount > 0) {
+        this.logger.info({ inflightCount: this.inflightCount }, "Waiting for in-flight messages to drain");
+        await this.waitForDrain(this.options.closeTimeout);
+      }
+      await this.channel?.close();
+      await this.connection?.close();
+      this.connection = null;
+      this.channel = null;
+      this.connected = false;
+      this.initializationPromise = null;
+      this.reconnectionPromise = null;
+      this.assertedExchanges.clear();
+      this.consumerTags.clear();
+      if (clearSubscriptions) {
+        this.subscriptions = [];
+      }
+      this.logger.info("Connection closed");
+    } catch (error) {
+      this.logger.error({ error }, "Error closing connection");
+      throw error;
+    }
+  }
+  async reconnectWithRetry() {
+    if (this.reconnectionPromise) {
+      return this.reconnectionPromise;
+    }
+    this.connected = false;
+    this.logger.info("Starting reconnection...");
+    this.reconnectionPromise = this.doReconnect();
+    this.reconnectionPromise.catch(() => void 0);
+    try {
+      await this.reconnectionPromise;
+    } finally {
+      this.reconnectionPromise = null;
+    }
+  }
+  async doReconnect() {
+    await this.doConnect();
+    await this.resubscribeAll();
+  }
+  async resubscribeAll() {
+    if (this.subscriptions.length === 0) {
+      return;
+    }
+    this.logger.info({ count: this.subscriptions.length }, "Re-establishing subscriptions");
+    const subs = [...this.subscriptions];
+    const results = await Promise.allSettled(
+      subs.map(async (sub) => {
+        await this.setupSubscription(sub);
+        return sub.queue;
+      })
+    );
+    const succeeded = [];
+    const failed = [];
+    results.forEach((result, index) => {
+      if (result.status === "fulfilled") {
+        succeeded.push(result.value);
+      } else {
+        const queue = subs[index].queue;
+        failed.push(queue);
+        this.logger.error({ error: result.reason, queue }, "Failed to re-subscribe to queue");
+      }
+    });
+    if (succeeded.length > 0) {
+      this.logger.info({ count: succeeded.length, queues: succeeded }, "Successfully re-subscribed to queues");
+    }
+    if (failed.length > 0) {
+      this.logger.warn({ count: failed.length, queues: failed }, "Some subscriptions failed to restore");
+    }
+    this.callHook(this.hooks.onReconnect, { subscriptionsRestored: succeeded.length, subscriptionsFailed: failed.length });
+  }
+  /**
+   * Subscribes to a queue with automatic DLQ infrastructure setup.
+   *
+   * Pass `options.queueArguments` to override the default quorum-queue
+   * arguments (merged with the DLQ wiring defaults).
+   */
+  async subscribe(exchange, routingKey, queue, handler, options) {
+    if (!this.connected || !this.channel) {
+      throw new Error("RabbitMQ client not connected. Call init() first.");
+    }
+    const sub = { exchange, routingKey, queue, handler, options };
+    const existingIndex = this.subscriptions.findIndex((s) => s.queue === queue);
+    if (existingIndex === -1) {
+      this.subscriptions.push(sub);
+    } else {
+      this.subscriptions[existingIndex] = sub;
+    }
+    await this.setupSubscription(sub);
+  }
+  /**
+   * Cancels a queue subscription and removes it from the restoration list.
+   */
+  async unsubscribe(queue) {
+    const tag = this.consumerTags.get(queue);
+    if (tag && this.channel) {
+      await this.channel.cancel(tag);
+    }
+    this.consumerTags.delete(queue);
+    this.subscriptions = this.subscriptions.filter((s) => s.queue !== queue);
+    this.logger.info({ queue }, "Unsubscribed from queue");
+  }
+  async setupSubscription(sub) {
+    if (!this.channel) {
+      throw new Error("Channel not available");
+    }
+    const { exchange, routingKey, queue, handler, options } = sub;
+    const dlxExchange = `${exchange}.dlx`;
+    const dlqQueue = `${queue}.dlq`;
+    const dlqRoutingKey = `${routingKey}.dead`;
+    await this.channel.assertExchange(dlxExchange, "topic", { durable: true });
+    await this.channel.assertQueue(dlqQueue, { durable: true });
+    await this.channel.bindQueue(dlqQueue, dlxExchange, dlqRoutingKey);
+    if (!this.assertedExchanges.has(exchange)) {
+      await this.channel.assertExchange(exchange, "topic", { durable: true });
+      this.assertedExchanges.add(exchange);
+    }
+    await this.channel.assertQueue(queue, {
+      durable: true,
+      deadLetterExchange: dlxExchange,
+      deadLetterRoutingKey: dlqRoutingKey,
+      arguments: {
+        "x-dead-letter-strategy": "at-least-once",
+        "x-queue-type": "quorum",
+        "x-overflow": "reject-publish",
+        ...options?.queueArguments
+      }
+    });
+    await this.channel.bindQueue(queue, exchange, routingKey);
+    const { consumerTag } = await this.channel.consume(
+      queue,
+      (message) => {
+        if (message) {
+          this.handleWithRetry(message, handler);
+        }
+      },
+      { noAck: false }
+    );
+    this.consumerTags.set(queue, consumerTag);
+    this.logger.info({ exchange, routingKey, queue }, "Subscribed to queue");
+  }
+  async handleWithRetry(message, handler) {
+    const channel = this.channel;
+    if (!channel) {
+      this.logger.warn("Cannot process message -- channel unavailable");
+      return;
+    }
+    this.inflightCount++;
+    try {
+      const startTime = Date.now();
+      let attempts = 0;
+      const routingKey = message.fields.routingKey;
+      const exchange = message.fields.exchange;
+      let content;
+      try {
+        content = JSON.parse(message.content.toString());
+      } catch (parseError) {
+        const rawContent = message.content.toString();
+        const rawPreview = rawContent.substring(0, 100);
+        this.logger.error(
+          {
+            error: parseError,
+            exchange,
+            routingKey,
+            rawContentPreview: rawPreview + (rawContent.length > 100 ? "..." : "")
+          },
+          "Failed to parse message JSON, sending to DLQ"
+        );
+        channel.nack(message, false, false);
+        this.callHook(this.hooks.onMessageDlq, { exchange, routingKey, duration: 0, reason: "invalid_json" });
+        return;
+      }
+      this.logger.debug({ exchange, routingKey, payload: content }, "Message received, processing");
+      while (attempts < this.options.maxRetries) {
+        try {
+          await handler(content);
+          const duration2 = Date.now() - startTime;
+          this.logger.info(
+            { exchange, routingKey, duration: duration2, attempts: attempts + 1 },
+            "Message processed successfully"
+          );
+          channel.ack(message);
+          this.callHook(this.hooks.onMessageProcessed, { exchange, routingKey, duration: duration2, attempts: attempts + 1 });
+          return;
+        } catch (error) {
+          attempts++;
+          this.logger.error(
+            {
+              error: error instanceof Error ? error.message : error,
+              stack: error instanceof Error ? error.stack : void 0,
+              exchange,
+              routingKey,
+              attempt: attempts,
+              maxRetries: this.options.maxRetries
+            },
+            "Handler failed"
+          );
+          if (attempts < this.options.maxRetries) {
+            await this.sleep(this.options.retryDelay);
+          }
+        }
+      }
+      const duration = Date.now() - startTime;
+      this.logger.error(
+        { exchange, routingKey, maxRetries: this.options.maxRetries, duration },
+        "Message failed after max retries, sending to DLQ"
+      );
+      channel.nack(message, false, false);
+      this.callHook(this.hooks.onMessageDlq, { exchange, routingKey, duration, reason: "max_retries_exhausted" });
+    } finally {
+      this.inflightCount--;
+      if (this.inflightCount === 0 && this.drainResolve) {
+        this.drainResolve();
+      }
+    }
+  }
+  /**
+   * Lightweight liveness probe: creates and immediately deletes a temporary
+   * exclusive queue. Returns `false` when disconnected or on broker error.
+   */
+  async checkHealth() {
+    if (!this.connected || !this.channel) {
+      return false;
+    }
+    try {
+      const { queue } = await this.channel.assertQueue("", {
+        exclusive: true,
+        autoDelete: true
+      });
+      await this.channel.deleteQueue(queue);
+      return true;
+    } catch (error) {
+      this.logger.warn({ error }, "Health check failed");
+      return false;
+    }
+  }
+  waitForDrain(timeout) {
+    if (this.inflightCount === 0) return Promise.resolve();
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        this.logger.warn(
+          { inflightCount: this.inflightCount },
+          "Close timeout reached with messages still in flight"
+        );
+        this.drainResolve = null;
+        resolve();
+      }, timeout);
+      this.drainResolve = () => {
+        clearTimeout(timer);
+        this.drainResolve = null;
+        resolve();
+      };
+    });
+  }
+  /** Invokes a hook callback, swallowing errors so hooks never break message flow. */
+  callHook(hook, info) {
+    try {
+      hook?.(info);
+    } catch {
+    }
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  RabbitMQClient
+});
+//# sourceMappingURL=index.cjs.map