breaker_machines 0.5.0 → 0.6.0

data/ext/breaker_machines_native/target/package/breaker-machines-0.6.0/src/classifier.rs

@@ -0,0 +1,177 @@
+//! Failure classification for exception filtering
+//!
+//! This module provides traits and types for determining which errors
+//! should trip the circuit breaker vs. being ignored.
+
+use std::any::Any;
+
+/// Context provided to failure classifiers for error evaluation
+#[derive(Debug)]
+pub struct FailureContext<'a> {
+    /// Circuit name
+    pub circuit_name: &'a str,
+    /// The error that occurred (can be downcast to specific types)
+    pub error: &'a dyn Any,
+    /// Duration of the failed call in seconds
+    pub duration: f64,
+}
+
+/// Trait for classifying failures - determines if an error should trip the circuit
+///
+/// Implementors can inspect the error type and context to decide whether
+/// this particular failure should count toward opening the circuit.
+///
+/// # Examples
+///
+/// ```rust
+/// use breaker_machines::{FailureClassifier, FailureContext};
+/// use std::sync::Arc;
+///
+/// #[derive(Debug)]
+/// struct ServerErrorClassifier;
+///
+/// impl FailureClassifier for ServerErrorClassifier {
+///     fn should_trip(&self, ctx: &FailureContext<'_>) -> bool {
+///         // Only trip on server errors (5xx), not client errors (4xx)
+///         // This would require your error type to be downcast-able
+///         true // Default: trip on all errors
+///     }
+/// }
+/// ```
+pub trait FailureClassifier: Send + Sync + std::fmt::Debug {
+    /// Determine if this error should count as a failure for circuit breaker logic
+    ///
+    /// Returns `true` if the error should trip the circuit, `false` to ignore it.
+    fn should_trip(&self, ctx: &FailureContext<'_>) -> bool;
+}
+
+/// Default classifier that trips on all errors
+#[derive(Debug, Clone, Copy)]
+pub struct DefaultClassifier;
+
+impl FailureClassifier for DefaultClassifier {
+    fn should_trip(&self, _ctx: &FailureContext<'_>) -> bool {
+        true // All errors trip the circuit (backward compatible)
+    }
+}
+
+impl Default for DefaultClassifier {
+    fn default() -> Self {
+        Self
+    }
+}
+
+/// Predicate-based classifier using a closure
+///
+/// Allows using simple closures for common filtering patterns.
+pub struct PredicateClassifier<F>
+where
+    F: Fn(&FailureContext<'_>) -> bool + Send + Sync,
+{
+    predicate: F,
+}
+
+impl<F> PredicateClassifier<F>
+where
+    F: Fn(&FailureContext<'_>) -> bool + Send + Sync,
+{
+    /// Create a new predicate-based classifier
+    pub fn new(predicate: F) -> Self {
+        Self { predicate }
+    }
+}
+
+impl<F> FailureClassifier for PredicateClassifier<F>
+where
+    F: Fn(&FailureContext<'_>) -> bool + Send + Sync,
+{
+    fn should_trip(&self, ctx: &FailureContext<'_>) -> bool {
+        (self.predicate)(ctx)
+    }
+}
+
+impl<F> std::fmt::Debug for PredicateClassifier<F>
+where
+    F: Fn(&FailureContext<'_>) -> bool + Send + Sync,
+{
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("PredicateClassifier")
+            .field("predicate", &"<closure>")
+            .finish()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_default_classifier_trips_all() {
+        let classifier = DefaultClassifier;
+        let ctx = FailureContext {
+            circuit_name: "test",
+            error: &"any error" as &dyn Any,
+            duration: 0.1,
+        };
+
+        assert!(classifier.should_trip(&ctx));
+    }
+
+    #[test]
+    fn test_predicate_classifier() {
+        // Classifier that only trips on slow errors
+        let classifier = PredicateClassifier::new(|ctx| ctx.duration > 1.0);
+
+        let fast_ctx = FailureContext {
+            circuit_name: "test",
+            error: &"fast error" as &dyn Any,
+            duration: 0.5,
+        };
+
+        let slow_ctx = FailureContext {
+            circuit_name: "test",
+            error: &"slow error" as &dyn Any,
+            duration: 2.0,
+        };
+
+        assert!(!classifier.should_trip(&fast_ctx));
+        assert!(classifier.should_trip(&slow_ctx));
+    }
+
+    #[test]
+    fn test_error_type_downcast() {
+        #[derive(Debug)]
+        struct MyError {
+            is_server_error: bool,
+        }
+
+        let server_error = MyError {
+            is_server_error: true,
+        };
+        let client_error = MyError {
+            is_server_error: false,
+        };
+
+        let classifier = PredicateClassifier::new(|ctx| {
+            ctx.error
+                .downcast_ref::<MyError>()
+                .map(|e| e.is_server_error)
+                .unwrap_or(true) // Trip on unknown errors
+        });
+
+        let server_ctx = FailureContext {
+            circuit_name: "test",
+            error: &server_error as &dyn Any,
+            duration: 0.1,
+        };
+
+        let client_ctx = FailureContext {
+            circuit_name: "test",
+            error: &client_error as &dyn Any,
+            duration: 0.1,
+        };
+
+        assert!(classifier.should_trip(&server_ctx));
+        assert!(!classifier.should_trip(&client_ctx));
+    }
+}

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

@@ -0,0 +1,47 @@
+//! 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 },
+    /// Bulkhead is at capacity, cannot acquire permit
+    BulkheadFull { circuit: String, limit: usize },
+    /// 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::BulkheadFull { circuit, limit } => {
+                write!(
+                    f,
+                    "Circuit '{}' bulkhead is full (limit: {})",
+                    circuit, limit
+                )
+            }
+            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.6.0/src/lib.rs

@@ -0,0 +1,62 @@
+//! 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 bulkhead;
+pub mod callbacks;
+pub mod circuit;
+pub mod classifier;
+pub mod errors;
+pub mod storage;
+
+pub use builder::CircuitBuilder;
+pub use bulkhead::{BulkheadGuard, BulkheadSemaphore};
+pub use circuit::{CallOptions, CircuitBreaker, Config, FallbackContext};
+pub use classifier::{DefaultClassifier, FailureClassifier, FailureContext, PredicateClassifier};
+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,
+}

data/ext/breaker_machines_native/target/package/breaker-machines-0.6.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());
+    }
+}