@bgaldino/nestjs-rabbitmq 1.5.1 → 2.0.0-beta.3

package/README.md

@@ -1,489 +1,599 @@
 # @bgaldino/nestjs-rabbitmq
 
-# Table of Contents
-
-<!--toc:start-->
-
-- [@bgaldino/nestjs-rabbitmq](#bgaldinonestjs-rabbitmq)
-- [Table of Contents](#table-of-contents)
-  - [Description](#description)
-  - [Motivation](#motivation)
-    - [Requirements](#requirements)
-    - [Instalation](#instalation)
-    - [PNPM](#pnpm)
-  - [Getting Started](#getting-started)
-    - [Importing the module](#importing-the-module)
-    - [The configuration file](#the-configuration-file)
-  - [Publishers](#publishers)
-    - [Publishing messages](#publishing-messages)
-    - [Custom headers](#custom-headers)
-  - [Consumers](#consumers)
-    - [The messageHandler callback](#the-messagehandler-callback)
-    - [Strongly typed consumer](#strongly-typed-consumer)
-    - [Declaration example](#declaration-example)
-  - [Retrying strategy](#retrying-strategy)
-  - [Deadletter strategy](#deadletter-strategy)
-  - [Disabling the automatic ack](#disabling-the-automatic-ack)
-  - [Custom Header metadata](#custom-header-metadata)
-  - [Extra options](#extra-options)
-    - [Consumer manual loading](#consumer-manual-loading)
-    - [Message inspection and logging](#message-inspection-and-logging)
-  - [How to build this library locally?](#how-to-build-this-library-locally)
-  - [Planned features](#planned-features)
-  - [Contribute](#contribute)
-  - [License](#license)
-  <!--toc:end-->
-
-## Description
-
-This module features an opinionated way of configuring the RabbitMQ connection
-by using a configuration file that describes the behaviour of all publishers
-and consumers present in your project
-
-## Motivation
-
-I wanted to have a central place where its easier to open the project and see
-the declared behaviour of the RabbitMQ instance for that project, without having
-to look around for NestJS annotations, microservices or whatever. Simply to open,
-go to the configuration file and know exactly what I'm looking at and what I should
-expect.
-
-### Requirements
-
-- @nestjs/common: ">9"
-- An RabbitMQ instance with the
-  [RabbitMQ Delayed Message Plugin](https://github.com/rabbitmq/rabbitmq-delayed-message-exchange) installed
-
-### Instalation
-
-### PNPM
+An opinionated NestJS module for RabbitMQ with built-in retry strategies, dead letter queues, and quorum queue support.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Requirements](#requirements)
+- [Getting Started](#getting-started)
+  - [forRoot](#forroot)
+  - [forRootAsync](#forrootasync)
+- [Consumers](#consumers)
+  - [Decorator-based consumers](#decorator-based-consumers)
+  - [Config-based consumers](#config-based-consumers)
+  - [Mixed usage](#mixed-usage)
+  - [Handler signature](#handler-signature)
+  - [Consumer groups](#consumer-groups)
+- [Publishers](#publishers)
+  - [Publishing messages](#publishing-messages)
+  - [Typed publishing](#typed-publishing)
+- [Multi-vhost Connections](#multi-vhost-connections)
+  - [Named connections](#named-connections)
+  - [Targeting a connection from consumers](#targeting-a-connection-from-consumers)
+  - [Publishing to a specific connection](#publishing-to-a-specific-connection)
+- [Retry Strategy](#retry-strategy)
+- [Dead Letter Strategy](#dead-letter-strategy)
+- [Disabling the automatic ack](#disabling-the-automatic-ack)
+- [Custom Header Metadata](#custom-header-metadata)
+- [Extra Options](#extra-options)
+  - [Consumer manual loading](#consumer-manual-loading)
+  - [Message inspection and logging](#message-inspection-and-logging)
+  - [Health check](#health-check)
+- [Building locally](#building-locally)
+- [License](#license)
+
+## Installation
 
 ```shell
 pnpm add @bgaldino/nestjs-rabbitmq
 ```
 
-**YARN**
-
 ```shell
 yarn add @bgaldino/nestjs-rabbitmq
 ```
 
-**NPM**
-
 ```shell
 npm add @bgaldino/nestjs-rabbitmq
 ```
 
+## Requirements
+
+- `@nestjs/common` and `@nestjs/core` version 9 or above
+- RabbitMQ 3.10+ (quorum queue per-message TTL support)
+
+No additional plugins are required. The retry mechanism uses native message TTL
+and dead letter exchanges instead of the delayed message plugin.
+
 ## Getting Started
 
-### Importing the module
+The `RabbitMQModule` is marked as `@Global`, so importing it once is enough
+to inject `RabbitMQService` anywhere in your application.
+
+### forRoot
 
-Import the `RabbitMQModule` in your `app.module.ts` and call the method `register({})`
+For simple setups where the configuration is static:
 
 ```typescript
 import { RabbitMQModule } from '@bgaldino/nestjs-rabbitmq';
-import { RabbitOptions } from '@bgaldino/nestjs-rabbitmq';
 
 @Module({
   imports: [
-    ...
-    RabbitMQModule.register({ useClass: RabbitOptions, injects: [...] }),
-    ...
-  ]
+    RabbitMQModule.forRoot({
+      connectionString: 'amqp://user:password@localhost:5672/vhost',
+      delayExchangeName: 'my_app',
+      assertExchanges: [
+        { name: 'orders', type: 'topic' },
+        { name: 'notifications', type: 'fanout' },
+      ],
+    }),
+  ],
 })
 export class AppModule {}
 ```
 
-The `RabbitMQModule` is marked as `@Global`, therefore, calling it once is enough
-to allow the injection of the `RabbitMQService`
+### forRootAsync
 
-### The configuration file
-
-Create a `rabbitmq.config.ts` or whatever the name you prefer containing the
-minimum configuration:
+When you need to inject dependencies or resolve configuration asynchronously:
 
 ```typescript
-import { Injectable } from "@nestjs/common";
-import {
-  RabbitMQModuleOptions,
-  RabbitOptionsFactory,
-} from "@bgaldino/nestjs-rabbitmq";
+import { RabbitMQModule, RabbitMQOptionsFactory, ModuleOptions } from '@bgaldino/nestjs-rabbitmq';
 
 @Injectable()
-export class RabbitOptions implements RabbitOptionsFactory {
-  createRabbitOptions(): RabbitMQModuleOptions {
+class RabbitConfig implements RabbitMQOptionsFactory {
+  constructor(private readonly configService: ConfigService) {}
+
+  createRabbitOptions(): ModuleOptions {
     return {
-      connectionString: "amqp://{user}:{password}@{url}/{vhost}",
-      delayExchangeName: "MyDelayExchange",
-      assertExchanges: [],
-      consumerChannels: [],
+      connectionString: this.configService.get('RABBIT_URL'),
+      delayExchangeName: 'my_app',
+      assertExchanges: [
+        { name: 'orders', type: 'topic' },
+      ],
     };
   }
 }
-```
 
-## Publishers
+@Module({
+  imports: [
+    RabbitMQModule.forRootAsync({
+      useClass: RabbitConfig,
+      imports: [ConfigModule],
+    }),
+  ],
+})
+export class AppModule {}
+```
 
-**Example config file**:
+You can also use `useFactory` directly:
 
 ```typescript
-assertExchanges: [
-  {
-    name: 'webhooks', type: 'topic',
-    options: { durable: true, autoDelete: false }
-  },
-  { name: 'test-fanout', type: 'fanout' },
-  { name: 'example-direct', type: 'direct'},
-],
+RabbitMQModule.forRootAsync({
+  useFactory: (configService: ConfigService) => ({
+    connectionString: configService.get('RABBIT_URL'),
+    delayExchangeName: 'my_app',
+    assertExchanges: [],
+  }),
+  inject: [ConfigService],
+  imports: [ConfigModule],
+})
 ```
 
-The `assertExchanges` property expects an array of `RabbitMQAssertExchange`
-and each entry will asserted against the RabbitMQ connected server.
+## Consumers
 
-If any entry does not match a current configuration, or cannot be
-created/attached. A terminal error `406 - PRECONDITION_FAILED` will be thrown
-with the reason and the server will not initialize
+There are two ways to register consumers: decorators and config. Both can be
+used simultaneously and produce the same result at runtime. The library
+validates that no duplicate queue names exist across both sources.
 
-### Publishing messages
+All queues are created as [quorum queues](https://www.rabbitmq.com/docs/quorum-queues)
+by default. Consumers do not create exchanges, they only bind to exchanges
+that already exist (declared via `assertExchanges`).
 
-**Example**:
+### Decorator-based consumers
+
+Decorate any method with `@RabbitConsumer()` and the library will
+automatically discover and wire it up during application bootstrap.
+This is the recommended approach for most use cases since it keeps the
+consumer logic located with the handler.
 
 ```typescript
-import { Injectable } from "@nestjs/common";
-import { RabbitMQService } from "@bgaldino/nestjs-rabbitmq";
+import { Injectable } from '@nestjs/common';
+import { RabbitConsumer, ConsumerOptions, MessageParams } from '@bgaldino/nestjs-rabbitmq';
 
 @Injectable()
-export class MyService {
-  constructor(private readonly rabbitMQService: RabbitMQService) {}
-}
-
-async publishMe(){
-  const isPublished = await this.rabbitMQService.publish('exchange_name', 'routing_key', {});
-}
-
-//or
-
-async publishMeTyped() {
-  const isPublished = await this.rabbitMQService.publish<CustomType>('exchange_name', 'routing_key', {});
-  //This will return an error if the object is not properly typed
+export class OrderService {
+  @RabbitConsumer({
+    queue: 'order.created',
+    exchangeName: 'orders',
+    routingKey: 'order.created',
+    prefetch: 5,
+  })
+  async handleOrderCreated(content: OrderPayload, params?: MessageParams) {
+    // handle message
+  }
 }
 ```
 
-The `publish()` method uses [Publish Confirms](https://www.rabbitmq.com/docs/confirms#publisher-confirms)
-to make sure that the message is delivered to the broker before returning
-the promise.
+The provider must be registered in a NestJS module. The library scans all
+providers and controllers for decorated methods.
 
-### Custom headers
+### Config-based consumers
 
-The library defines a couple custom headers
-
-## Consumers
-
-Inside the configuration file you can declare your consumers on the section
-`consumerChannels`. This list of `RabbitMQConsumerChannel` will be evaluated
-and each entry will try to create the queue and bind it to the declared
-exchange.
-
-**Example:**
+If you prefer centralized configuration, or need to conditionally register
+consumers based on environment, you can use the `consumerChannels` array.
+The `defineRabbitConsumer` helper provides type safety:
 
 ```typescript
-
-createRabbitOptions(): RabbitMQModuleOptions {
-    return {
-      ...,
-      consumerChannels: [
-        {
-          options: {
-            queue: 'myqueue',
-            exchangeName: 'foobar.exchange',
-            routingKey: 'myqueue',
-            prefetch: Number(process.env.RABBIT_PREFETCH ?? 10),
-            retryStrategy: {
-              enabled: true,
-              maxAttempts: 5,
-              delay: (attempt: number) => {
-                return attempt * 5000;
-              },
-            },
-          },
-          messageHandler: this.consumerService.messageHandler.bind(
-            this.consumerService,
-          ),
-        },
-      ]
-  }
-}
+import { defineRabbitConsumer } from '@bgaldino/nestjs-rabbitmq';
+
+RabbitMQModule.forRoot({
+  connectionString: 'amqp://localhost',
+  delayExchangeName: 'my_app',
+  assertExchanges: [{ name: 'orders', type: 'topic' }],
+  consumerChannels: [
+    defineRabbitConsumer({
+      queue: 'order.created',
+      exchangeName: 'orders',
+      routingKey: 'order.created',
+      prefetch: 5,
+      handler: {
+        provider: OrderService,
+        methodName: 'handleOrderCreated',
+      },
+    }),
+  ],
+})
 ```
 
-The consumer **DOES NOT** create exchanges and only bind to ones that already
-exists. This is to avoid creating exchanges with typos and
-misconfigurations.
+The library resolves the provider instance automatically. No need to manually
+bind `this` or inject the service into your config.
 
-You can also declare an array of `routingKeys: string[]` if you want to attach
-multiple keys to the same queue/callback
+### Mixed usage
 
-### The messageHandler callback
+Both approaches can coexist. A common pattern is using decorators for static
+consumers and config for conditional ones:
 
-As declared in the example above, the `messageHandler` property expects a
-callback of the type `IRabbitHandler`. Because of the nature of the library,
-we will need to call the `.bind(this.yourService)` in order to bind the `this`
-context of the origin service to the callback.
+```typescript
+// Static consumer via decorator
+@RabbitConsumer({ queue: 'audit.log', exchangeName: 'events', routingKey: '#' })
+async auditLog(content: any) { ... }
+
+// Conditional consumer via config
+consumerChannels: isProduction ? [
+  defineRabbitConsumer({ queue: 'debug.trace', ... })
+] : [],
+```
 
-The `RabbitMQModule.register()` accepts an array of NestJS Modules with the
-any module that contains an consumer callback function.
+### Handler signature
 
-The `callback` has the following signature:
+Every consumer handler follows the same signature regardless of registration
+method:
 
 ```typescript
-async messageHandler(content: any, params?: RabbitConsumerParams): Promise<void>;
+async handler(content: T, params?: MessageParams): Promise<void>;
 ```
 
-where `RabbitConsumerParams` is optional and contains the following info:
+The `MessageParams` object is optional and contains:
 
 ```typescript
-export type RabbitConsumerParameters = {
+type MessageParams = {
   message: ConsumeMessage;
   channel: ConfirmChannel;
   queue: string;
+  originalRoutingKey?: string;
 };
 ```
 
-### Strongly typed consumer
+The `content` parameter is the parsed message body. The library automatically
+attempts to parse the message as JSON. If parsing fails, the raw string is
+passed instead.
 
-You can use the `IRabbitConsumer<T>` to type the consumer first parameter `content`.
+You can implement the `ConsumerHandler<T>` interface to strongly type your
+consumer:
 
 ```typescript
-export interface MyInterface {
-  type: string;
-  id: number;
-}
+import { ConsumerHandler, MessageParams } from '@bgaldino/nestjs-rabbitmq';
 
 @Injectable()
-export class MyClass implements IRabbitConsumer<MyInterface> {
-  public async messageHandler(content: MyInterface): Promise<void> {
-    console.log(content.type);
+export class OrderService implements ConsumerHandler<OrderPayload> {
+  async messageHandler(content: OrderPayload, params?: MessageParams): Promise<void> {
+    console.log(content.orderId);
   }
 }
 ```
 
-### Declaration example
+### Consumer groups
 
-**Service example:**
+Groups allow you to control which consumers are enabled on a given deployment.
+This is useful when multiple instances of the same application serve different
+roles.
 
 ```typescript
-//consumer.module.ts
-@Module({
-  provides: [ConsumerService],
-  exports: [ConsumerService],
+@RabbitConsumer({
+  queue: 'heavy.processing',
+  exchangeName: 'jobs',
+  routingKey: 'heavy.*',
+  group: 'workers',
 })
-export class ConsumerModule {}
+async processHeavyJob(content: any) { ... }
+```
+
+The active group is determined by:
+
+1. The `RMQ_CONSUMER_GROUP` environment variable (highest priority)
+2. The `group` parameter passed to `createConsumers(group)`
+3. Defaults to `"rabbit-default"`
+
+Consumers without an explicit group are assigned to the active group and will
+always be initialized. Consumers with a group that does not match the active
+group are skipped.
+
+## Publishers
+
+### Publishing messages
+
+Inject `RabbitMQService` and call `publish()`:
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { RabbitMQService } from '@bgaldino/nestjs-rabbitmq';
 
-//consumer.service.ts
 @Injectable()
-export class ConsumerService {
-  async messageHandler(content: any) {
-    return null;
+export class OrderService {
+  constructor(private readonly rabbit: RabbitMQService) {}
+
+  async createOrder(order: Order) {
+    const published = await this.rabbit.publish('orders', 'order.created', order);
+
+    if (!published) {
+      // handle publish failure
+    }
   }
 }
 ```
 
-**Config Example:**
+The `publish()` method uses [Publisher Confirms](https://www.rabbitmq.com/docs/confirms#publisher-confirms)
+to guarantee the message was delivered to the broker before resolving the
+promise. Returns `true` on success, `false` on failure.
+
+### Typed publishing
+
+You can pass a generic type to enforce the message shape at compile time:
 
 ```typescript
-//rabbit.config.ts
-@Injectable()
-export class RabbitOptions implements RabbitOptionsFactory {
-  constructor(
-    readonly consumerService: ConsumerService ,
-  ) {}
-
-createRabbitOptions(): RabbitMQModuleOptions {
-  return {
-        ...
-        consumerchannels: [
-          {
-            options: {
-              queue: "myqueue",
-              exchangename: "test.exchange",
-              routingkey: "myqueue",
-              prefetch: number(process.env.rabbit_prefetch ?? 10),
-            },
-            messagehandler: this.MyService.messageHandler.bind(this.MyService),
-          },
-        ];
-    }
-}
+await this.rabbit.publish<OrderPayload>('orders', 'order.created', {
+  orderId: '123',
+  amount: 99.90,
+});
+```
 
-//app.module.ts
-@Module({
-  imports: [
-  ...,
-  RabbitMQModule.register({
-    useClass: RabbitConfig,
-    injects: [ConsumerModule]
-  })
-  ]
+You can also pass custom publish options as a fourth argument, such as
+additional headers or properties.
+
+## Multi-vhost Connections
+
+If your application needs to consume from or publish to multiple RabbitMQ
+vhosts (or entirely different brokers), you can use named connections.
+Each connection is a self-contained unit with its own `connectionString`,
+`delayExchangeName`, `assertExchanges`, and `consumerChannels`.
+
+### Named connections
+
+Replace the flat connection fields with a `connections` array. Each entry
+must have a unique `name`:
+
+```typescript
+import { RabbitMQModule, ConnectionConfig } from '@bgaldino/nestjs-rabbitmq';
+
+RabbitMQModule.forRoot({
+  connections: [
+    {
+      name: 'default',
+      connectionString: 'amqp://localhost/main',
+      delayExchangeName: 'my_app',
+      assertExchanges: [{ name: 'orders', type: 'topic' }],
+    },
+    {
+      name: 'shared-bus',
+      connectionString: 'amqp://localhost/shared',
+      delayExchangeName: 'shared_app',
+      assertExchanges: [{ name: 'events', type: 'topic' }],
+    },
+  ],
 })
-export class AppModule {}
 ```
 
-## Retrying strategy
+The flat shorthand (`connectionString` at the root level) still works for
+single-connection setups. Internally it becomes a connection named
+`"default"`. You cannot set both `connectionString` and `connections` at the
+same time.
+
+### Targeting a connection from consumers
 
-On each consumer declaration you can pass the optional parameter: `retryStrategy`
-with following the contract:
+Add the `connection` field to `@RabbitConsumer()` or to a config-based
+consumer to specify which connection it should attach to. If omitted,
+it defaults to `"default"`:
 
 ```typescript
-retryStrategy: {
-  enabled?: true,
-  maxAttempts?: 5,
-  delay?: (attempt) => {return attempt * 5000};
-}
+@RabbitConsumer({
+  queue: 'events.audit',
+  exchangeName: 'events',
+  routingKey: '#',
+  connection: 'shared-bus',
+})
+async auditEvents(content: any) { ... }
+```
+
+Config-based consumers declared inside a connection's `consumerChannels` are
+automatically scoped to that connection:
+
+```typescript
+connections: [
+  {
+    name: 'default',
+    connectionString: 'amqp://localhost/main',
+    delayExchangeName: 'my_app',
+    assertExchanges: [{ name: 'orders', type: 'topic' }],
+    consumerChannels: [
+      defineRabbitConsumer({
+        queue: 'order.created',
+        exchangeName: 'orders',
+        routingKey: 'order.created',
+        handler: { provider: OrderService, methodName: 'handleOrderCreated' },
+      }),
+    ],
+  },
+],
 ```
 
-By default, the `retryStrategy` is enabled. When consuming a new message and
-the callback throws an error.
+### Publishing to a specific connection
+
+Pass the `connection` option to `publish()`:
 
-When enabled, the library will create a `{options.queue}.dlq` queue and will use
-the `delayExchangeName` exchange as the retrying orchestrator where the
-`x-delay` value is the return of the anonymous callback `delay`.
+```typescript
+await this.rabbit.publish('events', 'audit.created', payload, {
+  connection: 'shared-bus',
+});
+```
 
-When the maximum attempts is reached, the library issues a nack, sending the
-message to the `.dlq` queue.
+When omitted, the message is published to the `"default"` connection.
 
-## Deadletter strategy
+## Retry Strategy
 
-Each consumer can have an optional parameter `deadletterStrategy` with the
-following contract:
+Each consumer can define a `retryStrategy` to handle transient failures. When
+the handler throws an error, the message is published to a retry queue
+(`{queue}.retry`) with a TTL. Once the TTL expires, the message is routed
+back to the original queue for another attempt.
 
 ```typescript
-retryStrategy: {
-  suffix: string
-  callback?: (content: T): boolean | Promise<boolean>;
-}
+@RabbitConsumer({
+  queue: 'order.process',
+  exchangeName: 'orders',
+  routingKey: 'order.process',
+  retryStrategy: {
+    enabled: true,
+    maxAttempts: 5,
+    delay: (content, attempt, error) => attempt * 5000,
+  },
+})
+async processOrder(content: OrderPayload) { ... }
 ```
 
-By default the `suffix` for all DLQs will be `.dlq`.
+The `delay` callback receives the message content, the current attempt number,
+and the error that was thrown. It should return the delay in milliseconds
+before the next retry. The return value controls the behavior:
 
-When giving a callback function, the library will execute it after finishing
-executing all retry attempts. This is useful if, in case of failure, you want
-to update your database, send an alert or anything else.
+- A positive number: the message is sent to the retry queue with that TTL
+- Zero: the message is retried immediately (republished to the end of the
+  original queue)
+- A negative number: retrying is skipped entirely, and the message goes
+  straight to the dead letter strategy
 
-The function expects you to return a boolean, where depending on the result
-it will behave differently, such as:
+**Defaults** (when `retryStrategy` is not specified):
 
-- When returning `TRUE`, the callback will be executed and the message will be
-  forwarded to DLQ
-- When returning `FALSE`, **the message will not be sent to the DLQ, skipping
-  it entirely**, allowing you to drop messages if the callback execution is
-  successful
+- `enabled`: true
+- `maxAttempts`: 5
+- `delay`: () => 5000
 
-Finally, if the callback throws any errors or is unable to be executed,
-an error message will be thrown with the reason and the message will be
-forwarded to the DLQ normally.
+When the maximum number of attempts is reached, the message is nacked and sent
+to the dead letter queue.
 
-## Disabling the automatic ack
+## Dead Letter Strategy
 
-By default, the consumer will automatically send an ack at the end of the
-callback execution. If you need to disable this behaviour, you can pass:
+Each consumer can define a `deadLetterStrategy` to control what happens when
+a message exhausts all retry attempts:
 
 ```typescript
-consumerChannels: [
-  options: {
-    ...,
-    autoAck: false
-  }
-]
+@RabbitConsumer({
+  queue: 'order.process',
+  exchangeName: 'orders',
+  routingKey: 'order.process',
+  deadLetterStrategy: {
+    suffix: '.dlq',
+    callback: async (content) => {
+      await alertService.notify('Order processing failed', content);
+      return true;
+    },
+  },
+})
+async processOrder(content: OrderPayload) { ... }
 ```
 
-When disabled, it is necessary to manually acknowledge the message as follows:
+The `suffix` controls the name of the dead letter queue. Defaults to `.dlq`,
+resulting in a queue named `{queue}.dlq`.
+
+The `callback` is executed before sending the message to the DLQ. It receives
+the raw message content and should return a boolean:
+
+- `true`: the message is forwarded to the DLQ after the callback executes
+- `false`: the message is acknowledged and dropped, it will not go to the DLQ
+
+If the callback throws an error, the message is forwarded to the DLQ regardless.
+
+## Disabling the automatic ack
+
+By default, the consumer automatically acknowledges the message after the
+handler completes. If you need manual control over acknowledgement, disable it:
 
 ```typescript
-async messageHandler(
-  content: ChangeEventStatusUseCaseInput,
-  params: RabbitConsumerParameters,
-): Promise<void> {
- params.channel.ack(params.message);
+@RabbitConsumer({
+  queue: 'order.process',
+  exchangeName: 'orders',
+  routingKey: 'order.process',
+  autoAck: false,
+})
+async processOrder(content: OrderPayload, params: MessageParams) {
+  // do work
+  params.channel.ack(params.message);
 }
 ```
 
-## Custom Header metadata
+When `autoAck` is disabled, you are responsible for calling `channel.ack()` or
+`channel.nack()`. If you do not acknowledge the message, it will remain
+unacknowledged and RabbitMQ will redeliver it when the consumer disconnects.
+
+## Custom Header Metadata
 
-Every published message contains the following custom header:
+Every published message includes the following custom headers automatically:
 
 ```json
 {
-  "x-application-headers": {
-    "original-exchange": String,
-    "original-routing-key": String,
-    "published-at": ISODate
-  }
+  "x-original-exchange": "exchange_name",
+  "x-original-routing-key": "routing.key",
+  "x-published-at": "2026-01-01T00:00:00.000Z"
 }
 ```
 
-This is important because when sending the message to the DLQ, the original
-routing-key and exchange references are lost.
+These headers preserve the original exchange and routing key references, which
+would otherwise be lost when a message is routed through retry queues or the
+DLQ.
+
+The `originalRoutingKey` field in `MessageParams` is derived from these headers
+when available, falling back to the message's current routing key.
 
-## Extra options
+## Extra Options
 
 ### Consumer manual loading
 
-This library attaches the consumers during the `OnApplicationBootstrap` lifecycle
-of the NestJS Application, meaning that the application will begin to receive
-messages as soon as the lifecycle is done.
+Consumers are attached during the `OnApplicationBootstrap` lifecycle, which
+means the application begins receiving messages as soon as all modules are
+initialized, but before `app.listen()` resolves.
 
-If your application needs some time to initiate the consumers for some reason,
-(pods with limited resource for example), you can set the flag
-`extraOptions.consumerManualLoad: true` on the configuration file and manually
-call the consumer instantiation.
+If you need consumers to start only after the HTTP server is ready (or need
+to defer startup for any other reason), set `consumerManualLoad: true` and
+call the initialization manually:
 
-**Example:**
+```typescript
+RabbitMQModule.forRoot({
+  connectionString: 'amqp://localhost',
+  delayExchangeName: 'my_app',
+  assertExchanges: [],
+  extraOptions: {
+    consumerManualLoad: true,
+  },
+})
+```
 
 ```typescript
 async function bootstrap() {
   const app = await NestFactory.create(AppModule);
   await app.listen(3000);
 
-  const rabbit: RabbitMQService = app.get(RabbitMQService);
-  await rabbit.createConsumers();
+  const rabbit = app.get(RabbitMQService);
+  await rabbit.startConsumers();
 }
 bootstrap();
 ```
 
+You can also pass a group name to `startConsumers(group)` to initialize only consumers
+belonging to that group.
+
 ### Message inspection and logging
 
-You can inspect the consumer/publisher messages by setting the parameter
-`extraOptions.logType` or setting the environment variable `RABBITMQ_LOG_TYPE`
-to either: `all | consumer | publisher | none`.
+You can inspect consumer and publisher messages by setting `extraOptions.logType`
+or the `RABBITMQ_LOG_TYPE` environment variable to one of:
 
-The default value is `none`
+- `all` — logs both consumer and publisher messages
+- `consumer` — logs consumer messages only
+- `publisher` — logs publisher messages only
+- `none` — no message logging (default)
 
-You can also use the `extraOptions.loggerInstance` to pass your custom Logger
-as long as it follows the Logger/Console interfaces. The SDK will use the given
-instance to log any messages
+The environment variable takes precedence over the config value.
 
-## How to build this library locally?
+Consumer errors are always logged regardless of this setting.
 
-Just pull the project and run:
+### Health check
 
-```shell
-pnpm install
-pnpm build
-```
+You can check the connection status of both the consumer and publisher
+connections:
 
-And should be good to go
+```typescript
+const rabbit = app.get(RabbitMQService);
 
-## Planned features
+// Check all connections (returns 0 if any connection is offline)
+const status = rabbit.checkHealth(); // 1 = online, 0 = offline
 
-- [x] Add tests
-- [ ] Improve semantics of the config file
-- [ ] Offer a retry mechanism without the `x-delay`
-- [ ] Make the publisher method strongly typed based on the `assertExchanges`
-      `exchangeName` and `routingKeys` configurations
+// Check a specific connection
+const sharedStatus = rabbit.checkHealth('shared-bus');
+```
 
-## Contribute
+## Building locally
 
-TBD
+```shell
+pnpm install
+pnpm build
+```
 
 ## License
 
-[MIT License](https://github.com/golevelup/nestjs/blob/master/LICENSE)
+[MIT License](https://github.com/brunogaldino/nestjs-rabbitmq/blob/master/LICENSE)