breaker_machines 0.3.0 → 0.5.0

data/lib/breaker_machines/circuit/execution.rb

@@ -89,7 +89,7 @@ module BreakerMachines
           return execute_call_async(&block)
         end
 
-        start_time = monotonic_time
+        start_time = BreakerMachines.monotonic_time
 
         begin
           # IMPORTANT: We do NOT implement forceful timeouts as they are inherently unsafe
@@ -113,11 +113,11 @@ module BreakerMachines
                      block.call
                    end
 
-          record_success(monotonic_time - start_time)
+          record_success(BreakerMachines.monotonic_time - start_time)
           handle_success
           result
         rescue *@config[:exceptions] => e
-          record_failure(monotonic_time - start_time, e)
+          record_failure(BreakerMachines.monotonic_time - start_time, e)
           handle_failure
           raise unless @config[:fallback]
 
@@ -217,7 +217,7 @@ module BreakerMachines
       end
 
       def record_failure(duration, error = nil)
-        @last_failure_at.value = monotonic_time
+        @last_failure_at.value = BreakerMachines.monotonic_time
         @last_error.value = error if error
         @metrics&.record_failure(@name, duration)
         @storage&.record_failure(@name, duration)
@@ -226,10 +226,6 @@ module BreakerMachines
         @storage.record_event_with_details(@name, :failure, duration,
                                            error: error)
       end
-
-      def monotonic_time
-        Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      end
     end
   end
 end

data/lib/breaker_machines/circuit/hedged_execution.rb

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

data/lib/breaker_machines/circuit/introspection.rb

@@ -6,13 +6,14 @@ module BreakerMachines
     # 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]),
@@ -20,7 +21,7 @@ module BreakerMachines
           opened_at: @opened_at.value,
           half_open_attempts: @half_open_attempts.value,
           half_open_successes: @half_open_successes.value
-        }
+        )
       end
 
       def configuration
@@ -36,41 +37,56 @@ module BreakerMachines
       end
 
       def to_h
-        {
+        hash = {
           name: @name,
           state: status_name,
-          stats: stats,
+          stats: stats.to_h,
           config: configuration.except(:owner, :storage, :metrics),
           event_log: event_log || [],
-          last_error: last_error_info
+          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
-        case status_name
-        when :closed
-          "Circuit '#{@name}' is CLOSED. #{stats[:failure_count]} failures recorded."
-        when :open
-          reset_time = Time.at(@opened_at.value + @config[:reset_timeout])
-          opened_time = Time.at(@opened_at.value)
-          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)."
+        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
 
-        {
-          class: error.class.name,
+        BreakerMachines::ErrorInfo.new(
+          error_class: error.class.name,
           message: error.message,
           occurred_at: @last_failure_at.value
-        }
+        )
       end
     end
   end

data/lib/breaker_machines/circuit/state_callbacks.rb

@@ -0,0 +1,60 @@
+# 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
+        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/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
@@ -19,6 +20,7 @@ module BreakerMachines
 
           event :reset do
             transition %i[open half_open] => :closed
+            transition closed: :closed
           end
 
           event :force_open do
@@ -29,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) if circuit.storage
+            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 = 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
-
-        monotonic_time - @opened_at.value >= timeout_with_jitter
-      end
     end
   end
 end

data/lib/breaker_machines/circuit.rb

@@ -1,15 +1,8 @@
 # frozen_string_literal: true
 
-require 'state_machines'
-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/console.rb

@@ -114,9 +114,9 @@ module BreakerMachines
 
         printf "%-20s %-12s %-10d %-10d %s\n",
                circuit.name,
-               colorize_state(stats[:state]),
-               stats[:failure_count],
-               stats[:success_count],
+               colorize_state(stats.state),
+               stats.failure_count,
+               stats.success_count,
                error_info
       end
 
@@ -167,22 +167,22 @@ module BreakerMachines
         stats = circuit.stats
         config = circuit.configuration
 
-        puts "Current State: #{colorize_state(stats[:state])}"
-        puts "Failure Count: #{stats[:failure_count]} / #{config[:failure_threshold]}"
-        puts "Success Count: #{stats[:success_count]}"
+        puts "Current State: #{colorize_state(stats.state)}"
+        puts "Failure Count: #{stats.failure_count} / #{config[:failure_threshold]}"
+        puts "Success Count: #{stats.success_count}"
 
-        if stats[:opened_at]
-          puts "Opened At: #{Time.at(stats[:opened_at])}"
-          reset_time = Time.at(stats[:opened_at] + config[:reset_timeout])
+        if stats.opened_at
+          puts "Opened At: #{Time.at(stats.opened_at)}"
+          reset_time = Time.at(stats.opened_at + config[:reset_timeout])
           puts "Reset At: #{reset_time} (in #{(reset_time - Time.now).to_i}s)"
         end
 
         if circuit.last_error
           error_info = circuit.last_error_info
           puts "\nLast Error:"
-          puts "  Class: #{error_info[:class]}"
-          puts "  Message: #{error_info[:message]}"
-          puts "  Time: #{Time.at(error_info[:occurred_at])}"
+          puts "  Class: #{error_info.error_class}"
+          puts "  Message: #{error_info.message}"
+          puts "  Time: #{Time.at(error_info.occurred_at)}"
         end
 
         puts "\nConfiguration:"

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/cascading_circuit_builder.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  module DSL
+    # Builder for cascading circuit breaker configuration
+    class CascadingCircuitBuilder < CircuitBuilder
+      def cascades_to(*circuit_names)
+        @config[:cascades_to] = circuit_names.flatten
+      end
+
+      def emergency_protocol(protocol_name)
+        @config[:emergency_protocol] = protocol_name
+      end
+
+      def on_cascade(&block)
+        @config[:on_cascade] = block
+      end
+    end
+  end
+end