Skip to content

Commit bb32c25

Browse files
bartovalgrs
bartoval
authored and
grs
committed
add_rabbitmq_example
1 parent f130cb1 commit bb32c25

File tree

6 files changed

+1056
-0
lines changed

6 files changed

+1056
-0
lines changed

‎examples/rabbitMQ/Readme.md

Lines changed: 299 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,299 @@
1+
# Getting Started with AMQP 1.0 and RabbitMQ
2+
3+
This guide will help you set up and use AMQP 1.0 with RabbitMQ, using the included Node.js scripts for queue management, message sending, and receiving.
4+
5+
## Prerequisites
6+
7+
- RabbitMQ server (4.0+)
8+
- Node.js (12.0+)
9+
- Administrator privileges (for RabbitMQ plugin management)
10+
11+
## Installation
12+
13+
1. **Install RabbitMQ** (if not already installed):
14+
15+
```bash
16+
# Fedora
17+
sudo dnf install rabbitmq-server
18+
19+
# Debian/Ubuntu
20+
sudo apt-get install rabbitmq-server
21+
22+
# MacOS
23+
brew install rabbitmq
24+
```
25+
26+
2. **Enable the AMQP 1.0 plugin (only for version < 4.0 and 3.8+)**:
27+
28+
```bash
29+
sudo rabbitmq-plugins enable rabbitmq_amqp1_0
30+
sudo systemctl restart rabbitmq-server
31+
```
32+
33+
3. **Install Node.js dependencies**:
34+
35+
```bash
36+
npm install rhea minimist
37+
```
38+
39+
4. **Clone or download the example scripts** to your working directory.
40+
41+
## Overview of Components
42+
43+
This package includes several components that work together:
44+
45+
1. **`options.js`** - A utility module for command-line argument parsing
46+
2. **`rabbitmq_queue_setup.js`** - Queue management script
47+
3. **`rabbitmq_sender.js`** - AMQP 1.0 message sender
48+
4. **`rabbitmq_receiver.js`** - AMQP 1.0 message receiver
49+
5. **`run_rabbitmq_demo.sh`** - Demo script to showcase all components working together
50+
51+
## Quick Start
52+
53+
For a quick demonstration of all components working together:
54+
55+
```bash
56+
chmod +x run_rabbitmq_demo.sh
57+
./run_rabbitmq_demo.sh
58+
```
59+
60+
This script will:
61+
62+
1. Check if RabbitMQ is running
63+
2. Verify the AMQP 1.0 plugin is enabled
64+
3. Create a test queue
65+
4. Start a message receiver in the background
66+
5. Send 5 test messages
67+
6. Show the receiver's output
68+
7. Optionally clean up the test queue
69+
70+
## Working with Queues
71+
72+
The `rabbitmq_queue_setup.js` script provides functionality to create, delete, and manage RabbitMQ queues through the RabbitMQ Management API.
73+
74+
### Creating a Queue
75+
76+
```bash
77+
node rabbitmq_queue_setup.js --queue=my_queue --durable=true
78+
```
79+
80+
### Deleting a Queue
81+
82+
```bash
83+
node rabbitmq_queue_setup.js --queue=my_queue --delete
84+
```
85+
86+
### Purging a Queue
87+
88+
```bash
89+
node rabbitmq_queue_setup.js --queue=my_queue --purge
90+
```
91+
92+
### Binding a Queue to an Exchange
93+
94+
```bash
95+
node rabbitmq_queue_setup.js --queue=my_queue --exchange=my_exchange --routing_key=my_key
96+
```
97+
98+
### Queue Configuration Options
99+
100+
| Option | Alias | Description | Default |
101+
| --------------- | ----- | ----------------------------------------- | ------------------ |
102+
| `--queue` | `-n` | Name of the queue to create | `test_queue` |
103+
| `--exchange` | `-e` | Name of the exchange to bind the queue to | - |
104+
| `--routing_key` | `-r` | Routing key for binding | Same as queue name |
105+
| `--durable` | `-d` | Make the queue durable | `true` |
106+
| `--auto_delete` | `-a` | Auto-delete the queue when not in use | `false` |
107+
| `--delete` | `-x` | Delete the queue instead of creating it | `false` |
108+
| `--purge` | `-p` | Purge all messages from the queue | `false` |
109+
| `--username` | `-u` | Username for RabbitMQ Management API | `guest` |
110+
| `--password` | `-w` | Password for RabbitMQ Management API | `guest` |
111+
| `--host` | `-h` | Hostname of the RabbitMQ server | `localhost` |
112+
| `--port` | `-P` | Port for RabbitMQ Management API | `15672` |
113+
114+
## Sending Messages
115+
116+
The `rabbitmq_sender.js` script uses the AMQP 1.0 protocol to send messages to RabbitMQ queues or exchanges.
117+
118+
### Basic Usage
119+
120+
```bash
121+
node rabbitmq_sender.js --node=my_queue --count=10
122+
```
123+
124+
### Sending to an Exchange with Routing Key
125+
126+
```bash
127+
node rabbitmq_sender.js --node=my_exchange --address=my_routing_key --count=5
128+
```
129+
130+
### Sender Configuration Options
131+
132+
| Option | Alias | Description | Default |
133+
| ------------ | ----- | -------------------------------------------------- | ------------ |
134+
| `--node` | `-n` | Name of the queue or exchange to send messages to | `test_queue` |
135+
| `--address` | `-a` | Address to use (e.g., routing key for an exchange) | - |
136+
| `--count` | `-c` | Number of messages to send | `10` |
137+
| `--interval` | `-i` | Interval between messages in milliseconds | `1000` |
138+
| `--username` | `-u` | Username for authentication | `guest` |
139+
| `--password` | `-p` | Password for authentication | `guest` |
140+
| `--host` | `-h` | Hostname of the RabbitMQ server | `localhost` |
141+
| `--port` | `-P` | AMQP service port | `5672` |
142+
143+
## Receiving Messages
144+
145+
The `rabbitmq_receiver.js` script uses the AMQP 1.0 protocol to receive messages from RabbitMQ queues.
146+
147+
### Basic Usage
148+
149+
```bash
150+
node rabbitmq_receiver.js --node=my_queue
151+
```
152+
153+
### Receiving a Limited Number of Messages
154+
155+
```bash
156+
node rabbitmq_receiver.js --node=my_queue --count=5
157+
```
158+
159+
### Receiver Configuration Options
160+
161+
| Option | Alias | Description | Default |
162+
| ------------ | ----- | --------------------------------------------- | ------------ |
163+
| `--node` | `-n` | Name of the queue to receive messages from | `test_queue` |
164+
| `--count` | `-c` | Number of messages to receive (0 = unlimited) | `0` |
165+
| `--username` | `-u` | Username for authentication | `guest` |
166+
| `--password` | `-p` | Password for authentication | `guest` |
167+
| `--host` | `-h` | Hostname of the RabbitMQ server | `localhost` |
168+
| `--port` | `-P` | AMQP service port | `5672` |
169+
| `--auto_ack` | `-a` | Automatic message acknowledgment | `true` |
170+
| `--prefetch` | `-f` | Credit window size (prefetch count) | `10` |
171+
172+
## Advanced Usage
173+
174+
### Custom Message Properties
175+
176+
The sender script allows you to customize message properties. You can modify the `send_message` function in `rabbitmq_sender.js` to include additional properties:
177+
178+
```javascript
179+
sender.send({
180+
message_id: message_id,
181+
user_id: args.username,
182+
creation_time: new Date(),
183+
subject: args.address || args.node,
184+
content_type: "application/json",
185+
application_properties: {
186+
source: "rhea-rabbitmq-sender",
187+
message_type: "test",
188+
routing_key: args.address,
189+
// Add your custom properties here
190+
priority: 1,
191+
correlation_id: "request-123",
192+
custom_property: "custom-value",
193+
},
194+
body: message_body,
195+
});
196+
```
197+
198+
### Handling Message Acknowledgments
199+
200+
By default, the receiver automatically acknowledges messages. To handle acknowledgments manually:
201+
202+
```bash
203+
node rabbitmq_receiver.js --auto_ack=false
204+
```
205+
206+
This allows you to acknowledge messages after processing:
207+
208+
```javascript
209+
container.on("message", function (context) {
210+
// Process the message
211+
console.log("Processing message:", context.message.body);
212+
213+
// Custom acknowledgment logic
214+
if (processSuccessful) {
215+
context.delivery.accept();
216+
} else {
217+
context.delivery.reject();
218+
}
219+
});
220+
```
221+
222+
### Using Exchanges with AMQP 1.0
223+
224+
To send messages to an exchange:
225+
226+
1. Create an exchange in RabbitMQ (using the Management UI or command line)
227+
2. Bind a queue to this exchange with a routing key
228+
3. Send messages to the exchange with the appropriate routing key:
229+
230+
```bash
231+
node rabbitmq_sender.js --node=my_exchange --address=my_routing_key
232+
```
233+
234+
## Troubleshooting
235+
236+
### Common Issues
237+
238+
1. **Connection Refused**
239+
240+
- Ensure RabbitMQ is running: `sudo systemctl status rabbitmq-server`
241+
- Check if the AMQP port is open: `telnet localhost 5672`
242+
243+
2. **Authentication Failed**
244+
245+
- Verify username and password: `rabbitmqctl list_users`
246+
- Set correct credentials: `--username=user --password=pass`
247+
248+
3. **AMQP 1.0 Protocol Error**
249+
250+
- Verify the plugin is enabled: `rabbitmq-plugins list -e | grep amqp1_0`
251+
- Restart RabbitMQ after enabling the plugin: `sudo systemctl restart rabbitmq-server`
252+
253+
4. **Queue Not Found**
254+
- Verify the queue exists: `rabbitmqctl list_queues`
255+
- Create the queue first using `rabbitmq_queue_setup.js`
256+
257+
### Logging and Debugging
258+
259+
For more detailed logging, you can modify the scripts to include debugging information:
260+
261+
```javascript
262+
// Enable rhea debug logging
263+
container.on("connection_open", function (context) {
264+
console.log("Connection details:", context.connection.options);
265+
});
266+
267+
container.on("error", function (context) {
268+
console.error("Error details:", context.error);
269+
});
270+
```
271+
272+
## Extending the Scripts
273+
274+
The included scripts provide a foundation that you can extend for your specific use cases:
275+
276+
1. **Add Message Filtering** - Modify the receiver to filter messages based on properties
277+
2. **Implement Request-Reply Pattern** - Add correlation IDs and reply-to addresses
278+
3. **Message Transformation** - Transform messages before sending or after receiving
279+
4. **Error Handling** - Add robust error handling and retry logic
280+
5. **Monitoring** - Add metrics collection for monitoring message flow
281+
282+
## Resources
283+
284+
- [RabbitMQ AMQP 1.0 Plugin Documentation](https://www.rabbitmq.com/plugins.html#rabbitmq_amqp1_0)
285+
- [AMQP 1.0 Specification](http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-overview-v1.0-os.html)
286+
- [Rhea AMQP Client Library](https://github.com/amqp/rhea)
287+
- [RabbitMQ Management HTTP API](https://rawcdn.githack.com/rabbitmq/rabbitmq-server/v4.0.0/deps/rabbitmq_management/priv/www/api/index.html)
288+
289+
## Conclusion
290+
291+
This guide covers the basics of working with AMQP 1.0 and RabbitMQ using the included Node.js scripts. You can use these examples as a starting point for building more complex messaging applications.
292+
293+
For production use, consider adding features such as:
294+
295+
- SSL/TLS security
296+
- Connection pooling
297+
- Robust error handling and retries
298+
- Monitoring and alerting
299+
- Message persistence guarantees

0 commit comments

Comments
 (0)