breaker_machines 0.9.2-x86_64-darwin

data/lib/breaker_machines/registry.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+require 'singleton'
+require 'weakref'
+
+module BreakerMachines
+  # Global registry for tracking all circuit breaker instances
+  class Registry
+    include Singleton
+
+    def initialize
+      @circuits = Concurrent::Map.new
+      @named_circuits = Concurrent::Map.new # For dynamic circuits by name
+      @mutex = Mutex.new
+      @registration_count = 0
+      @cleanup_interval = 100 # Clean up every N registrations
+    end
+
+    # Register a circuit instance
+    def register(circuit)
+      @mutex.synchronize do
+        # Use circuit object as key - Concurrent::Map handles object identity correctly
+        @circuits[circuit] = WeakRef.new(circuit)
+
+        # Periodic cleanup
+        @registration_count += 1
+        if @registration_count >= @cleanup_interval
+          cleanup_dead_references_unsafe
+          @registration_count = 0
+        end
+      end
+    end
+
+    # Unregister a circuit instance
+    def unregister(circuit)
+      @mutex.synchronize do
+        @circuits.delete(circuit)
+      end
+    end
+
+    # Get all active circuits
+    def all_circuits
+      @mutex.synchronize do
+        @circuits.values.map do |weak_ref|
+          weak_ref.__getobj__
+        rescue WeakRef::RefError
+          nil
+        end.compact
+      end
+    end
+
+    # Find circuits by name
+    def find_by_name(name)
+      all_circuits.select { |circuit| circuit.name == name }
+    end
+
+    # Find first circuit by name
+    def find(name)
+      find_by_name(name).first
+    end
+
+    # Force open a circuit by name
+    def force_open(name) # rubocop:disable Naming/PredicateMethod
+      circuits = find_by_name(name)
+      return false if circuits.empty?
+
+      circuits.each(&:force_open)
+      true
+    end
+
+    # Force close a circuit by name
+    def force_close(name) # rubocop:disable Naming/PredicateMethod
+      circuits = find_by_name(name)
+      return false if circuits.empty?
+
+      circuits.each(&:force_close)
+      true
+    end
+
+    # Reset a circuit by name
+    def reset(name) # rubocop:disable Naming/PredicateMethod
+      circuits = find_by_name(name)
+      return false if circuits.empty?
+
+      circuits.each(&:reset)
+      true
+    end
+
+    # Get summary statistics
+    def stats_summary
+      circuits = all_circuits
+      {
+        total: circuits.size,
+        by_state: circuits.group_by(&:status_name).transform_values(&:count),
+        by_name: circuits.group_by(&:name).transform_values(&:count)
+      }
+    end
+
+    # Get all stats with detailed metrics
+    def all_stats
+      circuits = all_circuits
+
+      {
+        summary: stats_summary,
+        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 }
+        }
+      }
+    end
+
+    # Get detailed information for all circuits
+    def detailed_report
+      all_circuits.map(&:to_h)
+    end
+
+    # Get or create a globally managed dynamic circuit
+    def get_or_create_dynamic_circuit(name, owner, config)
+      @mutex.synchronize do
+        # Check if circuit already exists and is still alive
+        if @named_circuits.key?(name)
+          weak_ref = @named_circuits[name]
+          begin
+            existing_circuit = weak_ref.__getobj__
+            return existing_circuit if existing_circuit
+          rescue WeakRef::RefError
+            # Circuit was garbage collected, remove the stale reference
+            @named_circuits.delete(name)
+          end
+        end
+
+        # Create new circuit with weak owner reference
+        # Don't auto-register to avoid deadlock
+        weak_owner = owner.is_a?(WeakRef) ? owner : WeakRef.new(owner)
+        circuit_config = config.merge(owner: weak_owner, auto_register: false)
+        new_circuit = Circuit.new(name, circuit_config)
+
+        # Manually register the circuit (we're already in sync block)
+        @circuits[new_circuit] = WeakRef.new(new_circuit)
+        @named_circuits[name] = WeakRef.new(new_circuit)
+
+        new_circuit
+      end
+    end
+
+    # Remove a dynamic circuit by name
+    def remove_dynamic_circuit(name)
+      @mutex.synchronize do
+        if @named_circuits.key?(name)
+          weak_ref = @named_circuits.delete(name)
+          begin
+            circuit = weak_ref.__getobj__
+            @circuits.delete(circuit) if circuit
+            true
+          rescue WeakRef::RefError
+            false
+          end
+        else
+          false
+        end
+      end
+    end
+
+    # Get all dynamic circuit names
+    def dynamic_circuit_names
+      @mutex.synchronize do
+        alive_names = []
+        @named_circuits.each_pair do |name, weak_ref|
+          weak_ref.__getobj__
+          alive_names << name
+        rescue WeakRef::RefError
+          @named_circuits.delete(name)
+        end
+        alive_names
+      end
+    end
+
+    # Cleanup stale dynamic circuits older than given age
+    def cleanup_stale_dynamic_circuits(max_age_seconds = 3600)
+      @mutex.synchronize do
+        cutoff_time = Time.now - max_age_seconds
+        stale_names = []
+
+        @named_circuits.each_pair do |name, weak_ref|
+          circuit = weak_ref.__getobj__
+          # Check if circuit has a last_activity_time and it's stale
+          if circuit.respond_to?(:last_activity_time) &&
+             circuit.last_activity_time &&
+             circuit.last_activity_time < cutoff_time
+            stale_names << name
+          end
+        rescue WeakRef::RefError
+          stale_names << name
+        end
+
+        stale_names.each do |name|
+          weak_ref = @named_circuits.delete(name)
+          begin
+            circuit = weak_ref.__getobj__
+            @circuits.delete(circuit) if circuit
+          rescue WeakRef::RefError
+            # Already gone
+          end
+        end
+
+        stale_names.size
+      end
+    end
+
+    # Clear all circuits (useful for testing)
+    def clear
+      @mutex.synchronize do
+        @circuits.clear
+        @named_circuits.clear
+      end
+    end
+
+    # Clean up dead references (thread-safe)
+    def cleanup_dead_references
+      @mutex.synchronize do
+        cleanup_dead_references_unsafe
+      end
+    end
+
+    private
+
+    # Clean up dead references (must be called within mutex)
+    def cleanup_dead_references_unsafe
+      dead_ids = []
+      @circuits.each_pair do |id, weak_ref|
+        weak_ref.__getobj__
+      rescue WeakRef::RefError
+        dead_ids << id
+      end
+
+      dead_ids.each { |id| @circuits.delete(id) }
+    end
+  end
+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/base.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  module Storage
+    # Abstract base class for storage backends
+    class Base
+      def initialize(**options)
+        @options = options
+      end
+
+      # Status management
+      def get_status(circuit_name)
+        raise NotImplementedError
+      end
+
+      def set_status(circuit_name, status, opened_at = nil)
+        raise NotImplementedError
+      end
+
+      # Metrics tracking
+      def record_success(circuit_name, duration)
+        raise NotImplementedError
+      end
+
+      def record_failure(circuit_name, duration)
+        raise NotImplementedError
+      end
+
+      def success_count(circuit_name, window_seconds)
+        raise NotImplementedError
+      end
+
+      def failure_count(circuit_name, window_seconds)
+        raise NotImplementedError
+      end
+
+      # Cleanup
+      def clear(circuit_name)
+        raise NotImplementedError
+      end
+
+      def clear_all
+        raise NotImplementedError
+      end
+
+      # Timeout handling - each backend must implement its own timeout strategy
+      def with_timeout(timeout_ms)
+        raise NotImplementedError, "#{self.class} must implement #with_timeout to handle #{timeout_ms}ms timeouts"
+      end
+    end
+  end
+end

data/lib/breaker_machines/storage/bucket_memory.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require 'concurrent/map'
+require 'concurrent/array'
+
+module BreakerMachines
+  module Storage
+    # Efficient bucket-based memory storage implementation
+    # Uses fixed-size circular buffers for constant-time event counting
+    #
+    # 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 BucketMemory < Base
+      BUCKET_SIZE = 1 # 1 second per bucket
+
+      def initialize(**options)
+        super
+        @circuits = Concurrent::Map.new
+        @circuit_buckets = Concurrent::Map.new
+        @event_logs = Concurrent::Map.new
+        @bucket_count = options[:bucket_count] || 300 # Default 5 minutes
+        @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)
+        @circuit_buckets.delete(circuit_name)
+        @event_logs.delete(circuit_name)
+      end
+
+      def clear_all
+        @circuits.clear
+        @circuit_buckets.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
+
+      private
+
+      def record_event(circuit_name, type, _duration)
+        buckets = @circuit_buckets.compute_if_absent(circuit_name) do
+          {
+            successes: Concurrent::Array.new(@bucket_count) { Concurrent::AtomicFixnum.new(0) },
+            failures: Concurrent::Array.new(@bucket_count) { Concurrent::AtomicFixnum.new(0) },
+            last_bucket_time: Concurrent::AtomicReference.new(current_bucket_time)
+          }
+        end
+
+        current_time = current_bucket_time
+        rotate_buckets_if_needed(buckets, current_time)
+
+        bucket_index = current_time % @bucket_count
+        counter_array = type == :success ? buckets[:successes] : buckets[:failures]
+        counter_array[bucket_index].increment
+      end
+
+      def count_events(circuit_name, type, window_seconds)
+        buckets = @circuit_buckets[circuit_name]
+        return 0 unless buckets
+
+        current_time = current_bucket_time
+        rotate_buckets_if_needed(buckets, current_time)
+
+        # Calculate how many buckets to count
+        buckets_to_count = [window_seconds / BUCKET_SIZE, @bucket_count].min.to_i
+
+        counter_array = type == :success ? buckets[:successes] : buckets[:failures]
+        total = 0
+
+        buckets_to_count.times do |i|
+          bucket_index = (current_time - i) % @bucket_count
+          total += counter_array[bucket_index].value
+        end
+
+        total
+      end
+
+      def rotate_buckets_if_needed(buckets, current_time)
+        last_time = buckets[:last_bucket_time].value
+
+        return if current_time == last_time
+
+        # Only one thread should rotate buckets
+        return unless buckets[:last_bucket_time].compare_and_set(last_time, current_time)
+
+        # Clear buckets that are now outdated
+        time_diff = current_time - last_time
+        buckets_to_clear = [time_diff, @bucket_count].min
+
+        buckets_to_clear.times do |i|
+          # Clear the bucket that will be reused
+          bucket_index = (last_time + i + 1) % @bucket_count
+          buckets[:successes][bucket_index].value = 0
+          buckets[:failures][bucket_index].value = 0
+        end
+      end
+
+      def current_bucket_time
+        (monotonic_time / BUCKET_SIZE).to_i
+      end
+
+      def monotonic_time
+        # Return time relative to storage creation (matches Rust implementation)
+        BreakerMachines.monotonic_time - @start_time
+      end
+
+      def with_timeout(_timeout_ms)
+        # BucketMemory operations should be instant, but we'll still respect the timeout
+        # This is more for consistency and to catch any potential deadlocks
+        yield
+      end
+    end
+  end
+end

data/lib/breaker_machines/storage/cache.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  module Storage
+    # Storage adapter for ActiveSupport::Cache
+    # Works with any Rails cache store (Redis, Memcached, Memory, etc.)
+    class Cache < Base
+      def initialize(cache_store: Rails.cache, **options)
+        super(**options)
+        @cache = cache_store
+        @prefix = options[:prefix] || 'breaker_machines'
+        @expires_in = options[:expires_in] || 300 # 5 minutes default
+      end
+
+      def get_status(circuit_name)
+        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)
+        @cache.write(
+          status_key(circuit_name),
+          {
+            status: status,
+            opened_at: opened_at,
+            updated_at: monotonic_time
+          },
+          expires_in: @expires_in
+        )
+      end
+
+      def record_success(circuit_name, _duration)
+        increment_counter(success_key(circuit_name))
+      end
+
+      def record_failure(circuit_name, _duration)
+        increment_counter(failure_key(circuit_name))
+      end
+
+      def success_count(circuit_name, window_seconds)
+        get_window_count(success_key(circuit_name), window_seconds)
+      end
+
+      def failure_count(circuit_name, window_seconds)
+        get_window_count(failure_key(circuit_name), window_seconds)
+      end
+
+      def clear(circuit_name)
+        @cache.delete(status_key(circuit_name))
+        @cache.delete(success_key(circuit_name))
+        @cache.delete(failure_key(circuit_name))
+        @cache.delete(events_key(circuit_name))
+      end
+
+      def clear_all
+        # Clear all circuit data by pattern if cache supports it
+        if @cache.respond_to?(:delete_matched)
+          @cache.delete_matched("#{@prefix}:*")
+        else
+          # Fallback: can't efficiently clear all without pattern support
+          BreakerMachines.logger&.warn(
+            "[BreakerMachines] Cache store doesn't support delete_matched. " \
+            'Individual circuit data must be cleared manually.'
+          )
+        end
+      end
+
+      def record_event_with_details(circuit_name, type, duration, error: nil, new_state: nil)
+        events = @cache.fetch(events_key(circuit_name)) { [] }
+
+        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
+        events.shift while events.size > (@max_events || 100)
+
+        @cache.write(events_key(circuit_name), events, expires_in: @expires_in)
+      end
+
+      def event_log(circuit_name, limit)
+        events = @cache.read(events_key(circuit_name)) || []
+        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)
+        # Use increment if available, otherwise fetch-and-update
+        if @cache.respond_to?(:increment)
+          @cache.increment(key, 1, expires_in: @expires_in)
+        else
+          # Fallback for caches without atomic increment
+          current = @cache.fetch(key) { {} }
+          current[current_bucket] = (current[current_bucket] || 0) + 1
+          prune_old_buckets(current)
+          @cache.write(key, current, expires_in: @expires_in)
+        end
+      end
+
+      def get_window_count(key, window_seconds)
+        if @cache.respond_to?(:increment)
+          # For simple counter-based caches, we can't get windowed counts
+          # Would need to implement bucketing similar to fallback
+          @cache.read(key) || 0
+        else
+          # Bucket-based counting for accurate windows
+          buckets = @cache.read(key) || {}
+          current_time = current_bucket
+
+          total = 0
+          window_seconds.times do |i|
+            bucket_key = current_time - i
+            total += buckets[bucket_key] || 0
+          end
+
+          total
+        end
+      end
+
+      def prune_old_buckets(buckets)
+        cutoff = current_bucket - 300 # Keep 5 minutes of data
+        buckets.delete_if { |time, _| time < cutoff }
+      end
+
+      def current_bucket
+        Time.now.to_i
+      end
+
+      def status_key(circuit_name)
+        "#{@prefix}:#{circuit_name}:status"
+      end
+
+      def success_key(circuit_name)
+        "#{@prefix}:#{circuit_name}:successes"
+      end
+
+      def failure_key(circuit_name)
+        "#{@prefix}:#{circuit_name}:failures"
+      end
+
+      def events_key(circuit_name)
+        "#{@prefix}:#{circuit_name}:events"
+      end
+
+      def monotonic_time
+        BreakerMachines.monotonic_time
+      end
+    end
+  end
+end