breaker_machines 0.9.2-x86_64-darwin

data/lib/breaker_machines/circuit/introspection.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  class Circuit
+    # Introspection provides methods for inspecting circuit state, statistics,
+    # and generating human-readable summaries of circuit status.
+    module Introspection
+      extend ActiveSupport::Concern
+
+      # State check methods are automatically generated by state_machines:
+      # - open? (returns true when status == :open)
+      # - closed? (returns true when status == :closed)
+      # - half_open? (returns true when status == :half_open)
+
+      def stats
+        BreakerMachines::Stats.new(
+          state: status_name,
+          failure_count: @storage.failure_count(@name, @config[:failure_window]),
+          success_count: @storage.success_count(@name, @config[:failure_window]),
+          last_failure_at: @last_failure_at.value,
+          opened_at: @opened_at.value,
+          half_open_attempts: @half_open_attempts.value,
+          half_open_successes: @half_open_successes.value
+        )
+      end
+
+      def configuration
+        @config.dup
+      end
+
+      def event_log(limit: 20)
+        @storage.event_log(@name, limit) if @storage.respond_to?(:event_log)
+      end
+
+      def last_error
+        @last_error.value
+      end
+
+      def to_h
+        hash = {
+          name: @name,
+          state: status_name,
+          stats: stats.to_h,
+          config: configuration.except(:owner, :storage, :metrics),
+          event_log: event_log || [],
+          last_error: last_error_info&.to_h
+        }
+
+        # Add cascade-specific information if this is a cascading circuit
+        hash[:cascade_info] = cascade_info.to_h if is_a?(CascadingCircuit)
+
+        hash
+      end
+
+      def summary
+        base_summary = case status_name
+                       when :closed
+                         "Circuit '#{@name}' is CLOSED. #{stats.failure_count} failures recorded."
+                       when :open
+                         # Calculate time remaining until reset
+                         time_since_open = BreakerMachines.monotonic_time - @opened_at.value
+                         time_until_reset = @config[:reset_timeout] - time_since_open
+                         reset_time = time_until_reset.seconds.from_now
+                         opened_time = time_since_open.seconds.ago
+                         error_info = @last_error.value ? " The last error was #{@last_error.value.class}." : ''
+                         "Circuit '#{@name}' is OPEN until #{reset_time}. " \
+                           "It opened at #{opened_time} after #{@config[:failure_threshold]} failures.#{error_info}"
+                       when :half_open
+                         "Circuit '#{@name}' is HALF-OPEN. Testing with limited requests " \
+                         "(#{@half_open_attempts.value}/#{@config[:half_open_calls]} attempts)."
+                       end
+
+        # Add cascade information if this is a cascading circuit
+        if is_a?(CascadingCircuit) && @dependent_circuits.any?
+          base_summary += " [Cascades to: #{@dependent_circuits.join(', ')}]"
+        end
+
+        base_summary
+      end
+
+      def last_error_info
+        error = @last_error.value
+        return nil unless error
+
+        BreakerMachines::ErrorInfo.new(
+          error_class: error.class.name,
+          message: error.message,
+          occurred_at: @last_failure_at.value
+        )
+      end
+    end
+  end
+end

data/lib/breaker_machines/circuit/native.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  class Circuit
+    # Native circuit breaker implementation using Rust FFI
+    #
+    # This provides a high-performance circuit breaker with state machine logic
+    # implemented in Rust. It's fully compatible with the Ruby circuit API but
+    # significantly faster for high-throughput scenarios.
+    #
+    # @example Basic usage
+    #   circuit = BreakerMachines::Circuit::Native.new('api_calls',
+    #     failure_threshold: 5,
+    #     failure_window_secs: 60.0
+    #   )
+    #
+    #   circuit.call { api.fetch_data }
+    class Native
+      # @return [String] Circuit name
+      attr_reader :name
+
+      # @return [Hash] Circuit configuration
+      attr_reader :config
+
+      # Create a new native circuit breaker
+      #
+      # @param name [String] Circuit name
+      # @param options [Hash] Configuration options
+      # @option options [Integer] :failure_threshold Number of failures to open circuit (default: 5)
+      # @option options [Float] :failure_window_secs Time window for counting failures (default: 60.0)
+      # @option options [Float] :half_open_timeout_secs Timeout before attempting reset (default: 30.0)
+      # @option options [Integer] :success_threshold Successes needed to close from half-open (default: 2)
+      # @option options [Boolean] :auto_register Register with global registry (default: true)
+      def initialize(name, options = {})
+        unless BreakerMachines.native_available?
+          raise BreakerMachines::ConfigurationError,
+                'Native extension not available. Install with native support or use Circuit::Ruby'
+        end
+
+        @name = name
+        @config = default_config.merge(options)
+
+        # Create the native circuit breaker
+        @native_circuit = BreakerMachinesNative::Circuit.new(
+          name,
+          {
+            failure_threshold: @config[:failure_threshold],
+            failure_window_secs: @config[:failure_window_secs],
+            half_open_timeout_secs: @config[:half_open_timeout_secs],
+            success_threshold: @config[:success_threshold]
+          }
+        )
+
+        # Register with global registry unless disabled
+        BreakerMachines::Registry.instance.register(self) unless @config[:auto_register] == false
+      end
+
+      # Execute a block with circuit breaker protection
+      #
+      # @yield Block to execute
+      # @return Result of the block
+      # @raise [CircuitOpenError] if circuit is open
+      def call
+        raise CircuitOpenError, "Circuit '#{@name}' is open" if open?
+
+        start_time = BreakerMachines.monotonic_time
+        begin
+          result = yield
+          duration = BreakerMachines.monotonic_time - start_time
+          @native_circuit.record_success(duration)
+          result
+        rescue StandardError => _e
+          duration = BreakerMachines.monotonic_time - start_time
+          @native_circuit.record_failure(duration)
+          raise
+        end
+      end
+
+      # Check if circuit is open
+      # @return [Boolean]
+      def open?
+        @native_circuit.is_open
+      end
+
+      # Check if circuit is closed
+      # @return [Boolean]
+      def closed?
+        @native_circuit.is_closed
+      end
+
+      # Get current state name
+      # @return [String] 'open' or 'closed'
+      def state
+        @native_circuit.state_name
+      end
+
+      # Reset the circuit (clear all events)
+      def reset!
+        @native_circuit.reset
+      end
+
+      # Get circuit status for inspection
+      # @return [Hash] Status information
+      def status
+        {
+          name: @name,
+          state: state,
+          open: open?,
+          closed: closed?,
+          config: @config
+        }
+      end
+
+      private
+
+      def default_config
+        {
+          failure_threshold: 5,
+          failure_window_secs: 60.0,
+          half_open_timeout_secs: 30.0,
+          success_threshold: 2,
+          auto_register: true
+        }
+      end
+    end
+  end
+end

data/lib/breaker_machines/circuit/state_callbacks.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  class Circuit
+    # StateCallbacks provides the common callback methods shared by all state management modules
+    module StateCallbacks
+      extend ActiveSupport::Concern
+
+      private
+
+      def on_circuit_open
+        @opened_at.value = BreakerMachines.monotonic_time
+        @storage&.set_status(@name, :open, @opened_at.value)
+        if @storage.respond_to?(:record_event_with_details)
+          @storage.record_event_with_details(@name, :state_change, 0,
+                                             new_state: :open)
+        end
+        invoke_callback(:on_open)
+        BreakerMachines.instrument('opened', circuit: @name)
+      end
+
+      def on_circuit_close
+        @opened_at.value = nil
+        @last_error.value = nil
+        @last_failure_at.value = nil
+        @storage&.set_status(@name, :closed)
+        if @storage.respond_to?(:record_event_with_details)
+          @storage.record_event_with_details(@name, :state_change, 0,
+                                             new_state: :closed)
+        end
+        invoke_callback(:on_close)
+        BreakerMachines.instrument('closed', circuit: @name)
+      end
+
+      def on_circuit_half_open
+        @half_open_attempts.value = 0
+        @half_open_successes.value = 0
+        @storage&.set_status(@name, :half_open)
+        if @storage.respond_to?(:record_event_with_details)
+          @storage.record_event_with_details(@name, :state_change, 0,
+                                             new_state: :half_open)
+        end
+        invoke_callback(:on_half_open)
+        BreakerMachines.instrument('half_opened', circuit: @name)
+      end
+
+      def reset_timeout_elapsed?
+        return false unless @opened_at.value
+
+        # Add jitter to prevent thundering herd using ChronoMachines
+        # This matches the Rust implementation which uses chrono-machines for jitter
+        timeout_with_jitter = if (jitter_factor = @config[:reset_timeout_jitter]) && jitter_factor.positive?
+                                calculate_timeout_with_jitter(@config[:reset_timeout], jitter_factor)
+                              else
+                                @config[:reset_timeout]
+                              end
+
+        BreakerMachines.monotonic_time - @opened_at.value >= timeout_with_jitter
+      end
+
+      # Calculate timeout with jitter using ChronoMachines algorithm
+      # Matches the Rust implementation: timeout * (1 - jitter + rand * jitter)
+      def calculate_timeout_with_jitter(base_timeout, jitter_factor)
+        # Use full jitter strategy from ChronoMachines
+        # Formula: base * (1 - jitter + rand * jitter)
+        # This gives values in range [base * (1-jitter), base]
+        normalized_jitter = [jitter_factor.to_f, 1.0].min
+        base_timeout * (1.0 - normalized_jitter + (rand * normalized_jitter))
+      end
+    end
+  end
+end

data/lib/breaker_machines/circuit/state_management.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  class Circuit
+    # StateManagement provides the state machine functionality for circuit breakers,
+    # managing transitions between closed, open, and half-open states.
+    module StateManagement
+      extend ActiveSupport::Concern
+
+      included do
+        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
+          end
+
+          event :reset do
+            transition %i[open half_open] => :closed
+            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
+    end
+  end
+end

data/lib/breaker_machines/circuit.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  class Circuit
+    include Circuit::Base
+    include StateManagement
+  end
+end

data/lib/breaker_machines/circuit_group.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  # CircuitGroup provides coordinated management of multiple related circuits
+  # with support for dependencies, shared configuration, and group-wide operations
+  class CircuitGroup
+    include BreakerMachines::DSL
+
+    attr_reader :name, :circuits, :dependencies, :config
+
+    def initialize(name, config = {})
+      @name = name
+      @config = config
+      @circuits = {}
+      @dependencies = {}
+      @async_mode = config[:async_mode] || false
+    end
+
+    # Define a circuit within this group with optional dependencies
+    # @param name [Symbol] Circuit name
+    # @param options [Hash] Circuit configuration
+    # @option options [Symbol, Array<Symbol>] :depends_on Other circuits this one depends on
+    # @option options [Proc] :guard_with Additional guard conditions
+    def circuit(name, options = {}, &)
+      depends_on = Array(options.delete(:depends_on))
+      guard_proc = options.delete(:guard_with)
+
+      # Add group-wide defaults
+      circuit_config = @config.merge(options)
+
+      # Create appropriate circuit type
+      circuit_class = if options[:cascades_to] || depends_on.any?
+                        BreakerMachines::CascadingCircuit
+                      elsif @async_mode
+                        BreakerMachines::AsyncCircuit
+                      else
+                        BreakerMachines::Circuit
+                      end
+
+      # Build the circuit
+      circuit_instance = if block_given?
+                           builder = BreakerMachines::DSL::CircuitBuilder.new
+                           builder.instance_eval(&)
+                           built_config = builder.config.merge(circuit_config)
+                           circuit_class.new(full_circuit_name(name), built_config)
+                         else
+                           circuit_class.new(full_circuit_name(name), circuit_config)
+                         end
+
+      # Store dependencies and guards
+      if depends_on.any? || guard_proc
+        @dependencies[name] = {
+          depends_on: depends_on,
+          guard: guard_proc
+        }
+
+        # Wrap the circuit with dependency checking
+        circuit_instance = DependencyWrapper.new(circuit_instance, self, name)
+      end
+
+      @circuits[name] = circuit_instance
+      BreakerMachines.register(circuit_instance)
+      circuit_instance
+    end
+
+    # Get a circuit by name
+    def [](name)
+      @circuits[name]
+    end
+
+    # Check if all circuits in the group are healthy
+    def all_healthy?
+      @circuits.values.all? { |circuit| circuit.closed? || circuit.half_open? }
+    end
+
+    # Check if any circuit in the group is open
+    def any_open?
+      @circuits.values.any?(&:open?)
+    end
+
+    # Get status of all circuits
+    def status
+      @circuits.transform_values(&:status_name)
+    end
+
+    # Reset all circuits in the group
+    def reset_all!
+      @circuits.each_value(&:reset!)
+    end
+
+    # Force open all circuits
+    def trip_all!
+      @circuits.each_value(&:force_open!)
+    end
+
+    # Check dependencies for a specific circuit
+    def dependencies_met?(circuit_name)
+      deps = @dependencies[circuit_name]
+      return true unless deps
+
+      depends_on = deps[:depends_on]
+      guard = deps[:guard]
+
+      # Check circuit dependencies recursively
+      dependencies_healthy = depends_on.all? do |dep_name|
+        dep_circuit = @circuits[dep_name]
+        # Circuit must exist, be healthy, AND have its own dependencies met
+        dep_circuit && (dep_circuit.closed? || dep_circuit.half_open?) && dependencies_met?(dep_name)
+      end
+
+      # Check custom guard
+      guard_passed = guard ? guard.call : true
+
+      dependencies_healthy && guard_passed
+    end
+
+    private
+
+    def full_circuit_name(name)
+      "#{@name}.#{name}"
+    end
+
+    # Wrapper to enforce dependencies
+    class DependencyWrapper < SimpleDelegator
+      def initialize(circuit, group, name)
+        super(circuit)
+        @group = group
+        @name = name
+      end
+
+      def call(&)
+        unless @group.dependencies_met?(@name)
+          raise BreakerMachines::CircuitDependencyError.new(__getobj__.name,
+                                                            "Dependencies not met for circuit #{@name}")
+        end
+
+        __getobj__.call(&)
+      end
+
+      def attempt_recovery!
+        return false unless @group.dependencies_met?(@name)
+
+        __getobj__.attempt_recovery!
+      end
+
+      def reset!
+        return false unless @group.dependencies_met?(@name)
+
+        __getobj__.reset!
+      end
+    end
+  end
+end