|
| 1 | +<p align="center"> |
| 2 | + <image src="nestjstools-logo.png" width="400"> |
| 3 | +</p> |
| 4 | + |
| 5 | +# @nestjstools/messaging-azure-service-bus-extension |
| 6 | + |
| 7 | +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. |
| 8 | + |
| 9 | +--- |
| 10 | + |
| 11 | +## Documentation |
| 12 | + |
| 13 | +https://nestjstools.gitbook.io/nestjstools-messaging-docs |
| 14 | + |
| 15 | +--- |
| 16 | + |
| 17 | +## Installation |
| 18 | + |
| 19 | +```bash |
| 20 | +npm install @nestjstools/messaging @nestjstools/messaging-azure-service-bus-extension |
| 21 | +``` |
| 22 | + |
| 23 | +or |
| 24 | + |
| 25 | +```bash |
| 26 | +yarn add @nestjstools/messaging @nestjstools/messaging-azure-service-bus-extension |
| 27 | +``` |
| 28 | +## Azure service bus Integration: Messaging Configuration Example |
| 29 | + |
| 30 | +--- |
| 31 | + |
| 32 | +```typescript |
| 33 | +import { Module } from '@nestjs/common'; |
| 34 | +import { MessagingModule } from '@nestjstools/messaging'; |
| 35 | +import { SendMessageHandler } from './handlers/send-message.handler'; |
| 36 | +import { MessagingAzureServiceBusExtensionModule, AzureServiceBusChannelConfig } from '@nestjstools/messaging-azure-service-bus-extension'; |
| 37 | + |
| 38 | +@Module({ |
| 39 | + imports: [ |
| 40 | + MessagingAzureServiceBusExtensionModule, |
| 41 | + MessagingModule.forRoot({ |
| 42 | + buses: [ |
| 43 | + { |
| 44 | + name: 'azure.bus', |
| 45 | + channels: ['azure-channel'], |
| 46 | + }, |
| 47 | + ], |
| 48 | + channels: [ |
| 49 | + new AzureServiceBusChannelConfig({ |
| 50 | + name: 'azure-channel', |
| 51 | + enableConsumer: true, |
| 52 | + autoCreate: false, // You need to have admin account to create a queue |
| 53 | + fullyQualifiedNamespace: 'Endpoint=...', |
| 54 | + queue: 'azure-queue', |
| 55 | + }), |
| 56 | + ], |
| 57 | + debug: true, // Optional: Enable debugging for Messaging operations |
| 58 | + }), |
| 59 | + ], |
| 60 | +}) |
| 61 | +export class AppModule {} |
| 62 | +``` |
| 63 | + |
| 64 | +## Dispatch messages via bus (example) |
| 65 | + |
| 66 | +```typescript |
| 67 | +import { Controller, Get } from '@nestjs/common'; |
| 68 | +import { CreateUser } from './application/command/create-user'; |
| 69 | +import { IMessageBus, MessageBus, RoutingMessage } from '@nestjstools/messaging'; |
| 70 | + |
| 71 | +@Controller() |
| 72 | +export class AppController { |
| 73 | + constructor( |
| 74 | + @MessageBus('azure.bus') private azureMessageBus: IMessageBus, |
| 75 | + ) {} |
| 76 | + |
| 77 | + @Get('/azure') |
| 78 | + createUser(): string { |
| 79 | + this.azureMessageBus.dispatch(new RoutingMessage(new CreateUser('John FROM Azure bus'), 'my_app_command.create_user')); |
| 80 | + |
| 81 | + return 'Message sent'; |
| 82 | + } |
| 83 | +} |
| 84 | +``` |
| 85 | + |
| 86 | +### Handler for your message |
| 87 | + |
| 88 | +```typescript |
| 89 | +import { CreateUser } from '../create-user'; |
| 90 | +import { IMessageBus, IMessageHandler, MessageBus, MessageHandler, RoutingMessage, DenormalizeMessage } from '@nestjstools/messaging'; |
| 91 | + |
| 92 | +@MessageHandler('my_app_command.create_user') |
| 93 | +export class CreateUserHandler implements IMessageHandler<CreateUser>{ |
| 94 | + |
| 95 | + handle(message: CreateUser): Promise<void> { |
| 96 | + console.log(message); |
| 97 | + // TODO Logic there |
| 98 | + } |
| 99 | +} |
| 100 | +``` |
| 101 | + |
| 102 | +--- |
| 103 | + |
| 104 | +### Key Features: |
| 105 | + |
| 106 | +* **Azure service bus Integration** Seamlessly send and receive messages using Azure service bus within your NestJS application. |
| 107 | + |
| 108 | +* **Automatic Queue Creation** Automatically creates when autoCreate: true is set in the configuration. |
| 109 | + |
| 110 | +* **Named Buses & Channel Routing** Supports custom-named message buses and routing of messages across multiple channels for event-driven architecture. |
| 111 | + |
| 112 | +--- |
| 113 | + |
| 114 | +## 📨 Communicating Beyond a NestJS Application (Cross-Language Messaging) |
| 115 | + |
| 116 | +### To enable communication with a Handler from services written in other languages, follow these steps: |
| 117 | + |
| 118 | +1. **Publish a Message to the queue** |
| 119 | + |
| 120 | +2. **Include the Routing Key Header** |
| 121 | + Your message **must** include a header attribute named `messaging-routing-key`. |
| 122 | + The value should correspond to the routing key defined in your NestJS message handler: |
| 123 | + |
| 124 | + ```ts |
| 125 | + @MessageHandler('my_app_command.create_user') // <-- Use this value as the routing key |
| 126 | + ``` |
| 127 | + |
| 128 | +--- |
| 129 | + |
| 130 | +## Configuration options |
| 131 | + |
| 132 | +### AzureServiceBusChannel |
| 133 | + |
| 134 | +#### **AzureServiceBusChannelConfig** |
| 135 | + |
| 136 | +| **Property** | **Description** | **Default Value** | |
| 137 | +|-------------------------------|-----------------------------------------------------------------------------------------------|-------------------| |
| 138 | +| **`name`** | The name of the messaging channel within your app (used for internal routing). | | |
| 139 | +| **`fullyQualifiedNamespace`** | Azure service bus credentials (e.g., `Endpoint=sb:...`). | | |
| 140 | +| **`enableConsumer`** | Whether to enable message consumption (i.e., subscribing and processing messages from queue). | `true` | |
| 141 | +| **`autoCreate`** | Automatically create the queue, but admin permission is required from IAM | `true` | |
| 142 | +| **`queue`** | The name of the queue to publish messages and consume. | | |
| 143 | + |
| 144 | +--- |
| 145 | + |
| 146 | +## Real world working example with RabbitMQ & Redis - but might be helpful to understand how it works |
| 147 | +https://github.com/nestjstools/messaging-rabbitmq-example |
0 commit comments