breaker_machines 0.1.0 → 0.2.0

data/lib/breaker_machines/dsl.rb

@@ -67,6 +67,36 @@ module BreakerMachines
         end
       end
 
+      # Define reusable circuit templates
+      def circuit_template(name, &block)
+        @circuit_templates ||= {}
+
+        if block_given?
+          builder = CircuitBuilder.new
+          builder.instance_eval(&block)
+          @circuit_templates[name] = builder.config
+        end
+
+        @circuit_templates[name]
+      end
+
+      # Get all circuit templates
+      def circuit_templates
+        # Start with parent templates if available
+        base_templates = if superclass.respond_to?(:circuit_templates)
+                           superclass.circuit_templates.deep_dup
+                         else
+                           {}
+                         end
+
+        # Merge with our own templates
+        if @circuit_templates
+          base_templates.merge(@circuit_templates)
+        else
+          base_templates
+        end
+      end
+
       # Get circuit definitions without sensitive data
       def circuit_definitions
         circuits.transform_values { |config| config.except(:owner, :storage, :metrics) }
@@ -129,6 +159,70 @@ module BreakerMachines
       @circuit_instances[name] ||= Circuit.new(name, self.class.circuits[name].merge(owner: self))
     end
 
+    # Create a dynamic circuit breaker with inline configuration
+    # Options:
+    #   global: true - Store circuit globally, preventing memory leaks in long-lived objects
+    #   global: false - Store circuit locally in this instance (default, backward compatible)
+    def dynamic_circuit(name, template: nil, global: false, &config_block)
+      # Start with template config if provided
+      base_config = if template && self.class.circuit_templates[template]
+                      self.class.circuit_templates[template].deep_dup
+                    else
+                      default_circuit_config
+                    end
+
+      # Apply additional configuration if block provided
+      if config_block
+        builder = CircuitBuilder.new
+        builder.instance_variable_set(:@config, base_config.deep_dup)
+        builder.instance_eval(&config_block)
+        base_config = builder.config
+      end
+
+      if global
+        # Use global registry to prevent memory leaks
+        BreakerMachines.registry.get_or_create_dynamic_circuit(name, self, base_config)
+      else
+        # Local storage (backward compatible)
+        @circuit_instances ||= {}
+        @circuit_instances[name] ||= Circuit.new(name, base_config.merge(owner: self))
+      end
+    end
+
+    # Apply a template to an existing or new circuit
+    def apply_template(circuit_name, template_name)
+      template_config = self.class.circuit_templates[template_name]
+      raise ArgumentError, "Template '#{template_name}' not found" unless template_config
+
+      @circuit_instances ||= {}
+      @circuit_instances[circuit_name] = Circuit.new(circuit_name, template_config.merge(owner: self))
+    end
+
+    private
+
+    def default_circuit_config
+      {
+        failure_threshold: 5,
+        failure_window: 60,
+        success_threshold: 1,
+        timeout: nil,
+        reset_timeout: 60,
+        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
+
+    public
+
     # Get all circuit instances for this object
     def circuit_instances
       @circuit_instances || {}
@@ -149,6 +243,21 @@ module BreakerMachines
       circuit_instances.each_value(&:reset)
     end
 
+    # Remove a global dynamic circuit by name
+    def remove_dynamic_circuit(name)
+      BreakerMachines.registry.remove_dynamic_circuit(name)
+    end
+
+    # Get all dynamic circuit names from global registry
+    def dynamic_circuit_names
+      BreakerMachines.registry.dynamic_circuit_names
+    end
+
+    # Cleanup stale dynamic circuits (global)
+    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
@@ -156,10 +265,10 @@ module BreakerMachines
       def initialize
         @config = {
           failure_threshold: 5,
-          failure_window: 60,
+          failure_window: 60.seconds,
           success_threshold: 1,
           timeout: nil,
-          reset_timeout: 60,
+          reset_timeout: 60.seconds,
           half_open_calls: 1,
           exceptions: [StandardError],
           storage: nil,
@@ -174,22 +283,48 @@ module BreakerMachines
         }
       end
 
-      def threshold(failures: nil, within: 60, successes: nil)
-        @config[:failure_threshold] = failures if failures
+      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
-        @config[:success_threshold] = successes if successes
+
+        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
-        @config[:reset_timeout_jitter] = jitter if jitter
+
+        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
 
@@ -199,6 +334,8 @@ module BreakerMachines
                               Storage::Memory.new(**)
                             when :bucket_memory
                               Storage::BucketMemory.new(**)
+                            when :cache
+                              Storage::Cache.new(**)
                             when :redis
                               Storage::Redis.new(**)
                             when Class
@@ -242,6 +379,26 @@ module BreakerMachines
         @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,
@@ -256,19 +413,81 @@ module BreakerMachines
         @config[:exceptions] = exceptions
       end
 
-      def fiber_safe(enabled = true)
+      def fiber_safe(enabled: true)
         @config[:fiber_safe] = enabled
       end
 
-      # Advanced features
-      def backends(list)
-        @config[:backends] = list
+      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

@@ -27,4 +27,15 @@ module BreakerMachines
 
   class ConfigurationError < Error; end
   class StorageError < Error; end
+
+  # Raised when circuit rejects call due to bulkhead limit
+  class CircuitBulkheadError < Error
+    attr_reader :circuit_name, :max_concurrent
+
+    def initialize(circuit_name, max_concurrent)
+      @circuit_name = circuit_name
+      @max_concurrent = max_concurrent
+      super("Circuit '#{circuit_name}' rejected call: max concurrent limit of #{max_concurrent} reached")
+    end
+  end
 end

data/lib/breaker_machines/hedged_async_support.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+# This file contains async support for hedged execution
+# It is only loaded when fiber_safe mode is enabled
+
+require 'async'
+require 'async/task'
+require 'async/condition'
+require 'concurrent'
+
+module BreakerMachines
+  # AsyncSupport for HedgedExecution
+  module HedgedAsyncSupport
+    # Execute hedged requests with configurable delay between attempts
+    # @param callables [Array<Proc>] Array of callables to execute
+    # @param delay_ms [Integer] Milliseconds to wait before starting hedged requests
+    # @return [Object] Result from the first successful callable
+    # @raise [StandardError] If all callables fail
+    def execute_hedged_with_async(callables, delay_ms)
+      race_tasks(callables, delay_ms: delay_ms)
+    end
+
+    # Execute parallel fallbacks without delay
+    # @param fallbacks [Array<Proc,Object>] Array of fallback values or callables
+    # @return [Object] Result from the first successful fallback
+    # @raise [StandardError] If all fallbacks fail
+    def execute_parallel_fallbacks_async(fallbacks)
+      # Normalize fallbacks to callables
+      callables = fallbacks.map do |fallback|
+        case fallback
+        when Proc
+          # Handle procs with different arities
+          -> { fallback.arity == 1 ? fallback.call(nil) : fallback.call }
+        else
+          # Wrap static values in callables
+          -> { fallback }
+        end
+      end
+
+      race_tasks(callables, delay_ms: 0)
+    end
+
+    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.
+    # @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
+
+        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
+              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
+              end
+            end
+          end
+        end
+
+        # block until first signal
+        condition.wait
+
+        # tear down
+        tasks.each(&:stop)
+
+        # propagate
+        raise(exception) if exception
+
+        winner
+      end.wait
+    end
+  end
+end

data/lib/breaker_machines/hedged_execution.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require 'concurrent'
+require 'timeout'
+
+module BreakerMachines
+  # 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

data/lib/breaker_machines/registry.rb

@@ -10,6 +10,7 @@ module BreakerMachines
 
     def initialize
       @circuits = Concurrent::Map.new
+      @named_circuits = Concurrent::Map.new # For dynamic circuits by name
       @mutex = Mutex.new
       @registration_count = 0
       @cleanup_interval = 100 # Clean up every N registrations
@@ -53,6 +54,38 @@ module BreakerMachines
       all_circuits.select { |circuit| circuit.name == name }
     end
 
+    # Find first circuit by name
+    def find(name)
+      find_by_name(name).first
+    end
+
+    # Force open a circuit by name
+    def force_open(name) # rubocop:disable Naming/PredicateMethod
+      circuits = find_by_name(name)
+      return false if circuits.empty?
+
+      circuits.each(&:force_open)
+      true
+    end
+
+    # Force close a circuit by name
+    def force_close(name) # rubocop:disable Naming/PredicateMethod
+      circuits = find_by_name(name)
+      return false if circuits.empty?
+
+      circuits.each(&:force_close)
+      true
+    end
+
+    # Reset a circuit by name
+    def reset(name) # rubocop:disable Naming/PredicateMethod
+      circuits = find_by_name(name)
+      return false if circuits.empty?
+
+      circuits.each(&:reset)
+      true
+    end
+
     # Get summary statistics
     def stats_summary
       circuits = all_circuits
@@ -63,15 +96,126 @@ module BreakerMachines
       }
     end
 
+    # Get all stats with detailed metrics
+    def all_stats
+      circuits = all_circuits
+
+      {
+        summary: stats_summary,
+        circuits: circuits.map(&:stats),
+        health: {
+          open_count: circuits.count(&:open?),
+          closed_count: circuits.count(&:closed?),
+          half_open_count: circuits.count(&:half_open?),
+          total_failures: circuits.sum { |c| c.stats[:failure_count] },
+          total_successes: circuits.sum { |c| c.stats[:success_count] }
+        }
+      }
+    end
+
     # Get detailed information for all circuits
     def detailed_report
       all_circuits.map(&:to_h)
     end
 
+    # Get or create a globally managed dynamic circuit
+    def get_or_create_dynamic_circuit(name, owner, config)
+      @mutex.synchronize do
+        # Check if circuit already exists and is still alive
+        if @named_circuits.key?(name)
+          weak_ref = @named_circuits[name]
+          begin
+            existing_circuit = weak_ref.__getobj__
+            return existing_circuit if existing_circuit
+          rescue WeakRef::RefError
+            # Circuit was garbage collected, remove the stale reference
+            @named_circuits.delete(name)
+          end
+        end
+
+        # Create new circuit with weak owner reference
+        # Don't auto-register to avoid deadlock
+        weak_owner = owner.is_a?(WeakRef) ? owner : WeakRef.new(owner)
+        circuit_config = config.merge(owner: weak_owner, auto_register: false)
+        new_circuit = Circuit.new(name, circuit_config)
+
+        # Manually register the circuit (we're already in sync block)
+        @circuits[new_circuit] = WeakRef.new(new_circuit)
+        @named_circuits[name] = WeakRef.new(new_circuit)
+
+        new_circuit
+      end
+    end
+
+    # Remove a dynamic circuit by name
+    def remove_dynamic_circuit(name)
+      @mutex.synchronize do
+        if @named_circuits.key?(name)
+          weak_ref = @named_circuits.delete(name)
+          begin
+            circuit = weak_ref.__getobj__
+            @circuits.delete(circuit) if circuit
+            true
+          rescue WeakRef::RefError
+            false
+          end
+        else
+          false
+        end
+      end
+    end
+
+    # Get all dynamic circuit names
+    def dynamic_circuit_names
+      @mutex.synchronize do
+        alive_names = []
+        @named_circuits.each_pair do |name, weak_ref|
+          weak_ref.__getobj__
+          alive_names << name
+        rescue WeakRef::RefError
+          @named_circuits.delete(name)
+        end
+        alive_names
+      end
+    end
+
+    # Cleanup stale dynamic circuits older than given age
+    def cleanup_stale_dynamic_circuits(max_age_seconds = 3600)
+      @mutex.synchronize do
+        cutoff_time = Time.now - max_age_seconds
+        stale_names = []
+
+        @named_circuits.each_pair do |name, weak_ref|
+          circuit = weak_ref.__getobj__
+          # Check if circuit has a last_activity_time and it's stale
+          if circuit.respond_to?(:last_activity_time) &&
+             circuit.last_activity_time &&
+             circuit.last_activity_time < cutoff_time
+            stale_names << name
+          end
+        rescue WeakRef::RefError
+          stale_names << name
+        end
+
+        stale_names.each do |name|
+          weak_ref = @named_circuits.delete(name)
+          begin
+            circuit = weak_ref.__getobj__
+            @circuits.delete(circuit) if circuit
+          rescue WeakRef::RefError
+            # Already gone
+          end
+        end
+
+        stale_names.size
+      end
+    end
+
     # Clear all circuits (useful for testing)
     def clear
       @mutex.synchronize do
         @circuits.clear
+        @named_circuits.clear
       end
     end