breaker_machines 0.3.0 → 0.5.0

data/lib/breaker_machines/registry.rb

@@ -102,13 +102,13 @@ module BreakerMachines
 
       {
         summary: stats_summary,
-        circuits: circuits.map(&:stats),
+        circuits: circuits.map { |c| c.stats.to_h },
         health: {
           open_count: circuits.count(&:open?),
           closed_count: circuits.count(&:closed?),
           half_open_count: circuits.count(&:half_open?),
-          total_failures: circuits.sum { |c| c.stats[:failure_count] },
-          total_successes: circuits.sum { |c| c.stats[:success_count] }
+          total_failures: circuits.sum { |c| c.stats.failure_count },
+          total_successes: circuits.sum { |c| c.stats.success_count }
         }
       }
     end

data/lib/breaker_machines/storage/backend_state.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  module Storage
+    # Manages the health state of a single storage backend using a state machine.
+    class BackendState
+      attr_reader :name, :failure_count, :last_failure_at
+      attr_accessor :health
+
+      def initialize(name, threshold:, timeout:)
+        @name = name
+        @threshold = threshold
+        @timeout = timeout
+        @failure_count = 0
+        @last_failure_at = nil
+        @health = :healthy
+      end
+
+      state_machine :health, initial: :healthy do
+        event :trip do
+          transition healthy: :unhealthy, if: :threshold_reached?
+        end
+
+        event :recover do
+          transition unhealthy: :healthy
+        end
+
+        event :reset do
+          transition all => :healthy
+        end
+
+        before_transition to: :unhealthy do |backend, _transition|
+          backend.instance_variable_set(:@unhealthy_until,
+                                        BreakerMachines.monotonic_time + backend.instance_variable_get(:@timeout))
+        end
+
+        after_transition to: :healthy do |backend, _transition|
+          backend.instance_variable_set(:@failure_count, 0)
+          backend.instance_variable_set(:@last_failure_at, nil)
+          backend.instance_variable_set(:@unhealthy_until, nil)
+        end
+      end
+
+      def record_failure
+        @failure_count += 1
+        @last_failure_at = BreakerMachines.monotonic_time
+        trip
+      end
+
+      def threshold_reached?
+        @failure_count >= @threshold
+      end
+
+      def unhealthy_due_to_timeout?
+        return false unless unhealthy?
+
+        unhealthy_until = instance_variable_get(:@unhealthy_until)
+        return false unless unhealthy_until
+
+        if BreakerMachines.monotonic_time > unhealthy_until
+          recover
+          false
+        else
+          true
+        end
+      end
+    end
+  end
+end

data/lib/breaker_machines/storage/bucket_memory.rb

@@ -27,10 +27,10 @@ module BreakerMachines
         circuit_data = @circuits[circuit_name]
         return nil unless circuit_data
 
-        {
+        BreakerMachines::Status.new(
           status: circuit_data[:status],
           opened_at: circuit_data[:opened_at]
-        }
+        )
       end
 
       def set_status(circuit_name, status, opened_at = nil)
@@ -160,7 +160,7 @@ module BreakerMachines
       end
 
       def monotonic_time
-        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        BreakerMachines.monotonic_time
       end
 
       def with_timeout(_timeout_ms)

data/lib/breaker_machines/storage/cache.rb

@@ -16,10 +16,10 @@ module BreakerMachines
         data = @cache.read(status_key(circuit_name))
         return nil unless data
 
-        {
+        BreakerMachines::Status.new(
           status: data[:status].to_sym,
           opened_at: data[:opened_at]
-        }
+        )
       end
 
       def set_status(circuit_name, status, opened_at = nil)
@@ -162,7 +162,7 @@ module BreakerMachines
       end
 
       def monotonic_time
-        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        BreakerMachines.monotonic_time
       end
     end
   end

data/lib/breaker_machines/storage/fallback_chain.rb

@@ -9,15 +9,18 @@ module BreakerMachines
     # cache stores (Redis, Memcached) will work properly. Memory-based backends (:memory,
     # :bucket_memory) are incompatible with DRb as they don't share state between processes.
     class FallbackChain < Base
-      attr_reader :storage_configs, :storage_instances, :unhealthy_until, :circuit_breaker_threshold, :circuit_breaker_timeout
+      attr_reader :storage_configs, :storage_instances, :backend_states
 
-      def initialize(storage_configs, **)
+      def initialize(storage_configs, circuit_breaker_threshold: 3, circuit_breaker_timeout: 30, **)
         super(**)
         @storage_configs = normalize_storage_configs(storage_configs)
         @storage_instances = {}
-        @unhealthy_until = {}
-        @circuit_breaker_threshold = 3 # After 3 failures, mark backend as unhealthy
-        @circuit_breaker_timeout = 30 # Keep marked as unhealthy for 30 seconds
+        @circuit_breaker_threshold = circuit_breaker_threshold
+        @circuit_breaker_timeout = circuit_breaker_timeout
+        @backend_states = @storage_configs.to_h do |config|
+          [config[:backend],
+           BackendState.new(config[:backend], threshold: @circuit_breaker_threshold, timeout: @circuit_breaker_timeout)]
+        end
         validate_configs!
       end
 
@@ -72,27 +75,28 @@ module BreakerMachines
           instance.clear_all if instance.respond_to?(:clear_all)
         end
         storage_instances.clear
-        @backend_failures&.clear
-        unhealthy_until.clear
+        backend_states.each_value(&:reset)
       end
 
       private
 
       def execute_with_fallback(method, *args, **kwargs)
-        chain_started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        chain_started_at = BreakerMachines.monotonic_time
         attempted_backends = []
 
         storage_configs.each_with_index do |config, index|
-          attempted_backends << config[:backend]
+          backend_type = config[:backend]
+          attempted_backends << backend_type
+          backend_state = backend_states[backend_type]
 
-          if backend_unhealthy?(config[:backend])
-            emit_backend_skipped_notification(config[:backend], method, index)
+          if backend_state.unhealthy_due_to_timeout?
+            emit_backend_skipped_notification(backend_type, method, index)
             next
           end
 
           begin
-            backend = get_backend_instance(config[:backend])
-            started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            backend = get_backend_instance(backend_type)
+            started_at = BreakerMachines.monotonic_time
 
             result = backend.with_timeout(config[:timeout]) do
               if kwargs.any?
@@ -102,35 +106,30 @@ module BreakerMachines
               end
             end
 
-            # Success - emit success notification and reset failure count
-            duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round(2)
-            emit_operation_success_notification(config[:backend], method, duration_ms, index)
-            reset_backend_failures(config[:backend])
+            duration_ms = ((BreakerMachines.monotonic_time - started_at) * 1000).round(2)
+            emit_operation_success_notification(backend_type, method, duration_ms, index)
+            reset_backend_failures(backend_type)
 
-            # Emit chain success notification
-            chain_duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - chain_started_at) * 1000).round(2)
-            emit_chain_success_notification(method, attempted_backends, config[:backend], chain_duration_ms)
+            chain_duration_ms = ((BreakerMachines.monotonic_time - chain_started_at) * 1000).round(2)
+            emit_chain_success_notification(method, attempted_backends, backend_type, chain_duration_ms)
 
             return result
           rescue BreakerMachines::StorageTimeoutError, BreakerMachines::StorageError, StandardError => e
-            duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round(2)
-
-            # Record the failure
-            record_backend_failure(config[:backend], e, duration_ms)
-
-            # Emit notification about the fallback
-            emit_fallback_notification(config[:backend], e, duration_ms, index)
-
-            # If this is the last backend, re-raise the error
-            raise e if index == storage_configs.size - 1
+            duration_ms = ((BreakerMachines.monotonic_time - started_at) * 1000).round(2)
+            record_backend_failure(backend_type, e, duration_ms)
+            emit_fallback_notification(backend_type, e, duration_ms, index)
+
+            if index == storage_configs.size - 1
+              chain_duration_ms = ((BreakerMachines.monotonic_time - chain_started_at) * 1000).round(2)
+              emit_chain_failure_notification(method, attempted_backends, chain_duration_ms)
+              raise e
+            end
 
-            # Continue to next backend
             next
           end
         end
 
-        # If we get here, all backends were unhealthy
-        chain_duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - chain_started_at) * 1000).round(2)
+        chain_duration_ms = ((BreakerMachines.monotonic_time - chain_started_at) * 1000).round(2)
         emit_chain_failure_notification(method, attempted_backends, chain_duration_ms)
         raise BreakerMachines::StorageError, 'All storage backends are unhealthy'
       end
@@ -158,49 +157,34 @@ module BreakerMachines
         end
       end
 
-      def backend_unhealthy?(backend_type)
-        unhealthy_until_time = unhealthy_until[backend_type]
-        return false unless unhealthy_until_time
-
-        if Process.clock_gettime(Process::CLOCK_MONOTONIC) > unhealthy_until_time
-          unhealthy_until.delete(backend_type)
-          false
-        else
-          true
-        end
-      end
-
-      def record_backend_failure(backend_type, error, duration_ms)
-        @backend_failures ||= {}
-        @backend_failures[backend_type] ||= []
-        @backend_failures[backend_type] << {
-          error: error,
-          duration_ms: duration_ms,
-          timestamp: Process.clock_gettime(Process::CLOCK_MONOTONIC)
-        }
-
-        # Keep only recent failures (last 60 seconds)
-        cutoff = Process.clock_gettime(Process::CLOCK_MONOTONIC) - 60
-        @backend_failures[backend_type].reject! { |f| f[:timestamp] < cutoff }
+      def record_backend_failure(backend_type, _error, _duration_ms)
+        backend_state = backend_states[backend_type]
+        return unless backend_state
 
-        # Mark as unhealthy if too many failures
-        return unless @backend_failures[backend_type].size >= circuit_breaker_threshold
+        previous_health = backend_state.health_name
+        backend_state.record_failure
+        new_health = backend_state.health_name
 
-        unhealthy_until[backend_type] = Process.clock_gettime(Process::CLOCK_MONOTONIC) + circuit_breaker_timeout
-        emit_backend_health_change_notification(backend_type, :healthy, :unhealthy, @backend_failures[backend_type].size)
+        if new_health != previous_health
+          emit_backend_health_change_notification(backend_type, previous_health, new_health,
+                                                  backend_state.failure_count)
+        end
       rescue StandardError => e
         # Don't let failure recording cause the whole chain to hang
         Rails.logger&.error("FallbackChain: Failed to record backend failure: #{e.message}")
       end
 
       def reset_backend_failures(backend_type)
-        was_unhealthy = unhealthy_until.key?(backend_type)
-        @backend_failures&.delete(backend_type)
-        unhealthy_until.delete(backend_type)
+        backend_state = backend_states[backend_type]
+        return unless backend_state&.unhealthy?
 
-        if was_unhealthy
-          emit_backend_health_change_notification(backend_type, :unhealthy, :healthy, 0)
-        end
+        previous_health = backend_state.health_name
+        backend_state.reset
+        new_health = backend_state.health_name
+
+        return unless new_health != previous_health
+
+        emit_backend_health_change_notification(backend_type, previous_health, new_health, 0)
       end
 
       def emit_fallback_notification(backend_type, error, duration_ms, backend_index)
@@ -227,25 +211,27 @@ module BreakerMachines
       end
 
       def emit_backend_skipped_notification(backend_type, method, backend_index)
+        backend_state = backend_states[backend_type]
         ActiveSupport::Notifications.instrument(
           'storage_backend_skipped.breaker_machines',
           backend: backend_type,
           operation: method,
           backend_index: backend_index,
           reason: 'unhealthy',
-          unhealthy_until: unhealthy_until[backend_type]
+          unhealthy_until: backend_state&.instance_variable_get(:@unhealthy_until)
         )
       end
 
       def emit_backend_health_change_notification(backend_type, previous_state, new_state, failure_count)
+        backend_state = backend_states[backend_type]
         ActiveSupport::Notifications.instrument(
           'storage_backend_health.breaker_machines',
           backend: backend_type,
           previous_state: previous_state,
           new_state: new_state,
           failure_count: failure_count,
-          threshold: circuit_breaker_threshold,
-          recovery_time: new_state == :unhealthy ? unhealthy_until[backend_type] : nil
+          threshold: backend_state&.instance_variable_get(:@threshold),
+          recovery_time: new_state == :unhealthy ? backend_state&.instance_variable_get(:@unhealthy_until) : nil
         )
       end
 

data/lib/breaker_machines/storage/memory.rb

@@ -23,10 +23,10 @@ module BreakerMachines
         circuit_data = @circuits[circuit_name]
         return nil unless circuit_data
 
-        {
+        BreakerMachines::Status.new(
           status: circuit_data[:status],
           opened_at: circuit_data[:opened_at]
-        }
+        )
       end
 
       def set_status(circuit_name, status, opened_at = nil)
@@ -130,7 +130,7 @@ module BreakerMachines
       end
 
       def monotonic_time
-        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        BreakerMachines.monotonic_time
       end
     end
   end

data/lib/breaker_machines/types.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  # Represents the status of a circuit from storage
+  # @return [Symbol] status - the circuit status (:open, :closed, :half_open)
+  # @return [Float, nil] opened_at - the monotonic time when the circuit was opened
+  Status = Data.define(:status, :opened_at)
+
+  # Represents statistical information about a circuit
+  Stats = Data.define(
+    :state,
+    :failure_count,
+    :success_count,
+    :last_failure_at,
+    :opened_at,
+    :half_open_attempts,
+    :half_open_successes
+  )
+
+  # Represents information about the last error that occurred
+  # @return [String] error_class - the error class name
+  # @return [String] message - the error message
+  # @return [Float, nil] occurred_at - the monotonic time when the error occurred
+  ErrorInfo = Data.define(:error_class, :message, :occurred_at)
+
+  # Represents cascade information for cascading circuits
+  CascadeInfo = Data.define(
+    :dependent_circuits,
+    :emergency_protocol,
+    :cascade_triggered_at,
+    :dependent_status
+  )
+
+  # Represents an event in the circuit's event log
+  # @return [Symbol] type - the event type (:success, :failure, :state_change)
+  # @return [Float] timestamp - the monotonic timestamp
+  # @return [Float] duration - the duration in milliseconds
+  # @return [String, nil] error - the error message if applicable
+  # @return [Symbol, nil] new_state - the new state if this was a state change
+  Event = Data.define(:type, :timestamp, :duration, :error, :new_state)
+end

data/lib/breaker_machines/version.rb

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

data/lib/breaker_machines.rb

@@ -3,14 +3,18 @@
 require 'zeitwerk'
 require 'active_support'
 require 'active_support/core_ext'
+require 'state_machines'
 require_relative 'breaker_machines/errors'
+require_relative 'breaker_machines/types'
 
 loader = Zeitwerk::Loader.for_gem
 loader.inflector.inflect('dsl' => 'DSL')
 loader.ignore("#{__dir__}/breaker_machines/errors.rb")
+loader.ignore("#{__dir__}/breaker_machines/types.rb")
 loader.ignore("#{__dir__}/breaker_machines/console.rb")
 loader.ignore("#{__dir__}/breaker_machines/async_support.rb")
 loader.ignore("#{__dir__}/breaker_machines/hedged_async_support.rb")
+loader.ignore("#{__dir__}/breaker_machines/circuit/async_state_management.rb")
 loader.setup
 
 # BreakerMachines provides a thread-safe implementation of the Circuit Breaker pattern
@@ -77,6 +81,31 @@ module BreakerMachines
     def registry
       Registry.instance
     end
+
+    # Register a circuit with the global registry
+    def register(circuit)
+      registry.register(circuit)
+    end
+
+    # Reset the registry and configurations (useful for testing)
+    def reset!
+      registry.clear
+      config.default_storage = :bucket_memory
+      config.default_timeout = nil
+      config.default_reset_timeout = 60.seconds
+      config.default_failure_threshold = 5
+      config.log_events = true
+      config.fiber_safe = false
+    end
+
+    # Returns the current monotonic time in seconds.
+    # Monotonic time is guaranteed to always increase and is not affected
+    # by system clock adjustments, making it ideal for measuring durations.
+    #
+    # @return [Float] current monotonic time in seconds
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
   end
 
   # Set up notifications on first use

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: breaker_machines
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Abdelkader Boudih
-bindir: exe
+bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '7.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '7.2'
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
   requirement: !ruby/object:Gem::Requirement
@@ -43,14 +43,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.31.0
+        version: 0.100.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.31.0
+        version: 0.100.0
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -108,26 +108,40 @@ files:
 - LICENSE.txt
 - README.md
 - lib/breaker_machines.rb
+- lib/breaker_machines/async_circuit.rb
 - lib/breaker_machines/async_support.rb
+- lib/breaker_machines/cascading_circuit.rb
 - lib/breaker_machines/circuit.rb
+- lib/breaker_machines/circuit/async_state_management.rb
+- lib/breaker_machines/circuit/base.rb
 - lib/breaker_machines/circuit/callbacks.rb
 - lib/breaker_machines/circuit/configuration.rb
+- lib/breaker_machines/circuit/coordinated_state_management.rb
 - lib/breaker_machines/circuit/execution.rb
+- lib/breaker_machines/circuit/hedged_execution.rb
 - lib/breaker_machines/circuit/introspection.rb
+- lib/breaker_machines/circuit/state_callbacks.rb
 - lib/breaker_machines/circuit/state_management.rb
+- lib/breaker_machines/circuit_group.rb
 - lib/breaker_machines/console.rb
+- lib/breaker_machines/coordinated_circuit.rb
 - lib/breaker_machines/dsl.rb
+- lib/breaker_machines/dsl/cascading_circuit_builder.rb
+- lib/breaker_machines/dsl/circuit_builder.rb
+- lib/breaker_machines/dsl/hedged_builder.rb
+- lib/breaker_machines/dsl/parallel_fallback_wrapper.rb
 - lib/breaker_machines/errors.rb
 - lib/breaker_machines/hedged_async_support.rb
-- lib/breaker_machines/hedged_execution.rb
 - lib/breaker_machines/registry.rb
 - lib/breaker_machines/storage.rb
+- lib/breaker_machines/storage/backend_state.rb
 - lib/breaker_machines/storage/base.rb
 - lib/breaker_machines/storage/bucket_memory.rb
 - lib/breaker_machines/storage/cache.rb
 - lib/breaker_machines/storage/fallback_chain.rb
 - lib/breaker_machines/storage/memory.rb
 - lib/breaker_machines/storage/null.rb
+- lib/breaker_machines/types.rb
 - lib/breaker_machines/version.rb
 - sig/README.md
 - sig/all.rbs

data/lib/breaker_machines/hedged_execution.rb

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