breaker_machines 0.4.0 → 0.6.0

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

@@ -6,6 +6,7 @@ module BreakerMachines
     # 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
@@ -30,77 +31,29 @@ module BreakerMachines
             transition any => :closed
           end
 
-          after_transition any => :open do |circuit|
+          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 any => :closed do |circuit|
+          after_transition to: :closed do |circuit|
             circuit.send(:on_circuit_close)
           end
 
-          after_transition open: :half_open do |circuit|
+          after_transition from: :open, to: :half_open do |circuit|
             circuit.send(:on_circuit_half_open)
           end
         end
       end
-
-      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 restore_status_from_storage
-        stored_status = @storage.get_status(@name)
-        return unless stored_status
-
-        self.status = stored_status.status.to_s
-        @opened_at.value = stored_status.opened_at if stored_status.opened_at
-      end
-
-      def reset_timeout_elapsed?
-        return false unless @opened_at.value
-
-        # Add jitter to prevent thundering herd
-        jitter_factor = @config[:reset_timeout_jitter] || 0.25
-        # Calculate random jitter between -jitter_factor and +jitter_factor
-        jitter_multiplier = 1.0 + (((rand * 2) - 1) * jitter_factor)
-        timeout_with_jitter = @config[:reset_timeout] * jitter_multiplier
-
-        BreakerMachines.monotonic_time - @opened_at.value >= timeout_with_jitter
-      end
     end
   end
 end

data/lib/breaker_machines/circuit.rb

@@ -1,14 +1,8 @@
 # frozen_string_literal: true
 
-require 'concurrent-ruby'
-
 module BreakerMachines
   class Circuit
+    include Circuit::Base
     include StateManagement
-    include Configuration
-    include Execution
-    include HedgedExecution
-    include Introspection
-    include Callbacks
   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

data/lib/breaker_machines/coordinated_circuit.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  # CoordinatedCircuit is a base class for circuits that need coordinated state management.
+  # It replaces the standard StateManagement module with CoordinatedStateManagement
+  # to enable state transitions based on other circuits' states.
+  class CoordinatedCircuit < Circuit
+    include Circuit::CoordinatedStateManagement
+  end
+end

data/lib/breaker_machines/dsl.rb

@@ -122,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
@@ -262,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

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

data/lib/breaker_machines/native_extension.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+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)
+
+        @loaded = true
+        require 'breaker_machines_native/breaker_machines_native'
+        BreakerMachines.instance_variable_set(:@native_available, true)
+        BreakerMachines.log(:info, 'Native extension loaded successfully')
+        true
+      rescue LoadError => e
+        @loaded = false
+        BreakerMachines.instance_variable_set(:@native_available, false)
+
+        # Only log if it's not JRuby (expected failure) and logging is enabled
+        if RUBY_ENGINE != 'jruby'
+          BreakerMachines.log(:warn, "Native extension not available: #{e.message}")
+          BreakerMachines.log(:warn, 'Using pure Ruby backend (slower but functional)')
+        end
+
+        false
+      end
+
+      # Check if load was attempted
+      def loaded?
+        defined?(@loaded) && @loaded
+      end
+    end
+  end
+end

data/lib/breaker_machines/native_speedup.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'native_extension'
+
+# Load the native extension if available
+BreakerMachines::NativeExtension.load!

data/lib/breaker_machines/storage/bucket_memory.rb

@@ -21,6 +21,8 @@ module BreakerMachines
         @event_logs = Concurrent::Map.new
         @bucket_count = options[:bucket_count] || 300 # Default 5 minutes
         @max_events = options[:max_events] || 100
+        # Store creation time as anchor for relative timestamps (like Rust implementation)
+        @start_time = BreakerMachines.monotonic_time
       end
 
       def get_status(circuit_name)
@@ -160,7 +162,8 @@ module BreakerMachines
       end
 
       def monotonic_time
-        BreakerMachines.monotonic_time
+        # Return time relative to storage creation (matches Rust implementation)
+        BreakerMachines.monotonic_time - @start_time
       end
 
       def with_timeout(_timeout_ms)

data/lib/breaker_machines/storage/memory.rb

@@ -17,6 +17,8 @@ module BreakerMachines
         @events = Concurrent::Map.new
         @event_logs = Concurrent::Map.new
         @max_events = options[:max_events] || 100
+        # Store creation time as anchor for relative timestamps (like Rust implementation)
+        @start_time = BreakerMachines.monotonic_time
       end
 
       def get_status(circuit_name)
@@ -130,7 +132,8 @@ module BreakerMachines
       end
 
       def monotonic_time
-        BreakerMachines.monotonic_time
+        # Return time relative to storage creation (matches Rust implementation)
+        BreakerMachines.monotonic_time - @start_time
       end
     end
   end

data/lib/breaker_machines/storage/native.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  module Storage
+    # Native extension storage backend for high-performance event tracking
+    #
+    # This backend provides identical functionality to Memory storage but with
+    # significantly better performance for sliding window calculations. It's
+    # particularly beneficial for high-throughput applications where circuit
+    # breaker state checks happen on every request.
+    #
+    # Performance: ~63x faster than Memory storage for sliding window calculations
+    #
+    # Usage:
+    #   BreakerMachines.configure do |config|
+    #     config.default_storage = :native
+    #   end
+    #
+    # Fallback: If the native extension isn't available (e.g., on JRuby or if
+    # Rust wasn't installed during gem installation), this will raise LoadError.
+    # Use Storage::Memory as a fallback in such cases.
+    class Native < Base
+      def initialize(**options)
+        super
+        unless defined?(BreakerMachinesNative::Storage)
+          raise LoadError, 'Native extension not available. Use Storage::Memory instead.'
+        end
+
+        @native = BreakerMachinesNative::Storage.new
+      end
+
+      def get_status(_circuit_name)
+        # Status is still managed by Ruby layer
+        # This storage backend only handles event tracking
+        nil
+      end
+
+      def set_status(circuit_name, status, opened_at = nil)
+        # Status management delegated to Ruby layer
+        # This backend focuses on high-performance event counting
+      end
+
+      def record_success(circuit_name, duration)
+        @native.record_success(circuit_name.to_s, duration.to_f)
+      end
+
+      def record_failure(circuit_name, duration)
+        @native.record_failure(circuit_name.to_s, duration.to_f)
+      end
+
+      def success_count(circuit_name, window_seconds)
+        @native.success_count(circuit_name.to_s, window_seconds.to_f)
+      end
+
+      def failure_count(circuit_name, window_seconds)
+        @native.failure_count(circuit_name.to_s, window_seconds.to_f)
+      end
+
+      def clear(circuit_name)
+        @native.clear(circuit_name.to_s)
+      end
+
+      def clear_all
+        @native.clear_all
+      end
+
+      def record_event_with_details(circuit_name, type, duration, error: nil, new_state: nil)
+        # Basic event recording (native extension handles type and duration)
+        case type
+        when :success
+          record_success(circuit_name, duration)
+        when :failure
+          record_failure(circuit_name, duration)
+        end
+
+        # NOTE: Error and state details not tracked in native backend
+        # This is intentional for performance - use Memory backend if you need full event details
+      end
+
+      def event_log(circuit_name, limit)
+        @native.event_log(circuit_name.to_s, limit)
+      end
+
+      def with_timeout(_timeout_ms)
+        # Native operations should be instant
+        yield
+      end
+    end
+  end
+end

data/lib/breaker_machines/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BreakerMachines
-  VERSION = '0.4.0'
+  VERSION = '0.6.0'
 end