breaker_machines 0.1.0 → 0.2.0

data/lib/breaker_machines/async_support.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+# This file contains all async-related functionality for fiber-safe mode
+# It is only loaded when fiber_safe mode is enabled
+
+require 'async'
+require 'async/task'
+
+module BreakerMachines
+  # AsyncSupport provides fiber-safe execution capabilities using the async gem
+  module AsyncSupport
+    extend ActiveSupport::Concern
+
+    # Returns the Async::TimeoutError class if available
+    def async_timeout_error_class
+      ::Async::TimeoutError
+    end
+
+    # Execute a call with async support (fiber-safe mode)
+    def execute_call_async(&)
+      start_time = monotonic_time
+
+      begin
+        # Execute with hedged requests if enabled
+        result = if @config[:hedged_requests] || @config[:backends]
+                   execute_hedged(&)
+                 else
+                   execute_with_async_timeout(@config[:timeout], &)
+                 end
+
+        record_success(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)
+        handle_failure
+        raise unless @config[:fallback]
+
+        invoke_fallback_with_async(e)
+      end
+    end
+
+    # Execute a block with optional timeout using Async
+    def execute_with_async_timeout(timeout, &)
+      if timeout
+        # Use safe, cooperative timeout from async gem
+        ::Async::Task.current.with_timeout(timeout, &)
+      else
+        yield
+      end
+    end
+
+    # Invoke fallback in async context
+    def invoke_fallback_with_async(error)
+      case @config[:fallback]
+      when BreakerMachines::DSL::ParallelFallbackWrapper
+        invoke_parallel_fallbacks(@config[:fallback].fallbacks, error)
+      when Proc
+        result = if @config[:owner]
+                   @config[:owner].instance_exec(error, &@config[:fallback])
+                 else
+                   @config[:fallback].call(error)
+                 end
+
+        # If the fallback returns an Async::Task, wait for it
+        result.is_a?(::Async::Task) ? result.wait : result
+      when Array
+        # Try each fallback in order until one succeeds
+        last_error = error
+        @config[:fallback].each do |fallback|
+          return invoke_single_fallback_async(fallback, last_error)
+        rescue StandardError => e
+          last_error = e
+        end
+        raise last_error
+      else
+        # Static values (strings, hashes, etc.) or Symbol fallbacks
+        @config[:fallback]
+      end
+    end
+
+    private
+
+    def invoke_single_fallback_async(fallback, error)
+      case fallback
+      when Proc
+        result = if @config[:owner]
+                   @config[:owner].instance_exec(error, &fallback)
+                 else
+                   fallback.call(error)
+                 end
+
+        # If the fallback returns an Async::Task, wait for it
+        result.is_a?(::Async::Task) ? result.wait : result
+      else
+        fallback
+      end
+    end
+  end
+end

data/lib/breaker_machines/circuit/callbacks.rb

@@ -16,7 +16,13 @@ module BreakerMachines
         return unless callback.is_a?(Proc)
 
         if @config[:owner]
-          @config[:owner].instance_exec(&callback)
+          owner = resolve_owner
+          if owner
+            owner.instance_exec(&callback)
+          else
+            # Owner has been garbage collected, execute callback without context
+            callback.call
+          end
         else
           callback.call
         end
@@ -24,9 +30,17 @@ module BreakerMachines
 
       def invoke_fallback(error)
         case @config[:fallback]
+        when BreakerMachines::DSL::ParallelFallbackWrapper
+          invoke_parallel_fallbacks(@config[:fallback].fallbacks, error)
         when Proc
           if @config[:owner]
-            @config[:owner].instance_exec(error, &@config[:fallback])
+            owner = resolve_owner
+            if owner
+              owner.instance_exec(error, &@config[:fallback])
+            else
+              # Owner has been garbage collected, execute fallback without context
+              @config[:fallback].call(error)
+            end
           else
             @config[:fallback].call(error)
           end
@@ -49,7 +63,12 @@ module BreakerMachines
         case fallback
         when Proc
           if @config[:owner]
-            @config[:owner].instance_exec(error, &fallback)
+            owner = resolve_owner
+            if owner
+              owner.instance_exec(error, &fallback)
+            else
+              fallback.call(error)
+            end
           else
             fallback.call(error)
           end
@@ -58,73 +77,62 @@ module BreakerMachines
         end
       end
 
-      # Async versions for fiber_safe mode
-      def invoke_callback_async(callback_name)
-        callback = @config[callback_name]
-        return unless callback
-        return unless callback.is_a?(Proc)
+      # Safely resolve owner from WeakRef if applicable
+      def resolve_owner
+        owner = @config[:owner]
+        return owner unless owner.is_a?(WeakRef)
+
+        begin
+          owner.__getobj__
+        rescue WeakRef::RefError
+          # Owner has been garbage collected
+          nil
+        end
+      end
 
-        result = if @config[:owner]
-                   @config[:owner].instance_exec(&callback)
-                 else
-                   callback.call
-                 end
+      def invoke_parallel_fallbacks(fallbacks, error)
+        return fallbacks.first if fallbacks.size == 1
 
-        # If the callback returns an Async::Task, wait for it
-        if defined?(::Async::Task) && result.is_a?(::Async::Task)
-          result.wait
+        if @config[:fiber_safe] && respond_to?(:execute_parallel_fallbacks_async)
+          execute_parallel_fallbacks_async(fallbacks)
         else
-          result
+          execute_parallel_fallbacks_sync(fallbacks, error)
         end
       end
 
-      def invoke_fallback_async(error)
-        case @config[:fallback]
-        when Proc
-          result = if @config[:owner]
-                     @config[:owner].instance_exec(error, &@config[:fallback])
-                   else
-                     @config[:fallback].call(error)
-                   end
-
-          # If the fallback returns an Async::Task, wait for it
-          if defined?(::Async::Task) && result.is_a?(::Async::Task)
-            result.wait
-          else
-            result
-          end
-        when Array
-          # Try each fallback in order until one succeeds
-          last_error = error
-          @config[:fallback].each do |fallback|
-            return invoke_single_fallback_async(fallback, last_error)
+      def execute_parallel_fallbacks_sync(fallbacks, error)
+        result_queue = Queue.new
+        error_queue = Queue.new
+        threads = fallbacks.map do |fallback|
+          Thread.new do
+            result = if fallback.is_a?(Proc)
+                       if fallback.arity == 1
+                         fallback.call(error)
+                       else
+                         fallback.call
+                       end
+                     else
+                       fallback
+                     end
+            result_queue << result
           rescue StandardError => e
-            last_error = e
+            error_queue << e
           end
-          raise last_error
-        else
-          # Static values (strings, hashes, etc.) or Symbol fallbacks
-          @config[:fallback]
         end
-      end
 
-      def invoke_single_fallback_async(fallback, error)
-        case fallback
-        when Proc
-          result = if @config[:owner]
-                     @config[:owner].instance_exec(error, &fallback)
-                   else
-                     fallback.call(error)
-                   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?
 
-          # If the fallback returns an Async::Task, wait for it
-          if defined?(::Async::Task) && result.is_a?(::Async::Task)
-            result.wait
-          else
-            result
+              raise error_queue.pop if error_queue.size >= fallbacks.size
+
+              sleep 0.001
+            end
           end
-        else
-          fallback
+        ensure
+          threads.each(&:kill)
         end
       end
     end

data/lib/breaker_machines/circuit/configuration.rb

@@ -25,11 +25,14 @@ module BreakerMachines
         @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
-        BreakerMachines::Registry.instance.register(self)
+        # Register with global registry unless auto_register is disabled
+        BreakerMachines::Registry.instance.register(self) unless @config[:auto_register] == false
       end
 
       private
@@ -51,7 +54,18 @@ module BreakerMachines
           on_half_open: nil,
           on_reject: nil,
           exceptions: [StandardError],
-          fiber_safe: BreakerMachines.config.fiber_safe
+          fiber_safe: BreakerMachines.config.fiber_safe,
+          # Rate-based threshold options
+          use_rate_threshold: false,
+          failure_rate: nil,
+          minimum_calls: 5,
+          # Bulkheading options
+          max_concurrent: nil,
+          # Hedged request options
+          hedged_requests: false,
+          hedging_delay: 50, # milliseconds
+          max_hedged_requests: 2,
+          backends: nil
         }
       end
 

data/lib/breaker_machines/circuit/execution.rb

@@ -9,39 +9,58 @@ module BreakerMachines
 
       # Lazy load async support only when needed
       def self.load_async_support
-        require 'async'
-        require 'async/task'
-      rescue LoadError
-        raise LoadError, "The 'async' gem is required for fiber_safe mode. Add `gem 'async'` to your Gemfile."
+        require 'breaker_machines/async_support'
+        require 'breaker_machines/hedged_async_support'
+        Circuit.include(BreakerMachines::AsyncSupport)
+        Circuit.include(BreakerMachines::HedgedAsyncSupport)
+      rescue LoadError => e
+        if e.message.include?('async')
+          raise LoadError, "The 'async' gem is required for fiber_safe mode. Add `gem 'async'` to your Gemfile."
+        end
+
+        raise
       end
 
       def call(&)
         wrap(&)
       end
 
-      def wrap(&block)
-        @mutex.with_read_lock do
-          case status_name
-          when :open
-            handle_open_status(&block)
-          when :half_open
-            handle_half_open_status(&block)
-          when :closed
-            handle_closed_status(&block)
-          end
-        end
+      def wrap(&)
+        execute_with_state_check(&)
       end
 
       private
 
-      def handle_open_status(&)
-        if reset_timeout_elapsed?
+      def execute_with_state_check(&block)
+        # Check if we need to transition from open to half-open first
+        if open? && reset_timeout_elapsed?
           @mutex.with_write_lock do
-            attempt_recovery if open?
+            attempt_recovery if open? # Double-check after acquiring lock
           end
-          handle_half_open_status(&)
-        else
-          reject_call
+        end
+
+        # Apply bulkheading first, outside of any locks
+        if @semaphore
+          acquired = @semaphore.try_acquire
+          unless acquired
+            # Reject immediately if we can't acquire semaphore
+            return reject_call_bulkhead
+          end
+        end
+
+        begin
+          @mutex.with_read_lock do
+            case status_name
+            when :open
+              reject_call
+            when :half_open
+              handle_half_open_status(&block)
+            when :closed
+              handle_closed_status(&block)
+            end
+          end
+        ensure
+          @semaphore&.release if @semaphore && acquired
         end
       end
 
@@ -64,7 +83,11 @@ module BreakerMachines
 
       def execute_call(&block)
         # Use async version if fiber_safe is enabled
-        return execute_call_async(&block) if @config[:fiber_safe]
+        if @config[:fiber_safe]
+          # Ensure async is loaded and included
+          Execution.load_async_support unless respond_to?(:execute_call_async)
+          return execute_call_async(&block)
+        end
 
         start_time = monotonic_time
 
@@ -83,51 +106,22 @@ module BreakerMachines
             )
           end
 
-          # Execute normally without forceful timeout
-          result = block.call
-
-          record_success(monotonic_time - start_time)
-          handle_success
-          result
-        rescue *@config[:exceptions] => e
-          record_failure(monotonic_time - start_time, e)
-          handle_failure
-          raise unless @config[:fallback]
-
-          invoke_fallback(e)
-        end
-      end
-
-      def execute_call_async(&)
-        # Ensure async is loaded
-        Execution.load_async_support unless defined?(::Async)
-
-        start_time = monotonic_time
-
-        begin
-          result = if @config[:timeout]
-                     # Use safe, cooperative timeout from async gem
-                     ::Async::Task.current.with_timeout(@config[:timeout], &)
+          # Execute with hedged requests if enabled
+          result = if @config[:hedged_requests] || @config[:backends]
+                     execute_hedged(&block)
                    else
-                     yield
+                     block.call
                    end
 
           record_success(monotonic_time - start_time)
           handle_success
           result
-        rescue ::Async::TimeoutError => e
-          # Handle async timeout as a failure
-          record_failure(monotonic_time - start_time, e)
-          handle_failure
-          raise unless @config[:fallback]
-
-          invoke_fallback_async(e)
         rescue *@config[:exceptions] => e
           record_failure(monotonic_time - start_time, e)
           handle_failure
           raise unless @config[:fallback]
 
-          invoke_fallback_async(e)
+          invoke_fallback(e)
         end
       end
 
@@ -140,7 +134,19 @@ module BreakerMachines
         invoke_fallback(BreakerMachines::CircuitOpenError.new(@name, @opened_at.value))
       end
 
+      def reject_call_bulkhead
+        @metrics&.record_rejection(@name)
+        invoke_callback(:on_reject)
+
+        error = BreakerMachines::CircuitBulkheadError.new(@name, @config[:max_concurrent])
+        raise error unless @config[:fallback]
+
+        invoke_fallback(error)
+      end
+
       def handle_success
+        return unless half_open?
+
         @mutex.with_write_lock do
           if half_open?
             # Check if all allowed half-open calls have succeeded
@@ -162,6 +168,8 @@ module BreakerMachines
       end
 
       def handle_failure
+        return unless closed? || half_open?
+
         @mutex.with_write_lock do
           if closed? && failure_threshold_exceeded?
             trip
@@ -174,8 +182,24 @@ module BreakerMachines
       end
 
       def failure_threshold_exceeded?
-        recent_failures = @storage.failure_count(@name, @config[:failure_window])
-        recent_failures >= @config[:failure_threshold]
+        if @config[:use_rate_threshold]
+          # Rate-based threshold
+          window = @config[:failure_window]
+          failures = @storage.failure_count(@name, window)
+          successes = @storage.success_count(@name, window)
+          total_calls = failures + successes
+
+          # Check minimum calls requirement
+          return false if total_calls < @config[:minimum_calls]
+
+          # Calculate failure rate
+          failure_rate = failures.to_f / total_calls
+          failure_rate >= @config[:failure_rate]
+        else
+          # Absolute count threshold (existing behavior)
+          recent_failures = @storage.failure_count(@name, @config[:failure_window])
+          recent_failures >= @config[:failure_threshold]
+        end
       end
 
       def success_threshold_reached?

data/lib/breaker_machines/circuit.rb

@@ -8,6 +8,7 @@ module BreakerMachines
     include StateManagement
     include Configuration
     include Execution
+    include HedgedExecution
     include Introspection
     include Callbacks
   end