breaker_machines 0.9.2-x86_64-linux

data/lib/breaker_machines/circuit/callbacks.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  class Circuit
+    # Callbacks handles the invocation of user-defined callbacks and fallback mechanisms
+    # when circuit state changes occur or calls are rejected.
+    module Callbacks
+      extend ActiveSupport::Concern
+
+      private
+
+      def invoke_callback(callback_name)
+        callback = @config[callback_name]
+        return unless callback
+
+        return unless callback.is_a?(Proc)
+
+        if @config[:owner]
+          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
+      end
+
+      def invoke_fallback(error)
+        case @config[:fallback]
+        when BreakerMachines::DSL::ParallelFallbackWrapper
+          invoke_parallel_fallbacks(@config[:fallback].fallbacks, error)
+        when Proc
+          if @config[:owner]
+            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
+        when Array
+          # Try each fallback in order until one succeeds
+          last_error = error
+          @config[:fallback].each do |fallback|
+            return invoke_single_fallback(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
+
+      def invoke_single_fallback(fallback, error)
+        case fallback
+        when Proc
+          if @config[:owner]
+            owner = resolve_owner
+            if owner
+              owner.instance_exec(error, &fallback)
+            else
+              fallback.call(error)
+            end
+          else
+            fallback.call(error)
+          end
+        else
+          fallback
+        end
+      end
+
+      # 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
+
+      def invoke_parallel_fallbacks(fallbacks, error)
+        return fallbacks.first if fallbacks.size == 1
+
+        if @config[:fiber_safe] && respond_to?(:execute_parallel_fallbacks_async)
+          execute_parallel_fallbacks_async(fallbacks)
+        else
+          execute_parallel_fallbacks_sync(fallbacks, error)
+        end
+      end
+
+      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
+            error_queue << e
+          end
+        end
+
+        threads.each(&:join)
+
+        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
+  end
+end

data/lib/breaker_machines/circuit/configuration.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  class Circuit
+    # Configuration manages circuit initialization and default settings,
+    # including thresholds, timeouts, storage backends, and callbacks.
+    module Configuration
+      extend ActiveSupport::Concern
+
+      included do
+        attr_reader :name, :config, :opened_at
+      end
+
+      private
+
+      def default_config
+        {
+          failure_threshold: 5,
+          failure_window: 60, # seconds
+          success_threshold: 1,
+          timeout: nil,
+          reset_timeout: 60, # seconds
+          reset_timeout_jitter: 0.25, # +/- 25% by default
+          half_open_calls: 1,
+          storage: nil, # Will default to Memory storage if nil
+          metrics: nil,
+          fallback: nil,
+          on_open: nil,
+          on_close: nil,
+          on_half_open: nil,
+          on_reject: nil,
+          exceptions: [StandardError],
+          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
+
+      def create_default_storage
+        case BreakerMachines.config.default_storage
+        when :memory
+          BreakerMachines::Storage::Memory.new
+        when :bucket_memory
+          BreakerMachines::Storage::BucketMemory.new
+        when :null
+          BreakerMachines::Storage::Null.new
+        else
+          # 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
+  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/execution.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  class Circuit
+    # Execution handles the core circuit breaker logic including call wrapping,
+    # state-based request handling, and failure/success tracking.
+    module Execution
+      extend ActiveSupport::Concern
+
+      # Lazy load async support only when needed
+      def self.load_async_support
+        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(&)
+        execute_with_state_check(&)
+      end
+
+      private
+
+      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? # Double-check after acquiring lock
+          end
+        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
+
+      def handle_half_open_status(&)
+        # Atomically increment and get the new value
+        new_attempts = @half_open_attempts.increment
+
+        if new_attempts <= @config[:half_open_calls]
+          execute_call(&)
+        else
+          # This thread lost the race, decrement back and reject
+          @half_open_attempts.decrement
+          reject_call
+        end
+      end
+
+      def handle_closed_status(&)
+        execute_call(&)
+      end
+
+      def execute_call(&block)
+        # Use async version if fiber_safe is enabled
+        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 = BreakerMachines.monotonic_time
+
+        begin
+          # IMPORTANT: We do NOT implement forceful timeouts as they are inherently unsafe
+          # The timeout configuration is provided for documentation/intent purposes
+          # Users should implement timeouts in their own code using safe mechanisms
+          # (e.g., HTTP client timeouts, database statement timeouts, etc.)
+          # Log a warning if timeout is configured
+          if @config[:timeout] && BreakerMachines.logger && BreakerMachines.config.log_events
+            BreakerMachines.logger.warn(
+              "[BreakerMachines] Circuit '#{@name}' has timeout configured but " \
+              'forceful timeouts are not implemented for safety. ' \
+              'Please use timeout mechanisms provided by your libraries ' \
+              '(e.g., Net::HTTP read_timeout, ActiveRecord statement_timeout).'
+            )
+          end
+
+          # Execute with hedged requests if enabled
+          result = if @config[:hedged_requests] || @config[:backends]
+                     execute_hedged(&block)
+                   else
+                     block.call
+                   end
+
+          record_success(BreakerMachines.monotonic_time - start_time)
+          handle_success
+          result
+        rescue *@config[:exceptions] => e
+          record_failure(BreakerMachines.monotonic_time - start_time, e)
+          handle_failure
+          raise unless @config[:fallback]
+
+          invoke_fallback(e)
+        end
+      end
+
+      def reject_call
+        @metrics&.record_rejection(@name)
+        invoke_callback(:on_reject)
+
+        raise BreakerMachines::CircuitOpenError.new(@name, @opened_at.value) unless @config[:fallback]
+
+        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
+            # This ensures the circuit can close even if success_threshold > half_open_calls
+            successful_attempts = @half_open_successes.increment
+
+            # Fast-close logic: Circuit closes if EITHER:
+            # 1. All allowed half-open calls succeeded (conservative approach)
+            # 2. Success threshold is reached (aggressive approach for quick recovery)
+            # This allows flexible configuration - set success_threshold=1 for fast recovery
+            # or success_threshold=half_open_calls for cautious recovery
+            if successful_attempts >= @config[:half_open_calls] || success_threshold_reached?
+              @half_open_attempts.value = 0
+              @half_open_successes.value = 0
+              reset
+            end
+          end
+        end
+      end
+
+      def handle_failure
+        return unless closed? || half_open?
+
+        @mutex.with_write_lock do
+          if closed? && failure_threshold_exceeded?
+            trip
+          elsif half_open?
+            @half_open_attempts.value = 0
+            @half_open_successes.value = 0
+            trip
+          end
+        end
+      end
+
+      def failure_threshold_exceeded?
+        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?
+        recent_successes = @storage.success_count(@name, @config[:failure_window])
+        recent_successes >= @config[:success_threshold]
+      end
+
+      def record_success(duration)
+        @metrics&.record_success(@name, duration)
+        @storage&.record_success(@name, duration)
+        return unless @storage.respond_to?(:record_event_with_details)
+
+        @storage.record_event_with_details(@name, :success,
+                                           duration)
+      end
+
+      def record_failure(duration, error = nil)
+        @last_failure_at.value = BreakerMachines.monotonic_time
+        @last_error.value = error if error
+        @metrics&.record_failure(@name, duration)
+        @storage&.record_failure(@name, duration)
+        return unless @storage.respond_to?(:record_event_with_details)
+
+        @storage.record_event_with_details(@name, :failure, duration,
+                                           error: error)
+      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