git.stella-ops.org/docs/router/transports/rabbitmq.md

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

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

routers:
  - host: rabbitmq.internal
    port: 5672
    transportType: RabbitMq
    priority: 1
    rabbitmq:
      virtualHost: /stellaops
      exchange: stellaops.router
      routingKeyPrefix: orders

Environment Variables

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

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

Exchange:
  Type: fanout

# All bound queues receive every message
# Good for broadcasting events to all services

Direct Routing

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

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

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
• Transport Overview
• Messaging Transports