breaker_machines 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc152fbf822d0eae49f25c2f8acea2c3268c141d8a62a7aa313168007499e8a5
-  data.tar.gz: 5e7d529cde4b41cbb32fca7502249c15465413c4fad31e9a29056fbc99196e09
+  metadata.gz: 97bc515f00b4402af03e813a121969745726a3635a8475bd3066877294f535a0
+  data.tar.gz: 20370133d03443108818133a98790194a4669a5b9daafdb1808d537b3915bb32
 SHA512:
-  metadata.gz: fa71a3f703c2d9814a836d2eb160eaf89f1ea991cf80d96a237aa9b59654d13d7b0459c41c4b8a5018fc27b83fd2a6729b7740238372a8691e0aff944f5965a3
-  data.tar.gz: 59c7fd005d672ad412f9824c4880f2fc9f0141fa56f0bc405d63f9f3a95f05278b54fdceb5e97e93a18116c4e4101dc80db730eecfcd854656e0324fb1074d3d
+  metadata.gz: 365d62466c1dae963c4f26e4f7920868358d9a39cd627bbc017ee7f8d36807e03ae808d1d4057dfee54b2edfc3e1dadaf36bf687b33aed8201bafac1a38f168f
+  data.tar.gz: 54fe1284d6710fab9a347b05821c41ea98f04212b224752d6bfc4f7d3fd995febb431acfee57f83a30859b2a7c7a138da59bb1c16ebf15032f018530c72fe397

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/lib/breaker_machines/async_circuit.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Requires async gem ~> 2.31.0 for modern async patterns
+
+require_relative 'circuit/async_state_management'
+
+module BreakerMachines
+  # AsyncCircuit provides a circuit breaker with async-enabled state machine
+  # for thread-safe, fiber-safe concurrent operations
+  class AsyncCircuit < Circuit
+    include Circuit::AsyncStateManagement
+
+    # Additional async-specific methods
+    def call_async(&block)
+      require 'async' unless defined?(::Async)
+
+      Async do
+        call(&block)
+      end
+    end
+
+    # Fire state transition events asynchronously
+    # @param event_name [Symbol] The event to fire
+    # @return [Async::Task] The async task
+    def fire_async(event_name)
+      require 'async' unless defined?(::Async)
+
+      fire_event_async(event_name)
+    end
+
+    # Check circuit health asynchronously
+    # Useful for monitoring multiple circuits concurrently
+    def health_check_async
+      require 'async' unless defined?(::Async)
+
+      Async do
+        {
+          name: @name,
+          status: status_name,
+          open: open?,
+          stats: stats.to_h,
+          can_recover: open? && reset_timeout_elapsed?
+        }
+      end
+    end
+  end
+end

data/lib/breaker_machines/async_support.rb

@@ -2,6 +2,7 @@
 
 # This file contains all async-related functionality for fiber-safe mode
 # It is only loaded when fiber_safe mode is enabled
+# Requires async gem ~> 2.31.0 for modern timeout API and Promise features
 
 require 'async'
 require 'async/task'
@@ -43,11 +44,11 @@ module BreakerMachines
       end
     end
 
-    # Execute a block with optional timeout using Async
+    # Execute a block with optional timeout using modern Async API
     def execute_with_async_timeout(timeout, &)
       if timeout
-        # Use safe, cooperative timeout from async gem
-        ::Async::Task.current.with_timeout(timeout, &)
+        # Use modern timeout API - the flexible with_timeout API is on the task level
+        Async::Task.current.with_timeout(timeout, &)
       else
         yield
       end

data/lib/breaker_machines/cascading_circuit.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+require_relative 'coordinated_circuit'
+
 module BreakerMachines
-  # CascadingCircuit extends the base Circuit class with the ability to automatically
+  # CascadingCircuit extends the CoordinatedCircuit class with the ability to automatically
   # trip dependent circuits when this circuit opens. This enables sophisticated
   # failure cascade modeling, similar to how critical system failures in a starship
   # would cascade to dependent subsystems.
@@ -18,7 +20,7 @@ module BreakerMachines
   #   network_circuit.call { raise 'Subspace relay offline!' }
   #   # => All dependent circuits are now open
   #
-  class CascadingCircuit < Circuit
+  class CascadingCircuit < CoordinatedCircuit
     attr_reader :dependent_circuits, :emergency_protocol
 
     def initialize(name, config = {})
@@ -144,7 +146,7 @@ module BreakerMachines
 
       # Allow custom emergency protocol handling
       owner = @config[:owner]
-      if owner&.respond_to?(@emergency_protocol, true)
+      if owner.respond_to?(@emergency_protocol, true)
         begin
           owner.send(@emergency_protocol, affected_circuits)
         rescue StandardError => e

data/lib/breaker_machines/circuit/async_state_management.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  class Circuit
+    # AsyncStateManagement provides state machine functionality with async support
+    # leveraging state_machines' async: true parameter for thread-safe operations
+    module AsyncStateManagement
+      extend ActiveSupport::Concern
+
+      included do
+        # Enable async mode for thread-safe state transitions
+        # This automatically provides:
+        # - Mutex-protected state reads/writes
+        # - Fiber-safe execution
+        # - Concurrent transition handling
+        state_machine :status, initial: :closed, async: true do
+          event :trip do
+            transition closed: :open
+            transition half_open: :open
+          end
+
+          event :attempt_recovery do
+            transition open: :half_open
+          end
+
+          event :reset do
+            transition %i[open half_open] => :closed
+            transition closed: :closed
+          end
+
+          event :force_open do
+            transition any => :open
+          end
+
+          event :force_close do
+            transition any => :closed
+          end
+
+          event :hard_reset do
+            transition any => :closed
+          end
+
+          before_transition on: :hard_reset do |circuit|
+            circuit.storage.clear(circuit.name) if circuit.storage
+            circuit.half_open_attempts.value = 0
+            circuit.half_open_successes.value = 0
+          end
+
+          # Async-safe callbacks using modern API
+          after_transition to: :open do |circuit|
+            circuit.send(:on_circuit_open)
+          end
+
+          after_transition to: :closed do |circuit|
+            circuit.send(:on_circuit_close)
+          end
+
+          after_transition from: :open, to: :half_open do |circuit|
+            circuit.send(:on_circuit_half_open)
+          end
+        end
+
+        # Additional async event methods are automatically generated:
+        # - trip_async! - Returns Async::Task
+        # - attempt_recovery_async! - Returns Async::Task
+        # - reset_async! - Returns Async::Task
+        # - fire_event_async(:event_name) - Generic async event firing
+      end
+    end
+  end
+end

data/lib/breaker_machines/circuit/base.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'concurrent-ruby'
+
+module BreakerMachines
+  class Circuit
+    # Base provides the common initialization and setup logic shared by all circuit types
+    module Base
+      extend ActiveSupport::Concern
+
+      included do
+        include Circuit::Configuration
+        include Circuit::Execution
+        include Circuit::HedgedExecution
+        include Circuit::Introspection
+        include Circuit::Callbacks
+        include Circuit::StateCallbacks
+
+        attr_reader :name, :config, :opened_at, :storage, :metrics, :semaphore
+        attr_reader :half_open_attempts, :half_open_successes, :mutex
+        attr_reader :last_failure_at, :last_error
+      end
+
+      def initialize(name, options = {})
+        @name = name
+        @config = default_config.merge(options)
+        # Always use a storage backend for proper sliding window implementation
+        # Use global default storage if not specified
+        @storage = @config[:storage] || create_default_storage
+        @metrics = @config[:metrics]
+        @opened_at = Concurrent::AtomicReference.new(nil)
+        @half_open_attempts = Concurrent::AtomicFixnum.new(0)
+        @half_open_successes = Concurrent::AtomicFixnum.new(0)
+        @mutex = Concurrent::ReentrantReadWriteLock.new
+        @last_failure_at = Concurrent::AtomicReference.new(nil)
+        @last_error = Concurrent::AtomicReference.new(nil)
+
+        # Initialize semaphore for bulkheading if max_concurrent is set
+        @semaphore = (Concurrent::Semaphore.new(@config[:max_concurrent]) if @config[:max_concurrent])
+
+        restore_status_from_storage if @storage
+
+        # Register with global registry unless auto_register is disabled
+        BreakerMachines::Registry.instance.register(self) unless @config[:auto_register] == false
+      end
+
+      private
+
+      def restore_status_from_storage
+        stored_status = @storage.get_status(@name)
+        return unless stored_status
+
+        self.status = stored_status.status.to_s
+        @opened_at.value = stored_status.opened_at if stored_status.opened_at
+      end
+    end
+  end
+end

data/lib/breaker_machines/circuit/callbacks.rb

@@ -120,19 +120,14 @@ module BreakerMachines
           end
         end
 
-        # Wait for first successful result
-        begin
-          Timeout.timeout(5) do # reasonable timeout for fallbacks
-            loop do
-              return result_queue.pop unless result_queue.empty?
-
-              raise error_queue.pop if error_queue.size >= fallbacks.size
+        threads.each(&:join)
 
-              sleep 0.001
-            end
-          end
-        ensure
-          threads.each(&:kill)
+        if result_queue.empty?
+          errors = []
+          errors << error_queue.pop until error_queue.empty?
+          raise BreakerMachines::ParallelFallbackError.new('All parallel fallbacks failed', errors)
+        else
+          result_queue.pop
         end
       end
     end

data/lib/breaker_machines/circuit/configuration.rb

@@ -11,30 +11,6 @@ module BreakerMachines
         attr_reader :name, :config, :opened_at
       end
 
-      def initialize(name, options = {})
-        @name = name
-        @config = default_config.merge(options)
-        # Always use a storage backend for proper sliding window implementation
-        # Use global default storage if not specified
-        @storage = @config[:storage] || create_default_storage
-        @metrics = @config[:metrics]
-        @opened_at = Concurrent::AtomicReference.new(nil)
-        @half_open_attempts = Concurrent::AtomicFixnum.new(0)
-        @half_open_successes = Concurrent::AtomicFixnum.new(0)
-        @mutex = Concurrent::ReentrantReadWriteLock.new
-        @last_failure_at = Concurrent::AtomicReference.new(nil)
-        @last_error = Concurrent::AtomicReference.new(nil)
-
-        # Initialize semaphore for bulkheading if max_concurrent is set
-        @semaphore = (Concurrent::Semaphore.new(@config[:max_concurrent]) if @config[:max_concurrent])
-
-        super() # Initialize state machine
-        restore_status_from_storage if @storage
-
-        # Register with global registry unless auto_register is disabled
-        BreakerMachines::Registry.instance.register(self) unless @config[:auto_register] == false
-      end
-
       private
 
       def default_config
@@ -78,8 +54,12 @@ module BreakerMachines
         when :null
           BreakerMachines::Storage::Null.new
         else
-          # Allow for custom storage class names
-          BreakerMachines.config.default_storage.new
+          # Allow for custom storage class names or instances
+          if BreakerMachines.config.default_storage.respond_to?(:new)
+            BreakerMachines.config.default_storage.new
+          else
+            BreakerMachines.config.default_storage
+          end
         end
       end
     end

data/lib/breaker_machines/circuit/coordinated_state_management.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  class Circuit
+    # CoordinatedStateManagement extends the base state machine with coordinated guards
+    # that allow circuits to make transitions based on the state of other circuits.
+    module CoordinatedStateManagement
+      extend ActiveSupport::Concern
+
+      included do
+        # Override the state machine to add coordinated guards
+        state_machine :status, initial: :closed do
+          event :trip do
+            transition closed: :open
+            transition half_open: :open
+          end
+
+          event :attempt_recovery do
+            transition open: :half_open,
+                       if: ->(circuit) { circuit.recovery_allowed? }
+          end
+
+          event :reset do
+            transition %i[open half_open] => :closed,
+                       if: ->(circuit) { circuit.reset_allowed? }
+            transition closed: :closed
+          end
+
+          event :force_open do
+            transition any => :open
+          end
+
+          event :force_close do
+            transition any => :closed
+          end
+
+          event :hard_reset do
+            transition any => :closed
+          end
+
+          before_transition on: :hard_reset do |circuit|
+            circuit.storage.clear(circuit.name) if circuit.storage
+            circuit.half_open_attempts.value = 0
+            circuit.half_open_successes.value = 0
+          end
+
+          after_transition to: :open do |circuit|
+            circuit.send(:on_circuit_open)
+          end
+
+          after_transition to: :closed do |circuit|
+            circuit.send(:on_circuit_close)
+          end
+
+          after_transition from: :open, to: :half_open do |circuit|
+            circuit.send(:on_circuit_half_open)
+          end
+        end
+      end
+
+      # Check if this circuit can attempt recovery
+      # For cascading circuits, this checks if dependent circuits allow it
+      def recovery_allowed?
+        return true unless respond_to?(:dependent_circuits) && dependent_circuits.any?
+
+        # Don't attempt recovery if any critical dependencies are still down
+        !has_critical_dependencies_down?
+      end
+
+      # Check if this circuit can reset to closed
+      # For cascading circuits, ensures dependencies are healthy
+      def reset_allowed?
+        return true unless respond_to?(:dependent_circuits) && dependent_circuits.any?
+
+        # Only reset if all dependencies are in acceptable states
+        all_dependencies_healthy?
+      end
+
+      private
+
+      # Check if any critical dependencies are down
+      def has_critical_dependencies_down?
+        return false unless respond_to?(:dependent_circuits)
+
+        dependent_circuits.any? do |circuit_name|
+          circuit = find_dependent_circuit(circuit_name)
+          circuit&.open?
+        end
+      end
+
+      # Check if all dependencies are in healthy states
+      def all_dependencies_healthy?
+        return true unless respond_to?(:dependent_circuits)
+
+        dependent_circuits.all? do |circuit_name|
+          circuit = find_dependent_circuit(circuit_name)
+          circuit.nil? || circuit.closed? || circuit.half_open?
+        end
+      end
+
+      # Find a dependent circuit by name
+      def find_dependent_circuit(circuit_name)
+        # First try registry
+        circuit = BreakerMachines.registry.find(circuit_name)
+
+        # If not found and we have an owner, try to get it from the owner
+        if !circuit && @config[:owner]
+          owner = @config[:owner]
+          owner = owner.__getobj__ if owner.is_a?(WeakRef)
+          circuit = owner.circuit(circuit_name) if owner.respond_to?(:circuit)
+        end
+
+        circuit
+      end
+    end
+  end
+end

data/lib/breaker_machines/circuit/hedged_execution.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require 'concurrent'
+require 'timeout'
+
+module BreakerMachines
+  class Circuit
+    # HedgedExecution provides hedged request functionality for circuit breakers
+    # Hedged requests improve latency by sending duplicate requests to multiple backends
+    # and returning the first successful response
+    module HedgedExecution
+      extend ActiveSupport::Concern
+
+      # Execute a hedged request pattern
+      def execute_hedged(&)
+        return execute_single_hedged(&) unless @config[:backends]&.any?
+
+        execute_multi_backend_hedged
+      end
+
+      private
+
+      # Execute hedged request with a single backend (original block)
+      def execute_single_hedged(&block)
+        return yield unless hedged_requests_enabled?
+
+        max_requests = @config[:max_hedged_requests] || 2
+        delay_ms = @config[:hedging_delay] || 50
+
+        if @config[:fiber_safe]
+          execute_hedged_async(Array.new(max_requests) { block }, delay_ms)
+        else
+          execute_hedged_sync(Array.new(max_requests) { block }, delay_ms)
+        end
+      end
+
+      # Execute hedged requests across multiple backends
+      def execute_multi_backend_hedged
+        backends = @config[:backends]
+        return backends.first.call if backends.size == 1
+
+        if @config[:fiber_safe]
+          execute_hedged_async(backends, @config[:hedging_delay] || 0)
+        else
+          execute_hedged_sync(backends, @config[:hedging_delay] || 0)
+        end
+      end
+
+      # Synchronous hedged execution using threads
+      def execute_hedged_sync(callables, delay_ms)
+        result_queue = Queue.new
+        error_queue = Queue.new
+        threads = []
+        cancelled = Concurrent::AtomicBoolean.new(false)
+
+        callables.each_with_index do |callable, index|
+          # Add delay for hedge requests (not the first one)
+          sleep(delay_ms / 1000.0) if index.positive? && delay_ms.positive?
+
+          # Skip if already got a result
+          break if cancelled.value
+
+          threads << Thread.new do
+            unless cancelled.value
+              begin
+                result = callable.call
+                result_queue << result unless cancelled.value
+                cancelled.value = true
+              rescue StandardError => e
+                error_queue << e unless cancelled.value
+              end
+            end
+          end
+        end
+
+        # Wait for first result or all errors
+        begin
+          Timeout.timeout(@config[:timeout] || 30) do
+            # Check for successful result
+            loop do
+              unless result_queue.empty?
+                result = result_queue.pop
+                cancelled.value = true
+                return result
+              end
+
+              # Check if all requests failed
+              raise error_queue.pop if error_queue.size >= callables.size
+
+              # Small sleep to prevent busy waiting
+              sleep 0.001
+            end
+          end
+        ensure
+          # Cancel remaining threads
+          cancelled.value = true
+          threads.each(&:kill)
+        end
+      end
+
+      # Async hedged execution (requires async support)
+      def execute_hedged_async(callables, delay_ms)
+        # This will be implemented when async support is loaded
+        # For now, fall back to sync implementation
+        return execute_hedged_sync(callables, delay_ms) unless respond_to?(:execute_hedged_with_async)
+
+        execute_hedged_with_async(callables, delay_ms)
+      end
+
+      def hedged_requests_enabled?
+        @config[:hedged_requests] == true
+      end
+    end
+  end
+end

data/lib/breaker_machines/circuit/introspection.rb

@@ -6,6 +6,7 @@ module BreakerMachines
     # and generating human-readable summaries of circuit status.
     module Introspection
       extend ActiveSupport::Concern
+
       # State check methods are automatically generated by state_machines:
       # - open? (returns true when status == :open)
       # - closed? (returns true when status == :closed)

data/lib/breaker_machines/circuit/state_callbacks.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  class Circuit
+    # StateCallbacks provides the common callback methods shared by all state management modules
+    module StateCallbacks
+      extend ActiveSupport::Concern
+
+      private
+
+      def on_circuit_open
+        @opened_at.value = BreakerMachines.monotonic_time
+        @storage&.set_status(@name, :open, @opened_at.value)
+        if @storage.respond_to?(:record_event_with_details)
+          @storage.record_event_with_details(@name, :state_change, 0,
+                                             new_state: :open)
+        end
+        invoke_callback(:on_open)
+        BreakerMachines.instrument('opened', circuit: @name)
+      end
+
+      def on_circuit_close
+        @opened_at.value = nil
+        @last_error.value = nil
+        @last_failure_at.value = nil
+        @storage&.set_status(@name, :closed)
+        if @storage.respond_to?(:record_event_with_details)
+          @storage.record_event_with_details(@name, :state_change, 0,
+                                             new_state: :closed)
+        end
+        invoke_callback(:on_close)
+        BreakerMachines.instrument('closed', circuit: @name)
+      end
+
+      def on_circuit_half_open
+        @half_open_attempts.value = 0
+        @half_open_successes.value = 0
+        @storage&.set_status(@name, :half_open)
+        if @storage.respond_to?(:record_event_with_details)
+          @storage.record_event_with_details(@name, :state_change, 0,
+                                             new_state: :half_open)
+        end
+        invoke_callback(:on_half_open)
+        BreakerMachines.instrument('half_opened', circuit: @name)
+      end
+
+      def reset_timeout_elapsed?
+        return false unless @opened_at.value
+
+        # Add jitter to prevent thundering herd
+        jitter_factor = @config[:reset_timeout_jitter] || 0.25
+        # Calculate random jitter between -jitter_factor and +jitter_factor
+        jitter_multiplier = 1.0 + (((rand * 2) - 1) * jitter_factor)
+        timeout_with_jitter = @config[:reset_timeout] * jitter_multiplier
+
+        BreakerMachines.monotonic_time - @opened_at.value >= timeout_with_jitter
+      end
+    end
+  end
+end

data/lib/breaker_machines/circuit/state_management.rb

@@ -6,6 +6,7 @@ module BreakerMachines
     # managing transitions between closed, open, and half-open states.
     module StateManagement
       extend ActiveSupport::Concern
+
       included do
         state_machine :status, initial: :closed do
           event :trip do
@@ -30,77 +31,29 @@ module BreakerMachines
             transition any => :closed
           end
 
-          after_transition any => :open do |circuit|
+          event :hard_reset do
+            transition any => :closed
+          end
+
+          before_transition on: :hard_reset do |circuit|
+            circuit.storage.clear(circuit.name) if circuit.storage
+            circuit.half_open_attempts.value = 0
+            circuit.half_open_successes.value = 0
+          end
+
+          after_transition to: :open do |circuit|
             circuit.send(:on_circuit_open)
           end
 
-          after_transition any => :closed do |circuit|
+          after_transition to: :closed do |circuit|
             circuit.send(:on_circuit_close)
           end
 
-          after_transition open: :half_open do |circuit|
+          after_transition from: :open, to: :half_open do |circuit|
             circuit.send(:on_circuit_half_open)
           end
         end
       end
-
-      private
-
-      def on_circuit_open
-        @opened_at.value = BreakerMachines.monotonic_time
-        @storage&.set_status(@name, :open, @opened_at.value)
-        if @storage.respond_to?(:record_event_with_details)
-          @storage.record_event_with_details(@name, :state_change, 0,
-                                             new_state: :open)
-        end
-        invoke_callback(:on_open)
-        BreakerMachines.instrument('opened', circuit: @name)
-      end
-
-      def on_circuit_close
-        @opened_at.value = nil
-        @last_error.value = nil
-        @last_failure_at.value = nil
-        @storage&.set_status(@name, :closed)
-        if @storage.respond_to?(:record_event_with_details)
-          @storage.record_event_with_details(@name, :state_change, 0,
-                                             new_state: :closed)
-        end
-        invoke_callback(:on_close)
-        BreakerMachines.instrument('closed', circuit: @name)
-      end
-
-      def on_circuit_half_open
-        @half_open_attempts.value = 0
-        @half_open_successes.value = 0
-        @storage&.set_status(@name, :half_open)
-        if @storage.respond_to?(:record_event_with_details)
-          @storage.record_event_with_details(@name, :state_change, 0,
-                                             new_state: :half_open)
-        end
-        invoke_callback(:on_half_open)
-        BreakerMachines.instrument('half_opened', circuit: @name)
-      end
-
-      def restore_status_from_storage
-        stored_status = @storage.get_status(@name)
-        return unless stored_status
-
-        self.status = stored_status.status.to_s
-        @opened_at.value = stored_status.opened_at if stored_status.opened_at
-      end
-
-      def reset_timeout_elapsed?
-        return false unless @opened_at.value
-
-        # Add jitter to prevent thundering herd
-        jitter_factor = @config[:reset_timeout_jitter] || 0.25
-        # Calculate random jitter between -jitter_factor and +jitter_factor
-        jitter_multiplier = 1.0 + (((rand * 2) - 1) * jitter_factor)
-        timeout_with_jitter = @config[:reset_timeout] * jitter_multiplier
-
-        BreakerMachines.monotonic_time - @opened_at.value >= timeout_with_jitter
-      end
     end
   end
 end

data/lib/breaker_machines/circuit.rb

@@ -1,14 +1,8 @@
 # frozen_string_literal: true
 
-require 'concurrent-ruby'
-
 module BreakerMachines
   class Circuit
+    include Circuit::Base
     include StateManagement
-    include Configuration
-    include Execution
-    include HedgedExecution
-    include Introspection
-    include Callbacks
   end
 end

data/lib/breaker_machines/circuit_group.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  # CircuitGroup provides coordinated management of multiple related circuits
+  # with support for dependencies, shared configuration, and group-wide operations
+  class CircuitGroup
+    include BreakerMachines::DSL
+
+    attr_reader :name, :circuits, :dependencies, :config
+
+    def initialize(name, config = {})
+      @name = name
+      @config = config
+      @circuits = {}
+      @dependencies = {}
+      @async_mode = config[:async_mode] || false
+    end
+
+    # Define a circuit within this group with optional dependencies
+    # @param name [Symbol] Circuit name
+    # @param options [Hash] Circuit configuration
+    # @option options [Symbol, Array<Symbol>] :depends_on Other circuits this one depends on
+    # @option options [Proc] :guard_with Additional guard conditions
+    def circuit(name, options = {}, &)
+      depends_on = Array(options.delete(:depends_on))
+      guard_proc = options.delete(:guard_with)
+
+      # Add group-wide defaults
+      circuit_config = @config.merge(options)
+
+      # Create appropriate circuit type
+      circuit_class = if options[:cascades_to] || depends_on.any?
+                        BreakerMachines::CascadingCircuit
+                      elsif @async_mode
+                        BreakerMachines::AsyncCircuit
+                      else
+                        BreakerMachines::Circuit
+                      end
+
+      # Build the circuit
+      circuit_instance = if block_given?
+                           builder = BreakerMachines::DSL::CircuitBuilder.new
+                           builder.instance_eval(&)
+                           built_config = builder.config.merge(circuit_config)
+                           circuit_class.new(full_circuit_name(name), built_config)
+                         else
+                           circuit_class.new(full_circuit_name(name), circuit_config)
+                         end
+
+      # Store dependencies and guards
+      if depends_on.any? || guard_proc
+        @dependencies[name] = {
+          depends_on: depends_on,
+          guard: guard_proc
+        }
+
+        # Wrap the circuit with dependency checking
+        circuit_instance = DependencyWrapper.new(circuit_instance, self, name)
+      end
+
+      @circuits[name] = circuit_instance
+      BreakerMachines.register(circuit_instance)
+      circuit_instance
+    end
+
+    # Get a circuit by name
+    def [](name)
+      @circuits[name]
+    end
+
+    # Check if all circuits in the group are healthy
+    def all_healthy?
+      @circuits.values.all? { |circuit| circuit.closed? || circuit.half_open? }
+    end
+
+    # Check if any circuit in the group is open
+    def any_open?
+      @circuits.values.any?(&:open?)
+    end
+
+    # Get status of all circuits
+    def status
+      @circuits.transform_values(&:status_name)
+    end
+
+    # Reset all circuits in the group
+    def reset_all!
+      @circuits.each_value(&:reset!)
+    end
+
+    # Force open all circuits
+    def trip_all!
+      @circuits.each_value(&:force_open!)
+    end
+
+    # Check dependencies for a specific circuit
+    def dependencies_met?(circuit_name)
+      deps = @dependencies[circuit_name]
+      return true unless deps
+
+      depends_on = deps[:depends_on]
+      guard = deps[:guard]
+
+      # Check circuit dependencies recursively
+      dependencies_healthy = depends_on.all? do |dep_name|
+        dep_circuit = @circuits[dep_name]
+        # Circuit must exist, be healthy, AND have its own dependencies met
+        dep_circuit && (dep_circuit.closed? || dep_circuit.half_open?) && dependencies_met?(dep_name)
+      end
+
+      # Check custom guard
+      guard_passed = guard ? guard.call : true
+
+      dependencies_healthy && guard_passed
+    end
+
+    private
+
+    def full_circuit_name(name)
+      "#{@name}.#{name}"
+    end
+
+    # Wrapper to enforce dependencies
+    class DependencyWrapper < SimpleDelegator
+      def initialize(circuit, group, name)
+        super(circuit)
+        @group = group
+        @name = name
+      end
+
+      def call(&)
+        unless @group.dependencies_met?(@name)
+          raise BreakerMachines::CircuitDependencyError.new(__getobj__.name,
+                                                            "Dependencies not met for circuit #{@name}")
+        end
+
+        __getobj__.call(&)
+      end
+
+      def attempt_recovery!
+        return false unless @group.dependencies_met?(@name)
+
+        __getobj__.attempt_recovery!
+      end
+
+      def reset!
+        return false unless @group.dependencies_met?(@name)
+
+        __getobj__.reset!
+      end
+    end
+  end
+end

data/lib/breaker_machines/coordinated_circuit.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  # CoordinatedCircuit is a base class for circuits that need coordinated state management.
+  # It replaces the standard StateManagement module with CoordinatedStateManagement
+  # to enable state transitions based on other circuits' states.
+  class CoordinatedCircuit < Circuit
+    include Circuit::CoordinatedStateManagement
+  end
+end

data/lib/breaker_machines/dsl.rb

@@ -122,7 +122,7 @@ module BreakerMachines
         instance_registry.each do |weak_ref|
           instance = weak_ref.__getobj__
           circuit_instances = instance.instance_variable_get(:@circuit_instances)
-          circuit_instances&.each_value(&:reset)
+          circuit_instances&.each_value(&:hard_reset!)
         rescue WeakRef::RefError
           # Instance was garbage collected, skip it
         end
@@ -262,7 +262,7 @@ module BreakerMachines
 
     # Reset all circuits for this instance
     def reset_all_circuits
-      circuit_instances.each_value(&:reset)
+      circuit_instances.each_value(&:hard_reset!)
     end
 
     # Remove a global dynamic circuit by name

data/lib/breaker_machines/errors.rb

@@ -14,6 +14,16 @@ module BreakerMachines
     end
   end
 
+  # Raised when a circuit cannot be called due to unmet dependencies
+  class CircuitDependencyError < CircuitOpenError
+    def initialize(circuit_name, message = nil)
+      @circuit_name = circuit_name
+      @opened_at = nil
+      super_message = message || "Circuit '#{circuit_name}' cannot be called: dependencies not met"
+      Error.instance_method(:initialize).bind(self).call(super_message)
+    end
+  end
+
   # Raised when a circuit-protected call exceeds the configured timeout
   class CircuitTimeoutError < Error
     attr_reader :circuit_name, :timeout
@@ -48,4 +58,14 @@ module BreakerMachines
       super("Circuit '#{circuit_name}' rejected call: max concurrent limit of #{max_concurrent} reached")
     end
   end
+
+  # Raised when all parallel fallbacks fail
+  class ParallelFallbackError < Error
+    attr_reader :errors
+
+    def initialize(message, errors)
+      @errors = errors
+      super(message)
+    end
+  end
 end

data/lib/breaker_machines/hedged_async_support.rb

@@ -2,10 +2,12 @@
 
 # This file contains async support for hedged execution
 # It is only loaded when fiber_safe mode is enabled
+# Requires async gem ~> 2.31.0 for Promise and modern API features
 
 require 'async'
 require 'async/task'
-require 'async/condition'
+require 'async/promise'
+require 'async/barrier'
 require 'concurrent'
 
 module BreakerMachines
@@ -43,53 +45,44 @@ module BreakerMachines
     private
 
     # Race callables; return first result or raise if it was an Exception
-    # Uses Async::Condition to signal the winner instead of an Async::Channel.
+    # Uses modern Async::Promise and Async::Barrier for cleaner synchronization
     # @param callables [Array<Proc>] Tasks to race
     # @param delay_ms [Integer] Delay in milliseconds between task starts
     # @return [Object] First successful result
     # @raise [Exception] The first exception received
     def race_tasks(callables, delay_ms: 0)
-      Async do |parent|
-        mutex     = Mutex.new
-        condition = Async::Condition.new
-        winner    = nil
-        exception = nil
+      promise = Async::Promise.new
+      barrier = Async::Barrier.new
 
-        tasks = callables.map.with_index do |callable, idx|
-          parent.async do |task|
-            # stagger hedged attempts
-            task.sleep(delay_ms / 1000.0) if idx.positive? && delay_ms.positive?
+      begin
+        result = Async do
+          callables.each_with_index do |callable, idx|
+            barrier.async do
+              # stagger hedged attempts
+              sleep(delay_ms / 1000.0) if idx.positive? && delay_ms.positive?
 
-            begin
-              res = callable.call
-              mutex.synchronize do
-                next if winner || exception
-
-                winner = res
-                condition.signal
-              end
-            rescue StandardError => e
-              mutex.synchronize do
-                next if winner || exception
-
-                exception = e
-                condition.signal
+              begin
+                result = callable.call
+                # Try to resolve the promise with this result
+                # Only the first resolution will succeed
+                promise.resolve(result) unless promise.resolved?
+              rescue StandardError => e
+                # Only set exception if no result has been resolved yet
+                promise.resolve(e) unless promise.resolved?
               end
             end
           end
-        end
 
-        # block until first signal
-        condition.wait
+          # Wait for the first resolution (either success or exception)
+          promise.wait
+        end.wait
 
-        # tear down
-        tasks.each(&:stop)
-
-        # propagate
-        raise(exception) if exception
-
-        winner
-      end.wait
+        # If result is an exception, raise it; otherwise return the result
+        result.is_a?(StandardError) ? raise(result) : result
+      ensure
+        # Ensure all tasks are stopped
+        barrier&.stop
+      end
     end
   end
 end

data/lib/breaker_machines/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BreakerMachines
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 end

data/lib/breaker_machines.rb

@@ -14,6 +14,7 @@ loader.ignore("#{__dir__}/breaker_machines/types.rb")
 loader.ignore("#{__dir__}/breaker_machines/console.rb")
 loader.ignore("#{__dir__}/breaker_machines/async_support.rb")
 loader.ignore("#{__dir__}/breaker_machines/hedged_async_support.rb")
+loader.ignore("#{__dir__}/breaker_machines/circuit/async_state_management.rb")
 loader.setup
 
 # BreakerMachines provides a thread-safe implementation of the Circuit Breaker pattern
@@ -81,6 +82,22 @@ module BreakerMachines
       Registry.instance
     end
 
+    # Register a circuit with the global registry
+    def register(circuit)
+      registry.register(circuit)
+    end
+
+    # Reset the registry and configurations (useful for testing)
+    def reset!
+      registry.clear
+      config.default_storage = :bucket_memory
+      config.default_timeout = nil
+      config.default_reset_timeout = 60.seconds
+      config.default_failure_threshold = 5
+      config.log_events = true
+      config.fiber_safe = false
+    end
+
     # Returns the current monotonic time in seconds.
     # Monotonic time is guaranteed to always increase and is not affected
     # by system clock adjustments, making it ideal for measuring durations.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: breaker_machines
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Abdelkader Boudih
@@ -43,14 +43,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.50.0
+        version: 0.100.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.50.0
+        version: 0.100.0
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -108,15 +108,23 @@ files:
 - LICENSE.txt
 - README.md
 - lib/breaker_machines.rb
+- lib/breaker_machines/async_circuit.rb
 - lib/breaker_machines/async_support.rb
 - lib/breaker_machines/cascading_circuit.rb
 - lib/breaker_machines/circuit.rb
+- lib/breaker_machines/circuit/async_state_management.rb
+- lib/breaker_machines/circuit/base.rb
 - lib/breaker_machines/circuit/callbacks.rb
 - lib/breaker_machines/circuit/configuration.rb
+- lib/breaker_machines/circuit/coordinated_state_management.rb
 - lib/breaker_machines/circuit/execution.rb
+- lib/breaker_machines/circuit/hedged_execution.rb
 - lib/breaker_machines/circuit/introspection.rb
+- lib/breaker_machines/circuit/state_callbacks.rb
 - lib/breaker_machines/circuit/state_management.rb
+- lib/breaker_machines/circuit_group.rb
 - lib/breaker_machines/console.rb
+- lib/breaker_machines/coordinated_circuit.rb
 - lib/breaker_machines/dsl.rb
 - lib/breaker_machines/dsl/cascading_circuit_builder.rb
 - lib/breaker_machines/dsl/circuit_builder.rb
@@ -124,7 +132,6 @@ files:
 - lib/breaker_machines/dsl/parallel_fallback_wrapper.rb
 - lib/breaker_machines/errors.rb
 - lib/breaker_machines/hedged_async_support.rb
-- lib/breaker_machines/hedged_execution.rb
 - lib/breaker_machines/registry.rb
 - lib/breaker_machines/storage.rb
 - lib/breaker_machines/storage/backend_state.rb

data/lib/breaker_machines/hedged_execution.rb

@@ -1,113 +0,0 @@
-# frozen_string_literal: true
-
-require 'concurrent'
-require 'timeout'
-
-module BreakerMachines
-  # HedgedExecution provides hedged request functionality for circuit breakers
-  # Hedged requests improve latency by sending duplicate requests to multiple backends
-  # and returning the first successful response
-  module HedgedExecution
-    extend ActiveSupport::Concern
-
-    # Execute a hedged request pattern
-    def execute_hedged(&)
-      return execute_single_hedged(&) unless @config[:backends]&.any?
-
-      execute_multi_backend_hedged
-    end
-
-    private
-
-    # Execute hedged request with a single backend (original block)
-    def execute_single_hedged(&block)
-      return yield unless hedged_requests_enabled?
-
-      max_requests = @config[:max_hedged_requests] || 2
-      delay_ms = @config[:hedging_delay] || 50
-
-      if @config[:fiber_safe]
-        execute_hedged_async(Array.new(max_requests) { block }, delay_ms)
-      else
-        execute_hedged_sync(Array.new(max_requests) { block }, delay_ms)
-      end
-    end
-
-    # Execute hedged requests across multiple backends
-    def execute_multi_backend_hedged
-      backends = @config[:backends]
-      return backends.first.call if backends.size == 1
-
-      if @config[:fiber_safe]
-        execute_hedged_async(backends, @config[:hedging_delay] || 0)
-      else
-        execute_hedged_sync(backends, @config[:hedging_delay] || 0)
-      end
-    end
-
-    # Synchronous hedged execution using threads
-    def execute_hedged_sync(callables, delay_ms)
-      result_queue = Queue.new
-      error_queue = Queue.new
-      threads = []
-      cancelled = Concurrent::AtomicBoolean.new(false)
-
-      callables.each_with_index do |callable, index|
-        # Add delay for hedge requests (not the first one)
-        sleep(delay_ms / 1000.0) if index.positive? && delay_ms.positive?
-
-        # Skip if already got a result
-        break if cancelled.value
-
-        threads << Thread.new do
-          unless cancelled.value
-            begin
-              result = callable.call
-              result_queue << result unless cancelled.value
-              cancelled.value = true
-            rescue StandardError => e
-              error_queue << e unless cancelled.value
-            end
-          end
-        end
-      end
-
-      # Wait for first result or all errors
-      begin
-        Timeout.timeout(@config[:timeout] || 30) do
-          # Check for successful result
-          loop do
-            unless result_queue.empty?
-              result = result_queue.pop
-              cancelled.value = true
-              return result
-            end
-
-            # Check if all requests failed
-            raise error_queue.pop if error_queue.size >= callables.size
-
-            # Small sleep to prevent busy waiting
-            sleep 0.001
-          end
-        end
-      ensure
-        # Cancel remaining threads
-        cancelled.value = true
-        threads.each(&:kill)
-      end
-    end
-
-    # Async hedged execution (requires async support)
-    def execute_hedged_async(callables, delay_ms)
-      # This will be implemented when async support is loaded
-      # For now, fall back to sync implementation
-      return execute_hedged_sync(callables, delay_ms) unless respond_to?(:execute_hedged_with_async)
-
-      execute_hedged_with_async(callables, delay_ms)
-    end
-
-    def hedged_requests_enabled?
-      @config[:hedged_requests] == true
-    end
-  end
-end