tokio_prompt_orchestrator::enhanced::circuit_breaker

Struct CircuitBreaker

pub struct CircuitBreaker { /* private fields */ }

Expand description

A circuit breaker that prevents cascading failures by stopping requests to a failing downstream service.

§State machine

Closed ──(failures ≥ threshold)──► Open
  ▲                                  │
  │                                  │ (timeout elapsed)
  │                                  ▼
  └──(success_rate ≥ threshold)── HalfOpen

Closed — normal operation; all requests flow through.
Open — all requests are rejected immediately with CircuitBreakerError::Open without calling the wrapped operation.
HalfOpen — a single probe request is allowed; on success the circuit closes; on failure it reopens.

§Cloning

CircuitBreaker is Clone + Send + Sync. All clones share the same underlying Arc<RwLock<CircuitState>>.

§Examples

use std::time::Duration;
use tokio_prompt_orchestrator::enhanced::CircuitBreaker;
use tokio_prompt_orchestrator::enhanced::circuit_breaker::CircuitBreakerError;

let cb = CircuitBreaker::new(5, 0.8, Duration::from_secs(30));

let result = cb.call(|| async {
    reqwest::get("https://api.example.com/infer")
        .await
        .map_err(|e| e.to_string())
}).await;

match result {
    Ok(resp) => { /* handle response */ }
    Err(CircuitBreakerError::Open) => { /* fail fast */ }
    Err(CircuitBreakerError::Failed(e)) => { /* handle error */ }
}

Implementations§

Source §

impl CircuitBreaker

Source

pub fn new( failure_threshold: usize, success_threshold: f64, timeout: Duration, ) -> Self

Create a new CircuitBreaker in the Closed state.

§Arguments

failure_threshold — Number of consecutive failures required to open the circuit. A value of 1 opens immediately on the first error.
success_threshold — Required success rate (0.0..=1.0) over the recent-results window before the circuit closes from HalfOpen. Typical values: 0.8 (80 %) or 1.0 (100 %).
timeout — How long to stay in the Open state before transitioning to HalfOpen and allowing one probe request through.

The default rolling-window size is 100 results. Use with_window_size to customise it.

§Examples

use std::time::Duration;
use tokio_prompt_orchestrator::enhanced::CircuitBreaker;

// Open after 5 failures; require 80 % success rate to close; probe after 60 s.
let cb = CircuitBreaker::new(5, 0.8, Duration::from_secs(60));

Source

pub fn with_window_size(self, size: usize) -> Self

Set the rolling-window size used to calculate the success rate.

The window keeps the most recent size call outcomes. A smaller window reacts faster to bursts of failures but is more sensitive to noise. The default is 100.

§Examples

use std::time::Duration;
use tokio_prompt_orchestrator::enhanced::CircuitBreaker;

// Tighter window — reacts faster to short failure bursts.
let cb = CircuitBreaker::new(5, 0.8, Duration::from_secs(30))
    .with_window_size(20);

§Panics

This function does not panic.

Source

pub async fn call<F, Fut, T, E>( &self, f: F, ) -> Result<T, CircuitBreakerError<E>>
where F: FnOnce() -> Fut, Fut: Future<Output = Result<T, E>>,

Execute a fallible async operation through the circuit breaker.

If the circuit is Open the operation is not called and Err(CircuitBreakerError::Open) is returned immediately. Otherwise the closure is invoked; its Ok/Err outcome is recorded and may cause a state transition.

§Arguments

f — A FnOnce that returns a Future<Output = Result<T, E>>. The closure is called at most once per call invocation.

§Returns

Ok(value) — operation succeeded.
Err(CircuitBreakerError::Open) — circuit is open; request rejected.
Err(CircuitBreakerError::Failed(e)) — operation returned Err(e).

§Examples

use std::time::Duration;
use tokio_prompt_orchestrator::enhanced::CircuitBreaker;
use tokio_prompt_orchestrator::enhanced::circuit_breaker::CircuitBreakerError;

let cb = CircuitBreaker::new(3, 0.8, Duration::from_secs(10));
let result = cb.call(|| async { Ok::<_, String>("ok") }).await;
assert!(matches!(result, Ok("ok")));