retrying

General-purpose retrying library, written in Rust, to simplify the task of adding retry behavior to rust functions.
Support sync and async (tokio, async-std) functions.

[dependencies]
retrying = "0.1.0"

Macros

The main public interface in retrying is retrying::retry macros.

#[retrying::retry]
fn my_function(){}

This macros has a lot of configuration options and allows developers to write fault tolerant functions without thinking about implementation of retry functionality.
⚠️ The macros generates code and adds variables with prefix retrying_ into code. To avoid variable conflicts please don't use variables with this prefix in functions with retry macros.

Configuration option

• Stop

This section describes configuration options that specify when method execution should stop retrying.

It is possible to combine several stop conditions by using the or operator(|) operator. For example, configuration

#[retrying::retry(stop=(attempts(10)|delay(60.8)))]
fn my_function(){}

means the function should retry 10 times but doesn't make new attempt after 60 seconds.

If stop configuration is not specified then retry macros makes new attempts until function be finished without Err.

• Wait

This section describes configuration options that specify delay between each attempt.

Using only one wait option is possible.

• Retry

This section describes configuration options that specify retrying conditions.

Using only one retry option is possible.

Using OS environment variables for updating retry configuration

There are certain list of use cases when retry configuration requires updating configuration values in runtime. For example, It is useful when we need a different number of attempts per environment (dev, prod, stage), systems, unit tests etc.

Retrying allows overriding macros configuration in runtime using env variables with special configuration option envs_prefix like

#[retrying::retry(<retry configurations>,envs_prefix="test")]

⚠️ Limitations

• It is possible to override only configuration value, not configuration option. It means, for example, if configuration option stop=attempts(1)) is not defined in macros code then the OS env variable {PREFIX}__RETRYING__STOP__ATTEMPTS doesn't affect code execution. In other words, the OS environment variable can override only the value of the configured option and it is not able to change the option itself.
• Configuration option from the OS environment variable has a higher priority than options in source code.
• If OS environment variables are not set then macros uses the value from its configuration (source code).
• If OS environment variable has the wrong format (for example, non-numeric value is specified for numeric configuration) then retrying macros ignores such configuration, logs error in stderr and continues using values from code.

Example of usage:

#[retrying::retry(stop=attempts(2),envs_prefix="test")]

With above configuration macros checks in runtime the availability of OS env variable TEST__RETRYING__STOP__ATTEMPTS (case-insensitive) and if variable is set then number of retry attempt will be the value of TEST__RETRYING__STOP__ATTEMPTS. If the list of OS environment contains more than one configuration option with the same prefix then macros ignores OS env variable and take configuration value from code.

Features

tokio - builds retrying library for using with tokio asynchronous runtime. async_std - builds retrying library for using with async_std asynchronous runtime.

Examples

Examples are available in ./crates/retrying/example and can be tested using cargo. Sync:

cargo run --example sync

Async tokio:

cargo run --features="tokio" --example tokio

Async async-std:

cargo run --features="async_std" --example async_std

Understanding of macros

retrying::retry macros is not a magic and it only helps developers to avoid writing extra code. The resulting code depends on the provided configuration and may be changed in future releases. Examples of code generation:

#[retry(stop=(attempts(4)|duration(2)),wait=fixed(0.9))]
fn my_method(in_param: &str) -> Result<i32, ParseIntError> {
    in_param.parse::<i32>()
}

Generated code:

fn my_method(in_param: &str) -> Result<i32, ParseIntError> {
    let mut retrying_context = ::retrying::RetryingContext::new();
    use ::retrying::stop::Stop;
    let retrying_stop =
        ::retrying::stop::StopAttemptsOrDuration::new(4u32, 2f32);
    use ::retrying::wait::Wait;
    let retrying_wait = ::retrying::wait::WaitFixed::new(0.9f32);
    loop {
        match { in_param.parse::<i32>() } {
            Ok(result) => return Ok(result),
            Err(err) if !retrying_stop.stop_execution(&retrying_context) => {
                match err {
                    std::num::ParseIntError { .. } => (),
                    _ => break Err(err),
                };
                retrying_context.add_attempt();
                ::retrying::sleep_sync(retrying_wait.wait_duration(&retrying_context));
            }
            Err(err) => break Err(err),
        }
    }
}

It is possible to use cargo for checking generated code. For examples, below command shows generated code for all examples,

cd ./crates/retrying
cargo rustc --profile=check --examples -- -Zunpretty=expanded