failsafe 1.3.0

A FailurePredicate<ERROR> is used to determine if a specific error should be recorded as a failure, which in turn increases the failure rate used by the failsafe mechanism.

You can implement this in two ways:

1. Using a closure or function: Any function with the signature Fn(&ERROR) -> bool automatically implements FailurePredicate.
2. Implementing the trait: Define a struct and implement the is_err(&self, err: &ERROR) -> bool method.

If you want every error to be treated as a failure regardless of its content, use the built-in Any struct.

// Option 1: Using a closure
let my_predicate = |err: &MyError| err.is_critical();

// Option 2: Using the Any predicate (always returns true)
let always_fail = Any;

// Option 3: Implementing the trait manually
struct MyPredicate;
impl FailurePredicate<MyError> for MyPredicate {
    fn is_err(&self, err: &MyError) -> bool {
        err.code == 500
    }
}

When you call .call() or .call_with(), you receive a ResponseFuture. This future manages the lifecycle of the wrapped operation:

1. Permission Check: Upon the first poll, the ResponseFuture checks is_call_permitted(). If the circuit is open, it immediately returns Poll::Ready(Err(Error::Rejected)).
2. Execution: If permitted, it polls the underlying TryFuture.
3. Outcome Recording:
   • Success: If the inner future returns Ok, the circuit breaker records a success via on_success().
   • Failure: If the inner future returns Err and the provided FailurePredicate identifies it as a failure, the circuit breaker records a failure via on_error(). If the predicate identifies the error as non-critical, it records a success instead.

This ensures that the circuit breaker's state (open/closed/half-open) is updated automatically based on the real-time results of the asynchronous tasks.

A CircuitBreaker detects failures and encapsulates the logic to prevent them from constantly recurring during maintenance or external system outages. You can use it to wrap functions that might fail. When the failure threshold is met, the circuit breaker enters an 'open' state and rejects subsequent calls with Error::Rejected until the backoff period expires.

By default, Config::new().build() provides a circuit breaker with a reasonable default backoff and failure accrual policy.

use rand::{thread_rng, Rng};
use failsafe::{Config, CircuitBreaker, Error};

// A function that sometimes fails.
fn dangerous_call() -> Result<(), ()> {
  if thread_rng().gen_range(0..2) == 0 {
    return Err(())
  }
  Ok(())
}

// Create a circuit breaker with default backoff and failure accrual policy.
let circuit_breaker = Config::new().build();

// Call the function in a loop. After some iterations, the circuit breaker 
// will be in an open state and reject next calls.
for n in 0..100 {
  match circuit_breaker.call(|| dangerous_call()) {
    Err(Error::Inner(_)) => {
      eprintln!("{}: fail", n);
    },
    Err(Error::Rejected) => {
       eprintln!("{}: rejected", n);
       break;
    },
    _ => {}
  }
}

You can customize the circuit breaker's behavior by providing a specific failure_policy to the Config builder. A policy typically combines a failure detection strategy with a backoff strategy.

• Backoff strategies: constant, exponential, equal_jittered, full_jittered.
• Failure detection policies: consecutive_failures, success_rate_over_time_window.

Example of configuring an exponential backoff and a consecutive failure policy:

use std::time::Duration;
use failsafe::{backoff, failure_policy, CircuitBreaker};

// Create an exponential growth backoff which starts from 10s and ends with 60s.
let backoff = backoff::exponential(Duration::from_secs(10), Duration::from_secs(60));

// Create a policy which failed when three consecutive failures were made.
let policy = failure_policy::consecutive_failures(3, backoff);

// Creates a circuit breaker with given policy.
let circuit_breaker = Config::new()
  .failure_policy(policy)
  .build();

You can create a circuit breaker with reasonable default backoff and failure accrual policies using Config::new().build(). Use the .call() method to wrap functions that might fail. If the circuit breaker is in an 'open' state (preventing calls to protect the system), it will return Err(Error::Rejected). If the wrapped function fails, it returns Err(Error::Inner(e)).

use failsafe::{Config, CircuitBreaker, Error};

// A function that sometimes failed.
fn dangerous_call() -> Result<(), ()> {
  if thread_rng().gen_range(0, 2) == 0 {
    return Err(())
  }
  Ok(())
}

// Create a circuit breaker which configured by reasonable default backoff and
// failure accrual policy.
let circuit_breaker = Config::new().build();

// Call the function in a loop, after some iterations the circuit breaker will
// be in a open state and reject next calls.
for n in 0..100 {
  match circuit_breaker.call(|| dangerous_call()) {
    Err(Error::Inner(_)) => {
      eprintln!("{}: fail", n);
    },
    Err(Error::Rejected) => {
       eprintln!("{}: rejected", n);
       break;
    },
    _ => {}
  }
}

You can customize how a CircuitBreaker behaves by providing a custom FailurePolicy. A policy typically combines a failure detection strategy (like consecutive failures) with a backoff strategy (how long to wait before attempting to close the circuit again).

Common components include:

• backoff::exponential: Creates an exponential growth backoff starting from a minimum duration up to a maximum duration.
• failure_policy::consecutive_failures: Creates a policy that triggers when a specific number of consecutive failures occur.

use std::time::Duration;
use failsafe::{backoff, failure_policy, Config, CircuitBreaker};

fn circuit_breaker() -> impl CircuitBreaker {
  // Create an exponential growth backoff which starts from 10s and ends with 60s.
  let backoff = backoff::exponential(Duration::from_secs(10), Duration::from_secs(60));

  // Create a policy which failed when three consecutive failures were made.
  let policy = failure_policy::consecutive_failures(3, backoff);

  // Creates a circuit breaker with given policy.
  Config::new()
    .failure_policy(policy)
    .build()
}