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

```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/)