@nestjstools/messaging-google-pubsub-extension/README.md

Extension to handle messages and dispatch them over Google PubSub

<p align="center">
    <image src="nestjstools-logo.png" width="400">
</p>

# @nestjstools/messaging-google-pubsub-extension

A NestJS library for managing asynchronous and synchronous messages with support for buses, handlers, channels, and consumers. This library simplifies building scalable and decoupled applications by facilitating robust message handling pipelines while ensuring flexibility and reliability.

---

## Documentation

https://nestjstools.gitbook.io/nestjstools-messaging-docs

---

## Installation

```bash
npm install @nestjstools/messaging @nestjstools/messaging-google-pubsub-extension 
```

or

```bash
yarn add @nestjstools/messaging @nestjstools/messaging-google-pubsub-extension
```
## Google PubSub Integration: Messaging Configuration Example

---

```typescript
import { Module } from '@nestjs/common';
import { MessagingModule } from '@nestjstools/messaging';
import { SendMessageHandler } from './handlers/send-message.handler';
import { MessagingGooglePubSubExtensionModule, GooglePubSubChannelConfig } from '@nestjstools/messaging-google-pubsub-extension';

@Module({
  imports: [
    MessagingGooglePubSubExtensionModule, // Importing the GooglePubSub extension module
    MessagingModule.forRoot({
      buses: [
        {
          name: 'pubsub-event.bus',
          channels: ['pubsub-event'],
        },
      ],
      channels: [
        new GooglePubSubChannelConfig({
          name: 'pubsub-event',
          enableConsumer: true, // Enable if you want to consume messages
          autoCreate: true, // Auto-create queue if it doesn't exist
          credentials: { // Optional
            projectId: 'x',
          },
          topicName: 'eventTopic',
          subscriptionName: 'eventSubscriptionTopic',
        }),
      ],
      debug: true, // Optional: Enable debugging for Messaging operations
    }),
  ],
})
export class AppModule {}
```

## Dispatch messages via bus (example)

```typescript
import { Controller, Get } from '@nestjs/common';
import { CreateUser } from './application/command/create-user';
import { IMessageBus, MessageBus, RoutingMessage } from '@nestjstools/messaging';

@Controller()
export class AppController {
  constructor(
    @MessageBus('pubsub-event.bus') private pubsubMessageBus: IMessageBus,
  ) {}

  @Get('/pubsub')
  createUser(): string {
    this.pubsubMessageBus.dispatch(new RoutingMessage(new CreateUser('John FROM SQS'), 'my_app_command.create_user'));

    return 'Message sent';
  }
}
```

### Handler for your message

```typescript
import { CreateUser } from '../create-user';
import { IMessageBus, IMessageHandler, MessageBus, MessageHandler, RoutingMessage, DenormalizeMessage } from '@nestjstools/messaging';

@MessageHandler('my_app_command.create_user')
export class CreateUserHandler implements IMessageHandler<CreateUser>{

  handle(message: CreateUser): Promise<void> {
    console.log(message);
    // TODO Logic there
  }
}
```

---

### Key Features:

* **Google Cloud Pub/Sub Integration** Seamlessly send and receive messages using Google Cloud Pub/Sub within your NestJS application.

* **Local Development Support with Emulator** Supports running against the Google Pub/Sub emulator for local development and testing (via PUBSUB_EMULATOR_HOST).

* **Automatic Topic and Subscription Creation** Automatically creates Pub/Sub topics and subscriptions when autoCreate: true is set in the configuration.

* **Named Buses & Channel Routing** Supports custom-named message buses and routing of messages across multiple channels for event-driven architecture.

* Easily configure projectId, topicName, and subscriptionName for full control over Pub/Sub setup.
---

## 📨 Communicating Beyond a NestJS Application (Cross-Language Messaging)

### To enable communication with a Handler from services written in other languages, follow these steps:

1. **Publish a Message to the Topic**

2. **Include the Routing Key Header**
   Your message **must** include a header attribute named `messaging-routing-key`.
   The value should correspond to the routing key defined in your NestJS message handler:

   ```ts
   @MessageHandler('my_app_command.create_user') // <-- Use this value as the routing key
   ```

---
## 🔧 Send additional attributes into your message

   ```ts
    this.pubSubMessageBus.dispatch(new RoutingMessage(new CreateUser('id'), 'my_app_command.create_user', new GooglePubSubMessageOptions({YourAttribute: 'value'})));
   ```
---

## Configuration options

### GooglePubSubChannel

#### **GooglePubSubChannelConfig**

| **Property**           | **Description**                                                                                  | **Default Value** |
| ---------------------- | ------------------------------------------------------------------------------------------------ | ----------------- |
| **`name`**             | The name of the messaging channel within your app (used for internal routing).                   |                   |
| **`credentials`**      | Google Cloud Pub/Sub credentials (e.g., `{ projectId: 'my-project' }`).                          |                   |
| **`enableConsumer`**   | Whether to enable message consumption (i.e., subscribing and processing messages from Pub/Sub).  | `true`            |
| **`autoCreate`**       | Automatically create the topic and subscription if they do not exist in the Pub/Sub environment. | `true`            |
| **`topicName`**        | The name of the Google Pub/Sub topic to publish messages to.                                     |                   |
| **`subscriptionName`** | The name of the subscription used to consume messages from the topic.                            |                   |

---

## Real world working example with RabbitMQ & Redis - but might be helpful to understand how it works
https://github.com/nestjstools/messaging-rabbitmq-example