do_over/lib.rs
1//! # do-over
2//!
3//! An async-first resilience and transient fault handling library for Rust,
4//! inspired by the .NET Polly library.
5//!
6//! ## Overview
7//!
8//! `do-over` provides a set of resilience policies that can be used to make your
9//! applications more robust when dealing with transient failures, network issues,
10//! and other common problems in distributed systems.
11//!
12//! ## Policies
13//!
14//! - [`retry::RetryPolicy`] - Retry failed operations with configurable backoff
15//! - [`circuit_breaker::CircuitBreaker`] - Prevent cascading failures
16//! - [`timeout::TimeoutPolicy`] - Time-bound operations
17//! - [`bulkhead::Bulkhead`] - Limit concurrent executions
18//! - [`rate_limit::RateLimiter`] - Token bucket rate limiting
19//! - [`hedge::Hedge`] - Hedged requests for latency reduction
20//! - [`fallback::FallbackExt`] - Return default values on failure
21//! - [`cache::TypedCache`] - Cache successful results
22//! - [`wrap::Wrap`] - Compose multiple policies together
23//!
24//! ## Utilities
25//!
26//! - [`context::Context`] - Pass metadata through policy execution
27//!
28//! ## Quick Start
29//!
30//! ```rust
31//! use do_over::{policy::Policy, retry::RetryPolicy, timeout::TimeoutPolicy, wrap::Wrap, error::DoOverError};
32//! use std::time::Duration;
33//!
34//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
35//! // Create a policy that retries 3 times with a 5s timeout per attempt
36//! let policy = Wrap::new(
37//! RetryPolicy::fixed(3, Duration::from_millis(100)),
38//! TimeoutPolicy::new(Duration::from_secs(5)),
39//! );
40//!
41//! // Execute your operation with resilience
42//! let result: Result<&str, DoOverError<&str>> = policy.execute(|| async {
43//! Ok("success")
44//! }).await;
45//! # Ok(())
46//! # }
47//! ```
48//!
49//! ## Policy Composition
50//!
51//! Policies can be composed using [`wrap::Wrap`]. The recommended ordering
52//! (from outer to inner) is:
53//!
54//! 1. Bulkhead - Limit concurrency first
55//! 2. Circuit Breaker - Fast-fail if too many errors
56//! 3. Rate Limiter - Throttle requests
57//! 4. Retry - Handle transient failures
58//! 5. Timeout - Bound individual attempts
59//!
60//! ## Feature Flags
61//!
62//! - `http` - Enables reqwest integration
63//! - `metrics-prometheus` - Prometheus metrics
64//! - `metrics-otel` - OpenTelemetry metrics
65
66pub mod error;
67pub mod policy;
68pub mod retry;
69pub mod circuit_breaker;
70pub mod timeout;
71pub mod bulkhead;
72pub mod rate_limit;
73pub mod hedge;
74pub mod fallback;
75pub mod cache;
76pub mod context;
77pub mod wrap;
78pub mod tower;
79
80#[cfg(feature = "http")]
81pub mod http;
82
83pub mod metrics;