# RabbitMQ

Source: https://docs.nestjs.com/microservices/rabbitmq

[RabbitMQ](https://www.rabbitmq.com/) is an open-source, lightweight message broker that supports multiple messaging protocols. It can be deployed in distributed and federated configurations to meet high-scale, high-availability requirements, and it is one of the most widely deployed message brokers, used by small startups and large enterprises alike.

#### Installation

To start building RabbitMQ-based microservices, first install the required packages:

```bash
$ npm i --save amqplib amqp-connection-manager
```

#### Overview

To use the RabbitMQ transporter, pass the following options object to the `createMicroservice()` method:

```typescript

const app = await NestFactory.createMicroservice<MicroserviceOptions>(AppModule, {
  transport: Transport.RMQ,
  options: {
    urls: ['amqp://localhost:5672'],
    queue: 'cats_queue',
    queueOptions: {
      durable: false
    },
  },
});
```

> info **Hint** The `Transport` enum is imported from the `@nestjs/microservices` package.

#### Options

The `options` property is specific to the chosen transporter. The <strong>RabbitMQ</strong> transporter exposes the following properties.

<table>
  <tr>
    <td><code>urls</code></td>
    <td>An array of connection URLs to try in order</td>
  </tr>
  <tr>
    <td><code>queue</code></td>
    <td>Name of the queue your server listens to</td>
  </tr>
  <tr>
    <td><code>prefetchCount</code></td>
    <td>Sets the prefetch count for the channel</td>
  </tr>
  <tr>
    <td><code>isGlobalPrefetchCount</code></td>
    <td>If <code>true</code>, applies the prefetch count per channel instead of per consumer</td>
  </tr>
  <tr>
    <td><code>noAck</code></td>
    <td>If <code>false</code>, enables manual acknowledgment mode. Defaults to <code>true</code></td>
  </tr>
  <tr>
    <td><code>consumerTag</code></td>
    <td>A name the server uses to distinguish message deliveries for the consumer; it must not already be in use on the channel. It's usually easier to omit it, in which case the server creates a random name and supplies it in the reply (see <a href="https://amqp-node.github.io/amqplib/channel_api.html#channel_consume" rel="nofollow" target="_blank"><code>channel.consume()</code> in the amqplib documentation</a>)</td>
  </tr>
  <tr>
    <td><code>queueOptions</code></td>
    <td>Additional queue options (see <a href="https://amqp-node.github.io/amqplib/channel_api.html#channel_assertQueue" rel="nofollow" target="_blank"><code>channel.assertQueue()</code> in the amqplib documentation</a>)</td>
  </tr>
  <tr>
    <td><code>socketOptions</code></td>
    <td>Additional socket options (see <a href="https://amqp-node.github.io/amqplib/channel_api.html#connect" rel="nofollow" target="_blank"><code>connect()</code> in the amqplib documentation</a>)</td>
  </tr>
  <tr>
    <td><code>headers</code></td>
    <td>Headers to send with every message. Applies only to the producer (client) configuration</td>
  </tr>
  <tr>
    <td><code>replyQueue</code></td>
    <td>Reply queue for the producer. Defaults to <code>amq.rabbitmq.reply-to</code></td>
  </tr>
  <tr>
    <td><code>persistent</code></td>
    <td>If truthy, messages survive broker restarts, provided they are in a queue that also survives restarts</td>
  </tr>
  <tr>
    <td><code>noAssert</code></td>
    <td>If <code>true</code>, the queue is not asserted before consuming. Defaults to <code>false</code></td>
  </tr>
  <tr>
    <td><code>wildcards</code></td>
    <td>Set to <code>true</code> only if you want to use a topic exchange to route messages to queues. Enabling it lets you use wildcards (<code>*</code>, <code>#</code>) in message and event patterns</td>
  </tr>
  <tr>
    <td><code>exchange</code></td>
    <td>Name of the exchange. Defaults to the queue name when <code>wildcards</code> is set to <code>true</code></td>
  </tr>
  <tr>
    <td><code>exchangeType</code></td>
    <td>Type of the exchange. Defaults to <code>topic</code>. Accepts the standard AMQP types <code>direct</code>, <code>fanout</code>, <code>topic</code>, and <code>headers</code>, or the name of a custom exchange type</td>
  </tr>
  <tr>
    <td><code>exchangeArguments</code></td>
    <td>Additional arguments passed when asserting the exchange</td>
  </tr>
  <tr>
    <td><code>routingKey</code></td>
    <td>Additional routing key for the topic exchange</td>
  </tr>
  <tr>
    <td><code>maxConnectionAttempts</code></td>
    <td>Maximum number of connection attempts. Applies only to the consumer configuration. Defaults to <code>-1</code> (infinite)</td>
  </tr>
  <tr>
    <td><code>maxMessageSize</code></td>
    <td>Maximum size of a message body, in bytes. The server logs and skips a larger message without decoding it (it is negatively acknowledged without requeue when <code>noAck</code> is <code>false</code>, and a request gets an error reply), and the client fails a request whose reply is larger. Set it to <code>Infinity</code> to lift the limit. A value that isn't a number, such as the <code>NaN</code> that <code>Number()</code> makes of an unset environment variable, gets the default. Defaults to <code>16777216</code> (16 MiB)</td>
  </tr>
  <tr>
    <td><code>gracefulShutdown</code></td>
    <td>Enables graceful shutdown. When enabled, closing the server first cancels its consumer, then waits for the requests and events being handled before it closes its channel and its connection. Applies only to the consumer configuration. Defaults to <code>false</code></td>
  </tr>
  <tr>
    <td><code>gracePeriod</code></td>
    <td>Longest time in milliseconds to wait for the requests and events being handled when <code>gracefulShutdown</code> is enabled. The server closes sooner when they are done before that. Applies only to the consumer configuration. Defaults to <code>10000</code></td>
  </tr>
</table>

> info **Hint** A handler that returns a stream which never completes is still being handled, so closing the server then takes the whole `gracePeriod`. With `noAck` set to `false`, the broker requeues the messages that are still unacknowledged when the channel closes, so a message whose handler outlasts the `gracePeriod` is delivered again.

#### Client

As with other microservice transporters, you have [several options](/microservices/basics#client-producer-class) for creating a RabbitMQ `ClientProxy` instance.

One way to create an instance is to use the `ClientsModule`. Import it and call its `register()` method, passing an options object with the same properties shown above for the `createMicroservice()` method, plus a `name` property to use as the injection token. Read more about `ClientsModule` in the [microservices overview](/microservices/basics#client-producer-class).

```typescript
@Module({
  imports: [
    ClientsModule.register([
      {
        name: 'MATH_SERVICE',
        transport: Transport.RMQ,
        options: {
          urls: ['amqp://localhost:5672'],
          queue: 'cats_queue',
          queueOptions: {
            durable: false
          },
        },
      },
    ]),
  ]
  ...
})
```

You can also create a client with `ClientProxyFactory` or `@Client()`, as described in the [microservices overview](/microservices/basics#client-producer-class).

#### Context

In more complex scenarios, you may need additional information about the incoming request. When using the RabbitMQ transporter, you can access the `RmqContext` object.

```typescript

@MessagePattern('notifications')
getNotifications(@Payload() data: number[], @Ctx() context: RmqContext) {
  console.log(`Pattern: ${context.getPattern()}`);
}
```

> info **Hint** `@Payload()`, `@Ctx()` and `RmqContext` are imported from the `@nestjs/microservices` package.

To access the original RabbitMQ message (with its `properties`, `fields`, and `content`), use the `getMessage()` method of the `RmqContext` object:

```typescript

@MessagePattern('notifications')
getNotifications(@Payload() data: number[], @Ctx() context: RmqContext) {
  console.log(context.getMessage());
}
```

To retrieve a reference to the RabbitMQ [channel](https://www.rabbitmq.com/channels.html), use the `getChannelRef()` method of the `RmqContext` object:

```typescript

@MessagePattern('notifications')
getNotifications(@Payload() data: number[], @Ctx() context: RmqContext) {
  console.log(context.getChannelRef());
}
```

#### Message acknowledgement

To make sure a message is never lost, RabbitMQ supports [message acknowledgements](https://www.rabbitmq.com/confirms.html). The consumer sends an acknowledgement back to tell RabbitMQ that a particular message has been received and processed, and that RabbitMQ is free to delete it. If a consumer dies (its channel is closed, its connection is closed, or the TCP connection is lost) without sending an ack, RabbitMQ assumes the message wasn't fully processed and re-queues it.

By default, the RabbitMQ transporter doesn't expect acknowledgements (`noAck` is `true`). To enable manual acknowledgment mode, set the `noAck` property to `false`:

```typescript
options: {
  urls: ['amqp://localhost:5672'],
  queue: 'cats_queue',
  noAck: false,
  queueOptions: {
    durable: false
  },
},
```

When manual consumer acknowledgements are turned on, you must send an acknowledgement from the worker to signal that it has finished the task:

```typescript

@MessagePattern('notifications')
getNotifications(@Payload() data: number[], @Ctx() context: RmqContext) {
  const channel = context.getChannelRef();
  const originalMsg = context.getMessage();

  channel.ack(originalMsg);
}
```

#### Record builders

To configure message options, use the `RmqRecordBuilder` class (this works for event-based flows as well). For example, to set the `headers` and `priority` properties, use the `setOptions()` method:

```typescript
const message = ':cat:';
const record = new RmqRecordBuilder(message)
  .setOptions({
    headers: {
      ['x-version']: '1.0.0',
    },
    priority: 3,
  })
  .build();

this.client.send('replace-emoji', record).subscribe(...);
```

> info **Hint** The `RmqRecordBuilder` class is exported from the `@nestjs/microservices` package.

AMQP carries some message properties as short strings, of at most 255 bytes: `contentType`, `contentEncoding`, `correlationId`, `replyTo`, `expiration`, `messageId`, `type`, `userId` and `appId`. The client fails a `send()` or `emit()` whose options set a longer one, or, with `wildcards` or a `fanout` exchange, whose pattern, which becomes the routing key, is longer than 255 bytes. A server doesn't reply to a request whose `replyTo` or `correlationId` is longer, and logs an error.

You can read these values on the server side as well, by accessing the `RmqContext`:

```typescript

@MessagePattern('replace-emoji')
replaceEmoji(@Payload() data: string, @Ctx() context: RmqContext): string {
  const { properties: { headers } } = context.getMessage();
  return headers['x-version'] === '1.0.0' ? '🐱' : '🐈';
}
```

Starting with NestJS v12.1.3, a message handler can also return a record. Nest sends the record data as the reply and applies the record options (for example, the `headers` and `priority` properties) to the reply message:

```typescript
@MessagePattern('replace-emoji')
replaceEmoji() {
  return new RmqRecordBuilder(':cat:')
    .setOptions({
      headers: {
        ['x-version']: '1.0.0',
      },
      priority: 3,
    })
    .build();
}
```

The reply always carries the correlation id of the request, so the client can match it to the request.

#### Instance status updates

To get real-time updates on the connection and the state of the underlying driver instance, subscribe to the `status` stream. This stream provides status updates specific to the chosen driver. For the RMQ driver, the `status` stream emits `connected`, `disconnected`, `blocked`, and `unblocked` events.

```typescript
this.client.status.subscribe((status: RmqStatus) => {
  console.log(status);
});
```

> info **Hint** The `RmqStatus` type is imported from the `@nestjs/microservices` package.

Similarly, you can subscribe to the server's `status` stream to receive notifications about the server's status:

```typescript
const server = app.connectMicroservice<MicroserviceOptions>(...);
server.status.subscribe((status: RmqStatus) => {
  console.log(status);
});
```

#### Listening to RabbitMQ events

In some cases, you might want to listen to internal events emitted by the microservice. For example, you could listen for the `error` event to trigger additional operations when an error occurs. To do this, use the `on()` method:

```typescript
this.client.on('error', (err) => {
  console.error(err);
});
```

Similarly, you can listen to the server's internal events:

```typescript
server.on<RmqEvents>('error', (err) => {
  console.error(err);
});
```

> info **Hint** The `RmqEvents` type is imported from the `@nestjs/microservices` package.

Starting with NestJS v12.1.2, listeners registered with the client's `on()` method stay registered until you call `close()`, so they are also attached to the new connection the client creates on the next `send()` or `emit()` call after a connection attempt failed. Registrations are not deduplicated, so register each listener once rather than again after a failed attempt.

#### Underlying driver access

For more advanced use cases, you may need to access the underlying driver instance, for example, to close the connection manually or to use driver-specific methods. However, in most cases you **shouldn't need** to access the driver directly.

To do so, use the `unwrap()` method, which returns the underlying driver instance. Use the generic type parameter to specify the type of driver instance you expect.

```typescript
const managerRef =
  this.client.unwrap<import('amqp-connection-manager').AmqpConnectionManager>();
```

Similarly, you can access the server's underlying driver instance:

```typescript
const managerRef =
  server.unwrap<import('amqp-connection-manager').AmqpConnectionManager>();
```

#### Wildcards

RabbitMQ supports the use of wildcards in routing keys to allow for flexible message routing. The `#` wildcard matches zero or more words, while the `*` wildcard matches exactly one word.

For example, the routing key `cats.#` matches `cats`, `cats.meow`, and `cats.meow.purr`. The routing key `cats.*` matches `cats.meow` but not `cats.meow.purr`.

To enable wildcard support in your RabbitMQ microservice, set the `wildcards` configuration option to `true` in the options object:

```typescript
const app = await NestFactory.createMicroservice<MicroserviceOptions>(
  AppModule,
  {
    transport: Transport.RMQ,
    options: {
      urls: ['amqp://localhost:5672'],
      queue: 'cats_queue',
      wildcards: true,
    },
  },
);
```

With this configuration, you can use wildcards in your routing keys when subscribing to events and messages. For example, to listen for messages with the routing key `cats.#`:

```typescript
@MessagePattern('cats.#')
getCats(@Payload() data: { message: string }, @Ctx() context: RmqContext) {
  console.log(`Received message with routing key: ${context.getPattern()}`);

  return {
    message: 'Hello from the cats service!',
  }
}
```

To send a message with a specific routing key, use the `send()` method of the `ClientProxy` instance:

```typescript
this.client.send('cats.meow', { message: 'Meow!' }).subscribe((response) => {
  console.log(response);
});
```

A routing key holds at most 255 bytes, so a message whose pattern is longer than 255 characters matches no wildcard pattern.
