breaker_machines 0.2.1 → 0.4.0

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)
@@ -94,6 +94,13 @@ module BreakerMachines
         events.last(limit)
       end
 
+      def with_timeout(_timeout_ms)
+        # Rails cache operations should rely on their own underlying timeouts
+        # Using Ruby's Timeout.timeout is dangerous and can cause deadlocks
+        # For Redis cache stores, configure connect_timeout and read_timeout instead
+        yield
+      end
+
       private
 
       def increment_counter(key)
@@ -155,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

@@ -0,0 +1,294 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  module Storage
+    # Apocalypse-resistant storage backend that tries multiple storage backends in sequence
+    # Falls back to the next storage backend when the current one times out or fails
+    #
+    # NOTE: For DRb (distributed Ruby) environments, only :cache backend with external
+    # 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, :backend_states
+
+      def initialize(storage_configs, circuit_breaker_threshold: 3, circuit_breaker_timeout: 30, **)
+        super(**)
+        @storage_configs = normalize_storage_configs(storage_configs)
+        @storage_instances = {}
+        @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
+
+      def get_status(circuit_name)
+        execute_with_fallback(:get_status, circuit_name)
+      end
+
+      def set_status(circuit_name, status, opened_at = nil)
+        execute_with_fallback(:set_status, circuit_name, status, opened_at)
+      end
+
+      def record_success(circuit_name, duration)
+        execute_with_fallback(:record_success, circuit_name, duration)
+      end
+
+      def record_failure(circuit_name, duration)
+        execute_with_fallback(:record_failure, circuit_name, duration)
+      end
+
+      def success_count(circuit_name, window_seconds)
+        execute_with_fallback(:success_count, circuit_name, window_seconds)
+      end
+
+      def failure_count(circuit_name, window_seconds)
+        execute_with_fallback(:failure_count, circuit_name, window_seconds)
+      end
+
+      def clear(circuit_name)
+        execute_with_fallback(:clear, circuit_name)
+      end
+
+      def clear_all
+        execute_with_fallback(:clear_all)
+      end
+
+      def record_event_with_details(circuit_name, type, duration, error: nil, new_state: nil)
+        execute_with_fallback(:record_event_with_details, circuit_name, type, duration, error: error,
+                                                                                        new_state: new_state)
+      end
+
+      def event_log(circuit_name, limit)
+        execute_with_fallback(:event_log, circuit_name, limit)
+      end
+
+      def with_timeout(_timeout_ms)
+        # FallbackChain doesn't use timeout directly - each backend handles its own
+        yield
+      end
+
+      def cleanup!
+        storage_instances.each_value do |instance|
+          instance.clear_all if instance.respond_to?(:clear_all)
+        end
+        storage_instances.clear
+        backend_states.each_value(&:reset)
+      end
+
+      private
+
+      def execute_with_fallback(method, *args, **kwargs)
+        chain_started_at = BreakerMachines.monotonic_time
+        attempted_backends = []
+
+        storage_configs.each_with_index do |config, index|
+          backend_type = config[:backend]
+          attempted_backends << backend_type
+          backend_state = backend_states[backend_type]
+
+          if backend_state.unhealthy_due_to_timeout?
+            emit_backend_skipped_notification(backend_type, method, index)
+            next
+          end
+
+          begin
+            backend = get_backend_instance(backend_type)
+            started_at = BreakerMachines.monotonic_time
+
+            result = backend.with_timeout(config[:timeout]) do
+              if kwargs.any?
+                backend.send(method, *args, **kwargs)
+              else
+                backend.send(method, *args)
+              end
+            end
+
+            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)
+
+            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 = ((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
+
+            next
+          end
+        end
+
+        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
+
+      def get_backend_instance(backend_type)
+        storage_instances[backend_type] ||= create_backend_instance(backend_type)
+      end
+
+      def create_backend_instance(backend_type)
+        case backend_type
+        when :memory
+          Memory.new
+        when :bucket_memory
+          BucketMemory.new
+        when :cache
+          Cache.new
+        when :null
+          Null.new
+        else
+          # Allow custom backend classes
+          raise ConfigurationError, "Unknown storage backend: #{backend_type}" unless backend_type.is_a?(Class)
+
+          backend_type.new
+
+        end
+      end
+
+      def record_backend_failure(backend_type, _error, _duration_ms)
+        backend_state = backend_states[backend_type]
+        return unless backend_state
+
+        previous_health = backend_state.health_name
+        backend_state.record_failure
+        new_health = backend_state.health_name
+
+        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)
+        backend_state = backend_states[backend_type]
+        return unless backend_state&.unhealthy?
+
+        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)
+        ActiveSupport::Notifications.instrument(
+          'storage_fallback.breaker_machines',
+          backend: backend_type,
+          error_class: error.class.name,
+          error_message: error.message,
+          duration_ms: duration_ms,
+          backend_index: backend_index,
+          next_backend: storage_configs[backend_index + 1]&.dig(:backend)
+        )
+      end
+
+      def emit_operation_success_notification(backend_type, method, duration_ms, backend_index)
+        ActiveSupport::Notifications.instrument(
+          'storage_operation.breaker_machines',
+          backend: backend_type,
+          operation: method,
+          duration_ms: duration_ms,
+          backend_index: backend_index,
+          success: true
+        )
+      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: 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: backend_state&.instance_variable_get(:@threshold),
+          recovery_time: new_state == :unhealthy ? backend_state&.instance_variable_get(:@unhealthy_until) : nil
+        )
+      end
+
+      def emit_chain_success_notification(method, attempted_backends, successful_backend, duration_ms)
+        ActiveSupport::Notifications.instrument(
+          'storage_chain_operation.breaker_machines',
+          operation: method,
+          attempted_backends: attempted_backends,
+          successful_backend: successful_backend,
+          duration_ms: duration_ms,
+          success: true,
+          fallback_count: attempted_backends.index(successful_backend)
+        )
+      end
+
+      def emit_chain_failure_notification(method, attempted_backends, duration_ms)
+        ActiveSupport::Notifications.instrument(
+          'storage_chain_operation.breaker_machines',
+          operation: method,
+          attempted_backends: attempted_backends,
+          successful_backend: nil,
+          duration_ms: duration_ms,
+          success: false,
+          fallback_count: attempted_backends.size
+        )
+      end
+
+      def normalize_storage_configs(configs)
+        return configs if configs.is_a?(Array)
+
+        # Convert hash format to array format
+        unless configs.is_a?(Hash)
+          raise ConfigurationError, "Storage configs must be Array or Hash, got: #{configs.class}"
+        end
+
+        configs.map do |_key, value|
+          if value.is_a?(Hash)
+            value
+          else
+            { backend: value, timeout: 5 }
+          end
+        end
+      end
+
+      def validate_configs!
+        raise ConfigurationError, 'Storage configs cannot be empty' if storage_configs.empty?
+
+        storage_configs.each_with_index do |config, index|
+          unless config.is_a?(Hash) && config[:backend] && config[:timeout]
+            raise ConfigurationError, "Invalid storage config at index #{index}: #{config}"
+          end
+
+          unless config[:timeout].is_a?(Numeric) && config[:timeout].positive?
+            raise ConfigurationError, "Timeout must be a positive number, got: #{config[:timeout]}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/breaker_machines/storage/memory.rb

@@ -6,6 +6,10 @@ require 'concurrent/array'
 module BreakerMachines
   module Storage
     # High-performance in-memory storage backend with thread-safe operations
+    #
+    # WARNING: This storage backend is NOT compatible with DRb (distributed Ruby)
+    # environments as memory is not shared between processes. Use Cache backend
+    # with an external cache store (Redis, Memcached) for distributed setups.
     class Memory < Base
       def initialize(**options)
         super
@@ -19,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)
@@ -87,6 +91,12 @@ module BreakerMachines
         events.last(limit).map(&:dup)
       end
 
+      def with_timeout(_timeout_ms)
+        # Memory operations should be instant, but we'll still respect the timeout
+        # This is more for consistency and to catch any potential deadlocks
+        yield
+      end
+
       private
 
       def record_event(circuit_name, type, duration)
@@ -120,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/storage/null.rb

@@ -40,6 +40,15 @@ module BreakerMachines
       def record_event_with_details(_circuit_name, _event_type, _duration, _metadata = {})
         # No-op
       end
+
+      def clear_all
+        # No-op
+      end
+
+      def with_timeout(_timeout_ms)
+        # Null storage always succeeds instantly - perfect for fail-open scenarios
+        yield
+      end
     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.2.1'
+  VERSION = '0.4.0'
 end

data/lib/breaker_machines.rb

@@ -3,11 +3,14 @@
 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")
@@ -77,6 +80,15 @@ module BreakerMachines
     def registry
       Registry.instance
     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

data/sig/README.md

@@ -24,7 +24,7 @@ To use these type signatures in your project:
    target :app do
      signature "sig"
      check "lib"
-     
+
      library "breaker_machines"
    end
    ```
@@ -38,7 +38,7 @@ To use these type signatures in your project:
 
 ### Basic Circuit Usage
 ```ruby
-circuit = BreakerMachines::Circuit.new("api", 
+circuit = BreakerMachines::Circuit.new("api",
   failure_threshold: 5,
   reset_timeout: 30
 )
@@ -50,7 +50,7 @@ result = circuit.call { api.fetch_data }
 ```ruby
 class MyService
   include BreakerMachines::DSL
-  
+
   circuit :database do
     threshold failures: 10, within: 60
     reset_after 120

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: breaker_machines
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.4.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.50.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.31.0
+        version: 0.50.0
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -109,6 +109,7 @@ files:
 - README.md
 - lib/breaker_machines.rb
 - lib/breaker_machines/async_support.rb
+- lib/breaker_machines/cascading_circuit.rb
 - lib/breaker_machines/circuit.rb
 - lib/breaker_machines/circuit/callbacks.rb
 - lib/breaker_machines/circuit/configuration.rb
@@ -117,16 +118,23 @@ files:
 - lib/breaker_machines/circuit/state_management.rb
 - lib/breaker_machines/console.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