Fix build and code structure improvements. New but essential UI functionality. CI improvements. Documentation improvements. AI module improvements.
This commit is contained in:
StellaOps Bot
241
docs/router/transports/rabbitmq.md
Normal file
241
docs/router/transports/rabbitmq.md
Normal file
@@ -0,0 +1,241 @@
|
||||
# RabbitMQ Transport
|
||||
|
||||
The RabbitMQ transport provides durable, asynchronous message delivery using AMQP 0.9.1 protocol. Ideal for high-volume async processing, fan-out patterns, and scenarios requiring message persistence.
|
||||
|
||||
## Overview
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Plugin Assembly | `StellaOps.Router.Transport.RabbitMq.dll` |
|
||||
| Transport Name | `rabbitmq` |
|
||||
| Protocol | AMQP 0.9.1 (RabbitMQ.Client 7.x) |
|
||||
| Security | TLS, SASL authentication |
|
||||
| Use Case | Async processing, fan-out, durable messaging |
|
||||
|
||||
## Configuration
|
||||
|
||||
### router.yaml
|
||||
|
||||
```yaml
|
||||
Router:
|
||||
Transport:
|
||||
Type: rabbitmq
|
||||
RabbitMq:
|
||||
HostName: rabbitmq.internal
|
||||
Port: 5672
|
||||
VirtualHost: /stellaops
|
||||
UserName: stellaops
|
||||
Password: ${RABBITMQ_PASSWORD:-}
|
||||
Ssl:
|
||||
Enabled: true
|
||||
ServerName: rabbitmq.internal
|
||||
CertPath: /certs/client.pfx
|
||||
Exchange:
|
||||
Name: stellaops.router
|
||||
Type: topic
|
||||
Durable: true
|
||||
Queue:
|
||||
Durable: true
|
||||
AutoDelete: false
|
||||
PrefetchCount: 100
|
||||
```
|
||||
|
||||
### microservice.yaml
|
||||
|
||||
```yaml
|
||||
routers:
|
||||
- host: rabbitmq.internal
|
||||
port: 5672
|
||||
transportType: RabbitMq
|
||||
priority: 1
|
||||
rabbitmq:
|
||||
virtualHost: /stellaops
|
||||
exchange: stellaops.router
|
||||
routingKeyPrefix: orders
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
```bash
|
||||
ROUTER__TRANSPORT__TYPE=rabbitmq
|
||||
ROUTER__TRANSPORT__RABBITMQ__HOSTNAME=rabbitmq.internal
|
||||
ROUTER__TRANSPORT__RABBITMQ__PORT=5672
|
||||
ROUTER__TRANSPORT__RABBITMQ__USERNAME=stellaops
|
||||
ROUTER__TRANSPORT__RABBITMQ__PASSWORD=secret
|
||||
```
|
||||
|
||||
## Options Reference
|
||||
|
||||
### Connection Options
|
||||
|
||||
| Option | Type | Default | Description |
|
||||
|--------|------|---------|-------------|
|
||||
| `HostName` | string | `localhost` | RabbitMQ server hostname |
|
||||
| `Port` | int | `5672` | AMQP port (5671 for TLS) |
|
||||
| `VirtualHost` | string | `/` | RabbitMQ virtual host |
|
||||
| `UserName` | string | `guest` | Authentication username |
|
||||
| `Password` | string | `guest` | Authentication password |
|
||||
| `ConnectionTimeout` | TimeSpan | `00:00:30` | Connection timeout |
|
||||
| `RequestedHeartbeat` | TimeSpan | `00:01:00` | Heartbeat interval |
|
||||
|
||||
### SSL Options
|
||||
|
||||
| Option | Type | Default | Description |
|
||||
|--------|------|---------|-------------|
|
||||
| `Ssl:Enabled` | bool | `false` | Enable TLS |
|
||||
| `Ssl:ServerName` | string | - | Expected server certificate name |
|
||||
| `Ssl:CertPath` | string | - | Client certificate path |
|
||||
| `Ssl:CertPassphrase` | string | - | Client certificate password |
|
||||
| `Ssl:Version` | SslProtocols | `Tls13` | TLS version |
|
||||
|
||||
### Exchange Options
|
||||
|
||||
| Option | Type | Default | Description |
|
||||
|--------|------|---------|-------------|
|
||||
| `Exchange:Name` | string | `stellaops.router` | Exchange name |
|
||||
| `Exchange:Type` | string | `topic` | Exchange type (direct, topic, fanout, headers) |
|
||||
| `Exchange:Durable` | bool | `true` | Survive broker restart |
|
||||
| `Exchange:AutoDelete` | bool | `false` | Delete when unused |
|
||||
|
||||
### Queue Options
|
||||
|
||||
| Option | Type | Default | Description |
|
||||
|--------|------|---------|-------------|
|
||||
| `Queue:Durable` | bool | `true` | Persist messages to disk |
|
||||
| `Queue:AutoDelete` | bool | `false` | Delete when all consumers disconnect |
|
||||
| `Queue:Exclusive` | bool | `false` | Single-consumer queue |
|
||||
| `Queue:PrefetchCount` | int | `100` | Prefetch limit per consumer |
|
||||
|
||||
## Message Flow
|
||||
|
||||
```
|
||||
┌───────────────┐ ┌─────────────────────────────────────────────┐
|
||||
│ Gateway │ │ RabbitMQ Broker │
|
||||
│ │ │ │
|
||||
│ ─────────────►│ AMQP │ ┌───────────────┐ ┌──────────────────┐ │
|
||||
│ Publish │────────►│ │ Exchange │───►│ Service Queue │ │
|
||||
│ │ │ │ (topic/fanout)│ │ (orders.*) │ │
|
||||
└───────────────┘ │ └───────────────┘ └────────┬─────────┘ │
|
||||
│ │ │
|
||||
└─────────────────────────────────│──────────┘
|
||||
│
|
||||
▼
|
||||
┌───────────────────────────────────────────┐
|
||||
│ Microservices │
|
||||
│ ┌─────────────┐ ┌─────────────────────┐ │
|
||||
│ │ OrderCreate │ │ OrderNotification │ │
|
||||
│ │ Consumer │ │ Consumer │ │
|
||||
│ └─────────────┘ └─────────────────────┘ │
|
||||
└───────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Routing Patterns
|
||||
|
||||
### Topic Routing
|
||||
|
||||
```yaml
|
||||
Exchange:
|
||||
Type: topic
|
||||
|
||||
# Microservice A binds to: orders.create.#
|
||||
# Microservice B binds to: orders.*.notify
|
||||
# Gateway publishes to: orders.create.premium → matches A only
|
||||
# Gateway publishes to: orders.cancel.notify → matches B only
|
||||
```
|
||||
|
||||
### Fan-Out Pattern
|
||||
|
||||
```yaml
|
||||
Exchange:
|
||||
Type: fanout
|
||||
|
||||
# All bound queues receive every message
|
||||
# Good for broadcasting events to all services
|
||||
```
|
||||
|
||||
### Direct Routing
|
||||
|
||||
```yaml
|
||||
Exchange:
|
||||
Type: direct
|
||||
|
||||
# Exact routing key match required
|
||||
# Gateway publishes to: order-service
|
||||
# Only queue bound with key "order-service" receives
|
||||
```
|
||||
|
||||
## Performance Characteristics
|
||||
|
||||
| Metric | Typical Value |
|
||||
|--------|---------------|
|
||||
| Latency (p50) | < 5ms |
|
||||
| Latency (p99) | < 20ms |
|
||||
| Throughput | 50,000+ mps |
|
||||
| Memory per connection | ~16KB |
|
||||
|
||||
*Persistent messages with acknowledgments on dedicated broker*
|
||||
|
||||
## High Availability
|
||||
|
||||
### Clustered RabbitMQ
|
||||
|
||||
```yaml
|
||||
RabbitMq:
|
||||
Endpoints:
|
||||
- Host: rabbit1.internal
|
||||
Port: 5672
|
||||
- Host: rabbit2.internal
|
||||
Port: 5672
|
||||
- Host: rabbit3.internal
|
||||
Port: 5672
|
||||
Queue:
|
||||
Arguments:
|
||||
x-ha-policy: all # Mirror to all nodes
|
||||
x-queue-type: quorum # Quorum queue (RabbitMQ 3.8+)
|
||||
```
|
||||
|
||||
### Dead Letter Handling
|
||||
|
||||
```yaml
|
||||
Queue:
|
||||
Arguments:
|
||||
x-dead-letter-exchange: stellaops.dlx
|
||||
x-dead-letter-routing-key: failed
|
||||
x-message-ttl: 3600000 # 1 hour TTL
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Connection Refused
|
||||
|
||||
```
|
||||
Error: Failed to connect to rabbitmq.internal:5672
|
||||
```
|
||||
|
||||
1. Verify RabbitMQ is running: `rabbitmqctl status`
|
||||
2. Check firewall allows AMQP port
|
||||
3. Verify virtual host exists: `rabbitmqctl list_vhosts`
|
||||
4. Confirm user has permissions: `rabbitmqctl list_user_permissions stellaops`
|
||||
|
||||
### Authentication Failed
|
||||
|
||||
```
|
||||
Error: ACCESS_REFUSED - Login was refused
|
||||
```
|
||||
|
||||
1. Check username/password are correct
|
||||
2. Verify user exists: `rabbitmqctl list_users`
|
||||
3. Grant permissions: `rabbitmqctl set_permissions -p /stellaops stellaops ".*" ".*" ".*"`
|
||||
|
||||
### Messages Not Being Consumed
|
||||
|
||||
1. Check queue exists: `rabbitmqctl list_queues`
|
||||
2. Verify binding: `rabbitmqctl list_bindings -p /stellaops`
|
||||
3. Check consumer is connected: `rabbitmqctl list_consumers`
|
||||
4. Monitor unacked messages: `rabbitmqctl list_queues messages_unacknowledged`
|
||||
|
||||
## See Also
|
||||
|
||||
- [RabbitMQ Documentation](https://www.rabbitmq.com/documentation.html)
|
||||
- [Transport Overview](./README.md)
|
||||
- [Messaging Transports](../../messaging/)
|
||||
Reference in New Issue
Block a user