breaker_machines 0.9.2-arm64-darwin

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

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require 'concurrent/map'
+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
+        @circuits = Concurrent::Map.new
+        @events = Concurrent::Map.new
+        @event_logs = Concurrent::Map.new
+        @max_events = options[:max_events] || 100
+        # Store creation time as anchor for relative timestamps (like Rust implementation)
+        @start_time = BreakerMachines.monotonic_time
+      end
+
+      def get_status(circuit_name)
+        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)
+        @circuits[circuit_name] = {
+          status: status,
+          opened_at: opened_at,
+          updated_at: monotonic_time
+        }
+      end
+
+      def record_success(circuit_name, duration)
+        record_event(circuit_name, :success, duration)
+      end
+
+      def record_failure(circuit_name, duration)
+        record_event(circuit_name, :failure, duration)
+      end
+
+      def success_count(circuit_name, window_seconds)
+        count_events(circuit_name, :success, window_seconds)
+      end
+
+      def failure_count(circuit_name, window_seconds)
+        count_events(circuit_name, :failure, window_seconds)
+      end
+
+      def clear(circuit_name)
+        @circuits.delete(circuit_name)
+        @events.delete(circuit_name)
+        @event_logs.delete(circuit_name)
+      end
+
+      def clear_all
+        @circuits.clear
+        @events.clear
+        @event_logs.clear
+      end
+
+      def record_event_with_details(circuit_name, type, duration, error: nil, new_state: nil)
+        events = @event_logs.compute_if_absent(circuit_name) { Concurrent::Array.new }
+
+        event = {
+          type: type,
+          timestamp: monotonic_time,
+          duration_ms: (duration * 1000).round(2)
+        }
+
+        event[:error_class] = error.class.name if error
+        event[:error_message] = error.message if error
+        event[:new_state] = new_state if new_state
+
+        events << event
+
+        # Keep only the most recent events
+        events.shift while events.size > @max_events
+      end
+
+      def event_log(circuit_name, limit)
+        events = @event_logs[circuit_name]
+        return [] unless events
+
+        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)
+        # Initialize if needed
+        @events.compute_if_absent(circuit_name) { Concurrent::Array.new }
+
+        # Get the array and add event
+        events = @events[circuit_name]
+        current_time = monotonic_time
+
+        # Add new event
+        events << {
+          type: type,
+          duration: duration,
+          timestamp: current_time
+        }
+
+        # Clean old events periodically (every 100 events)
+        return unless events.size > 100
+
+        cutoff_time = current_time - 300 # Keep 5 minutes of history
+        events.delete_if { |e| e[:timestamp] < cutoff_time }
+      end
+
+      def count_events(circuit_name, type, window_seconds)
+        events = @events[circuit_name]
+        return 0 unless events
+
+        cutoff_time = monotonic_time - window_seconds
+        events.count { |e| e[:type] == type && e[:timestamp] >= cutoff_time }
+      end
+
+      def monotonic_time
+        # Return time relative to storage creation (matches Rust implementation)
+        BreakerMachines.monotonic_time - @start_time
+      end
+    end
+  end
+end

data/lib/breaker_machines/storage/native.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  module Storage
+    # Native extension storage backend with graceful fallback to pure Ruby
+    #
+    # This backend provides identical functionality to Memory storage but with
+    # significantly better performance for sliding window calculations when the
+    # native extension is available. If the native extension isn't available
+    # (e.g., on JRuby or if Rust wasn't installed), it automatically falls back
+    # to the pure Ruby Memory storage backend.
+    #
+    # Performance: ~63x faster than Memory storage when native extension is available
+    #
+    # Usage:
+    #   BreakerMachines.configure do |config|
+    #     config.default_storage = :native
+    #   end
+    #
+    # FFI Hybrid Pattern: This class is only loaded when native extension is available
+    # Fallback happens at load time (native_speedup.rb), not at runtime
+    class Native < Base
+      def initialize(**options)
+        super
+        # Native extension is guaranteed to be available when this class is loaded
+        @backend = BreakerMachinesNative::Storage.new
+      end
+
+      # Check if using native backend
+      # @return [Boolean] always true - this class only exists when native is available
+      def native?
+        true
+      end
+
+      def get_status(_circuit_name)
+        # Status is still managed by Ruby layer
+        # This storage backend only handles event tracking
+        nil
+      end
+
+      def set_status(circuit_name, status, opened_at = nil)
+        # Status management delegated to Ruby layer
+        # This backend focuses on high-performance event counting
+      end
+
+      def record_success(circuit_name, duration)
+        @backend.record_success(circuit_name.to_s, duration)
+      end
+
+      def record_failure(circuit_name, duration)
+        @backend.record_failure(circuit_name.to_s, duration)
+      end
+
+      def success_count(circuit_name, window_seconds)
+        @backend.success_count(circuit_name.to_s, window_seconds)
+      end
+
+      def failure_count(circuit_name, window_seconds)
+        @backend.failure_count(circuit_name.to_s, window_seconds)
+      end
+
+      def clear(circuit_name)
+        @backend.clear(circuit_name.to_s)
+      end
+
+      def clear_all
+        @backend.clear_all
+      end
+
+      def record_event_with_details(circuit_name, type, duration, error: nil, new_state: nil)
+        # Basic event recording (native extension handles type and duration)
+        case type
+        when :success
+          record_success(circuit_name, duration)
+        when :failure
+          record_failure(circuit_name, duration)
+        end
+
+        # NOTE: Error and state details not tracked in native backend
+        # This is intentional for performance - use Memory backend if you need full event details
+      end
+
+      def event_log(circuit_name, limit)
+        @backend.event_log(circuit_name.to_s, limit)
+      end
+
+      def with_timeout(_timeout_ms)
+        # Native operations should be instant
+        yield
+      end
+    end
+  end
+end

data/lib/breaker_machines/storage/null.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  module Storage
+    # A no-op storage backend for minimal overhead
+    # Use this when you don't need event logging or metrics
+    class Null < Base
+      def record_success(_circuit_name, _duration = nil)
+        # No-op
+      end
+
+      def record_failure(_circuit_name, _duration = nil)
+        # No-op
+      end
+
+      def success_count(_circuit_name, _window = nil)
+        0
+      end
+
+      def failure_count(_circuit_name, _window = nil)
+        0
+      end
+
+      def get_status(_circuit_name)
+        nil
+      end
+
+      def set_status(_circuit_name, _status, _opened_at = nil)
+        # No-op
+      end
+
+      def clear(_circuit_name)
+        # No-op
+      end
+
+      def event_log(_circuit_name, _limit = 20)
+        []
+      end
+
+      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/storage.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  # Storage backends for persisting circuit state and metrics
+  module Storage
+    # Storage module for circuit breaker state persistence
+  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

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