# rust-rabbit 🐰
[](https://github.com/nghiaphamln/rust-rabbit/actions)
[](https://crates.io/crates/rust-rabbit)
[](https://docs.rs/rust-rabbit)
[](https://opensource.org/licenses/MIT)
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`:
```toml
[dependencies]
rust-rabbit = "1.0"
tokio = { version = "1.0", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }
```
## 🎯 **Basic Usage**
### Publisher - Send Messages
```rust
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
```rust
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
```rust
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
```rust
// 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
```rust
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
```rust
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
```rust
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](docs/retry-guide.md)** - Detailed retry patterns and configuration
- **[Exchange & Queue Management](docs/queues-exchanges.md)** - Queue binding, exchange types, and best practices
- **[Error Handling](docs/error-handling.md)** - Error types and handling strategies
- **[Best Practices](docs/best-practices.md)** - Production tips and patterns
## 🛠️ **Examples**
See the [`examples/`](examples/) directory for complete working examples:
- **[Basic Publisher](examples/basic_publisher.rs)** - Simple message publishing
- **[Basic Consumer](examples/basic_consumer.rs)** - Simple message consumption
- **[Retry Examples](examples/retry_examples.rs)** - Different retry configurations
- **[Production Setup](examples/production_setup.rs)** - Production-ready configuration
## 🧪 **Testing**
Run the tests:
```bash
cargo test
```
For integration tests with real RabbitMQ:
```bash
# 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:
```rust
// 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:
1. **Simplicity First**: Only essential features, no bloat
2. **Reliability Built-in**: Automatic retry and error handling
3. **Easy Configuration**: Sensible defaults, minimal setup
4. **Production Ready**: Persistent messages, proper ACK handling
5. **Developer Friendly**: Clear errors, good documentation
## 🗺️ **Roadmap**
See [ROADMAP.md](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](LICENSE) for details.
## 🤝 **Contributing**
Contributions welcome! Please read our [contributing guide](CONTRIBUTING.md) and submit pull requests.
## 💬 **Support**
- **Issues**: [GitHub Issues](https://github.com/nghiaphamln/rust-rabbit/issues)
- **Discussions**: [GitHub Discussions](https://github.com/nghiaphamln/rust-rabbit/discussions)
- **Documentation**: [docs.rs](https://docs.rs/rust-rabbit)
---
Made with ❤️ by the rust-rabbit team