breaker_machines 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e76d6f4335010b14f4ee48ac1366c060bd6b5feaad379896d857856c3dc6a2d
-  data.tar.gz: d7f48bec133630d584387aaa56df9c3cd3884e8f9771353e8df7e214b8df7431
+  metadata.gz: dc152fbf822d0eae49f25c2f8acea2c3268c141d8a62a7aa313168007499e8a5
+  data.tar.gz: 5e7d529cde4b41cbb32fca7502249c15465413c4fad31e9a29056fbc99196e09
 SHA512:
-  metadata.gz: f98f52400de806bb0df4784d0635560764600ba812b5bc7e99c5eebc8f4ab1d884890d08ca399e458d1f5ca4a1b9192be46562e9b3c66aa311923f0a59f58604
-  data.tar.gz: c5349911ce027af37b0c41557feb9c0126a1d6d11539650e48f8151855bd7512a859711f0335e9934c18abd879ce28b39adde778bc85d751cdd89728a3c768af
+  metadata.gz: fa71a3f703c2d9814a836d2eb160eaf89f1ea991cf80d96a237aa9b59654d13d7b0459c41c4b8a5018fc27b83fd2a6729b7740238372a8691e0aff944f5965a3
+  data.tar.gz: 59c7fd005d672ad412f9824c4880f2fc9f0141fa56f0bc405d63f9f3a95f05278b54fdceb5e97e93a18116c4e4101dc80db730eecfcd854656e0324fb1074d3d

data/lib/breaker_machines/async_support.rb

@@ -18,7 +18,7 @@ module BreakerMachines
 
     # Execute a call with async support (fiber-safe mode)
     def execute_call_async(&)
-      start_time = monotonic_time
+      start_time = BreakerMachines.monotonic_time
 
       begin
         # Execute with hedged requests if enabled
@@ -28,14 +28,14 @@ module BreakerMachines
                    execute_with_async_timeout(@config[:timeout], &)
                  end
 
-        record_success(monotonic_time - start_time)
+        record_success(BreakerMachines.monotonic_time - start_time)
         handle_success
         result
       rescue StandardError => e
         # Re-raise if it's not an async timeout or configured exception
         raise unless e.is_a?(async_timeout_error_class) || @config[:exceptions].any? { |klass| e.is_a?(klass) }
 
-        record_failure(monotonic_time - start_time, e)
+        record_failure(BreakerMachines.monotonic_time - start_time, e)
         handle_failure
         raise unless @config[:fallback]
 

data/lib/breaker_machines/cascading_circuit.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  # CascadingCircuit extends the base Circuit class with the ability to automatically
+  # trip dependent circuits when this circuit opens. This enables sophisticated
+  # failure cascade modeling, similar to how critical system failures in a starship
+  # would cascade to dependent subsystems.
+  #
+  # @example Starship network dependency
+  #   # Network circuit that cascades to dependent systems
+  #   network_circuit = BreakerMachines::CascadingCircuit.new('subspace_network', {
+  #     failure_threshold: 1,
+  #     cascades_to: ['weapons_targeting', 'navigation_sensors', 'communications'],
+  #     emergency_protocol: :red_alert
+  #   })
+  #
+  #   # When network fails, all dependent systems are automatically tripped
+  #   network_circuit.call { raise 'Subspace relay offline!' }
+  #   # => All dependent circuits are now open
+  #
+  class CascadingCircuit < Circuit
+    attr_reader :dependent_circuits, :emergency_protocol
+
+    def initialize(name, config = {})
+      @dependent_circuits = Array(config.delete(:cascades_to))
+      @emergency_protocol = config.delete(:emergency_protocol)
+
+      super
+    end
+
+    # Override the trip method to include cascading behavior
+    def trip!
+      result = super
+      perform_cascade if result && @dependent_circuits.any?
+      result
+    end
+
+    # Force cascade failure to all dependent circuits
+    def cascade_failure!
+      perform_cascade
+    end
+
+    # Get the current status of all dependent circuits
+    def dependent_status
+      return {} if @dependent_circuits.empty?
+
+      @dependent_circuits.each_with_object({}) do |circuit_name, status|
+        circuit = BreakerMachines.registry.find(circuit_name)
+        status[circuit_name] = circuit ? circuit.status_name : :not_found
+      end
+    end
+
+    # Check if any dependent circuits are open
+    def dependents_compromised?
+      @dependent_circuits.any? do |circuit_name|
+        circuit = BreakerMachines.registry.find(circuit_name)
+        circuit&.open?
+      end
+    end
+
+    # Summary that includes cascade information
+    def summary
+      base_summary = super
+      return base_summary if @dependent_circuits.empty?
+
+      if @cascade_triggered_at&.value
+        compromised_count = dependent_status.values.count(:open)
+        " CASCADE TRIGGERED: #{compromised_count}/#{@dependent_circuits.length} dependent systems compromised."
+      else
+        " Monitoring #{@dependent_circuits.length} dependent systems."
+      end
+
+      base_summary + cascade_info_text
+    end
+
+    # Provide cascade info for introspection
+    def cascade_info
+      BreakerMachines::CascadeInfo.new(
+        dependent_circuits: @dependent_circuits,
+        emergency_protocol: @emergency_protocol,
+        cascade_triggered_at: @cascade_triggered_at&.value,
+        dependent_status: dependent_status
+      )
+    end
+
+    private
+
+    def perform_cascade
+      return if @dependent_circuits.empty?
+
+      cascade_results = []
+      @cascade_triggered_at ||= Concurrent::AtomicReference.new
+      @cascade_triggered_at.value = BreakerMachines.monotonic_time
+
+      @dependent_circuits.each do |circuit_name|
+        # First try to find circuit in registry
+        circuit = BreakerMachines.registry.find(circuit_name)
+
+        # If not found and we have an owner, try to get it from the owner
+        if !circuit && @config[:owner]
+          owner = @config[:owner]
+          # Handle WeakRef if present
+          owner = owner.__getobj__ if owner.is_a?(WeakRef)
+
+          circuit = owner.circuit(circuit_name) if owner.respond_to?(:circuit)
+        end
+
+        next unless circuit
+        next unless circuit.closed? || circuit.half_open?
+
+        # Force the dependent circuit to open
+        circuit.force_open!
+        cascade_results << circuit_name
+
+        BreakerMachines.instrument('cascade_failure', {
+                                     source_circuit: @name,
+                                     target_circuit: circuit_name,
+                                     emergency_protocol: @emergency_protocol
+                                   })
+      end
+
+      # Trigger emergency protocol if configured
+      trigger_emergency_protocol(cascade_results) if @emergency_protocol && cascade_results.any?
+
+      # Invoke cascade callback if configured
+      if @config[:on_cascade]
+        begin
+          @config[:on_cascade].call(cascade_results) if @config[:on_cascade].respond_to?(:call)
+        rescue StandardError => e
+          # Log callback error but don't fail the cascade
+          BreakerMachines.logger&.error "Cascade callback error: #{e.message}"
+        end
+      end
+
+      cascade_results
+    end
+
+    def trigger_emergency_protocol(affected_circuits)
+      BreakerMachines.instrument('emergency_protocol_triggered', {
+                                   protocol: @emergency_protocol,
+                                   source_circuit: @name,
+                                   affected_circuits: affected_circuits
+                                 })
+
+      # Allow custom emergency protocol handling
+      owner = @config[:owner]
+      if owner&.respond_to?(@emergency_protocol, true)
+        begin
+          owner.send(@emergency_protocol, affected_circuits)
+        rescue StandardError => e
+          BreakerMachines.logger&.error "Emergency protocol error: #{e.message}"
+        end
+      elsif respond_to?(@emergency_protocol, true)
+        begin
+          send(@emergency_protocol, affected_circuits)
+        rescue StandardError => e
+          BreakerMachines.logger&.error "Emergency protocol error: #{e.message}"
+        end
+      end
+    end
+
+    # Override the on_circuit_open callback to include cascading
+    def on_circuit_open
+      super # Call the original implementation
+      perform_cascade if @dependent_circuits.any?
+    end
+
+    # Force open should also cascade
+    def force_open!
+      result = super
+      perform_cascade if result && @dependent_circuits.any?
+      result
+    end
+  end
+end

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

@@ -12,7 +12,7 @@ module BreakerMachines
       # - 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 +20,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 +36,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_management.rb

@@ -19,6 +19,7 @@ module BreakerMachines
 
           event :reset do
             transition %i[open half_open] => :closed
+            transition closed: :closed
           end
 
           event :force_open do
@@ -46,7 +47,7 @@ module BreakerMachines
       private
 
       def on_circuit_open
-        @opened_at.value = monotonic_time
+        @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,
@@ -85,8 +86,8 @@ module BreakerMachines
         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]
+        self.status = stored_status.status.to_s
+        @opened_at.value = stored_status.opened_at if stored_status.opened_at
       end
 
       def reset_timeout_elapsed?
@@ -98,7 +99,7 @@ module BreakerMachines
         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
+        BreakerMachines.monotonic_time - @opened_at.value >= timeout_with_jitter
       end
     end
   end

data/lib/breaker_machines/circuit.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require 'state_machines'
 require 'concurrent-ruby'
 
 module BreakerMachines

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/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

data/lib/breaker_machines/dsl/circuit_builder.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  module DSL
+    # DSL builder for configuring circuit breakers with a fluent interface
+    class CircuitBuilder
+      attr_reader :config
+
+      def initialize
+        @config = {
+          failure_threshold: 5,
+          failure_window: 60.seconds,
+          success_threshold: 1,
+          timeout: nil,
+          reset_timeout: 60.seconds,
+          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
+
+      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
+
+        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
+
+        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
+
+      def storage(backend, **options)
+        @config[:storage] = case backend
+                            when :memory
+                              Storage::Memory.new(**options)
+                            when :bucket_memory
+                              Storage::BucketMemory.new(**options)
+                            when :cache
+                              Storage::Cache.new(**options)
+                            when :null
+                              Storage::Null.new(**options)
+                            when :fallback_chain
+                              config = options.is_a?(Proc) ? options.call(timeout: 5) : options
+                              Storage::FallbackChain.new(config)
+                            when Class
+                              backend.new(**options)
+                            else
+                              backend
+                            end
+      end
+
+      def metrics(recorder = nil, &block)
+        @config[:metrics] = recorder || block
+      end
+
+      def fallback(value = nil, &block)
+        raise ArgumentError, 'Fallback requires either a value or a block' if value.nil? && !block_given?
+
+        fallback_value = block || value
+
+        if @config[:fallback].is_a?(Array)
+          @config[:fallback] << fallback_value
+        elsif @config[:fallback]
+          @config[:fallback] = [@config[:fallback], fallback_value]
+        else
+          @config[:fallback] = fallback_value
+        end
+      end
+
+      def on_open(&block)
+        @config[:on_open] = block
+      end
+
+      def on_close(&block)
+        @config[:on_close] = block
+      end
+
+      def on_half_open(&block)
+        @config[:on_half_open] = block
+      end
+
+      def on_reject(&block)
+        @config[:on_reject] = block
+      end
+
+      # Configure hedged requests
+      def hedged(&)
+        if block_given?
+          hedged_builder = DSL::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] = DSL::ParallelFallbackWrapper.new(fallback_list)
+      end
+
+      def notify(service, url = nil, events: %i[open close], **options)
+        notification = {
+          via: service,
+          url: url,
+          events: Array(events),
+          options: options
+        }
+        @config[:notifications] << notification
+      end
+
+      def handle(*exceptions)
+        @config[:exceptions] = exceptions
+      end
+
+      def fiber_safe(enabled = true) # rubocop:disable Style/OptionalBooleanParameter
+        @config[:fiber_safe] = enabled
+      end
+
+      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
+  end
+end