Struct Retry

pub struct Retry<B: Backoff, T, E, Fut: Future<Output = Result<T, E>>, FutureFn: FnMut() -> Fut, SF: MaybeSleeper = DefaultSleeper, RF = fn(&E) -> bool, NF = fn(&E, Duration), AF = fn(&E, Option<Duration>) -> Option<Duration>> { /* private fields */ }

Struct generated by Retryable.

Implementations

impl<B, T, E, Fut, FutureFn, SF, RF, NF, AF> Retry<B, T, E, Fut, FutureFn, SF, RF, NF, AF>

where B: Backoff, Fut: Future<Output = Result<T, E>>, FutureFn: FnMut() -> Fut, SF: MaybeSleeper, RF: FnMut(&E) -> bool, NF: FnMut(&E, Duration), AF: FnMut(&E, Option<Duration>) -> Option<Duration>,

pub fn sleep<SN: Sleeper>( self, sleep_fn: SN, ) -> Retry<B, T, E, Fut, FutureFn, SN, RF, NF, AF>

Set the sleeper for retrying.

The sleeper should implement the Sleeper trait. The simplest way is to use a closure that returns a Future<Output=()>.

If not specified, we use the DefaultSleeper.

use std::future::ready;

use anyhow::Result;
use backon::ExponentialBuilder;
use backon::Retryable;

async fn fetch() -> Result<String> {
    Ok(reqwest::get("https://www.rust-lang.org")
        .await?
        .text()
        .await?)
}

#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<()> {
    let content = fetch
        .retry(ExponentialBuilder::default())
        .sleep(|_| ready(()))
        .await?;
    println!("fetch succeeded: {}", content);

    Ok(())
}

pub fn when<RN: FnMut(&E) -> bool>( self, retryable: RN, ) -> Retry<B, T, E, Fut, FutureFn, SF, RN, NF, AF>

Set the conditions for retrying.

If not specified, all errors are considered retryable.

Examples

use anyhow::Result;
use backon::ExponentialBuilder;
use backon::Retryable;

async fn fetch() -> Result<String> {
    Ok(reqwest::get("https://www.rust-lang.org")
        .await?
        .text()
        .await?)
}

#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<()> {
    let content = fetch
        .retry(ExponentialBuilder::default())
        .when(|e| e.to_string() == "EOF")
        .await?;
    println!("fetch succeeded: {}", content);

    Ok(())
}

pub fn notify<NN: FnMut(&E, Duration)>( self, notify: NN, ) -> Retry<B, T, E, Fut, FutureFn, SF, RF, NN, AF>

Set to notify for all retry attempts.

When a retry happens, the input function will be invoked with the error and the sleep duration before pausing.

If not specified, this operation does nothing.

Examples

use core::time::Duration;

use anyhow::Result;
use backon::ExponentialBuilder;
use backon::Retryable;

async fn fetch() -> Result<String> {
    Ok(reqwest::get("https://www.rust-lang.org")
        .await?
        .text()
        .await?)
}

#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<()> {
    let content = fetch
        .retry(ExponentialBuilder::default())
        .notify(|err: &anyhow::Error, dur: Duration| {
            println!("retrying error {:?} with sleeping {:?}", err, dur);
        })
        .await?;
    println!("fetch succeeded: {}", content);

    Ok(())
}

pub fn adjust<NAF: FnMut(&E, Option<Duration>) -> Option<Duration>>( self, adjust: NAF, ) -> Retry<B, T, E, Fut, FutureFn, SF, RF, NF, NAF>

Sets the function to adjust the backoff duration for retry attempts.

When a retry occurs, the provided function will be called with the error and the proposed backoff duration, allowing you to modify the final duration used.

If the function returns None, it indicates that no further retries should be made, and the error will be returned regardless of the backoff duration provided by the input.

If no adjust function is specified, the original backoff duration from the input will be used without modification.

adjust can be used to implement dynamic backoff strategies, such as adjust backoff values from the http Retry-After headers.

Examples

use core::time::Duration;
use std::error::Error;
use std::fmt::Display;
use std::fmt::Formatter;

use anyhow::Result;
use backon::ExponentialBuilder;
use backon::Retryable;
use reqwest::header::HeaderMap;
use reqwest::StatusCode;

#[derive(Debug)]
struct HttpError {
    headers: HeaderMap,
}

impl Display for HttpError {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        write!(f, "http error")
    }
}

impl Error for HttpError {}

async fn fetch() -> Result<String> {
    let resp = reqwest::get("https://www.rust-lang.org").await?;
    if resp.status() != StatusCode::OK {
        let source = HttpError {
            headers: resp.headers().clone(),
        };
        return Err(anyhow::Error::new(source));
    }
    Ok(resp.text().await?)
}

#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<()> {
    let content = fetch
        .retry(ExponentialBuilder::default())
        .adjust(|err, dur| {
            match err.downcast_ref::<HttpError>() {
                Some(v) => {
                    if let Some(retry_after) = v.headers.get("Retry-After") {
                        // Parse the Retry-After header and adjust the backoff duration
                        let retry_after = retry_after.to_str().unwrap_or("0");
                        let retry_after = retry_after.parse::<u64>().unwrap_or(0);
                        Some(Duration::from_secs(retry_after))
                    } else {
                        dur
                    }
                }
                None => dur,
            }
        })
        .await?;
    println!("fetch succeeded: {}", content);

    Ok(())
}

Trait Implementations

impl<B, T, E, Fut, FutureFn, SF, RF, NF, AF> Future for Retry<B, T, E, Fut, FutureFn, SF, RF, NF, AF>

where B: Backoff, Fut: Future<Output = Result<T, E>>, FutureFn: FnMut() -> Fut, SF: Sleeper, RF: FnMut(&E) -> bool, NF: FnMut(&E, Duration), AF: FnMut(&E, Option<Duration>) -> Option<Duration>,

type Output = Result<T, E>

The type of value produced on completion.

fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>

Attempts to resolve the future to a final value, registering the current task for wakeup if the value is not yet available.