🐰 rabbit-relay

A lightweight, plug-and-play RabbitMQ abstraction for route-based communication between microservices.
Supports both RPC-style messaging (sendAndReceive) and fire-and-forget (sendAndForget) messaging.

✨ Features

• 🔁 RPC Messaging: Send a message and wait for a response (sendAndReceive)
• 🚀 Fire-and-Forget: Send a message without expecting a reply (sendAndForget)
• 📬 Dynamic Dispatching: Register route handlers with registerRoutes
• ⚙️ Reusable Package: Designed to be imported in multiple microservices with minimal setup

📦 Installation

npm install rabbit-relay

🧪 Requirements

• Node.js >= v14
• RabbitMQ server running (you can use Docker for local development)

🔧 Environment Variables

Set these in your .env file in each microservice:

RABBITMQ_URL=amqp://localhost
EXCHANGE_NAME=main_exchange

🔸 The package does not load .env internally, so make sure to call require('dotenv').config() at the top of your microservice’s main file.

🛠️ Usage

1. Setup Route Registry in Your Service

// user-service/src/rabbit/routeRegistry.js

const userController = require('../controllers/user.controller');

module.exports = {
  'POST /user/create': userController.createUser,
  'DELETE /user/delete': userController.deleteUser,
};

2. Register Routes & Start Consumer

// user-service/src/server.js

require('dotenv').config(); // required!

const { initialiseConsumer } = require('rabbit-relay');
const routeRegistry = require('./rabbit/routeRegistry');

initialiseConsumer(routeRegistry, <queueName>)

3. Send a Message

// auth-service/src/someController.js

const { sendAndReceive, sendAndForget } = require('rabbit-relay');

// Send and wait for response
const response = await sendAndReceive(<queueName>, {
  path: '/user/create',
  method: 'POST',
  body: { name: 'somename', email: '[email protected]' }
});

// Fire-and-forget
await sendAndForget(<queueName>, { userId: 123, action: 'LOGIN' });

🧰 API

sendAndReceive(route, payload, timeout = 8000)

Sends a message and waits for a response. Useful for request-response workflows.

sendAndForget(route, payload)

Sends a message without expecting a response. Useful for logging, notifications, etc.

startConsumer()

Initializes the consumer to listen for messages. Should be called in the service that handles incoming messages.

registerRoutes(routeRegistry)

Maps incoming routes to specific handler functions.

📂 Suggested Folder Structure in Your Service

your-service/
├── controllers/
│   └── user.controller.js
├── rabbit/
│   └── routeRegistry.js
├── server.js
└── .env

❓ FAQs

What format should routes follow?

Use URL-style strings like /user/create, /user/delete, /notification/send.

What happens if a route is not found?

An error is logged, and the message is nacked (not acknowledged).

Can I define DLQ or Retry Mechanisms?

Currently not included. Can be added later by extending consumer.js.

🚀 Roadmap

• [ ] Add support for Dead Letter Queues
• [ ] Retry logic for failed messages
• [ ] Optional logging adapter support
• [ ] TypeScript support

🧑‍💻 Contributing

1. Fork the repo
2. Create your branch: git checkout -b feature/some-feature
3. Commit your changes
4. Push and create a PR

📝 License

MIT License

Made with ❤️ for microservice developers.