breaker_machines 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e76d6f4335010b14f4ee48ac1366c060bd6b5feaad379896d857856c3dc6a2d
-  data.tar.gz: d7f48bec133630d584387aaa56df9c3cd3884e8f9771353e8df7e214b8df7431
+  metadata.gz: 97bc515f00b4402af03e813a121969745726a3635a8475bd3066877294f535a0
+  data.tar.gz: 20370133d03443108818133a98790194a4669a5b9daafdb1808d537b3915bb32
 SHA512:
-  metadata.gz: f98f52400de806bb0df4784d0635560764600ba812b5bc7e99c5eebc8f4ab1d884890d08ca399e458d1f5ca4a1b9192be46562e9b3c66aa311923f0a59f58604
-  data.tar.gz: c5349911ce027af37b0c41557feb9c0126a1d6d11539650e48f8151855bd7512a859711f0335e9934c18abd879ce28b39adde778bc85d751cdd89728a3c768af
+  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'
@@ -18,7 +19,7 @@ module BreakerMachines
 
     # Execute a call with async support (fiber-safe mode)
     def execute_call_async(&)
-      start_time = monotonic_time
+      start_time = BreakerMachines.monotonic_time
 
       begin
         # Execute with hedged requests if enabled
@@ -28,14 +29,14 @@ module BreakerMachines
                    execute_with_async_timeout(@config[:timeout], &)
                  end
 
-        record_success(monotonic_time - start_time)
+        record_success(BreakerMachines.monotonic_time - start_time)
         handle_success
         result
       rescue StandardError => e
         # Re-raise if it's not an async timeout or configured exception
         raise unless e.is_a?(async_timeout_error_class) || @config[:exceptions].any? { |klass| e.is_a?(klass) }
 
-        record_failure(monotonic_time - start_time, e)
+        record_failure(BreakerMachines.monotonic_time - start_time, e)
         handle_failure
         raise unless @config[:fallback]
 
@@ -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

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require_relative 'coordinated_circuit'
+
+module BreakerMachines
+  # 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.
+  #
+  # @example Starship network dependency
+  #   # Network circuit that cascades to dependent systems
+  #   network_circuit = BreakerMachines::CascadingCircuit.new('subspace_network', {
+  #     failure_threshold: 1,
+  #     cascades_to: ['weapons_targeting', 'navigation_sensors', 'communications'],
+  #     emergency_protocol: :red_alert
+  #   })
+  #
+  #   # When network fails, all dependent systems are automatically tripped
+  #   network_circuit.call { raise 'Subspace relay offline!' }
+  #   # => All dependent circuits are now open
+  #
+  class CascadingCircuit < CoordinatedCircuit
+    attr_reader :dependent_circuits, :emergency_protocol
+
+    def initialize(name, config = {})
+      @dependent_circuits = Array(config.delete(:cascades_to))
+      @emergency_protocol = config.delete(:emergency_protocol)
+
+      super
+    end
+
+    # Override the trip method to include cascading behavior
+    def trip!
+      result = super
+      perform_cascade if result && @dependent_circuits.any?
+      result
+    end
+
+    # Force cascade failure to all dependent circuits
+    def cascade_failure!
+      perform_cascade
+    end
+
+    # Get the current status of all dependent circuits
+    def dependent_status
+      return {} if @dependent_circuits.empty?
+
+      @dependent_circuits.each_with_object({}) do |circuit_name, status|
+        circuit = BreakerMachines.registry.find(circuit_name)
+        status[circuit_name] = circuit ? circuit.status_name : :not_found
+      end
+    end
+
+    # Check if any dependent circuits are open
+    def dependents_compromised?
+      @dependent_circuits.any? do |circuit_name|
+        circuit = BreakerMachines.registry.find(circuit_name)
+        circuit&.open?
+      end
+    end
+
+    # Summary that includes cascade information
+    def summary
+      base_summary = super
+      return base_summary if @dependent_circuits.empty?
+
+      if @cascade_triggered_at&.value
+        compromised_count = dependent_status.values.count(:open)
+        " CASCADE TRIGGERED: #{compromised_count}/#{@dependent_circuits.length} dependent systems compromised."
+      else
+        " Monitoring #{@dependent_circuits.length} dependent systems."
+      end
+
+      base_summary + cascade_info_text
+    end
+
+    # Provide cascade info for introspection
+    def cascade_info
+      BreakerMachines::CascadeInfo.new(
+        dependent_circuits: @dependent_circuits,
+        emergency_protocol: @emergency_protocol,
+        cascade_triggered_at: @cascade_triggered_at&.value,
+        dependent_status: dependent_status
+      )
+    end
+
+    private
+
+    def perform_cascade
+      return if @dependent_circuits.empty?
+
+      cascade_results = []
+      @cascade_triggered_at ||= Concurrent::AtomicReference.new
+      @cascade_triggered_at.value = BreakerMachines.monotonic_time
+
+      @dependent_circuits.each do |circuit_name|
+        # First try to find circuit in 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]
+          # Handle WeakRef if present
+          owner = owner.__getobj__ if owner.is_a?(WeakRef)
+
+          circuit = owner.circuit(circuit_name) if owner.respond_to?(:circuit)
+        end
+
+        next unless circuit
+        next unless circuit.closed? || circuit.half_open?
+
+        # Force the dependent circuit to open
+        circuit.force_open!
+        cascade_results << circuit_name
+
+        BreakerMachines.instrument('cascade_failure', {
+                                     source_circuit: @name,
+                                     target_circuit: circuit_name,
+                                     emergency_protocol: @emergency_protocol
+                                   })
+      end
+
+      # Trigger emergency protocol if configured
+      trigger_emergency_protocol(cascade_results) if @emergency_protocol && cascade_results.any?
+
+      # Invoke cascade callback if configured
+      if @config[:on_cascade]
+        begin
+          @config[:on_cascade].call(cascade_results) if @config[:on_cascade].respond_to?(:call)
+        rescue StandardError => e
+          # Log callback error but don't fail the cascade
+          BreakerMachines.logger&.error "Cascade callback error: #{e.message}"
+        end
+      end
+
+      cascade_results
+    end
+
+    def trigger_emergency_protocol(affected_circuits)
+      BreakerMachines.instrument('emergency_protocol_triggered', {
+                                   protocol: @emergency_protocol,
+                                   source_circuit: @name,
+                                   affected_circuits: affected_circuits
+                                 })
+
+      # Allow custom emergency protocol handling
+      owner = @config[:owner]
+      if owner.respond_to?(@emergency_protocol, true)
+        begin
+          owner.send(@emergency_protocol, affected_circuits)
+        rescue StandardError => e
+          BreakerMachines.logger&.error "Emergency protocol error: #{e.message}"
+        end
+      elsif respond_to?(@emergency_protocol, true)
+        begin
+          send(@emergency_protocol, affected_circuits)
+        rescue StandardError => e
+          BreakerMachines.logger&.error "Emergency protocol error: #{e.message}"
+        end
+      end
+    end
+
+    # Override the on_circuit_open callback to include cascading
+    def on_circuit_open
+      super # Call the original implementation
+      perform_cascade if @dependent_circuits.any?
+    end
+
+    # Force open should also cascade
+    def force_open!
+      result = super
+      perform_cascade if result && @dependent_circuits.any?
+      result
+    end
+  end
+end

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