mulligan 0.6.0

A flexible retry library for Rust async operations with configurable backoff strategies and jitter.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

use log::{debug, error, info, warn};
use std::time::Duration;

/// This example demonstrates using mulligan to retry HTTP requests to httpbin.org
///
/// It shows several scenarios:
/// 1. Retrying a request that always fails (status endpoint)
/// 2. Retrying until we get a successful response
/// 3. Custom retry conditions based on HTTP status codes
/// 4. Reusing a reqwest::Client across multiple retries by capturing it in closures
///
/// Note: httpbin's `/status/:code` endpoint returns the specified HTTP status code
///
/// Run with: cargo run --example reqwest
/// For more verbose output: RUST_LOG=debug cargo run --example reqwest
/// For minimal output: RUST_LOG=warn cargo run --example reqwest
async fn fetch_with_status(
    client: &reqwest::Client,
    status_code: u16,
) -> Result<reqwest::Response, reqwest::Error> {
    let url = format!("https://httpbin.org/status/{}", status_code);
    debug!("Requesting: {}", url);
    client.get(&url).send().await
}

async fn fetch_json(client: &reqwest::Client) -> Result<serde_json::Value, reqwest::Error> {
    debug!("Requesting: https://httpbin.org/json");
    let response = client.get("https://httpbin.org/json").send().await?;
    let json = response.json::<serde_json::Value>().await?;
    Ok(json)
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    env_logger::builder()
        .filter_level(log::LevelFilter::Info)
        .parse_default_env()
        .init();

    // Create a single client to reuse across all requests
    let client = reqwest::Client::new();

    info!("Example 1: Retry a failing request (503 Service Unavailable)");

    let result = mulligan::until_ok()
        .stop_after(5)
        .max_delay(Duration::from_secs(3))
        .exponential(Duration::from_millis(500))
        .full_jitter()
        .after_attempt(|res, attempt| {
            if let Err(e) = res {
                debug!("Attempt {} failed: {}", attempt + 1, e);
            }
        })
        .execute(async || fetch_with_status(&client, 503).await)
        .await;

    match result {
        Ok(response) => info!("Success with status: {}", response.status()),
        Err(e) => warn!("Failed after all retries: {}", e),
    }

    info!("Example 2: Retry until successful (200 OK)");

    let result = mulligan::until_ok()
        .stop_after(3)
        .fixed(Duration::from_millis(500))
        .equal_jitter()
        .execute(async || fetch_with_status(&client, 200).await)
        .await;

    match result {
        Ok(response) => info!("Success with status: {}", response.status()),
        Err(e) => error!("Failed: {}", e),
    }

    info!("Example 3: Custom retry condition (retry only on 5xx errors)");

    let result = mulligan::until(
        |res: &Result<reqwest::Response, reqwest::Error>| match res {
            Ok(response) => {
                let status = response.status();
                !status.is_server_error()
            }
            Err(_) => false,
        },
    )
    .stop_after(4)
    .linear(Duration::from_millis(300))
    .full_jitter()
    .after_attempt(|res, attempt| match res {
        Ok(response) => {
            let status = response.status();
            if status.is_server_error() {
                debug!(
                    "Attempt {}: Got 5xx error ({}), retrying...",
                    attempt + 1,
                    status
                );
            }
        }
        Err(e) => debug!("Attempt {}: Network error: {}", attempt + 1, e),
    })
    .execute(async || fetch_with_status(&client, 500).await)
    .await;

    match result {
        Ok(response) => info!("Final status: {}", response.status()),
        Err(e) => warn!("Failed: {}", e),
    }

    info!("Example 4: Fetching JSON with retry");

    let result = mulligan::until_ok()
        .stop_after(3)
        .exponential(Duration::from_millis(200))
        .decorrelated_jitter(Duration::from_millis(100))
        .max_delay(Duration::from_secs(2))
        .execute(async || fetch_json(&client).await)
        .await;

    match result {
        Ok(json) => info!(
            "Successfully fetched JSON: {}",
            serde_json::to_string_pretty(&json)?
        ),
        Err(e) => error!("Failed to fetch JSON: {}", e),
    }

    Ok(())
}