breaker_machines 0.5.0 → 0.6.0

data/ext/breaker_machines_native/target/package/breaker-machines-0.1.0/src/storage.rs

@@ -0,0 +1,377 @@
+//! Storage backends for circuit breaker events
+//!
+//! This module provides different storage implementations:
+//! - `MemoryStorage`: Thread-safe in-memory storage with sliding window
+//! - `NullStorage`: No-op storage for testing and benchmarking
+
+use crate::{Event, EventKind};
+use std::collections::HashMap;
+use std::sync::RwLock;
+use std::time::Instant;
+
+/// Abstract storage backend for circuit breaker events
+pub trait StorageBackend: Send + Sync + std::fmt::Debug {
+    /// Record a successful operation
+    fn record_success(&self, circuit_name: &str, duration: f64);
+
+    /// Record a failed operation
+    fn record_failure(&self, circuit_name: &str, duration: f64);
+
+    /// Count successful operations within a time window
+    fn success_count(&self, circuit_name: &str, window_seconds: f64) -> usize;
+
+    /// Count failed operations within a time window
+    fn failure_count(&self, circuit_name: &str, window_seconds: f64) -> usize;
+
+    /// Clear all events for a circuit
+    fn clear(&self, circuit_name: &str);
+
+    /// Clear all events for all circuits
+    fn clear_all(&self);
+
+    /// Get event log for a circuit (limited to last N events)
+    fn event_log(&self, circuit_name: &str, limit: usize) -> Vec<Event>;
+
+    /// Get monotonic time in seconds (relative to storage creation)
+    fn monotonic_time(&self) -> f64;
+}
+
+/// Thread-safe in-memory storage for circuit breaker events
+#[derive(Debug)]
+pub struct MemoryStorage {
+    /// Events keyed by circuit name
+    events: RwLock<HashMap<String, Vec<Event>>>,
+    /// Maximum events to keep per circuit
+    max_events: usize,
+    /// Monotonic time anchor (prevents clock skew issues from NTP)
+    start_time: Instant,
+}
+
+impl MemoryStorage {
+    /// Create a new storage instance
+    pub fn new() -> Self {
+        Self::with_max_events(1000)
+    }
+
+    /// Create storage with custom max events per circuit
+    pub fn with_max_events(max_events: usize) -> Self {
+        Self {
+            events: RwLock::new(HashMap::new()),
+            max_events,
+            start_time: Instant::now(),
+        }
+    }
+
+    // Private helper methods
+
+    fn record_event(&self, circuit_name: &str, kind: EventKind, duration: f64) {
+        let mut events = self.events.write().unwrap();
+        let circuit_events = events.entry(circuit_name.to_string()).or_default();
+
+        circuit_events.push(Event {
+            kind,
+            timestamp: self.monotonic_time(),
+            duration,
+        });
+
+        // Cleanup old events if we exceed max_events
+        if circuit_events.len() > self.max_events {
+            // Remove oldest 10% to avoid cleanup on every event
+            // Ensure we remove at least 1 event even with small max_events
+            let remove_count = (self.max_events / 10).max(1);
+            circuit_events.drain(0..remove_count);
+        }
+    }
+
+    fn count_events(&self, circuit_name: &str, kind: EventKind, window_seconds: f64) -> usize {
+        let events = self.events.read().unwrap();
+        let cutoff = self.monotonic_time() - window_seconds;
+
+        events
+            .get(circuit_name)
+            .map(|ev| {
+                ev.iter()
+                    .filter(|e| e.kind == kind && e.timestamp >= cutoff)
+                    .count()
+            })
+            .unwrap_or(0)
+    }
+}
+
+impl Default for MemoryStorage {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl StorageBackend for MemoryStorage {
+    fn record_success(&self, circuit_name: &str, duration: f64) {
+        self.record_event(circuit_name, EventKind::Success, duration);
+    }
+
+    fn record_failure(&self, circuit_name: &str, duration: f64) {
+        self.record_event(circuit_name, EventKind::Failure, duration);
+    }
+
+    fn success_count(&self, circuit_name: &str, window_seconds: f64) -> usize {
+        self.count_events(circuit_name, EventKind::Success, window_seconds)
+    }
+
+    fn failure_count(&self, circuit_name: &str, window_seconds: f64) -> usize {
+        self.count_events(circuit_name, EventKind::Failure, window_seconds)
+    }
+
+    fn clear(&self, circuit_name: &str) {
+        let mut events = self.events.write().unwrap();
+        events.remove(circuit_name);
+    }
+
+    fn clear_all(&self) {
+        let mut events = self.events.write().unwrap();
+        events.clear();
+    }
+
+    fn event_log(&self, circuit_name: &str, limit: usize) -> Vec<Event> {
+        let events = self.events.read().unwrap();
+        events
+            .get(circuit_name)
+            .map(|ev| {
+                let start = if ev.len() > limit {
+                    ev.len() - limit
+                } else {
+                    0
+                };
+                ev[start..].to_vec()
+            })
+            .unwrap_or_default()
+    }
+
+    fn monotonic_time(&self) -> f64 {
+        self.start_time.elapsed().as_secs_f64()
+    }
+}
+
+/// No-op storage backend for testing and benchmarking
+///
+/// This storage implementation discards all events and always returns zero counts.
+/// Useful for:
+/// - Testing circuit breaker logic without storage overhead
+/// - Benchmarking pure state machine performance
+/// - Scenarios where external systems track metrics
+///
+/// # Example
+///
+/// ```rust
+/// use breaker_machines::{CircuitBreaker, NullStorage};
+/// use std::sync::Arc;
+///
+/// let storage = Arc::new(NullStorage::new());
+/// let mut circuit = CircuitBreaker::builder("test")
+///     .storage(storage)
+///     .build();
+/// ```
+#[derive(Debug, Clone, Copy)]
+pub struct NullStorage {
+    start_time: Instant,
+}
+
+impl NullStorage {
+    /// Create a new null storage instance
+    pub fn new() -> Self {
+        Self {
+            start_time: Instant::now(),
+        }
+    }
+}
+
+impl Default for NullStorage {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl StorageBackend for NullStorage {
+    fn record_success(&self, _circuit_name: &str, _duration: f64) {
+        // No-op
+    }
+
+    fn record_failure(&self, _circuit_name: &str, _duration: f64) {
+        // No-op
+    }
+
+    fn success_count(&self, _circuit_name: &str, _window_seconds: f64) -> usize {
+        0
+    }
+
+    fn failure_count(&self, _circuit_name: &str, _window_seconds: f64) -> usize {
+        0
+    }
+
+    fn clear(&self, _circuit_name: &str) {
+        // No-op
+    }
+
+    fn clear_all(&self) {
+        // No-op
+    }
+
+    fn event_log(&self, _circuit_name: &str, _limit: usize) -> Vec<Event> {
+        Vec::new()
+    }
+
+    fn monotonic_time(&self) -> f64 {
+        self.start_time.elapsed().as_secs_f64()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_memory_storage_record_and_count() {
+        let storage = MemoryStorage::new();
+
+        storage.record_success("test_circuit", 0.1);
+        storage.record_success("test_circuit", 0.2);
+        storage.record_failure("test_circuit", 0.5);
+
+        assert_eq!(storage.success_count("test_circuit", 60.0), 2);
+        assert_eq!(storage.failure_count("test_circuit", 60.0), 1);
+    }
+
+    #[test]
+    fn test_memory_storage_clear() {
+        let storage = MemoryStorage::new();
+
+        storage.record_success("test_circuit", 0.1);
+        assert_eq!(storage.success_count("test_circuit", 60.0), 1);
+
+        storage.clear("test_circuit");
+        assert_eq!(storage.success_count("test_circuit", 60.0), 0);
+    }
+
+    #[test]
+    fn test_memory_storage_event_log() {
+        let storage = MemoryStorage::new();
+
+        storage.record_success("test_circuit", 0.1);
+        storage.record_failure("test_circuit", 0.2);
+        storage.record_success("test_circuit", 0.3);
+
+        let log = storage.event_log("test_circuit", 10);
+        assert_eq!(log.len(), 3);
+        assert_eq!(log[0].kind, EventKind::Success);
+        assert_eq!(log[1].kind, EventKind::Failure);
+        assert_eq!(log[2].kind, EventKind::Success);
+    }
+
+    #[test]
+    fn test_memory_storage_max_events_cleanup() {
+        let storage = MemoryStorage::with_max_events(100);
+
+        for i in 0..150 {
+            storage.record_success("test_circuit", i as f64 * 0.01);
+        }
+
+        let events = storage.events.read().unwrap();
+        let circuit_events = events.get("test_circuit").unwrap();
+
+        assert!(circuit_events.len() <= 100);
+    }
+
+    #[test]
+    fn test_memory_storage_small_max_events() {
+        let storage = MemoryStorage::with_max_events(5);
+
+        for i in 0..20 {
+            storage.record_success("test_circuit", i as f64 * 0.01);
+        }
+
+        let events = storage.events.read().unwrap();
+        let circuit_events = events.get("test_circuit").unwrap();
+
+        assert!(
+            circuit_events.len() <= 5,
+            "Expected <= 5 events, got {}",
+            circuit_events.len()
+        );
+    }
+
+    #[test]
+    fn test_memory_storage_monotonic_time() {
+        let storage = MemoryStorage::new();
+
+        storage.record_success("test_circuit", 0.1);
+        let time1 = storage.monotonic_time();
+
+        std::thread::sleep(std::time::Duration::from_millis(10));
+
+        storage.record_success("test_circuit", 0.2);
+        let time2 = storage.monotonic_time();
+
+        assert!(time2 > time1);
+        assert_eq!(storage.success_count("test_circuit", 1.0), 2);
+    }
+
+    #[test]
+    fn test_null_storage_discards_events() {
+        let storage = NullStorage::new();
+
+        storage.record_success("test_circuit", 0.1);
+        storage.record_failure("test_circuit", 0.2);
+
+        assert_eq!(storage.success_count("test_circuit", 60.0), 0);
+        assert_eq!(storage.failure_count("test_circuit", 60.0), 0);
+    }
+
+    #[test]
+    fn test_null_storage_empty_event_log() {
+        let storage = NullStorage::new();
+
+        storage.record_success("test_circuit", 0.1);
+        storage.record_failure("test_circuit", 0.2);
+
+        let log = storage.event_log("test_circuit", 10);
+        assert_eq!(log.len(), 0);
+    }
+
+    #[test]
+    fn test_null_storage_clear_operations() {
+        let storage = NullStorage::new();
+
+        storage.clear("test_circuit");
+        storage.clear_all();
+
+        assert_eq!(storage.success_count("test_circuit", 60.0), 0);
+    }
+
+    #[test]
+    fn test_null_storage_monotonic_time() {
+        let storage = NullStorage::new();
+
+        let time1 = storage.monotonic_time();
+        std::thread::sleep(std::time::Duration::from_millis(10));
+        let time2 = storage.monotonic_time();
+
+        assert!(time2 > time1);
+    }
+
+    #[test]
+    fn test_null_storage_with_circuit_breaker() {
+        use std::sync::Arc;
+
+        let storage = Arc::new(NullStorage::new());
+        let mut circuit = crate::CircuitBreaker::builder("test")
+            .storage(storage)
+            .failure_threshold(3)
+            .build();
+
+        let _ = circuit.call(|| Err::<(), _>("error 1"));
+        let _ = circuit.call(|| Err::<(), _>("error 2"));
+        let _ = circuit.call(|| Err::<(), _>("error 3"));
+
+        assert!(circuit.is_closed());
+        assert!(!circuit.is_open());
+    }
+}

data/ext/breaker_machines_native/target/package/breaker-machines-0.2.0/Cargo.toml

@@ -0,0 +1,48 @@
+# THIS FILE IS AUTOMATICALLY GENERATED BY CARGO
+#
+# When uploading crates to the registry Cargo will automatically
+# "normalize" Cargo.toml files for maximal compatibility
+# with all versions of Cargo and also rewrite `path` dependencies
+# to registry (e.g., crates.io) dependencies.
+#
+# If you are reading this file be aware that the original Cargo.toml
+# will likely look very different (and much more reasonable).
+# See Cargo.toml.orig for the original contents.
+
+[package]
+edition = "2024"
+name = "breaker-machines"
+version = "0.2.0"
+authors = ["Abdelkader Boudih <terminale@gmail.com>"]
+build = false
+autolib = false
+autobins = false
+autoexamples = false
+autotests = false
+autobenches = false
+description = "High-performance circuit breaker with fallback support and rate-based thresholds"
+readme = "README.md"
+keywords = [
+    "circuit-breaker",
+    "reliability",
+    "fault-tolerance",
+]
+categories = ["concurrency"]
+license = "MIT"
+repository = "https://github.com/seuros/breaker_machines"
+resolver = "2"
+
+[lib]
+name = "breaker_machines"
+crate-type = ["lib"]
+path = "src/lib.rs"
+
+[[example]]
+name = "basic"
+path = "examples/basic.rs"
+
+[dependencies.chrono-machines]
+version = "0.2.1"
+
+[dependencies.state-machines]
+version = "0.6"

data/ext/breaker_machines_native/target/package/breaker-machines-0.2.0/examples/basic.rs

@@ -0,0 +1,61 @@
+//! Basic circuit breaker usage example
+
+use breaker_machines::CircuitBreaker;
+
+fn main() {
+    println!("=== Circuit Breaker Basic Example ===\n");
+
+    // Create a circuit with builder API
+    let mut circuit = CircuitBreaker::builder("payment_api")
+        .failure_threshold(3)
+        .failure_window_secs(10.0)
+        .half_open_timeout_secs(5.0)
+        .success_threshold(2)
+        .on_open(|name| println!("🔴 Circuit '{}' opened!", name))
+        .on_close(|name| println!("🟢 Circuit '{}' closed!", name))
+        .on_half_open(|name| println!("🟡 Circuit '{}' half-open, testing...", name))
+        .build();
+
+    println!("Initial state: {}\n", circuit.state_name());
+
+    // Simulate successful calls
+    println!("--- Successful calls ---");
+    for i in 1..=2 {
+        match circuit.call(move || Ok::<_, String>(format!("Payment {}", i))) {
+            Ok(result) => println!("✓ {}", result),
+            Err(e) => println!("✗ Error: {}", e),
+        }
+    }
+    println!("State: {}\n", circuit.state_name());
+
+    // Simulate failures
+    println!("--- Triggering failures ---");
+    for i in 1..=3 {
+        match circuit.call(move || Err::<String, _>(format!("Payment failed {}", i))) {
+            Ok(_) => println!("✓ Success"),
+            Err(e) => println!("✗ {}", e),
+        }
+    }
+    println!("State: {} (circuit opened)\n", circuit.state_name());
+
+    // Try calling while open
+    println!("--- Attempting call while open ---");
+    match circuit.call(|| Ok::<_, String>("Should be rejected")) {
+        Ok(_) => println!("✓ Success"),
+        Err(e) => println!("✗ {}", e),
+    }
+    println!();
+
+    // Reset and demonstrate recovery
+    println!("--- Resetting circuit ---");
+    circuit.reset();
+    println!("State after reset: {}\n", circuit.state_name());
+
+    // Successful calls after reset
+    println!("--- Calls after reset ---");
+    match circuit.call(|| Ok::<_, String>("Payment successful")) {
+        Ok(result) => println!("✓ {}", result),
+        Err(e) => println!("✗ {}", e),
+    }
+    println!("State: {}", circuit.state_name());
+}

data/ext/breaker_machines_native/target/package/breaker-machines-0.2.0/src/builder.rs

@@ -0,0 +1,173 @@
+//! Builder API for ergonomic circuit breaker configuration
+
+use crate::{
+    MemoryStorage, StorageBackend,
+    callbacks::Callbacks,
+    circuit::{CircuitBreaker, CircuitContext, Config},
+};
+use std::sync::Arc;
+
+/// Builder for creating circuit breakers with fluent API
+pub struct CircuitBuilder {
+    name: String,
+    config: Config,
+    storage: Option<Arc<dyn StorageBackend>>,
+    callbacks: Callbacks,
+}
+
+impl CircuitBuilder {
+    /// Create a new builder for a circuit with the given name
+    pub fn new(name: impl Into<String>) -> Self {
+        Self {
+            name: name.into(),
+            config: Config::default(),
+            storage: None,
+            callbacks: Callbacks::new(),
+        }
+    }
+
+    /// Set the absolute failure threshold (number of failures to open circuit)
+    pub fn failure_threshold(mut self, threshold: usize) -> Self {
+        self.config.failure_threshold = Some(threshold);
+        self
+    }
+
+    /// Disable absolute failure threshold (use only rate-based)
+    pub fn disable_failure_threshold(mut self) -> Self {
+        self.config.failure_threshold = None;
+        self
+    }
+
+    /// Set the failure rate threshold (0.0-1.0)
+    /// Circuit opens when (failures / total_calls) >= this value
+    pub fn failure_rate(mut self, rate: f64) -> Self {
+        self.config.failure_rate_threshold = Some(rate.clamp(0.0, 1.0));
+        self
+    }
+
+    /// Set minimum number of calls before rate-based threshold is evaluated
+    pub fn minimum_calls(mut self, calls: usize) -> Self {
+        self.config.minimum_calls = calls;
+        self
+    }
+
+    /// Set the failure window in seconds
+    pub fn failure_window_secs(mut self, seconds: f64) -> Self {
+        self.config.failure_window_secs = seconds;
+        self
+    }
+
+    /// Set the half-open timeout in seconds
+    pub fn half_open_timeout_secs(mut self, seconds: f64) -> Self {
+        self.config.half_open_timeout_secs = seconds;
+        self
+    }
+
+    /// Set the success threshold (successes needed to close from half-open)
+    pub fn success_threshold(mut self, threshold: usize) -> Self {
+        self.config.success_threshold = threshold;
+        self
+    }
+
+    /// Set the jitter factor (0.0 = no jitter, 1.0 = full jitter)
+    /// Uses chrono-machines formula: timeout * (1 - jitter + rand * jitter)
+    pub fn jitter_factor(mut self, factor: f64) -> Self {
+        self.config.jitter_factor = factor;
+        self
+    }
+
+    /// Set custom storage backend
+    pub fn storage(mut self, storage: Arc<dyn StorageBackend>) -> Self {
+        self.storage = Some(storage);
+        self
+    }
+
+    /// Set callback for when circuit opens
+    pub fn on_open<F>(mut self, f: F) -> Self
+    where
+        F: Fn(&str) + Send + Sync + 'static,
+    {
+        self.callbacks.on_open = Some(Arc::new(f));
+        self
+    }
+
+    /// Set callback for when circuit closes
+    pub fn on_close<F>(mut self, f: F) -> Self
+    where
+        F: Fn(&str) + Send + Sync + 'static,
+    {
+        self.callbacks.on_close = Some(Arc::new(f));
+        self
+    }
+
+    /// Set callback for when circuit enters half-open
+    pub fn on_half_open<F>(mut self, f: F) -> Self
+    where
+        F: Fn(&str) + Send + Sync + 'static,
+    {
+        self.callbacks.on_half_open = Some(Arc::new(f));
+        self
+    }
+
+    /// Build the circuit breaker
+    pub fn build(self) -> CircuitBreaker {
+        let storage = self
+            .storage
+            .unwrap_or_else(|| Arc::new(MemoryStorage::new()));
+
+        let context = CircuitContext {
+            name: self.name,
+            config: self.config,
+            storage,
+        };
+
+        CircuitBreaker::with_context_and_callbacks(context, self.callbacks)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_builder_defaults() {
+        let circuit = CircuitBuilder::new("test").build();
+
+        assert_eq!(circuit.state_name(), "Closed");
+        assert!(circuit.is_closed());
+    }
+
+    #[test]
+    fn test_builder_custom_config() {
+        let circuit = CircuitBuilder::new("test")
+            .failure_threshold(10)
+            .failure_window_secs(120.0)
+            .half_open_timeout_secs(60.0)
+            .success_threshold(3)
+            .build();
+
+        assert!(circuit.is_closed());
+    }
+
+    #[test]
+    fn test_builder_with_callbacks() {
+        use std::sync::atomic::{AtomicBool, Ordering};
+
+        let opened = Arc::new(AtomicBool::new(false));
+        let opened_clone = opened.clone();
+
+        let mut circuit = CircuitBuilder::new("test")
+            .failure_threshold(2)
+            .on_open(move |_name| {
+                opened_clone.store(true, Ordering::SeqCst);
+            })
+            .build();
+
+        // Trigger failures to open circuit
+        let _ = circuit.call(|| Err::<(), _>("error 1"));
+        let _ = circuit.call(|| Err::<(), _>("error 2"));
+
+        // Callback should have been triggered
+        assert!(opened.load(Ordering::SeqCst));
+    }
+}