breaker_machines 0.5.0 → 0.6.0

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

@@ -0,0 +1,232 @@
+//! Builder API for ergonomic circuit breaker configuration
+
+use crate::{
+    MemoryStorage, StorageBackend,
+    bulkhead::BulkheadSemaphore,
+    callbacks::Callbacks,
+    circuit::{CircuitBreaker, CircuitContext, Config},
+    classifier::FailureClassifier,
+};
+use std::sync::Arc;
+
+/// Builder for creating circuit breakers with fluent API
+pub struct CircuitBuilder {
+    name: String,
+    config: Config,
+    storage: Option<Arc<dyn StorageBackend>>,
+    failure_classifier: Option<Arc<dyn FailureClassifier>>,
+    bulkhead: Option<Arc<BulkheadSemaphore>>,
+    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,
+            failure_classifier: None,
+            bulkhead: 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 a failure classifier to filter which errors should trip the circuit
+    ///
+    /// The classifier determines whether a given error should count toward
+    /// opening the circuit. Use this to ignore "expected" errors like validation
+    /// failures or client errors (4xx), while still tripping on server errors (5xx).
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use breaker_machines::{CircuitBreaker, PredicateClassifier};
+    /// use std::sync::Arc;
+    ///
+    /// let circuit = CircuitBreaker::builder("api")
+    ///     .failure_classifier(Arc::new(PredicateClassifier::new(|ctx| {
+    ///         // Only trip on slow errors
+    ///         ctx.duration > 1.0
+    ///     })))
+    ///     .build();
+    /// ```
+    pub fn failure_classifier(mut self, classifier: Arc<dyn FailureClassifier>) -> Self {
+        self.failure_classifier = Some(classifier);
+        self
+    }
+
+    /// Set maximum concurrency limit (bulkheading)
+    ///
+    /// When set, the circuit breaker will reject calls with `BulkheadFull` error
+    /// if the number of concurrent calls exceeds this limit. This prevents
+    /// resource exhaustion by limiting how many operations can run simultaneously.
+    ///
+    /// # Panics
+    ///
+    /// Panics if `limit` is 0.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use breaker_machines::CircuitBreaker;
+    ///
+    /// let mut circuit = CircuitBreaker::builder("api")
+    ///     .max_concurrency(10) // Allow max 10 concurrent calls
+    ///     .build();
+    ///
+    /// // This will succeed until 10 calls are running concurrently
+    /// let result = circuit.call(|| Ok::<_, String>("success"));
+    /// ```
+    pub fn max_concurrency(mut self, limit: usize) -> Self {
+        self.bulkhead = Some(Arc::new(BulkheadSemaphore::new(limit)));
+        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,
+            failure_classifier: self.failure_classifier,
+            bulkhead: self.bulkhead,
+        };
+
+        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));
+    }
+}

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

@@ -0,0 +1,223 @@
+//! Bulkhead implementation for concurrency limiting
+//!
+//! This module provides a semaphore-based bulkhead pattern to limit
+//! the number of concurrent calls through a circuit breaker.
+
+use std::sync::Arc;
+use std::sync::atomic::{AtomicUsize, Ordering};
+
+/// A semaphore-based bulkhead for limiting concurrent operations
+///
+/// Bulkheading prevents thread pool exhaustion by rejecting requests
+/// when a maximum concurrency limit is reached.
+#[derive(Debug)]
+pub struct BulkheadSemaphore {
+    /// Maximum number of concurrent permits
+    limit: usize,
+    /// Current number of acquired permits
+    acquired: AtomicUsize,
+}
+
+impl BulkheadSemaphore {
+    /// Create a new bulkhead semaphore with the given concurrency limit
+    ///
+    /// # Panics
+    ///
+    /// Panics if `limit` is 0.
+    pub fn new(limit: usize) -> Self {
+        assert!(limit > 0, "Bulkhead limit must be greater than 0");
+        Self {
+            limit,
+            acquired: AtomicUsize::new(0),
+        }
+    }
+
+    /// Try to acquire a permit without blocking
+    ///
+    /// Returns `Some(BulkheadGuard)` if a permit was acquired, or `None` if
+    /// the bulkhead is at capacity.
+    pub fn try_acquire(self: &Arc<Self>) -> Option<BulkheadGuard> {
+        // Try to increment the counter
+        let mut current = self.acquired.load(Ordering::Acquire);
+
+        loop {
+            // Check if we're at capacity
+            if current >= self.limit {
+                return None;
+            }
+
+            // Try to increment atomically
+            match self.acquired.compare_exchange_weak(
+                current,
+                current + 1,
+                Ordering::AcqRel,
+                Ordering::Acquire,
+            ) {
+                Ok(_) => {
+                    // Successfully acquired permit
+                    return Some(BulkheadGuard {
+                        semaphore: Arc::clone(self),
+                    });
+                }
+                Err(actual) => {
+                    // Another thread modified the counter, try again
+                    current = actual;
+                }
+            }
+        }
+    }
+
+    /// Get the current number of acquired permits
+    pub fn acquired(&self) -> usize {
+        self.acquired.load(Ordering::Acquire)
+    }
+
+    /// Get the maximum number of permits (bulkhead limit)
+    pub fn limit(&self) -> usize {
+        self.limit
+    }
+
+    /// Get the number of available permits
+    pub fn available(&self) -> usize {
+        self.limit.saturating_sub(self.acquired())
+    }
+
+    /// Release a permit (called by BulkheadGuard on drop)
+    fn release(&self) {
+        self.acquired.fetch_sub(1, Ordering::Release);
+    }
+}
+
+/// Guard that releases a bulkhead permit when dropped
+///
+/// This ensures that permits are always released, even if the guarded
+/// operation panics.
+#[derive(Debug)]
+pub struct BulkheadGuard {
+    semaphore: Arc<BulkheadSemaphore>,
+}
+
+impl Drop for BulkheadGuard {
+    fn drop(&mut self) {
+        self.semaphore.release();
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::thread;
+
+    #[test]
+    fn test_bulkhead_basic_acquire_release() {
+        let bulkhead = Arc::new(BulkheadSemaphore::new(3));
+
+        assert_eq!(bulkhead.limit(), 3);
+        assert_eq!(bulkhead.acquired(), 0);
+        assert_eq!(bulkhead.available(), 3);
+
+        // Acquire first permit
+        let guard1 = bulkhead.try_acquire();
+        assert!(guard1.is_some());
+        assert_eq!(bulkhead.acquired(), 1);
+        assert_eq!(bulkhead.available(), 2);
+
+        // Acquire second permit
+        let guard2 = bulkhead.try_acquire();
+        assert!(guard2.is_some());
+        assert_eq!(bulkhead.acquired(), 2);
+
+        // Release first permit
+        drop(guard1);
+        assert_eq!(bulkhead.acquired(), 1);
+        assert_eq!(bulkhead.available(), 2);
+
+        // Release second permit
+        drop(guard2);
+        assert_eq!(bulkhead.acquired(), 0);
+        assert_eq!(bulkhead.available(), 3);
+    }
+
+    #[test]
+    fn test_bulkhead_at_capacity() {
+        let bulkhead = Arc::new(BulkheadSemaphore::new(2));
+
+        let guard1 = bulkhead.try_acquire().expect("Should acquire");
+        let guard2 = bulkhead.try_acquire().expect("Should acquire");
+
+        // At capacity - should fail
+        let guard3 = bulkhead.try_acquire();
+        assert!(guard3.is_none(), "Should not acquire when at capacity");
+        assert_eq!(bulkhead.acquired(), 2);
+
+        // Release one permit
+        drop(guard1);
+
+        // Now should succeed
+        let guard4 = bulkhead.try_acquire();
+        assert!(guard4.is_some(), "Should acquire after release");
+        assert_eq!(bulkhead.acquired(), 2);
+
+        drop(guard2);
+        drop(guard4);
+    }
+
+    #[test]
+    fn test_bulkhead_concurrent_access() {
+        let bulkhead = Arc::new(BulkheadSemaphore::new(5));
+        let mut handles = vec![];
+
+        // Spawn 10 threads trying to acquire permits
+        for _ in 0..10 {
+            let bulkhead_clone = Arc::clone(&bulkhead);
+            let handle = thread::spawn(move || {
+                if let Some(_guard) = bulkhead_clone.try_acquire() {
+                    // Hold the permit briefly
+                    thread::sleep(std::time::Duration::from_millis(10));
+                    true
+                } else {
+                    false
+                }
+            });
+            handles.push(handle);
+        }
+
+        // Wait for all threads
+        let mut acquired_count = 0;
+        for handle in handles {
+            if handle.join().unwrap() {
+                acquired_count += 1;
+            }
+        }
+
+        // At least 5 should have succeeded (limit is 5)
+        assert!(
+            acquired_count >= 5,
+            "At least 5 threads should acquire permits"
+        );
+
+        // All permits should be released now
+        assert_eq!(bulkhead.acquired(), 0);
+    }
+
+    #[test]
+    #[should_panic(expected = "Bulkhead limit must be greater than 0")]
+    fn test_bulkhead_zero_limit() {
+        BulkheadSemaphore::new(0);
+    }
+
+    #[test]
+    fn test_bulkhead_guard_releases_on_panic() {
+        let bulkhead = Arc::new(BulkheadSemaphore::new(2));
+
+        let bulkhead_clone = Arc::clone(&bulkhead);
+        let result = std::panic::catch_unwind(move || {
+            let _guard = bulkhead_clone.try_acquire().unwrap();
+            panic!("Simulated panic");
+        });
+
+        assert!(result.is_err());
+        // Guard should have been dropped and permit released
+        assert_eq!(bulkhead.acquired(), 0);
+    }
+}

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

@@ -0,0 +1,58 @@
+//! Callback system for circuit breaker state transitions
+
+use std::sync::Arc;
+
+/// Type alias for circuit breaker callback functions
+pub type CallbackFn = Arc<dyn Fn(&str) + Send + Sync>;
+
+/// Callbacks for circuit breaker events
+#[derive(Clone)]
+pub struct Callbacks {
+    pub on_open: Option<CallbackFn>,
+    pub on_close: Option<CallbackFn>,
+    pub on_half_open: Option<CallbackFn>,
+}
+
+impl Callbacks {
+    pub fn new() -> Self {
+        Self {
+            on_open: None,
+            on_close: None,
+            on_half_open: None,
+        }
+    }
+
+    pub fn trigger_open(&self, circuit: &str) {
+        if let Some(ref callback) = self.on_open {
+            callback(circuit);
+        }
+    }
+
+    pub fn trigger_close(&self, circuit: &str) {
+        if let Some(ref callback) = self.on_close {
+            callback(circuit);
+        }
+    }
+
+    pub fn trigger_half_open(&self, circuit: &str) {
+        if let Some(ref callback) = self.on_half_open {
+            callback(circuit);
+        }
+    }
+}
+
+impl Default for Callbacks {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl std::fmt::Debug for Callbacks {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("Callbacks")
+            .field("on_open", &self.on_open.is_some())
+            .field("on_close", &self.on_close.is_some())
+            .field("on_half_open", &self.on_half_open.is_some())
+            .finish()
+    }
+}