breaker_machines 0.5.0 → 0.6.0

data/ext/breaker_machines_native/target/package/breaker-machines-0.5.0/src/circuit.rs

@@ -0,0 +1,607 @@
+//! Circuit breaker implementation using state machines
+//!
+//! This module provides a complete circuit breaker with state management.
+
+use crate::{callbacks::Callbacks, errors::CircuitError, StorageBackend};
+use state_machines::state_machine;
+use std::sync::Arc;
+
+/// Circuit breaker configuration
+#[derive(Debug, Clone, Copy)]
+pub struct Config {
+    /// Number of failures required to open the circuit
+    pub failure_threshold: usize,
+
+    /// Time window in seconds for counting failures
+    pub failure_window_secs: f64,
+
+    /// Timeout in seconds before transitioning from Open to HalfOpen
+    pub half_open_timeout_secs: f64,
+
+    /// Number of successes required in HalfOpen to close the circuit
+    pub success_threshold: usize,
+
+    /// Jitter factor for half_open_timeout (0.0 = no jitter, 1.0 = full jitter)
+    /// Uses chrono-machines formula: timeout * (1 - jitter + rand * jitter)
+    pub jitter_factor: f64,
+}
+
+impl Default for Config {
+    fn default() -> Self {
+        Self {
+            failure_threshold: 5,
+            failure_window_secs: 60.0,
+            half_open_timeout_secs: 30.0,
+            success_threshold: 2,
+            jitter_factor: 0.0,
+        }
+    }
+}
+
+/// Circuit breaker context - shared data across all states
+#[derive(Clone)]
+pub struct CircuitContext {
+    pub name: String,
+    pub config: Config,
+    pub storage: Arc<dyn StorageBackend>,
+}
+
+impl Default for CircuitContext {
+    fn default() -> Self {
+        Self {
+            name: String::new(),
+            config: Config::default(),
+            storage: Arc::new(crate::MemoryStorage::new()),
+        }
+    }
+}
+
+impl std::fmt::Debug for CircuitContext {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("CircuitContext")
+            .field("name", &self.name)
+            .field("config", &self.config)
+            .field("storage", &"<dyn StorageBackend>")
+            .finish()
+    }
+}
+
+/// Data specific to the Open state
+#[derive(Debug, Clone, Default)]
+pub struct OpenData {
+    pub opened_at: f64,
+}
+
+/// Data specific to the HalfOpen state
+#[derive(Debug, Clone, Default)]
+pub struct HalfOpenData {
+    pub consecutive_successes: usize,
+}
+
+// Define the circuit breaker state machine with dynamic mode
+state_machine! {
+    name: Circuit,
+    context: CircuitContext,
+    dynamic: true,  // Enable dynamic mode for runtime state transitions
+
+    initial: Closed,
+    states: [
+        Closed,
+        Open(OpenData),
+        HalfOpen(HalfOpenData),
+    ],
+    events {
+        trip {
+            guards: [should_open],
+            transition: { from: [Closed, HalfOpen], to: Open }
+        }
+        attempt_reset {
+            guards: [timeout_elapsed],
+            transition: { from: Open, to: HalfOpen }
+        }
+        close {
+            guards: [should_close],
+            transition: { from: HalfOpen, to: Closed }
+        }
+    }
+}
+
+// Guards for dynamic mode - implemented on typestate machines
+impl Circuit<Closed> {
+    /// Check if failure threshold is exceeded
+    fn should_open(&self, ctx: &CircuitContext) -> bool {
+        let failures = ctx
+            .storage
+            .failure_count(&ctx.name, ctx.config.failure_window_secs);
+        failures >= ctx.config.failure_threshold
+    }
+}
+
+impl Circuit<HalfOpen> {
+    /// Check if failure threshold is exceeded
+    fn should_open(&self, ctx: &CircuitContext) -> bool {
+        let failures = ctx
+            .storage
+            .failure_count(&ctx.name, ctx.config.failure_window_secs);
+        failures >= ctx.config.failure_threshold
+    }
+
+    /// Check if enough successes to close circuit
+    fn should_close(&self, ctx: &CircuitContext) -> bool {
+        let data = self
+            .state_data_half_open()
+            .expect("HalfOpen state must have data");
+        data.consecutive_successes >= ctx.config.success_threshold
+    }
+}
+
+impl Circuit<Open> {
+    /// Check if timeout has elapsed for Open -> HalfOpen transition
+    fn timeout_elapsed(&self, ctx: &CircuitContext) -> bool {
+        let data = self.state_data_open().expect("Open state must have data");
+        let current_time = ctx.storage.monotonic_time();
+        let elapsed = current_time - data.opened_at;
+
+        // Apply jitter using chrono-machines if jitter_factor > 0
+        let timeout_secs = if ctx.config.jitter_factor > 0.0 {
+            let policy = chrono_machines::Policy {
+                max_attempts: 1,
+                base_delay_ms: (ctx.config.half_open_timeout_secs * 1000.0) as u64,
+                multiplier: 1.0,
+                max_delay_ms: (ctx.config.half_open_timeout_secs * 1000.0) as u64,
+            };
+            let timeout_ms = policy.calculate_delay(1, ctx.config.jitter_factor);
+            (timeout_ms as f64) / 1000.0
+        } else {
+            ctx.config.half_open_timeout_secs
+        };
+
+        elapsed >= timeout_secs
+    }
+}
+
+/// Circuit breaker public API
+pub struct CircuitBreaker {
+    machine: DynamicCircuit,
+    context: CircuitContext,
+    callbacks: Callbacks,
+}
+
+impl CircuitBreaker {
+    /// Create a new circuit breaker (use builder() for more options)
+    pub fn new(name: String, config: Config) -> Self {
+        let storage = Arc::new(crate::MemoryStorage::new());
+        let context = CircuitContext {
+            name,
+            config,
+            storage,
+        };
+
+        let machine = DynamicCircuit::new(context.clone());
+        let callbacks = Callbacks::new();
+
+        Self {
+            machine,
+            context,
+            callbacks,
+        }
+    }
+
+    /// Create a circuit breaker with custom context and callbacks (used by builder)
+    pub(crate) fn with_context_and_callbacks(
+        context: CircuitContext,
+        callbacks: Callbacks,
+    ) -> Self {
+        let machine = DynamicCircuit::new(context.clone());
+
+        Self {
+            machine,
+            context,
+            callbacks,
+        }
+    }
+
+    /// Create a new circuit breaker builder
+    pub fn builder(name: impl Into<String>) -> crate::builder::CircuitBuilder {
+        crate::builder::CircuitBuilder::new(name)
+    }
+
+    /// Execute a fallible operation with circuit breaker protection
+    pub fn call<F, T, E>(&mut self, f: F) -> Result<T, CircuitError<E>>
+    where
+        F: FnOnce() -> Result<T, E>,
+    {
+        // Check for timeout-based Open -> HalfOpen transition
+        if self.machine.current_state() == "Open" {
+            let _ = self.machine.handle(CircuitEvent::AttemptReset);
+            if self.machine.current_state() == "HalfOpen" {
+                self.callbacks.trigger_half_open(&self.context.name);
+            }
+        }
+
+        // Handle based on current state
+        match self.machine.current_state() {
+            "Open" => {
+                let opened_at = self.machine.open_data().map(|d| d.opened_at).unwrap_or(0.0);
+                Err(CircuitError::Open {
+                    circuit: self.context.name.clone(),
+                    opened_at,
+                })
+            }
+            "HalfOpen" => {
+                // Check if we've reached the success threshold
+                if let Some(data) = self.machine.half_open_data() {
+                    if data.consecutive_successes >= self.context.config.success_threshold {
+                        return Err(CircuitError::HalfOpenLimitReached {
+                            circuit: self.context.name.clone(),
+                        });
+                    }
+                }
+                self.execute_call(f)
+            }
+            _ => self.execute_call(f),
+        }
+    }
+
+    fn execute_call<F, T, E>(&mut self, f: F) -> Result<T, CircuitError<E>>
+    where
+        F: FnOnce() -> Result<T, E>,
+    {
+        let start = self.context.storage.monotonic_time();
+
+        match f() {
+            Ok(val) => {
+                let duration = self.context.storage.monotonic_time() - start;
+                self.context
+                    .storage
+                    .record_success(&self.context.name, duration);
+
+                // Handle success in HalfOpen state
+                if self.machine.current_state() == "HalfOpen" {
+                    if let Some(data) = self.machine.half_open_data_mut() {
+                        data.consecutive_successes += 1;
+                    }
+
+                    // Try to close the circuit
+                    if self.machine.handle(CircuitEvent::Close).is_ok() {
+                        self.callbacks.trigger_close(&self.context.name);
+                    }
+                }
+
+                Ok(val)
+            }
+            Err(e) => {
+                let duration = self.context.storage.monotonic_time() - start;
+                self.context
+                    .storage
+                    .record_failure(&self.context.name, duration);
+
+                // Try to trip the circuit
+                let result = self.machine.handle(CircuitEvent::Trip);
+                if result.is_ok() {
+                    // Transition succeeded - update opened_at timestamp
+                    if let Some(data) = self.machine.open_data_mut() {
+                        data.opened_at = self.context.storage.monotonic_time();
+                    }
+                    self.callbacks.trigger_open(&self.context.name);
+                }
+
+                Err(CircuitError::Execution(e))
+            }
+        }
+    }
+
+    /// Record a successful operation (for manual tracking)
+    pub fn record_success(&self, duration: f64) {
+        self.context
+            .storage
+            .record_success(&self.context.name, duration);
+    }
+
+    /// Record a failed operation (for manual tracking)
+    pub fn record_failure(&self, duration: f64) {
+        self.context
+            .storage
+            .record_failure(&self.context.name, duration);
+    }
+
+    /// Check if circuit is open
+    pub fn is_open(&self) -> bool {
+        self.machine.current_state() == "Open"
+    }
+
+    /// Check if circuit is closed
+    pub fn is_closed(&self) -> bool {
+        self.machine.current_state() == "Closed"
+    }
+
+    /// Get current state name
+    pub fn state_name(&self) -> &'static str {
+        self.machine.current_state()
+    }
+
+    /// Clear all events and reset circuit to Closed state
+    pub fn reset(&mut self) {
+        self.context.storage.clear(&self.context.name);
+        // Recreate machine in Closed state
+        self.machine = DynamicCircuit::new(self.context.clone());
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_circuit_breaker_creation() {
+        let config = Config::default();
+        let circuit = CircuitBreaker::new("test".to_string(), config);
+
+        assert!(circuit.is_closed());
+        assert!(!circuit.is_open());
+    }
+
+    #[test]
+    fn test_circuit_opens_after_threshold() {
+        let config = Config {
+            failure_threshold: 3,
+            failure_window_secs: 60.0,
+            half_open_timeout_secs: 30.0,
+            success_threshold: 2,
+            jitter_factor: 0.0,
+        };
+
+        let mut circuit = CircuitBreaker::new("test".to_string(), config);
+
+        // Trigger failures via call() method
+        let _ = circuit.call(|| Err::<(), _>("error 1"));
+        let _ = circuit.call(|| Err::<(), _>("error 2"));
+        assert!(circuit.is_closed());
+
+        let _ = circuit.call(|| Err::<(), _>("error 3"));
+        assert!(circuit.is_open());
+    }
+
+    #[test]
+    fn test_reset_clears_state() {
+        let config = Config {
+            failure_threshold: 2,
+            ..Default::default()
+        };
+
+        let mut circuit = CircuitBreaker::new("test".to_string(), config);
+
+        // Trigger failures
+        let _ = circuit.call(|| Err::<(), _>("error 1"));
+        let _ = circuit.call(|| Err::<(), _>("error 2"));
+        assert!(circuit.is_open());
+
+        circuit.reset();
+        assert!(circuit.is_closed());
+    }
+
+    #[test]
+    fn test_state_machine_closed_to_open_transition() {
+        let storage = Arc::new(crate::MemoryStorage::new());
+        let config = Config {
+            failure_threshold: 3,
+            failure_window_secs: 60.0,
+            half_open_timeout_secs: 30.0,
+            success_threshold: 2,
+            jitter_factor: 0.0,
+        };
+
+        let ctx = CircuitContext {
+            name: "test_circuit".to_string(),
+            config,
+            storage: storage.clone(),
+        };
+
+        let mut circuit = DynamicCircuit::new(ctx.clone());
+
+        // Initially closed - trip should fail guard
+        let result = circuit.handle(CircuitEvent::Trip);
+        assert!(result.is_err(), "Should fail guard when below threshold");
+
+        // Record failures to exceed threshold
+        storage.record_failure("test_circuit", 0.1);
+        storage.record_failure("test_circuit", 0.1);
+        storage.record_failure("test_circuit", 0.1);
+
+        // Now trip should succeed - guards pass
+        circuit
+            .handle(CircuitEvent::Trip)
+            .expect("Should open after reaching threshold");
+
+        assert_eq!(circuit.current_state(), "Open");
+    }
+
+    #[test]
+    fn test_state_machine_open_to_half_open_transition() {
+        let storage = Arc::new(crate::MemoryStorage::new());
+        let config = Config {
+            failure_threshold: 2,
+            failure_window_secs: 60.0,
+            half_open_timeout_secs: 0.001, // Very short timeout for testing
+            success_threshold: 2,
+            jitter_factor: 0.0,
+        };
+
+        let ctx = CircuitContext {
+            name: "test_circuit".to_string(),
+            config,
+            storage: storage.clone(),
+        };
+
+        // Record failures and open circuit
+        storage.record_failure("test_circuit", 0.1);
+        storage.record_failure("test_circuit", 0.1);
+
+        let mut circuit = DynamicCircuit::new(ctx.clone());
+        circuit.handle(CircuitEvent::Trip).expect("Should open");
+
+        // Set opened_at timestamp
+        if let Some(data) = circuit.open_data_mut() {
+            data.opened_at = storage.monotonic_time();
+        }
+
+        // Immediately try to reset - should fail guard (timeout not elapsed)
+        let result = circuit.handle(CircuitEvent::AttemptReset);
+        assert!(
+            result.is_err(),
+            "Should fail guard when timeout not elapsed"
+        );
+
+        // Wait for timeout
+        std::thread::sleep(std::time::Duration::from_millis(5));
+
+        circuit
+            .handle(CircuitEvent::AttemptReset)
+            .expect("Should reset after timeout");
+
+        // Verify we're in HalfOpen state
+        assert_eq!(circuit.current_state(), "HalfOpen");
+        let data = circuit.half_open_data().expect("Should have HalfOpen data");
+        assert_eq!(data.consecutive_successes, 0);
+    }
+
+    #[test]
+    fn test_state_machine_half_open_to_closed_guard() {
+        let storage = Arc::new(crate::MemoryStorage::new());
+        let config = Config {
+            failure_threshold: 2,
+            failure_window_secs: 60.0,
+            half_open_timeout_secs: 0.001,
+            success_threshold: 2,
+            jitter_factor: 0.0,
+        };
+
+        let ctx = CircuitContext {
+            name: "test_circuit".to_string(),
+            config,
+            storage: storage.clone(),
+        };
+
+        // Get to HalfOpen state
+        storage.record_failure("test_circuit", 0.1);
+        storage.record_failure("test_circuit", 0.1);
+
+        let mut circuit = DynamicCircuit::new(ctx.clone());
+        circuit.handle(CircuitEvent::Trip).expect("Should open");
+
+        // Set opened_at and wait for timeout
+        if let Some(data) = circuit.open_data_mut() {
+            data.opened_at = storage.monotonic_time();
+        }
+        std::thread::sleep(std::time::Duration::from_millis(5));
+
+        circuit
+            .handle(CircuitEvent::AttemptReset)
+            .expect("Should reset");
+
+        // Try to close - should fail guard (not enough successes)
+        let result = circuit.handle(CircuitEvent::Close);
+        assert!(result.is_err(), "Should fail guard without successes");
+    }
+
+    #[test]
+    fn test_jitter_disabled() {
+        let storage = Arc::new(crate::MemoryStorage::new());
+        let config = Config {
+            failure_threshold: 1,
+            failure_window_secs: 60.0,
+            half_open_timeout_secs: 1.0, // 1 second timeout
+            success_threshold: 1,
+            jitter_factor: 0.0, // No jitter
+        };
+
+        let ctx = CircuitContext {
+            name: "test_circuit".to_string(),
+            config,
+            storage: storage.clone(),
+        };
+
+        // Open circuit
+        storage.record_failure("test_circuit", 0.1);
+        let mut circuit = DynamicCircuit::new(ctx.clone());
+        circuit.handle(CircuitEvent::Trip).expect("Should open");
+
+        // Set opened_at
+        if let Some(data) = circuit.open_data_mut() {
+            data.opened_at = storage.monotonic_time();
+        }
+
+        // Wait exactly 1 second
+        std::thread::sleep(std::time::Duration::from_secs(1));
+
+        // Should transition to HalfOpen (no jitter = exact timeout)
+        circuit
+            .handle(CircuitEvent::AttemptReset)
+            .expect("Should reset after exact timeout");
+        assert_eq!(circuit.current_state(), "HalfOpen");
+    }
+
+    #[test]
+    fn test_jitter_enabled() {
+        let storage = Arc::new(crate::MemoryStorage::new());
+        let config = Config {
+            failure_threshold: 1,
+            failure_window_secs: 60.0,
+            half_open_timeout_secs: 1.0,
+            success_threshold: 1,
+            jitter_factor: 0.1, // 10% jitter = 90-100% of timeout
+        };
+
+        let ctx = CircuitContext {
+            name: "test_circuit".to_string(),
+            config,
+            storage: storage.clone(),
+        };
+
+        // Test multiple times to verify jitter reduces timeout
+        let mut found_early_reset = false;
+        for _ in 0..10 {
+            // Open circuit
+            storage.record_failure("test_circuit", 0.1);
+            let mut circuit = DynamicCircuit::new(ctx.clone());
+            circuit.handle(CircuitEvent::Trip).expect("Should open");
+
+            if let Some(data) = circuit.open_data_mut() {
+                data.opened_at = storage.monotonic_time();
+            }
+
+            // With 10% jitter, timeout should be 900-1000ms
+            // Try at 950ms - should sometimes succeed (jitter applied)
+            std::thread::sleep(std::time::Duration::from_millis(950));
+
+            if circuit.handle(CircuitEvent::AttemptReset).is_ok() {
+                found_early_reset = true;
+                break;
+            }
+
+            storage.clear("test_circuit");
+        }
+
+        assert!(
+            found_early_reset,
+            "Jitter should occasionally allow reset before full timeout"
+        );
+    }
+
+    #[test]
+    fn test_builder_with_jitter() {
+        let mut circuit = CircuitBreaker::builder("test")
+            .failure_threshold(2)
+            .half_open_timeout_secs(1.0)
+            .jitter_factor(0.5) // 50% jitter
+            .build();
+
+        // Trigger failures
+        let _ = circuit.call(|| Err::<(), _>("error 1"));
+        let _ = circuit.call(|| Err::<(), _>("error 2"));
+        assert!(circuit.is_open());
+
+        // Verify jitter_factor was set
+        assert_eq!(circuit.context.config.jitter_factor, 0.5);
+    }
+}

data/ext/breaker_machines_native/target/package/breaker-machines-0.5.0/src/errors.rs

@@ -0,0 +1,38 @@
+//! Error types for circuit breaker operations
+
+use std::error::Error;
+use std::fmt;
+
+/// Errors that can occur during circuit breaker operations
+#[derive(Debug)]
+pub enum CircuitError<E = Box<dyn Error + Send + Sync>> {
+    /// Circuit is open, calls are being rejected
+    Open { circuit: String, opened_at: f64 },
+    /// Half-open request limit has been reached
+    HalfOpenLimitReached { circuit: String },
+    /// The wrapped operation failed
+    Execution(E),
+}
+
+impl<E: fmt::Display> fmt::Display for CircuitError<E> {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            CircuitError::Open { circuit, opened_at } => {
+                write!(f, "Circuit '{}' is open (opened at {})", circuit, opened_at)
+            }
+            CircuitError::HalfOpenLimitReached { circuit } => {
+                write!(f, "Circuit '{}' half-open request limit reached", circuit)
+            }
+            CircuitError::Execution(e) => write!(f, "Circuit execution failed: {}", e),
+        }
+    }
+}
+
+impl<E: Error + 'static> Error for CircuitError<E> {
+    fn source(&self) -> Option<&(dyn Error + 'static)> {
+        match self {
+            CircuitError::Execution(e) => Some(e),
+            _ => None,
+        }
+    }
+}

data/ext/breaker_machines_native/target/package/breaker-machines-0.5.0/src/lib.rs

@@ -0,0 +1,58 @@
+//! BreakerMachines - High-performance circuit breaker implementation
+//!
+//! This crate provides a complete circuit breaker implementation with:
+//! - Thread-safe event storage with sliding window calculations
+//! - State machine for circuit breaker lifecycle (Closed → Open → HalfOpen)
+//! - Monotonic time tracking to prevent NTP clock skew issues
+//! - Configurable failure thresholds and timeouts
+//!
+//! # Example
+//!
+//! ```rust
+//! use breaker_machines::CircuitBreaker;
+//!
+//! let mut circuit = CircuitBreaker::builder("my_service")
+//!     .failure_threshold(5)
+//!     .failure_window_secs(60.0)
+//!     .half_open_timeout_secs(30.0)
+//!     .success_threshold(2)
+//!     .on_open(|name| println!("Circuit {} opened!", name))
+//!     .build();
+//!
+//! // Execute with circuit protection
+//! let result = circuit.call(|| {
+//!     // Your service call here
+//!     Ok::<_, String>("success")
+//! });
+//!
+//! // Check circuit state
+//! if circuit.is_open() {
+//!     println!("Circuit is open, skipping call");
+//! }
+//! ```
+
+pub mod builder;
+pub mod callbacks;
+pub mod circuit;
+pub mod errors;
+pub mod storage;
+
+pub use builder::CircuitBuilder;
+pub use circuit::{CircuitBreaker, Config};
+pub use errors::CircuitError;
+pub use storage::{MemoryStorage, NullStorage, StorageBackend};
+
+/// Event type for circuit breaker operations
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum EventKind {
+    Success,
+    Failure,
+}
+
+/// A single event recorded by the circuit breaker
+#[derive(Debug, Clone)]
+pub struct Event {
+    pub kind: EventKind,
+    pub timestamp: f64,
+    pub duration: f64,
+}