Struct CircuitBreaker 

pub struct CircuitBreaker { /* private fields */ }

Circuit breaker guarding a fallible operation.

Guarantees

• Opens after threshold consecutive failures
• Transitions to HalfOpen after recovery_window has elapsed
• Closes on the first successful probe in HalfOpen

Implementations

impl CircuitBreaker

pub fn new( service: impl Into<String>, threshold: u32, recovery_window: Duration, ) -> Result<Self, AgentRuntimeError>

Create a new circuit breaker backed by an in-memory backend.

Arguments

• service — name used in error messages and logs
• threshold — consecutive failures before opening
• recovery_window — how long to stay open before probing

pub fn with_backend(self, backend: Arc<dyn CircuitBreakerBackend>) -> Self

Replace the default in-memory backend with a custom one.

Useful for sharing circuit breaker state across processes.

pub fn call<T, E, F>(&self, f: F) -> Result<T, AgentRuntimeError>

where F: FnOnce() -> Result<T, E>, E: Display,

Attempt to call f, respecting the circuit breaker state.

Errors

• AgentRuntimeError::CircuitOpen — the breaker is in the Open state and the recovery window has not yet elapsed
• AgentRuntimeError::Orchestration — f returned an error; the error message is the Display of the inner error. This call may open the breaker if it pushes the consecutive failure count above threshold.

pub fn state(&self) -> Result<CircuitState, AgentRuntimeError>

Return the current circuit state.

pub fn failure_count(&self) -> Result<u32, AgentRuntimeError>

Return the consecutive failure count.

pub fn record_success(&self)

Record a successful call, resetting the consecutive failure counter.

Call this when a protected operation succeeds so the circuit can transition back to Closed after a HalfOpen probe.

pub fn record_failure(&self)

Record a failed call, incrementing the consecutive failure counter.

Opens the circuit when the failure count reaches threshold.

pub fn service_name(&self) -> &str

Return the service name this circuit breaker is protecting.

pub fn is_closed(&self) -> bool

Return true if the circuit is currently Closed (healthy).

pub fn is_open(&self) -> bool

Return true if the circuit is currently Open (fast-failing).

pub fn is_half_open(&self) -> bool

Return true if the circuit is currently HalfOpen (probing).

pub fn is_healthy(&self) -> bool

Return true if the circuit is in a state that allows calls to proceed.

Calls are allowed in both Closed and HalfOpen states; only Open fast-fails.

pub fn threshold(&self) -> u32

Return the configured consecutive-failure threshold.

The circuit opens when failure_count() reaches this value.

pub fn failure_headroom(&self) -> u32

Return how many more failures can be recorded before the circuit opens.

Returns 0 when the circuit is already open or at the threshold. Useful for alerting logic that needs to know how close the system is to being cut off.

pub fn failure_rate(&self) -> f64

Return the current failure count as a ratio of the threshold.

Returns a value in [0.0, 1.0] where 1.0 (or greater) means the circuit will open (or is already open). Returns 0.0 when the threshold is zero to avoid division by zero.

pub fn is_at_threshold(&self) -> bool

Return true when failure_count() has reached the configured threshold.

The circuit opens immediately when this returns true on the next record_failure call.

pub fn failures_until_open(&self) -> u32

Return the number of additional failures needed to open the circuit.

Returns 0 when the circuit is already at or beyond threshold.

pub fn recovery_window(&self) -> Duration

Return the configured recovery window duration.

After the circuit has been Open for this long, it transitions to HalfOpen and allows the next call through as a recovery probe.

pub fn reset(&self)

Force the circuit back to Closed state, resetting all failure counters.

Useful for tests and manual operator recovery. Under normal operation the circuit closes automatically after a successful HalfOpen probe.

pub fn describe(&self) -> Result<String, AgentRuntimeError>

Return a human-readable one-line summary of the circuit breaker state.

Format: "service='<name>' state=<State> failures=<n>/<threshold>".

Errors

Propagates any error returned by state or failure_count.

pub async fn async_call<T, E, F, Fut>( &self, backend: &dyn AsyncCircuitBreakerBackend, f: F, ) -> Result<T, AgentRuntimeError>

where F: FnOnce() -> Fut, Fut: Future<Output = Result<T, E>>, E: Display,

Execute an async fallible operation under the circuit breaker using an AsyncCircuitBreakerBackend.

This is the async counterpart of call and is intended for backends that perform genuine async I/O (e.g. Redis, etcd, distributed stores). The in-process default can be used via InMemoryCircuitBreakerBackend which trivially implements AsyncCircuitBreakerBackend.

Trait Implementations

impl Clone for CircuitBreaker

fn clone(&self) -> CircuitBreaker

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CircuitBreaker

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.