Struct Wrap 

pub struct Wrap<O, I> {
    pub outer: O,
    pub inner: I,
}

Composes two policies together.

The outer policy wraps the inner policy. Execution flows: outer → inner → operation

Type Parameters

• O - The outer policy type
• I - The inner policy type

Examples

Basic composition:

use do_over::{wrap::Wrap, retry::RetryPolicy, timeout::TimeoutPolicy};
use std::time::Duration;

let policy = Wrap::new(
    RetryPolicy::fixed(3, Duration::from_millis(100)),
    TimeoutPolicy::new(Duration::from_secs(5)),
);

Multi-layer composition:

use do_over::{wrap::Wrap, bulkhead::Bulkhead, retry::RetryPolicy, timeout::TimeoutPolicy};
use std::time::Duration;

let policy = Wrap::new(
    Bulkhead::new(10),
    Wrap::new(
        RetryPolicy::fixed(3, Duration::from_millis(100)),
        TimeoutPolicy::new(Duration::from_secs(5)),
    ),
);

Fields

outer: O

The outer policy (executed first).

inner: I

The inner policy (executed second, wrapping the operation).

Implementations

impl<O, I> Wrap<O, I>

pub fn new(outer: O, inner: I) -> Self

Create a new policy composition.

Arguments

• outer - The outer policy (executed first)
• inner - The inner policy (wraps the operation)

Examples

use do_over::{wrap::Wrap, retry::RetryPolicy, timeout::TimeoutPolicy};
use std::time::Duration;

let policy = Wrap::new(
    RetryPolicy::fixed(3, Duration::from_millis(100)),
    TimeoutPolicy::new(Duration::from_secs(5)),
);

Examples found in repository

examples/comprehensive.rs (lines 54-60)

fn create_inventory_policy() -> InventoryPolicy {
    Wrap::new(
        RateLimiter::new(3, Duration::from_secs(1)), // 3 requests per second
        Wrap::new(
            RetryPolicy::fixed(2, Duration::from_millis(100)),
            TimeoutPolicy::new(Duration::from_millis(500)),
        ),
    )
}

fn create_payment_policy() -> PaymentPolicy {
    Wrap::new(
        CircuitBreaker::new(3, Duration::from_secs(5)), // Opens after 3 failures
        Wrap::new(
            RetryPolicy::fixed(2, Duration::from_millis(200)),
            TimeoutPolicy::new(Duration::from_secs(1)),
        ),
    )
}

fn create_notification_policy() -> NotificationPolicy {
    Wrap::new(
        Hedge::new(Duration::from_millis(100)), // Start hedge after 100ms
        TimeoutPolicy::new(Duration::from_millis(500)),
    )
}

examples/http_service.rs (lines 12-15)

async fn main() {
    let policy = Wrap::new(
        RetryPolicy::fixed(2, Duration::from_millis(50)),
        TimeoutPolicy::new(Duration::from_secs(1)),
    );

    let app = Router::new().route(
        "/",
        get(|| async move {
            let result: Result<&str, DoOverError<()>> =
                policy.execute(|| async { Ok("hello from do-over") }).await;
            result.unwrap()
        }),
    );

    println!("Starting server on http://0.0.0.0:3000");
    let listener = TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

examples/composition.rs (lines 42-45)

async fn pattern1_retry_timeout() {
    println!("📌 Pattern 1: Retry wrapping Timeout");
    println!("   Wrap::new(Retry(3, 100ms), Timeout(200ms))");
    println!("   → Each retry attempt gets its own 200ms timeout\n");

    let policy = Wrap::new(
        RetryPolicy::fixed(3, Duration::from_millis(100)),
        TimeoutPolicy::new(Duration::from_millis(200)),
    );

    let attempt_count = Arc::new(AtomicUsize::new(0));
    let start = Instant::now();

    // Scenario: First 2 attempts timeout, third succeeds quickly
    let result: Result<String, DoOverError<String>> = {
        let ac = Arc::clone(&attempt_count);
        policy
            .execute(|| {
                let count = Arc::clone(&ac);
                async move {
                    let attempt = count.fetch_add(1, Ordering::SeqCst) + 1;
                    let elapsed = start.elapsed().as_millis();
                    println!(
                        "   [+{:>4}ms] Attempt {}: Started",
                        elapsed, attempt
                    );

                    if attempt < 3 {
                        // First two attempts are slow - will timeout
                        println!(
                            "   [+{:>4}ms] Attempt {}: Processing slowly (will timeout)...",
                            elapsed, attempt
                        );
                        tokio::time::sleep(Duration::from_millis(500)).await;
                        Ok("Should not reach here".to_string())
                    } else {
                        // Third attempt is fast
                        tokio::time::sleep(Duration::from_millis(50)).await;
                        let elapsed = start.elapsed().as_millis();
                        println!(
                            "   [+{:>4}ms] Attempt {}: ✅ Completed quickly!",
                            elapsed, attempt
                        );
                        Ok("Success on attempt 3".to_string())
                    }
                }
            })
            .await
    };

    let total_time = start.elapsed().as_millis();
    println!("\n   Result: {:?}", result.unwrap());
    println!("   Total time: {}ms", total_time);
    println!("   Total attempts: {}", attempt_count.load(Ordering::SeqCst));
    println!("\n   💡 Each attempt had its own timeout; operation succeeded on 3rd try");
}

async fn pattern2_circuit_retry() {
    println!("📌 Pattern 2: CircuitBreaker wrapping Retry");
    println!("   Wrap::new(CircuitBreaker(3, 1s), Retry(2, 50ms))");
    println!("   → Retries happen inside the circuit breaker\n");

    let policy = Wrap::new(
        CircuitBreaker::new(3, Duration::from_secs(1)),
        RetryPolicy::fixed(2, Duration::from_millis(50)),
    );

    let failure_count = Arc::new(AtomicUsize::new(0));
    let start = Instant::now();

    // Make several calls that fail to open the circuit
    println!("   Phase 1: Failing calls to open circuit");
    for i in 1..=4 {
        let fc = Arc::clone(&failure_count);
        let s = start;
        let result: Result<String, DoOverError<String>> = policy
            .execute(|| {
                let count = Arc::clone(&fc);
                async move {
                    count.fetch_add(1, Ordering::SeqCst);
                    let elapsed = s.elapsed().as_millis();
                    println!(
                        "   [+{:>4}ms] Call {}: Inner operation failing...",
                        elapsed, i
                    );
                    Err(DoOverError::Inner(format!("Service error")))
                }
            })
            .await;

        let elapsed = start.elapsed().as_millis();
        match &result {
            Err(DoOverError::Inner(_)) => {
                println!(
                    "   [+{:>4}ms] Call {}: ❌ Failed after retries",
                    elapsed, i
                );
            }
            Err(DoOverError::CircuitOpen) => {
                println!(
                    "   [+{:>4}ms] Call {}: 🚫 Circuit is OPEN",
                    elapsed, i
                );
            }
            _ => {}
        }
    }

    let inner_calls = failure_count.load(Ordering::SeqCst);
    println!("\n   Summary:");
    println!("   - Inner operation calls: {} (includes retries)", inner_calls);
    println!("   - Circuit opened after threshold reached");
    println!("\n   💡 Retries happened inside circuit breaker; failures accumulated to open circuit");
}

async fn pattern3_full_stack() {
    println!("📌 Pattern 3: Full Resilience Stack");
    println!("   Bulkhead(2) → Retry(2, 100ms) → Timeout(500ms)");
    println!("   Recommended ordering for production systems\n");

    // Note: Using Bulkhead + Retry + Timeout for this example to avoid
    // CircuitBreaker clone issues in concurrent async context
    let policy = Arc::new(Wrap::new(
        Bulkhead::new(2),
        Wrap::new(
            RetryPolicy::fixed(2, Duration::from_millis(100)),
            TimeoutPolicy::new(Duration::from_millis(500)),
        ),
    ));

    let call_count = Arc::new(AtomicUsize::new(0));
    let start = Instant::now();

    println!("   Launching 4 concurrent requests (bulkhead limit is 2)...\n");

    let mut handles = vec![];
    for i in 1..=4 {
        let p = Arc::clone(&policy);
        let cc = Arc::clone(&call_count);
        let s = start;

        let handle = tokio::spawn(async move {
            let result: Result<String, DoOverError<String>> = p
                .execute(|| {
                    let count = Arc::clone(&cc);
                    async move {
                        let call = count.fetch_add(1, Ordering::SeqCst) + 1;
                        let elapsed = s.elapsed().as_millis();
                        println!(
                            "   [+{:>4}ms] Request {}, call {}: Processing...",
                            elapsed, i, call
                        );
                        tokio::time::sleep(Duration::from_millis(200)).await;
                        let elapsed = s.elapsed().as_millis();
                        println!(
                            "   [+{:>4}ms] Request {}, call {}: ✅ Done",
                            elapsed, i, call
                        );
                        Ok(format!("Response {}", i))
                    }
                })
                .await;

            let elapsed = s.elapsed().as_millis();
            match &result {
                Ok(msg) => println!("   [+{:>4}ms] Request {}: ✅ {}", elapsed, i, msg),
                Err(DoOverError::BulkheadFull) => {
                    println!("   [+{:>4}ms] Request {}: 🚫 Rejected by bulkhead", elapsed, i)
                }
                Err(e) => println!("   [+{:>4}ms] Request {}: ❌ {:?}", elapsed, i, e),
            }
        });
        handles.push(handle);

        tokio::time::sleep(Duration::from_millis(10)).await;
    }

    for handle in handles {
        handle.await.unwrap();
    }

    let total_time = start.elapsed().as_millis();
    let total_calls = call_count.load(Ordering::SeqCst);

    println!("\n   Summary:");
    println!("   - Total inner operation calls: {}", total_calls);
    println!("   - Total time: {}ms", total_time);
    println!("\n   Policy execution order:");
    println!("   1. Bulkhead: Limits to 2 concurrent executions");
    println!("   2. Retry: Retries transient failures");
    println!("   3. Timeout: Each attempt bounded to 500ms");
}

Trait Implementations

impl<O: Clone, I: Clone> Clone for Wrap<O, I>

fn clone(&self) -> Wrap<O, I>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<O, I, E> Policy<E> for Wrap<O, I>

where O: Policy<E>, I: Policy<E>, E: Send + Sync,

fn execute<'life0, 'async_trait, F, Fut, T>( &'life0 self, f: F, ) -> Pin<Box<dyn Future<Output = Result<T, E>> + Send + 'async_trait>>

where F: Fn() -> Fut + Send + Sync + 'async_trait, Fut: Future<Output = Result<T, E>> + Send + 'async_trait, T: Send + 'async_trait, Self: 'async_trait, 'life0: 'async_trait,

Execute an async operation with this policy’s resilience behavior.