@bitrix24/b24rabbitmq
Version:
Library for integrating Bitrix24 applications with RabbitMQ
195 lines (152 loc) • 7.73 kB
Markdown
[](https://github.com/bitrix24/b24rabbitmq/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@bitrix24/b24rabbitmq)
[](https://www.npmjs.com/package/@bitrix24/b24rabbitmq)
[](LICENSE)
[](package.json)
Config-driven `Producer` and `Consumer` primitives over [`amqplib`](https://github.com/amqp-node/amqplib) for integrating Bitrix24 applications with RabbitMQ. Declare your exchanges, queues and bindings once; get priority and dead-letter handling out of the box.
> Built primarily for Bitrix24 integrators, but works for any Node.js service that needs RabbitMQ with sensible defaults.
> **Status:** actively being reanimated (2026), pre-v0.1. See [`PROJECT-BRIEF.md`](PROJECT-BRIEF.md) for the roadmap and known limitations. PHP templates are planned (see roadmap).
## Quickstart
Install the library and the `amqplib` peer dependency:
```bash
pnpm add @bitrix24/b24rabbitmq amqplib
# or: npm i @bitrix24/b24rabbitmq amqplib
```
Spin up a local RabbitMQ (with the management UI on http://localhost:15672):
```bash
docker run -d --name rabbitmq -p 5672:5672 -p 15672:15672 rabbitmq:3-management
```
Send and receive a message end-to-end:
```typescript
import {
RabbitMQProducer,
RabbitMQConsumer,
type RabbitMQConfig
} from '@bitrix24/b24rabbitmq'
const config: RabbitMQConfig = {
connection: { url: 'amqp://localhost' },
exchanges: [{ name: 'demo.events.v1', type: 'direct', options: { durable: true } }],
queues: [
{
name: 'demo.v1',
options: { durable: true },
bindings: [{ exchange: 'demo.events.v1', routingKey: 'event.succeeded' }]
}
]
}
// Consumer
const consumer = new RabbitMQConsumer(config)
await consumer.initialize()
consumer.registerHandler('demo.v1', async (msg, ack) => {
console.log('received', msg)
ack()
})
await consumer.consume('demo.v1')
// Producer
const producer = new RabbitMQProducer(config)
await producer.initialize()
await producer.publish('demo.events.v1', 'event.succeeded', { hello: 'world' })
```
```typescript
// rabbitmq.config.ts
import type { RabbitMQConfig } from '@bitrix24/b24rabbitmq';
export const rabbitMQConfig: RabbitMQConfig = {
connection: {
url: 'amqp://localhost',
reconnectInterval: 5000,
maxRetries: 5
},
exchanges: [
{
name: 'demo1.events.v1',
type: 'direct',
options: { durable: true }
}
],
queues: [
{
name: 'demo1.v1',
options: { durable: true },
bindings: [
{
exchange: 'demo1.events.v1',
routingKey: 'event.succeeded'
}
]
}
],
channel: {
prefetchCount: 1
}
};
```
```typescript
// producers/demo1-producer.ts
import { RabbitMQProducer } from '@bitrix24/b24rabbitmq';
import { rabbitMQConfig } from '../rabbitmq.config';
const producer = new RabbitMQProducer(rabbitMQConfig);
await producer.initialize();
export async function sendTask(dots: string) {
await producer.publish(
'demo1.events.v1',
'event.succeeded',
{ task: dots },
{ persistent: true }
);
console.log(`Sent task: ${dots}`);
}
// Example message sending
const tasks = ['...', '....', '.....', '..', '.'];
tasks.forEach(async (task) => {
await sendTask(task);
await new Promise(resolve => setTimeout(resolve, 1000));
});
```
More examples can be found in [documentation](
If you build on Bitrix24, your handlers (PHP modules, application events, REST API consumers) usually talk to the outside world over HTTPS — REST calls in, webhooks out. That pattern hits two limits quickly:
- a slow downstream system blocks the request and risks losing the event,
- retries, ordering, fan-out and dead-lettering have to be reimplemented per integration.
This library is for the **Node.js worker process that sits next to your Bitrix24 app and handles those messages asynchronously**. A typical layout:
1. A Bitrix24 outbound webhook (or your PHP app) publishes an event to a small ingestion endpoint.
2. The endpoint hands it to RabbitMQ via `RabbitMQProducer` ([Runnable examples](#runnable-examples) below).
3. A `RabbitMQConsumer` worker picks it up, calls the Bitrix24 REST API (use [`@bitrix24/b24jssdk`](https://www.npmjs.com/package/@bitrix24/b24jssdk)) or any third-party service, with retries and dead-letter handling configured declaratively.
**Where to run RabbitMQ** — anything that speaks AMQP works. Common choices:
| Option | Notes |
|---|---|
| Self-hosted Docker / Kubernetes | Fastest for prototypes; see the `docker run` line in [Quickstart](
| [CloudAMQP](https://www.cloudamqp.com/) | Managed RabbitMQ in multiple regions (incl. São Paulo and EU); generous free tier for development. |
| AWS MQ for RabbitMQ | Run inside your VPC; available in `sa-east-1`, `eu-central-1`, and others — useful when LGPD/GDPR data-residency rules apply. |
For any non-local broker, use `amqps://user:pass@host/vhost` (TLS) and keep credentials in environment variables, **not** in `rabbitmq.config.ts`.
**Logging.** Diagnostics default to `console.*`; pass `logger: yourLogger` in the config to route them through `pino`, `consola`, the `@bitrix24/b24jssdk` logger, or any object with `{ debug, info, warn, error }` methods. The library scrubs `amqp[s]://user:pass@host` credentials from error messages before they reach your logger.
```ts
import { LoggerBrowser } from '@bitrix24/b24jssdk'
const logger = LoggerBrowser.build('rabbitmq', true)
const config: RabbitMQConfig = {
connection: { url: process.env.RABBITMQ_URL! },
exchanges: [/* … */],
queues: [/* … */],
logger
}
```
Clone the repo and look at [`examples/`](https://github.com/bitrix24/b24rabbitmq/tree/main/examples) for end-to-end scripts you can `pnpm exec tsx` against a local RabbitMQ:
- [`examples/01-uniform-distribution`](https://github.com/bitrix24/b24rabbitmq/tree/main/examples/01-uniform-distribution) — one queue, multiple consumers, round-robin.
- [`examples/02-retry-dlq`](https://github.com/bitrix24/b24rabbitmq/tree/main/examples/02-retry-dlq) — minimal native dead-letter-queue pattern (DLX-driven `nack`).
The library is typed end-to-end with TypeScript and every public symbol carries a JSDoc block — TypeScript users get the full API reference in their IDE (hover, signature help) without any external site. To browse the API reference locally as static HTML, run `pnpm docs:build` and open `docs/api/index.html`.
* [Project brief & roadmap](PROJECT-BRIEF.md)
* [Architecture](docs/ARCHITECTURE.md)
* [Contributing](CONTRIBUTING.md)
* [CHANGELOG](CHANGELOG.md)
* [Terms](docs/en/1_page.md)
* [Demo 1: Even Distribution](docs/en/demo/1_page.md)
* [Demo 2: Balcony and Garden](docs/en/demo/2_page.md)
## Read
- [Official documentation RabbitMQ](https://www.rabbitmq.com/documentation.html)
- [RabbitMQ Patterns: Work Queues](https://www.rabbitmq.com/tutorials/tutorial-two-dotnet.html)
- [Understanding Prefetch](https://www.rabbitmq.com/consumer-prefetch.html)
- [101 Ways to Cook RabbitMQ and a Little About Pipeline Architecture](https://highload.guide/blog/101-RabbitMQ-way-of-cooking.html)