breaker_machines 0.9.2-x86_64-darwin

data/lib/breaker_machines/dsl.rb

@@ -0,0 +1,283 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  # DSL module for adding circuit breakers to classes
+  #
+  # This module uses WeakRef to track instances that include the DSL.
+  # Why? In long-running applications (web servers, background workers),
+  # objects that include this DSL may be created and destroyed frequently.
+  # Without WeakRef, the registry would hold strong references to these
+  # objects, preventing garbage collection and causing memory leaks.
+  #
+  # Example scenario: A Rails controller that includes BreakerMachines::DSL
+  # is instantiated for each request. Without WeakRef, every controller
+  # instance would be kept in memory forever.
+  module DSL
+    extend ActiveSupport::Concern
+
+    # Track instances for each class that includes DSL
+    # Using WeakRef to allow garbage collection
+    @instance_registries = Concurrent::Map.new
+
+    class_methods do
+      # Get or create instance registry for this class
+      def instance_registry
+        # Access the module-level registry
+        registry = BreakerMachines::DSL.instance_variable_get(:@instance_registries)
+        registry.compute_if_absent(self) { Concurrent::Array.new }
+      end
+
+      # Clean up dead references in the registry
+      def cleanup_instance_registry
+        registry = instance_registry
+        # Concurrent::Array supports delete_if
+        registry.delete_if do |weak_ref|
+          weak_ref.__getobj__
+          false
+        rescue WeakRef::RefError
+          true
+        end
+      end
+
+      def circuit(name, &block)
+        @circuits ||= {}
+
+        if block_given?
+          builder = DSL::CircuitBuilder.new
+          builder.instance_eval(&block)
+          @circuits[name] = builder.config
+        end
+
+        @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)
+                          superclass.circuits.deep_dup
+                        else
+                          {}
+                        end
+
+        # Merge with our own circuits
+        if @circuits
+          base_circuits.merge(@circuits)
+        else
+          base_circuits
+        end
+      end
+
+      # Define reusable circuit templates
+      def circuit_template(name, &block)
+        @circuit_templates ||= {}
+
+        if block_given?
+          builder = DSL::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) }
+      end
+
+      # Reset all circuits for all instances of this class
+      def reset_all_circuits
+        cleanup_instance_registry # Clean up dead refs first
+
+        instance_registry.each do |weak_ref|
+          instance = weak_ref.__getobj__
+          circuit_instances = instance.instance_variable_get(:@circuit_instances)
+          circuit_instances&.each_value(&:hard_reset!)
+        rescue WeakRef::RefError
+          # Instance was garbage collected, skip it
+        end
+      end
+
+      # Get aggregated stats for all circuits of this class
+      def circuit_stats
+        stats = Hash.new { |h, k| h[k] = { total: 0, by_state: {} } }
+        cleanup_instance_registry # Clean up dead refs first
+
+        instance_registry.each do |weak_ref|
+          instance = weak_ref.__getobj__
+          circuit_instances = instance.instance_variable_get(:@circuit_instances)
+          next unless circuit_instances
+
+          circuit_instances.each do |name, circuit|
+            stats[name][:total] += 1
+            state = circuit.status_name
+            stats[name][:by_state][state] ||= 0
+            stats[name][:by_state][state] += 1
+          end
+        rescue WeakRef::RefError
+          # Instance was garbage collected, skip it
+        end
+
+        stats
+      end
+    end
+
+    # Use included callback to add instance tracking
+    def self.included(base)
+      super
+
+      # Hook into new to register instances
+      base.singleton_class.prepend(Module.new do
+        def new(...)
+          instance = super
+          instance_registry << WeakRef.new(instance)
+          instance
+        end
+      end)
+    end
+
+    def circuit(name)
+      self.class.circuits[name] ||= {}
+      @circuit_instances ||= {}
+
+      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
+    # 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 = DSL::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 || {}
+    end
+
+    # Get summary of all circuits for this instance
+    def circuits_summary
+      circuit_instances.transform_values(&:summary)
+    end
+
+    # Get detailed information for all circuits
+    def circuits_report
+      circuit_instances.transform_values(&:to_h)
+    end
+
+    # Reset all circuits for this instance
+    def reset_all_circuits
+      circuit_instances.each_value(&:hard_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
+  end
+end

data/lib/breaker_machines/errors.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  class Error < StandardError; end
+
+  # Raised when attempting to use a circuit that is in the open state
+  class CircuitOpenError < Error
+    attr_reader :circuit_name, :opened_at
+
+    def initialize(circuit_name, opened_at = nil)
+      @circuit_name = circuit_name
+      @opened_at = opened_at
+      super("Circuit '#{circuit_name}' is open")
+    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
+
+    def initialize(circuit_name, timeout)
+      @circuit_name = circuit_name
+      @timeout = timeout
+      super("Circuit '#{circuit_name}' timed out after #{timeout}s")
+    end
+  end
+
+  class ConfigurationError < Error; end
+  class StorageError < Error; end
+
+  # Raised when storage backend operation times out
+  class StorageTimeoutError < StorageError
+    attr_reader :timeout_ms
+
+    def initialize(message, timeout_ms = nil)
+      @timeout_ms = timeout_ms
+      super(message)
+    end
+  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
+
+  # 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

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+# 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/promise'
+require 'async/barrier'
+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 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)
+      promise = Async::Promise.new
+      barrier = Async::Barrier.new
+
+      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
+                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
+
+          # Wait for the first resolution (either success or exception)
+          promise.wait
+        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

data/lib/breaker_machines/native_extension.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'rbconfig'
+require 'active_support/core_ext/object/blank'
+
+module BreakerMachines
+  # Handles loading and status of the optional native extension
+  module NativeExtension
+    class << self
+      # Load the native extension and set availability flag
+      # Can be called multiple times - subsequent calls are memoized
+      def load!
+        return @loaded if defined?(@loaded)
+
+        # Native extension is opt-in: only load if explicitly enabled
+        unless ENV['BREAKER_MACHINES_NATIVE'] == '1'
+          @loaded = false
+          BreakerMachines.instance_variable_set(:@native_available, false)
+          return false
+        end
+
+        errors = []
+
+        native_library_candidates.each do |require_path|
+          try_require(require_path)
+          @loaded = true
+          BreakerMachines.instance_variable_set(:@native_available, true)
+          BreakerMachines.log(:info, "Native extension loaded successfully (#{require_path})")
+          return true
+        rescue LoadError => e
+          errors << "#{require_path}: #{e.message}"
+        end
+
+        @loaded = false
+        BreakerMachines.instance_variable_set(:@native_available, false)
+        BreakerMachines.log(:warn, "Native extension not available: #{errors.join(' | ')}") unless errors.empty?
+
+        false
+      end
+
+      # Check if load was attempted
+      def loaded?
+        defined?(@loaded) && @loaded
+      end
+
+      private
+
+      def native_library_candidates
+        dlext = RbConfig::CONFIG['DLEXT']
+        base_dir = File.expand_path('../breaker_machines_native', __dir__)
+        ruby_version = RbConfig::CONFIG['ruby_version']
+        arch = RbConfig::CONFIG['arch']
+        platform = Gem::Platform.local.to_s
+
+        matches = Dir.glob(File.join(base_dir, '**', "breaker_machines_native.#{dlext}"))
+
+        prioritized = matches.sort_by do |path|
+          score = 0
+          score -= 3 if path.include?(ruby_version)
+          score -= 2 if path.include?(arch)
+          score -= 1 if path.include?(platform)
+          [score, path]
+        end
+
+        candidates = prioritized.map { |full_path| require_path_for(full_path, dlext) }.presence
+        candidates ||= ['breaker_machines_native/breaker_machines_native']
+        candidates.uniq
+      end
+
+      def require_path_for(full_path, dlext)
+        root = File.expand_path('..', __dir__)
+        relative = full_path.sub(%r{^#{Regexp.escape(root)}/?}, '')
+        relative.sub(/\.#{Regexp.escape(dlext)}\z/, '')
+      end
+
+      def try_require(require_path)
+        require require_path
+      end
+    end
+  end
+end

data/lib/breaker_machines/native_speedup.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative 'native_extension'
+
+# Load the native extension if available
+if BreakerMachines::NativeExtension.load!
+  # Only load Storage::Native if native extension loaded successfully
+  # This prevents referencing BreakerMachinesNative::Storage when not available
+  require_relative 'storage/native'
+end