breaker_machines 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc152fbf822d0eae49f25c2f8acea2c3268c141d8a62a7aa313168007499e8a5
-  data.tar.gz: 5e7d529cde4b41cbb32fca7502249c15465413c4fad31e9a29056fbc99196e09
+  metadata.gz: fae87263df3eaaba47c2a78df338740ae9ed8599e13a42867110270787f9dc8a
+  data.tar.gz: 03bb57d8e463c3bd92ed2d7938788563b3df6d94329f87cf176b6934c218a963
 SHA512:
-  metadata.gz: fa71a3f703c2d9814a836d2eb160eaf89f1ea991cf80d96a237aa9b59654d13d7b0459c41c4b8a5018fc27b83fd2a6729b7740238372a8691e0aff944f5965a3
-  data.tar.gz: 59c7fd005d672ad412f9824c4880f2fc9f0141fa56f0bc405d63f9f3a95f05278b54fdceb5e97e93a18116c4e4101dc80db730eecfcd854656e0324fb1074d3d
+  metadata.gz: 67a9a1adad11d9d83fba339ccf3fe24317dde8e1da919b5fa7ffd2cf0509908daeb20a6efac0519e30604433617d493bdfa358e9b3de41140a0f440432c626df
+  data.tar.gz: 907986bddf430ea0daa163d2c8d51e7c77e3a61031927117529bcdc5586bec664f45c9b9c293cb614ca0c96ee2f539e810fdebef9ea55a04d2d3a6c163d54d25

data/README.md

@@ -44,6 +44,10 @@ Built on the battle-tested `state_machines` gem, because I don't reinvent wheels
 
 - **Thread-safe** circuit breaker implementation
 - **Fiber-safe mode** for async Ruby (Falcon, async gem)
+- **AsyncCircuit** class with mutex-protected state transitions
+- **Circuit Groups** for managing related circuits with dependencies
+- **Coordinated State Management** for dependency-aware transitions
+- **Cascading Circuit Breakers** for modeling system dependencies
 - **Hedged requests** for latency reduction
 - **Multiple backends** with automatic failover
 - **Bulkheading** to limit concurrent requests
@@ -52,21 +56,39 @@ Built on the battle-tested `state_machines` gem, because I don't reinvent wheels
 - **Pluggable storage** (Memory, Redis, Custom)
 - **Rich callbacks** and instrumentation
 - **ActiveSupport::Notifications** integration
+- **Cross-platform support** - Optimized for MRI, JRuby, and TruffleRuby
 
 ## Documentation
 
+### Core Features
 - **Getting Started Guide** (docs/GETTING_STARTED.md) - Installation and basic usage
 - **Configuration Reference** (docs/CONFIGURATION.md) - All configuration options
 - **Advanced Patterns** (docs/ADVANCED_PATTERNS.md) - Complex scenarios and patterns
+
+### Advanced Features
+- **Circuit Groups** (docs/CIRCUIT_GROUPS.md) - Managing related circuits with dependencies
+- **Coordinated State Management** (docs/COORDINATED_STATE_MANAGEMENT.md) - Dependency-aware state transitions
+- **Cascading Circuit Breakers** (docs/CASCADING_CIRCUITS.md) - Modeling system dependencies
+
+### Async & Concurrency
+- **Async Mode** (docs/ASYNC.md) - Fiber-safe operations and AsyncCircuit
+- **Async Storage Examples** (docs/ASYNC_STORAGE_EXAMPLES.md) - Non-blocking storage backends
+
+### Storage & Persistence
 - **Persistence Options** (docs/PERSISTENCE.md) - Storage backends and distributed state
-- **Observability Guide** (docs/OBSERVABILITY.md) - Monitoring and metrics
-- **Async Mode** (docs/ASYNC.md) - Fiber-safe operations
+
+### Testing
 - **Testing Guide** (docs/TESTING.md) - Testing strategies
   - [RSpec Testing](docs/TESTING_RSPEC.md)
   - [ActiveSupport Testing](docs/TESTING_ACTIVESUPPORT.md)
+
+### Integration & Monitoring
 - **Rails Integration** (docs/RAILS_INTEGRATION.md) - Rails-specific patterns
-- **Horror Stories** (docs/HORROR_STORIES.md) - Real production failures and lessons learned
+- **Observability Guide** (docs/OBSERVABILITY.md) - Monitoring and metrics
+
+### Reference
 - **API Reference** (docs/API_REFERENCE.md) - Complete API documentation
+- **Horror Stories** (docs/HORROR_STORIES.md) - Real production failures and lessons learned
 
 ## Why BreakerMachines?
 

data/ext/breaker_machines_native/Cargo.toml

@@ -0,0 +1,8 @@
+[workspace]
+members = ["core", "ffi"]
+resolver = "2"
+
+[workspace.dependencies]
+breaker-machines = { path = "./core" }
+state-machines = "0.6"
+chrono-machines = "0.2.1"

data/ext/breaker_machines_native/core/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "breaker-machines"
+version = "0.6.0"
+edition = "2024"
+authors = ["Abdelkader Boudih <terminale@gmail.com>"]
+license = "MIT"
+description = "High-performance circuit breaker with fallback support and rate-based thresholds"
+repository = "https://github.com/seuros/breaker_machines"
+readme = "README.md"
+keywords = ["circuit-breaker", "reliability", "fault-tolerance"]
+categories = ["concurrency"]
+
+[lib]
+crate-type = ["lib"]
+
+[dependencies]
+state-machines = { workspace = true }
+chrono-machines = { workspace = true }

data/ext/breaker_machines_native/core/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/core/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/core/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/core/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()
+    }
+}