breaker_machines 0.3.0 → 0.5.0

data/lib/breaker_machines/dsl/circuit_builder.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  module DSL
+    # DSL builder for configuring circuit breakers with a fluent interface
+    class CircuitBuilder
+      attr_reader :config
+
+      def initialize
+        @config = {
+          failure_threshold: 5,
+          failure_window: 60.seconds,
+          success_threshold: 1,
+          timeout: nil,
+          reset_timeout: 60.seconds,
+          half_open_calls: 1,
+          exceptions: [StandardError],
+          storage: nil,
+          metrics: nil,
+          fallback: nil,
+          on_open: nil,
+          on_close: nil,
+          on_half_open: nil,
+          on_reject: nil,
+          notifications: [],
+          fiber_safe: BreakerMachines.config.fiber_safe
+        }
+      end
+
+      def threshold(failures: nil, failure_rate: nil, minimum_calls: nil, within: 60.seconds, successes: nil)
+        if failure_rate
+          # Rate-based threshold
+          validate_failure_rate!(failure_rate)
+          validate_positive_integer!(:minimum_calls, minimum_calls) if minimum_calls
+
+          @config[:failure_rate] = failure_rate
+          @config[:minimum_calls] = minimum_calls || 5
+          @config[:use_rate_threshold] = true
+        elsif failures
+          # Absolute count threshold (existing behavior)
+          validate_positive_integer!(:failures, failures)
+          @config[:failure_threshold] = failures
+          @config[:use_rate_threshold] = false
+        end
+
+        validate_positive_integer!(:within, within.to_i)
+        @config[:failure_window] = within.to_i
+
+        return unless successes
+
+        validate_positive_integer!(:successes, successes)
+        @config[:success_threshold] = successes
+      end
+
+      def reset_after(duration, jitter: nil)
+        validate_positive_integer!(:duration, duration.to_i)
+        @config[:reset_timeout] = duration.to_i
+
+        return unless jitter
+
+        validate_jitter!(jitter)
+        @config[:reset_timeout_jitter] = jitter
+      end
+
+      def timeout(duration)
+        validate_non_negative_integer!(:timeout, duration.to_i)
+        @config[:timeout] = duration.to_i
+      end
+
+      def half_open_requests(count)
+        validate_positive_integer!(:half_open_requests, count)
+        @config[:half_open_calls] = count
+      end
+
+      def storage(backend, **options)
+        @config[:storage] = case backend
+                            when :memory
+                              Storage::Memory.new(**options)
+                            when :bucket_memory
+                              Storage::BucketMemory.new(**options)
+                            when :cache
+                              Storage::Cache.new(**options)
+                            when :null
+                              Storage::Null.new(**options)
+                            when :fallback_chain
+                              config = options.is_a?(Proc) ? options.call(timeout: 5) : options
+                              Storage::FallbackChain.new(config)
+                            when Class
+                              backend.new(**options)
+                            else
+                              backend
+                            end
+      end
+
+      def metrics(recorder = nil, &block)
+        @config[:metrics] = recorder || block
+      end
+
+      def fallback(value = nil, &block)
+        raise ArgumentError, 'Fallback requires either a value or a block' if value.nil? && !block_given?
+
+        fallback_value = block || value
+
+        if @config[:fallback].is_a?(Array)
+          @config[:fallback] << fallback_value
+        elsif @config[:fallback]
+          @config[:fallback] = [@config[:fallback], fallback_value]
+        else
+          @config[:fallback] = fallback_value
+        end
+      end
+
+      def on_open(&block)
+        @config[:on_open] = block
+      end
+
+      def on_close(&block)
+        @config[:on_close] = block
+      end
+
+      def on_half_open(&block)
+        @config[:on_half_open] = block
+      end
+
+      def on_reject(&block)
+        @config[:on_reject] = block
+      end
+
+      # Configure hedged requests
+      def hedged(&)
+        if block_given?
+          hedged_builder = DSL::HedgedBuilder.new(@config)
+          hedged_builder.instance_eval(&)
+        else
+          @config[:hedged_requests] = true
+        end
+      end
+
+      # Configure multiple backends
+      def backends(*backend_list)
+        @config[:backends] = backend_list.flatten
+      end
+
+      # Configure parallel fallback execution
+      def parallel_fallback(fallback_list)
+        @config[:fallback] = DSL::ParallelFallbackWrapper.new(fallback_list)
+      end
+
+      def notify(service, url = nil, events: %i[open close], **options)
+        notification = {
+          via: service,
+          url: url,
+          events: Array(events),
+          options: options
+        }
+        @config[:notifications] << notification
+      end
+
+      def handle(*exceptions)
+        @config[:exceptions] = exceptions
+      end
+
+      def fiber_safe(enabled = true) # rubocop:disable Style/OptionalBooleanParameter
+        @config[:fiber_safe] = enabled
+      end
+
+      def max_concurrent(limit)
+        validate_positive_integer!(:max_concurrent, limit)
+        @config[:max_concurrent] = limit
+      end
+
+      # Advanced features
+      def parallel_calls(count, timeout: nil)
+        @config[:parallel_calls] = count
+        @config[:parallel_timeout] = timeout
+      end
+
+      private
+
+      def validate_positive_integer!(name, value)
+        return if value.is_a?(Integer) && value.positive?
+
+        raise BreakerMachines::ConfigurationError,
+              "#{name} must be a positive integer, got: #{value.inspect}"
+      end
+
+      def validate_non_negative_integer!(name, value)
+        return if value.is_a?(Integer) && value >= 0
+
+        raise BreakerMachines::ConfigurationError,
+              "#{name} must be a non-negative integer, got: #{value.inspect}"
+      end
+
+      def validate_failure_rate!(rate)
+        return if rate.is_a?(Numeric) && rate >= 0.0 && rate <= 1.0
+
+        raise BreakerMachines::ConfigurationError,
+              "failure_rate must be between 0.0 and 1.0, got: #{rate.inspect}"
+      end
+
+      def validate_jitter!(jitter)
+        return if jitter.is_a?(Numeric) && jitter >= 0.0 && jitter <= 1.0
+
+        raise BreakerMachines::ConfigurationError,
+              "jitter must be between 0.0 and 1.0 (0% to 100%), got: #{jitter.inspect}"
+      end
+    end
+  end
+end

data/lib/breaker_machines/dsl/hedged_builder.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  module DSL
+    # Builder for hedged request configuration
+    class HedgedBuilder
+      def initialize(config)
+        @config = config
+        @config[:hedged_requests] = true
+      end
+
+      def delay(milliseconds)
+        @config[:hedging_delay] = milliseconds
+      end
+
+      def max_requests(count)
+        @config[:max_hedged_requests] = count
+      end
+    end
+  end
+end

data/lib/breaker_machines/dsl/parallel_fallback_wrapper.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  module DSL
+    # Wrapper to indicate parallel execution for fallbacks
+    class ParallelFallbackWrapper
+      attr_reader :fallbacks
+
+      def initialize(fallbacks)
+        @fallbacks = fallbacks
+      end
+
+      def call(error)
+        # This will be handled by the circuit's fallback mechanism
+        # to execute fallbacks in parallel
+        raise NotImplementedError, 'ParallelFallbackWrapper should be handled by Circuit'
+      end
+    end
+  end
+end

data/lib/breaker_machines/dsl.rb

@@ -43,7 +43,7 @@ module BreakerMachines
         @circuits ||= {}
 
         if block_given?
-          builder = CircuitBuilder.new
+          builder = DSL::CircuitBuilder.new
           builder.instance_eval(&block)
           @circuits[name] = builder.config
         end
@@ -51,6 +51,19 @@ module BreakerMachines
         @circuits[name]
       end
 
+      # Define a cascading circuit breaker that can trip dependent circuits
+      def cascade_circuit(name, &block)
+        @circuits ||= {}
+
+        if block_given?
+          builder = DSL::CascadingCircuitBuilder.new
+          builder.instance_eval(&block)
+          @circuits[name] = builder.config.merge(circuit_type: :cascading)
+        end
+
+        @circuits[name]
+      end
+
       def circuits
         # Start with parent circuits if available
         base_circuits = if superclass.respond_to?(:circuits)
@@ -72,7 +85,7 @@ module BreakerMachines
         @circuit_templates ||= {}
 
         if block_given?
-          builder = CircuitBuilder.new
+          builder = DSL::CircuitBuilder.new
           builder.instance_eval(&block)
           @circuit_templates[name] = builder.config
         end
@@ -109,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
@@ -156,7 +169,16 @@ module BreakerMachines
     def circuit(name)
       self.class.circuits[name] ||= {}
       @circuit_instances ||= {}
-      @circuit_instances[name] ||= Circuit.new(name, self.class.circuits[name].merge(owner: self))
+
+      config = self.class.circuits[name].merge(owner: self)
+      circuit_type = config.delete(:circuit_type)
+
+      @circuit_instances[name] ||= case circuit_type
+                                   when :cascading
+                                     CascadingCircuit.new(name, config)
+                                   else
+                                     Circuit.new(name, config)
+                                   end
     end
 
     # Create a dynamic circuit breaker with inline configuration
@@ -173,7 +195,7 @@ module BreakerMachines
 
       # Apply additional configuration if block provided
       if config_block
-        builder = CircuitBuilder.new
+        builder = DSL::CircuitBuilder.new
         builder.instance_variable_set(:@config, base_config.deep_dup)
         builder.instance_eval(&config_block)
         base_config = builder.config
@@ -240,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
@@ -257,240 +279,5 @@ module BreakerMachines
     def cleanup_stale_dynamic_circuits(max_age_seconds = 3600)
       BreakerMachines.registry.cleanup_stale_dynamic_circuits(max_age_seconds)
     end
-
-    # DSL builder for configuring circuit breakers with a fluent interface
-    class CircuitBuilder
-      attr_reader :config
-
-      def initialize
-        @config = {
-          failure_threshold: 5,
-          failure_window: 60.seconds,
-          success_threshold: 1,
-          timeout: nil,
-          reset_timeout: 60.seconds,
-          half_open_calls: 1,
-          exceptions: [StandardError],
-          storage: nil,
-          metrics: nil,
-          fallback: nil,
-          on_open: nil,
-          on_close: nil,
-          on_half_open: nil,
-          on_reject: nil,
-          notifications: [],
-          fiber_safe: BreakerMachines.config.fiber_safe
-        }
-      end
-
-      def threshold(failures: nil, failure_rate: nil, minimum_calls: nil, within: 60.seconds, successes: nil)
-        if failure_rate
-          # Rate-based threshold
-          validate_failure_rate!(failure_rate)
-          validate_positive_integer!(:minimum_calls, minimum_calls) if minimum_calls
-
-          @config[:failure_rate] = failure_rate
-          @config[:minimum_calls] = minimum_calls || 5
-          @config[:use_rate_threshold] = true
-        elsif failures
-          # Absolute count threshold (existing behavior)
-          validate_positive_integer!(:failures, failures)
-          @config[:failure_threshold] = failures
-          @config[:use_rate_threshold] = false
-        end
-
-        validate_positive_integer!(:within, within.to_i)
-        @config[:failure_window] = within.to_i
-
-        return unless successes
-
-        validate_positive_integer!(:successes, successes)
-        @config[:success_threshold] = successes
-      end
-
-      def reset_after(duration, jitter: nil)
-        validate_positive_integer!(:duration, duration.to_i)
-        @config[:reset_timeout] = duration.to_i
-
-        return unless jitter
-
-        validate_jitter!(jitter)
-        @config[:reset_timeout_jitter] = jitter
-      end
-
-      def timeout(duration)
-        validate_non_negative_integer!(:timeout, duration.to_i)
-        @config[:timeout] = duration.to_i
-      end
-
-      def half_open_requests(count)
-        validate_positive_integer!(:half_open_requests, count)
-        @config[:half_open_calls] = count
-      end
-
-      def storage(backend, **options)
-        @config[:storage] = case backend
-                            when :memory
-                              Storage::Memory.new(**options)
-                            when :bucket_memory
-                              Storage::BucketMemory.new(**options)
-                            when :cache
-                              Storage::Cache.new(**options)
-                            when :null
-                              Storage::Null.new(**options)
-                            when :fallback_chain
-                              config = options.is_a?(Proc) ? options.call(timeout: 5) : options
-                              Storage::FallbackChain.new(config)
-                            when Class
-                              backend.new(**options)
-                            else
-                              backend
-                            end
-      end
-
-      def metrics(recorder = nil, &block)
-        @config[:metrics] = recorder || block
-      end
-
-      def fallback(value = nil, &block)
-        raise ArgumentError, 'Fallback requires either a value or a block' if value.nil? && !block_given?
-
-        fallback_value = block || value
-
-        if @config[:fallback].is_a?(Array)
-          @config[:fallback] << fallback_value
-        elsif @config[:fallback]
-          @config[:fallback] = [@config[:fallback], fallback_value]
-        else
-          @config[:fallback] = fallback_value
-        end
-      end
-
-      def on_open(&block)
-        @config[:on_open] = block
-      end
-
-      def on_close(&block)
-        @config[:on_close] = block
-      end
-
-      def on_half_open(&block)
-        @config[:on_half_open] = block
-      end
-
-      def on_reject(&block)
-        @config[:on_reject] = block
-      end
-
-      # Configure hedged requests
-      def hedged(&)
-        if block_given?
-          hedged_builder = HedgedBuilder.new(@config)
-          hedged_builder.instance_eval(&)
-        else
-          @config[:hedged_requests] = true
-        end
-      end
-
-      # Configure multiple backends
-      def backends(*backend_list)
-        @config[:backends] = backend_list.flatten
-      end
-
-      # Configure parallel fallback execution
-      def parallel_fallback(fallback_list)
-        @config[:fallback] = ParallelFallbackWrapper.new(fallback_list)
-      end
-
-      def notify(service, url = nil, events: %i[open close], **options)
-        notification = {
-          via: service,
-          url: url,
-          events: Array(events),
-          options: options
-        }
-        @config[:notifications] << notification
-      end
-
-      def handle(*exceptions)
-        @config[:exceptions] = exceptions
-      end
-
-      def fiber_safe(enabled = true) # rubocop:disable Style/OptionalBooleanParameter
-        @config[:fiber_safe] = enabled
-      end
-
-      def max_concurrent(limit)
-        validate_positive_integer!(:max_concurrent, limit)
-        @config[:max_concurrent] = limit
-      end
-
-      # Advanced features
-      def parallel_calls(count, timeout: nil)
-        @config[:parallel_calls] = count
-        @config[:parallel_timeout] = timeout
-      end
-
-      private
-
-      def validate_positive_integer!(name, value)
-        return if value.is_a?(Integer) && value.positive?
-
-        raise BreakerMachines::ConfigurationError,
-              "#{name} must be a positive integer, got: #{value.inspect}"
-      end
-
-      def validate_non_negative_integer!(name, value)
-        return if value.is_a?(Integer) && value >= 0
-
-        raise BreakerMachines::ConfigurationError,
-              "#{name} must be a non-negative integer, got: #{value.inspect}"
-      end
-
-      def validate_failure_rate!(rate)
-        return if rate.is_a?(Numeric) && rate >= 0.0 && rate <= 1.0
-
-        raise BreakerMachines::ConfigurationError,
-              "failure_rate must be between 0.0 and 1.0, got: #{rate.inspect}"
-      end
-
-      def validate_jitter!(jitter)
-        return if jitter.is_a?(Numeric) && jitter >= 0.0 && jitter <= 1.0
-
-        raise BreakerMachines::ConfigurationError,
-              "jitter must be between 0.0 and 1.0 (0% to 100%), got: #{jitter.inspect}"
-      end
-    end
-
-    # Builder for hedged request configuration
-    class HedgedBuilder
-      def initialize(config)
-        @config = config
-        @config[:hedged_requests] = true
-      end
-
-      def delay(milliseconds)
-        @config[:hedging_delay] = milliseconds
-      end
-
-      def max_requests(count)
-        @config[:max_hedged_requests] = count
-      end
-    end
-
-    # Wrapper to indicate parallel execution for fallbacks
-    class ParallelFallbackWrapper
-      attr_reader :fallbacks
-
-      def initialize(fallbacks)
-        @fallbacks = fallbacks
-      end
-
-      def call(error)
-        # This will be handled by the circuit's fallback mechanism
-        # to execute fallbacks in parallel
-        raise NotImplementedError, 'ParallelFallbackWrapper should be handled by Circuit'
-      end
-    end
   end
 end

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