relentless

Retry and polling for Rust — with composable strategies, policy reuse, and first-class support for polling workflows where Ok(_) doesn't always mean "done."

Most retry libraries handle the simple case well: call a function, retry on error, back off. relentless handles that too, but it also handles the cases those libraries make awkward:

• Polling, where Ok("pending") means "keep going" and you need .until(predicate::ok(...)) rather than just retrying errors.
• Policy reuse, where a single RetryPolicy captures your retry rules and gets shared across multiple call sites — no duplicated builder chains.
• Strategy composition, where wait::fixed(50ms) + wait::exponential(100ms) and stop::attempts(5) | stop::elapsed(2s) express complex behavior in one line.
• Hooks and stats, where you observe the retry lifecycle (logging, metrics) without restructuring your retry logic.

All of this works in sync and async code, across std, no_std, and wasm targets.

Inspired by Python's tenacity (composable strategy algebra) and Rust's backon (ergonomic retry builders).

Install

cargo add relentless

Feature flags

Async retry does not require alloc.

Examples

For full docs, see https://docs.rs/relentless. Behavior spec: docs/SPEC.md. Runnable examples live in examples/.

Sync examples omit .sleep(...) because std builds fall back to std::thread::sleep automatically. Without std, pass an explicit sleeper before .call().

1) Retry with defaults

The .retry() extension trait is the fastest way to add retries. Defaults: 3 attempts, exponential backoff from 100 ms, retry on any Err.

use relentless::RetryExt;

fn fetch_job_output() -> Result<String, std::io::Error> {
    std::fs::read_to_string("/var/run/background_job.output")
}

let results = fetch_job_output.retry().call();

2) Customized retry

The retry free function is equivalent to the extension trait, with the added ability to capture retry loop state. Both the free function and extension trait give full control over which errors to retry, how long to wait, and when to stop.

use core::time::Duration;
use relentless::{Wait, retry, predicate, stop, wait};

let body = retry(|state| {
    println!("attempt {}", state.attempt);
    reqwest::blocking::get("https://api.example.com/data")?.text()
})
.when(predicate::error(|e: &reqwest::Error| e.is_timeout()))
.wait(
    wait::exponential(Duration::from_millis(200))
        .full_jitter()
        .cap(Duration::from_secs(5)),
)
.stop(stop::attempts(10))
.timeout(Duration::from_secs(30))
.call();

3) Reuse a policy across call sites

RetryPolicy captures retry rules once. Compose wait strategies with + and stop strategies with | or &.

use core::time::Duration;
use relentless::{RetryPolicy, stop, wait};

fn check_health() -> Result<String, std::io::Error> { todo!() }
fn fetch_invoice(id: &str) -> Result<String, std::io::Error> { todo!() }

let policy = RetryPolicy::new()
    .wait(
        wait::fixed(Duration::from_millis(50))
            + wait::exponential(Duration::from_millis(100)),
    )
    .stop(stop::attempts(5) | stop::elapsed(Duration::from_secs(30)));

// Same policy, different operations.
let health = policy.retry(|_| check_health()).call();
let invoice = policy.retry(|_| fetch_invoice("inv_123")).call();

4) Poll for a condition

Use .until(predicate) to keep retrying until a success condition is met. Unlike .when(), which retries on matching outcomes, .until() retries on everything except the matching outcome.

use relentless::{RetryPolicy, predicate};

#[derive(Debug, PartialEq)]
enum Status { Pending, Done }

fn poll_status() -> Result<Status, std::io::Error> { todo!() }

let result = RetryPolicy::new()
    .until(predicate::ok(|s: &Status| *s == Status::Done))
    .retry(|_| poll_status())
    .call();

To also retry selected errors during polling, use predicate::result:

use relentless::{RetryPolicy, predicate};

#[derive(Debug)]
enum Status { Pending, Done }
#[derive(Debug)]
enum Error { Retryable, Fatal }

fn poll_job() -> Result<Status, Error> { todo!() }

// Retry until Done or Fatal; keep going on Pending or Retryable.
let result = RetryPolicy::new()
    .until(predicate::result(|outcome: &Result<Status, Error>| {
        matches!(outcome, Ok(Status::Done) | Err(Error::Fatal))
    }))
    .retry(|_| poll_job())
    .call();

5) Async retry

Pass an async sleep adapter — here via the tokio-sleep feature.

use relentless::retry_async;

async fn fetch(url: &str) -> Result<String, reqwest::Error> {
    reqwest::get(url).await?.text().await
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let body = retry_async(|_| fetch("https://api.example.com/data"))
        .sleep(relentless::sleep::tokio())
        .call()
        .await?;
    Ok(())
}

More

Full inline code for these lives in the API docs, with runnable versions in examples/:

• Hooks & stats — observe the retry lifecycle for logging or metrics with .before_attempt / .after_attempt, and collect a RetryStats summary via .with_stats(). (hooks-and-stats.rs)
• Error handling — on failure you get a RetryError: Exhausted { last } when the stop strategy fired (last is the final attempt's full Result<T, E> — polling can exhaust while the last outcome was still Ok), or Rejected { last } when a predicate deemed the error non-retryable (last is that error itself).
• Deterministic testing — the test-util feature's VirtualClock asserts the exact backoff schedule with zero wall-clock time spent, so timeout and backoff tests stay fast and non-flaky. (testing-with-virtual-clock.rs)
• Cancellation — there is no built-in cancel primitive; the loop observes the cancellation your environment already provides (a dropped future, an AtomicBool, .timeout(...)) at attempt boundaries. (sync-cancel.rs, async-cancel.rs)

How the builders fit together

The full API surface — every strategy, predicate, and type — lives on docs.rs. Two things worth knowing up front:

Builder chains read best in this order: when/until -> wait -> stop -> sleep -> hooks -> stats -> call. That order is a reading convention, not a compiler contract — the types enforce only three rules: strategy overrides (when/until/wait/stop) exist only on builders that own their policy (below), everything is configured before .with_stats(), and an async chain needs .sleep(...) before .call().

Where you start decides what you can override. The free-function and extension-trait builders own their policy, so they accept the strategy overrides when/until/wait/stop. An execution started from a shared RetryPolicy (policy.retry(...)) keeps that policy's strategies fixed and accepts only sleep, hooks, timing, and stats methods.

MSRV

Minimum supported Rust version: 1.85.

Contributing

See CONTRIBUTING.md.

Release notes

For user-facing changes, see the changelog.

License

Licensed under either:

• MIT (LICENSE-MIT)
• Apache-2.0 (LICENSE-APACHE)