rust-rabbit 🐰

A simple, reliable RabbitMQ client library for Rust. Easy to use with minimal configuration and flexible retry mechanisms.

🚀 Key Features

Simple API: Just Publisher and Consumer with essential methods
Flexible Retry: Exponential, linear, or custom retry mechanisms
Auto-Setup: Automatic queue/exchange declaration and binding
Built-in Reliability: Default ACK behavior with intelligent error handling
Zero Complexity: No enterprise patterns, no metrics - just core messaging

📦 Quick Start

Add to your Cargo.toml:

[dependencies]

rust-rabbit = "1.0"

tokio = { version = "1.0", features = ["full"] }

serde = { version = "1.0", features = ["derive"] }

🎯 Basic Usage

Publisher - Send Messages

use rust_rabbit::{Connection, Publisher, PublishOptions};
use serde::Serialize;

#[derive(Serialize)]
struct Order {
    id: u32,
    amount: f64,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to RabbitMQ
    let connection = Connection::new("amqp://localhost:5672").await?;
    let publisher = Publisher::new(connection);
    
    let order = Order { id: 123, amount: 99.99 };
    
    // Publish to exchange (with routing)
    publisher.publish_to_exchange("orders", "new.order", &order, None).await?;
    
    // Publish directly to queue (simple)
    publisher.publish_to_queue("order_queue", &order, None).await?;
    
    Ok(())
}

Consumer - Receive Messages with Retry

use rust_rabbit::{Connection, Consumer, RetryConfig};
use serde::Deserialize;

#[derive(Deserialize)]
struct Order {
    id: u32,
    amount: f64,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let connection = Connection::new("amqp://localhost:5672").await?;
    
    let consumer = Consumer::builder(connection, "order_queue")
        .retry(RetryConfig::exponential_default()) // 1s->2s->4s->8s->16s
        .bind_to_exchange("orders")
        .concurrency(5)
        .build()
        .await?;
    
    consumer.consume(|order: Order| async move {
        println!("Processing order {}: ${}", order.id, order.amount);
        
        // Your business logic here
        if order.amount > 1000.0 {
            return Err("Amount too high".into()); // Will retry
        }
        
        Ok(()) // ACK message
    }).await?;
    
    Ok(())
}

🔄 Retry Configurations

Built-in Retry Patterns

use rust_rabbit::RetryConfig;
use std::time::Duration;

// Exponential: 1s → 2s → 4s → 8s → 16s (5 retries)
let exponential = RetryConfig::exponential_default();

// Custom exponential: 2s → 4s → 8s → 16s → 32s (max 60s)
let custom_exp = RetryConfig::exponential(5, Duration::from_secs(2), Duration::from_secs(60));

// Linear: 10s → 10s → 10s (3 retries)  
let linear = RetryConfig::linear(3, Duration::from_secs(10));

// Custom delays: 1s → 5s → 30s
let custom = RetryConfig::custom(vec![
    Duration::from_secs(1),
    Duration::from_secs(5), 
    Duration::from_secs(30),
]);

// No retries - fail immediately
let no_retry = RetryConfig::no_retry();

How Retry Works

// Failed messages are automatically:
// 1. Sent to retry queue with delay (e.g., orders.retry.1)
// 2. After delay, returned to original queue for retry
// 3. If max retries exceeded, sent to dead letter queue (e.g., orders.dlq)

⚙️ Advanced Configuration

Connection Options

use rust_rabbit::{Connection, ConnectionBuilder};

// Simple connection
let connection = Connection::new("amqp://guest:guest@localhost:5672").await?;

// With custom settings
let connection = ConnectionBuilder::new("amqp://user:pass@localhost:5672/vhost")
    .connection_timeout(60)  // 60 seconds
    .heartbeat(30)          // 30 seconds  
    .connect()
    .await?;

Publisher Options

use rust_rabbit::PublishOptions;
use std::time::Duration;

let options = PublishOptions::new()
    .persistent(true)                    // Survive broker restart
    .priority(5)                         // Message priority (0-255)
    .ttl(Duration::from_secs(300))      // 5 minutes TTL
    .header("source", "order-service")   // Custom headers
    .header("version", "1.0");

publisher.publish_to_queue("orders", &message, Some(options)).await?;

Consumer Options

let consumer = Consumer::builder(connection, "order_queue")
    .retry(RetryConfig::exponential_default())
    .bind_to_exchange("order_exchange")  // Optional exchange binding
    .routing_key("new.order")            // Custom routing key
    .concurrency(10)                     // Process 10 messages in parallel
    .manual_declare()                    // Skip auto-queue creation
    .build()
    .await?;

📚 Documentation

For detailed guides and advanced topics:

Retry Configuration Guide - Detailed retry patterns and configuration
Exchange & Queue Management - Queue binding, exchange types, and best practices
Error Handling - Error types and handling strategies
Best Practices - Production tips and patterns

🛠️ Examples

See the examples/ directory for complete working examples:

Basic Publisher - Simple message publishing
Basic Consumer - Simple message consumption
Retry Examples - Different retry configurations
Production Setup - Production-ready configuration

🧪 Testing

Run the tests:

cargo test

For integration tests with real RabbitMQ:

# Start RabbitMQ with Docker

docker run -d --name rabbitmq -p 5672:5672 -p 15672:15672 rabbitmq:3-management


# Run integration tests

cargo test --test integration

🔧 Requirements

Rust: 1.70+
RabbitMQ: 3.8+
Tokio: Async runtime

🚦 Migration from v0.x

If you're upgrading from the complex v0.x version:

// OLD (v0.x) - Complex
let consumer = Consumer::new(connection_manager, ConsumerOptions {
    auto_ack: false,
    retry_policy: Some(RetryPolicy::fast()),
    prefetch_count: Some(10),
    // ... many more options
}).await?;

// NEW (v1.0) - Simple  
let consumer = Consumer::builder(connection, "queue")
    .retry(RetryConfig::exponential_default())
    .concurrency(10)
    .build()
    .await?;

Major Changes:

✅ Simplified API with just Publisher and Consumer
✅ Removed enterprise patterns (saga, event sourcing, request-response)
✅ Removed metrics and health monitoring
✅ Unified retry system with flexible mechanisms
✅ Auto-declare queues and exchanges by default

🎯 Design Philosophy

rust-rabbit v1.0 follows these principles:

Simplicity First: Only essential features, no bloat
Reliability Built-in: Automatic retry and error handling
Easy Configuration: Sensible defaults, minimal setup
Production Ready: Persistent messages, proper ACK handling
Developer Friendly: Clear errors, good documentation

🗺️ Roadmap

See ROADMAP.md for planned features:

Connection pooling and load balancing
Monitoring and metrics integration
Advanced retry patterns and policies
Performance optimizations
Additional messaging patterns

📄 License

MIT License - see LICENSE for details.

🤝 Contributing

Contributions welcome! Please read our contributing guide and submit pull requests.

💬 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: docs.rs

Made with ❤️ by the rust-rabbit team

rust-rabbit 1.0.0