breaker_machines 0.4.0 → 0.6.0

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)
+            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,59 @@
+# 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
+
+        # name/config/opened_at readers are defined in Circuit::Configuration
+        attr_reader :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: lambda(&:recovery_allowed?)
+          end
+
+          event :reset do
+            transition %i[open half_open] => :closed,
+                       if: lambda(&: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)
+            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/native.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  class Circuit
+    # Native circuit breaker implementation using Rust FFI
+    #
+    # This provides a high-performance circuit breaker with state machine logic
+    # implemented in Rust. It's fully compatible with the Ruby circuit API but
+    # significantly faster for high-throughput scenarios.
+    #
+    # @example Basic usage
+    #   circuit = BreakerMachines::Circuit::Native.new('api_calls',
+    #     failure_threshold: 5,
+    #     failure_window_secs: 60.0
+    #   )
+    #
+    #   circuit.call { api.fetch_data }
+    class Native
+      # @return [String] Circuit name
+      attr_reader :name
+
+      # @return [Hash] Circuit configuration
+      attr_reader :config
+
+      # Create a new native circuit breaker
+      #
+      # @param name [String] Circuit name
+      # @param options [Hash] Configuration options
+      # @option options [Integer] :failure_threshold Number of failures to open circuit (default: 5)
+      # @option options [Float] :failure_window_secs Time window for counting failures (default: 60.0)
+      # @option options [Float] :half_open_timeout_secs Timeout before attempting reset (default: 30.0)
+      # @option options [Integer] :success_threshold Successes needed to close from half-open (default: 2)
+      # @option options [Boolean] :auto_register Register with global registry (default: true)
+      def initialize(name, options = {})
+        unless BreakerMachines.native_available?
+          raise BreakerMachines::ConfigurationError,
+                'Native extension not available. Install with native support or use Circuit::Ruby'
+        end
+
+        @name = name
+        @config = default_config.merge(options)
+
+        # Create the native circuit breaker
+        @native_circuit = BreakerMachinesNative::Circuit.new(
+          name,
+          {
+            failure_threshold: @config[:failure_threshold],
+            failure_window_secs: @config[:failure_window_secs],
+            half_open_timeout_secs: @config[:half_open_timeout_secs],
+            success_threshold: @config[:success_threshold]
+          }
+        )
+
+        # Register with global registry unless disabled
+        BreakerMachines::Registry.instance.register(self) unless @config[:auto_register] == false
+      end
+
+      # Execute a block with circuit breaker protection
+      #
+      # @yield Block to execute
+      # @return Result of the block
+      # @raise [CircuitOpenError] if circuit is open
+      def call
+        raise CircuitOpenError, "Circuit '#{@name}' is open" if open?
+
+        start_time = BreakerMachines.monotonic_time
+        begin
+          result = yield
+          duration = BreakerMachines.monotonic_time - start_time
+          @native_circuit.record_success(duration)
+          result
+        rescue StandardError => _e
+          duration = BreakerMachines.monotonic_time - start_time
+          @native_circuit.record_failure(duration)
+          raise
+        end
+      end
+
+      # Check if circuit is open
+      # @return [Boolean]
+      def open?
+        @native_circuit.is_open
+      end
+
+      # Check if circuit is closed
+      # @return [Boolean]
+      def closed?
+        @native_circuit.is_closed
+      end
+
+      # Get current state name
+      # @return [String] 'open' or 'closed'
+      def state
+        @native_circuit.state_name
+      end
+
+      # Reset the circuit (clear all events)
+      def reset!
+        @native_circuit.reset
+      end
+
+      # Get circuit status for inspection
+      # @return [Hash] Status information
+      def status
+        {
+          name: @name,
+          state: state,
+          open: open?,
+          closed: closed?,
+          config: @config
+        }
+      end
+
+      private
+
+      def default_config
+        {
+          failure_threshold: 5,
+          failure_window_secs: 60.0,
+          half_open_timeout_secs: 30.0,
+          success_threshold: 2,
+          auto_register: true
+        }
+      end
+    end
+  end
+end