breaker_machines 0.21.2-aarch64-linux → 0.23.0-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c971cfed381f2d07b89282e624acd46d3a08f3810bd15816218ab0c989a4a99d
-  data.tar.gz: 98774e5f9b87f993c09b52d7c4066f1338523d9ac57c6b87d5a5a13b15e0b4c3
+  metadata.gz: 91385c927ff170ab3cfee26eaad04d6e5ac01a5633a7cd4d12451e8c56f0e1a4
+  data.tar.gz: 24129cb01cd3c719dbd3629ba6bf981b64cd0618fdca720e3c5d534028a9ca2a
 SHA512:
-  metadata.gz: a3a7ba6bdd201547323b3a29f2fcfe0faaa8e57643a830e590e12dd73b2209caaec7db833c861500ef0372300dd29ff6332e3020f6f23e62be42f4c3233593ff
-  data.tar.gz: dd625105381e8e1b37ddf0c818de361172373d75278fd5b3d823ca258423dc6659910dfad6d58106fec8a06e9c9fd709b1da6d850836d85d171b91d44cf119e7
+  metadata.gz: 6e9ada73d92778670a60b0ab2c6984b1afa4b30c6cad2ec632ab6918e24979e7999263c4f104866d5218e6bb6f7c1c70ad36365d6b9a7ad54bc7b0949fe10773
+  data.tar.gz: cf10c1cd6e0b452960100144883d7a1ce6698371c37588d0aa57904058f5582a9fc150958562a0dcb833fdaa97a4bf55fed0f1604cc00101ad9f5d334b404690

data/lib/breaker_machines/async_support.rb

@@ -31,6 +31,7 @@ module BreakerMachines
       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) }
+        raise if caller_gave_up?(e)
 
         complete_call_failure(admission, start_time, e)
         completed = true

data/lib/breaker_machines/circuit/admission.rb

@@ -53,9 +53,10 @@ module BreakerMachines
 
       def admit_half_open_call
         state_epoch = @state_epoch.value
-        new_attempts = @half_open_attempts.increment
+        # Slots taken, less those already banked as successes.
+        probes_in_flight = @half_open_attempts.increment - @half_open_successes.value
 
-        return Call.new(state: :half_open, state_epoch:) if new_attempts <= @config[:half_open_calls]
+        return Call.new(state: :half_open, state_epoch:) if probes_in_flight <= @config[:half_open_calls]
 
         # This caller lost the race for a probe slot.
         @half_open_attempts.decrement
@@ -69,28 +70,32 @@ module BreakerMachines
       def handle_success(admission)
         return unless admission.half_open?
 
-        with_refreshed_status do
-          return unless admission_current?(admission) && half_open?
+        with_deferred_callbacks do
+          with_refreshed_status do
+            return unless admission_current?(admission) && half_open?
 
-          successful_attempts = @half_open_successes.increment
-          next unless successful_attempts >= @config[:half_open_calls] || success_threshold_reached?
+            successful_attempts = @half_open_successes.increment
+            next unless successful_attempts >= @config[:success_threshold]
 
-          @half_open_attempts.value = 0
-          @half_open_successes.value = 0
-          reset
+            @half_open_attempts.value = 0
+            @half_open_successes.value = 0
+            reset
+          end
         end
       end
 
       def handle_failure(admission)
-        with_refreshed_status do
-          return unless admission_current?(admission)
-
-          if admission.closed? && closed? && failure_threshold_exceeded?
-            trip
-          elsif admission.half_open? && half_open?
-            @half_open_attempts.value = 0
-            @half_open_successes.value = 0
-            trip
+        with_deferred_callbacks do
+          with_refreshed_status do
+            return unless admission_current?(admission)
+
+            if admission.closed? && closed? && failure_threshold_exceeded?
+              trip
+            elsif admission.half_open? && half_open?
+              @half_open_attempts.value = 0
+              @half_open_successes.value = 0
+              trip
+            end
           end
         end
       end

data/lib/breaker_machines/circuit/base.rb

@@ -38,6 +38,7 @@ module BreakerMachines
 
       def initialize_runtime_state
         @opened_at = Concurrent::AtomicReference.new(nil)
+        @open_timeout = Concurrent::AtomicReference.new(nil)
         @half_open_attempts = Concurrent::AtomicFixnum.new(0)
         @half_open_successes = Concurrent::AtomicFixnum.new(0)
         @state_epoch = Concurrent::AtomicFixnum.new(0)

data/lib/breaker_machines/circuit/callbacks.rb

@@ -9,7 +9,32 @@ module BreakerMachines
 
       private
 
+      DEFERRED = :breaker_machines_deferred_callbacks
+
+      # A state-change callback is user code. Running it under the circuit's
+      # write lock lets it block every other caller, and letting it raise
+      # replaces the operation's own error, so it is collected here and run
+      # after the lock is released.
       def invoke_callback(callback_name)
+        pending = Thread.current[DEFERRED]
+        return pending << callback_name if pending
+
+        run_callback(callback_name)
+      end
+
+      def with_deferred_callbacks
+        outer = Thread.current[DEFERRED]
+        pending = []
+        Thread.current[DEFERRED] = pending
+        begin
+          yield
+        ensure
+          Thread.current[DEFERRED] = outer
+          pending.each { |name| run_callback(name) }
+        end
+      end
+
+      def run_callback(callback_name)
         callback = @config[callback_name]
         return unless callback
 
@@ -26,6 +51,8 @@ module BreakerMachines
         else
           callback.call
         end
+      rescue StandardError => e
+        BreakerMachines.instrument('callback_error', circuit: @name, callback: callback_name, error: e)
       end
 
       def invoke_fallback(error)

data/lib/breaker_machines/circuit/execution.rb

@@ -32,6 +32,7 @@ module BreakerMachines
       private
 
       def execute_with_state_check(&)
+        DeadlineMachines.check!
         attempt_recovery_if_ready
 
         # Apply bulkheading first, outside of any locks
@@ -78,6 +79,8 @@ module BreakerMachines
           completed = true
           result
         rescue *@config[:exceptions] => e
+          raise if caller_gave_up?(e)
+
           complete_call_failure(admission, start_time, e)
           completed = true
           raise unless @config[:fallback]
@@ -88,6 +91,13 @@ module BreakerMachines
         end
       end
 
+      # A caller abandoning its own budget says nothing about the dependency's
+      # health, so it must not count toward the failure threshold. An inner
+      # scope expiring is a genuine timeout and still does.
+      def caller_gave_up?(error)
+        error.is_a?(DeadlineMachines::Error) && DeadlineMachines.current&.done?
+      end
+
       def execute_sync_operation(&)
         warn_about_sync_timeout
         return execute_hedged(&) if @config[:hedged_requests] || @config[:backends]
@@ -157,11 +167,6 @@ module BreakerMachines
         end
       end
 
-      def success_threshold_reached?
-        recent_successes = @storage.success_count(@name, @config[:failure_window])
-        recent_successes >= @config[:success_threshold]
-      end
-
       def record_success(duration)
         @metrics&.record_success(@name, duration)
         @storage&.record_success(@name, duration)

data/lib/breaker_machines/circuit/hedged_execution.rb

@@ -12,6 +12,12 @@ module BreakerMachines
       extend ActiveSupport::Concern
 
       # Execute a hedged request pattern
+      # Seconds a hedge waits when the circuit configures no timeout.
+      HEDGE_TIMEOUT = 30
+
+      # Seconds between polls of the result queue.
+      HEDGE_POLL = 0.001
+
       def execute_hedged(&)
         return execute_single_hedged(&) unless @config[:backends]&.any?
 
@@ -55,7 +61,7 @@ module BreakerMachines
 
         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?
+          sleep(DeadlineMachines.clamp_sleep(delay_ms / 1000.0)) if index.positive? && delay_ms.positive?
 
           # Skip if already got a result
           break if cancelled.value
@@ -75,7 +81,8 @@ module BreakerMachines
 
         # Wait for first result or all errors
         begin
-          Timeout.timeout(@config[:timeout] || 30) do
+          DeadlineMachines.check!
+          Timeout.timeout(DeadlineMachines.clamp_sleep(@config[:timeout] || HEDGE_TIMEOUT)) do
             # Check for successful result
             loop do
               unless result_queue.empty?
@@ -87,8 +94,8 @@ module BreakerMachines
               # Check if all requests failed
               raise error_queue.pop if error_queue.size >= callables.size
 
-              # Small sleep to prevent busy waiting
-              sleep 0.001
+              DeadlineMachines.check!
+              sleep HEDGE_POLL
             end
           end
         ensure

data/lib/breaker_machines/circuit/introspection.rb

@@ -67,7 +67,7 @@ module BreakerMachines
                            "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)."
+                         "(#{@half_open_successes.value}/#{@config[:success_threshold]} successes)."
                        end
 
         # Add cascade information if this is a cascading circuit

data/lib/breaker_machines/circuit/native.rb

@@ -5,8 +5,9 @@ module BreakerMachines
     # Native circuit breaker implementation using Rust FFI
     #
     # This provides a high-performance circuit breaker with state machine logic
-    # implemented in Rust. It's fully compatible with the Ruby circuit API but
-    # significantly faster for high-throughput scenarios.
+    # implemented in Rust. It answers the same questions as the pure-Ruby
+    # circuit under the same names, so the global registry reports on both
+    # kinds of circuit alike.
     #
     # @example Basic usage
     #   circuit = BreakerMachines::Circuit::Native.new('api_calls',
@@ -31,27 +32,32 @@ module BreakerMachines
       # @option options [Integer] :failure_threshold Number of failures to open circuit (default: 5)
       # @option options [Float] :failure_window_secs Time window for counting failures (default: 60.0)
       # @option options [Float] :half_open_timeout_secs Timeout before attempting reset (default: 30.0)
+      # @option options [Float] :jitter_factor Cooldown jitter, 0.0-1.0 (default: 0.0)
       # @option options [Integer] :success_threshold Successes needed to close from half-open (default: 2)
+      # @option options [Integer] :half_open_calls Probes admitted at a time while half-open (default: 1)
       # @option options [Boolean] :auto_register Register with global registry (default: true)
+      # @raise [ConfigurationError] for an option the native circuit cannot honour
       def initialize(name, options = {})
         unless BreakerMachines.native_available?
           raise BreakerMachines::ConfigurationError,
                 'Native extension not available. Install with native support or use Circuit::Ruby'
         end
 
+        unhonoured = options.keys - default_config.keys
+        if unhonoured.any?
+          raise BreakerMachines::ConfigurationError,
+                "Circuit::Native cannot honour #{unhonoured.join(', ')}; use BreakerMachines::Circuit for those"
+        end
+
         @name = name
         @config = default_config.merge(options)
 
         # Create the native circuit breaker
-        @native_circuit = BreakerMachinesNative::Circuit.new(
-          name,
-          {
-            failure_threshold: @config[:failure_threshold],
-            failure_window_secs: @config[:failure_window_secs],
-            half_open_timeout_secs: @config[:half_open_timeout_secs],
-            success_threshold: @config[:success_threshold]
-          }
-        )
+        @native_circuit = BreakerMachinesNative::Circuit.new(name, native_config)
+
+        # Zero of the native circuit's own clock, which its timestamps count from.
+        @clock_origin = BreakerMachines.monotonic_time
+        @epoch_origin = BreakerMachines.monotonic_to_epoch(@clock_origin)
 
         # Register with global registry unless disabled
         BreakerMachines::Registry.instance.register(self) unless @config[:auto_register] == false
@@ -88,40 +94,109 @@ module BreakerMachines
         @native_circuit.is_half_open
       end
 
-      # Get current state name
-      # @return [String] 'closed', 'open', or 'half_open'
-      def state
-        @native_circuit.state_name
+      # Current state name
+      # @return [Symbol] :closed, :open, or :half_open
+      def status_name
+        @native_circuit.state_name.to_sym
       end
 
-      # Reset the circuit (clear all events)
-      def reset!
-        @native_circuit.reset
+      # @return [BreakerMachines::Stats] counts over the configured failure window
+      def stats
+        BreakerMachines::Stats.new(
+          state: status_name,
+          failure_count: @native_circuit.failure_count,
+          success_count: @native_circuit.success_count,
+          last_failure_at: nil,
+          opened_at: opened_at,
+          half_open_attempts: @native_circuit.half_open_attempts,
+          half_open_successes: @native_circuit.half_open_successes
+        )
+      end
+
+      # @return [Hash] a copy of this circuit's configuration
+      def configuration
+        @config.dup
+      end
+
+      # @param limit [Integer] how many of the most recent outcomes to return
+      # @return [Array<Hash>] recorded outcomes, oldest first
+      def event_log(limit: 20)
+        @native_circuit.event_log(limit).map do |event|
+          event.merge(timestamp_epoch: @epoch_origin + event[:timestamp])
+        end
+      end
+
+      # The native circuit records outcomes, not the errors behind them.
+      # @return [nil]
+      def last_error
+        nil
       end
 
-      # Get circuit status for inspection
-      # @return [Hash] Status information
-      def status
+      # @return [nil] (see #last_error)
+      def last_error_info
+        nil
+      end
+
+      # @return [Hash] full state, statistics and configuration
+      def to_h
         {
           name: @name,
-          state: state,
-          open: open?,
-          closed: closed?,
-          config: @config
+          state: status_name,
+          stats: stats.to_h,
+          config: configuration,
+          event_log: event_log,
+          last_error: last_error_info&.to_h
         }
       end
 
+      # Open the circuit whatever its failure count
+      # @return [true]
+      def force_open
+        @native_circuit.force_open
+        true
+      end
+
+      # Close the circuit, keeping the events in its failure window
+      # @return [true]
+      def force_close
+        @native_circuit.force_close
+        true
+      end
+
+      alias reset force_close
+      alias reset! force_close
+
+      # Close the circuit and clear its failure window
+      # @return [true]
+      def hard_reset
+        @native_circuit.reset
+        true
+      end
+
       private
 
+      # Native timestamps count from the circuit's own clock; Stats reports
+      # BreakerMachines.monotonic_time.
+      def opened_at
+        opened = @native_circuit.opened_at
+        opened && @clock_origin + opened
+      end
+
       def default_config
         {
           failure_threshold: 5,
           failure_window_secs: 60.0,
           half_open_timeout_secs: 30.0,
+          jitter_factor: 0.0,
           success_threshold: 2,
+          half_open_calls: 1,
           auto_register: true
         }
       end
+
+      def native_config
+        @config.except(:auto_register)
+      end
     end
   end
 end

data/lib/breaker_machines/circuit/state_callbacks.rb

@@ -11,6 +11,7 @@ module BreakerMachines
       def on_circuit_open
         @state_epoch.increment
         @opened_at.value = BreakerMachines.monotonic_time
+        @open_timeout.value = draw_reset_timeout
         persist_status(:open, @opened_at.value)
         if @storage.respond_to?(:record_event_with_details)
           @storage.record_event_with_details(@name, :state_change, 0,
@@ -23,6 +24,7 @@ module BreakerMachines
       def on_circuit_close
         @state_epoch.increment
         @opened_at.value = nil
+        @open_timeout.value = nil
         @last_error.value = nil
         @last_failure_at.value = nil
         persist_status(:closed)
@@ -50,26 +52,19 @@ module BreakerMachines
       def reset_timeout_elapsed?
         return false unless @opened_at.value
 
-        # Add jitter to prevent thundering herd using ChronoMachines
-        # This matches the Rust implementation which uses chrono-machines for jitter
-        timeout_with_jitter = if (jitter_factor = @config[:reset_timeout_jitter]) && jitter_factor.positive?
-                                calculate_timeout_with_jitter(@config[:reset_timeout], jitter_factor)
-                              else
-                                @config[:reset_timeout]
-                              end
-
-        BreakerMachines.monotonic_time - @opened_at.value >= timeout_with_jitter
+        BreakerMachines.monotonic_time - @opened_at.value >= (@open_timeout.value || draw_reset_timeout)
       end
 
-      # Calculate timeout with jitter using ChronoMachines algorithm
-      # Matches the Rust implementation: timeout * (1 - jitter + rand * jitter)
-      def calculate_timeout_with_jitter(base_timeout, jitter_factor)
-        # Use full jitter strategy from ChronoMachines
-        # Formula: base * (1 - jitter + rand * jitter)
-        # This gives values in range [base * (1-jitter), base]
-        normalized_jitter = [jitter_factor.to_f, 1.0].min
-        base_timeout * (1.0 - normalized_jitter + (rand * normalized_jitter))
+      # Drawn once per opening. Re-drawing on every check would return the
+      # minimum of N samples, pinning the cooldown to the bottom of its range
+      # and synchronising a fleet instead of spreading it.
+      def draw_reset_timeout
+        jitter_factor = @config[:reset_timeout_jitter]
+        return @config[:reset_timeout] unless jitter_factor&.positive?
+
+        ChronoMachines.jitter(@config[:reset_timeout], factor: jitter_factor)
       end
+
     end
   end
 end

data/lib/breaker_machines/console.rb

@@ -221,7 +221,11 @@ module BreakerMachines
           puts '-' * 80
 
           events.each do |event|
-            timestamp = Time.at(event[:timestamp]).strftime('%Y-%m-%d %H:%M:%S')
+            timestamp = if event[:timestamp_epoch]
+                          Time.at(event[:timestamp_epoch]).strftime('%Y-%m-%d %H:%M:%S')
+                        else
+                          format('%.3fs', event[:timestamp])
+                        end
             type = colorize_event_type(event[:type])
             duration = event[:duration_ms] ? "#{event[:duration_ms]}ms" : '-'
             error = event[:error_class] || '-'

data/lib/breaker_machines/hedged_async_support.rb

@@ -47,40 +47,43 @@ module BreakerMachines
     # Race callables; return first result or raise if it was an Exception
     # Uses modern Async::Promise and Async::Barrier for cleaner synchronization
     # @param callables [Array<Proc>] Tasks to race
+    # One hedge's outcome, so a returned exception object is not mistaken
+    # for a failure.
+    Hedge = Data.define(:value, :error)
+
     # @param delay_ms [Integer] Delay in milliseconds between task starts
     # @return [Object] First successful result
     # @raise [Exception] The first exception received
     def race_tasks(callables, delay_ms: 0)
       promise = Async::Promise.new
       barrier = Async::Barrier.new
+      outstanding = callables.size
+      failure = nil
 
       begin
-        result = Async do
+        outcome = Async do
           callables.each_with_index do |callable, idx|
             barrier.async do
-              # stagger hedged attempts
-              sleep(delay_ms / 1000.0) if idx.positive? && delay_ms.positive?
+              sleep(DeadlineMachines.clamp_sleep(delay_ms / 1000.0)) if idx.positive? && delay_ms.positive?
 
               begin
-                result = callable.call
-                # Try to resolve the promise with this result
-                # Only the first resolution will succeed
-                promise.resolve(result) unless promise.resolved?
+                value = callable.call
+                promise.resolve(Hedge.new(value, nil)) unless promise.resolved?
               rescue StandardError => e
-                # Only set exception if no result has been resolved yet
-                promise.resolve(e) unless promise.resolved?
+                failure = e
+                outstanding -= 1
+                promise.resolve(Hedge.new(nil, e)) if outstanding.zero? && !promise.resolved?
               end
             end
           end
 
-          # Wait for the first resolution (either success or exception)
           promise.wait
         end.wait
 
-        # If result is an exception, raise it; otherwise return the result
-        result.is_a?(StandardError) ? raise(result) : result
+        raise outcome.error if outcome.error
+
+        outcome.value
       ensure
-        # Ensure all tasks are stopped
         barrier&.stop
       end
     end

data/lib/breaker_machines/registry.rb

@@ -11,6 +11,7 @@ module BreakerMachines
     def initialize
       @circuits = Concurrent::Map.new
       @named_circuits = Concurrent::Map.new # For dynamic circuits by name
+      @named_last_used = Concurrent::Map.new # Monotonic time each was last handed out
       @mutex = Mutex.new
       @registration_count = 0
       @cleanup_interval = 100 # Clean up every N registrations
@@ -19,13 +20,13 @@ module BreakerMachines
     # 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)
+        @circuits[circuit.object_id] = WeakRef.new(circuit)
 
         # Periodic cleanup
         @registration_count += 1
         if @registration_count >= @cleanup_interval
           cleanup_dead_references_unsafe
+          cleanup_stale_dynamic_circuits_unsafe(DYNAMIC_CIRCUIT_MAX_AGE)
           @registration_count = 0
         end
       end
@@ -34,7 +35,7 @@ module BreakerMachines
     # Unregister a circuit instance
     def unregister(circuit)
       @mutex.synchronize do
-        @circuits.delete(circuit)
+        @circuits.delete(circuit.object_id)
       end
     end
 
@@ -122,15 +123,10 @@ module BreakerMachines
     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
+        existing = @named_circuits[name]
+        if existing
+          @named_last_used[name] = BreakerMachines.monotonic_time
+          return existing
         end
 
         # Create new circuit with weak owner reference
@@ -139,9 +135,9 @@ module BreakerMachines
         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)
+        @circuits[new_circuit.object_id] = WeakRef.new(new_circuit)
+        @named_circuits[name] = new_circuit
+        @named_last_used[name] = BreakerMachines.monotonic_time
 
         new_circuit
       end
@@ -151,14 +147,10 @@ module BreakerMachines
     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
+          circuit = @named_circuits.delete(name)
+          @named_last_used.delete(name)
+          @circuits.delete(circuit.object_id) if circuit
+          true
         else
           false
         end
@@ -168,47 +160,34 @@ module BreakerMachines
     # 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
+        @named_circuits.keys
       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
+    def cleanup_stale_dynamic_circuits(max_age_seconds = DYNAMIC_CIRCUIT_MAX_AGE)
+      @mutex.synchronize { cleanup_stale_dynamic_circuits_unsafe(max_age_seconds) }
+    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
+    # Seconds a named dynamic circuit is kept after its last activity.
+    DYNAMIC_CIRCUIT_MAX_AGE = 3600
+
+    private def cleanup_stale_dynamic_circuits_unsafe(max_age_seconds)
+      cutoff_time = BreakerMachines.monotonic_time - max_age_seconds
+      stale_names = []
 
-        stale_names.size
+      @named_circuits.each_pair do |name, _circuit|
+        last_used = @named_last_used[name]
+        stale_names << name if last_used.nil? || last_used < cutoff_time
       end
+
+      stale_names.each do |name|
+        circuit = @named_circuits.delete(name)
+        @named_last_used.delete(name)
+        @circuits.delete(circuit.object_id) if circuit
+      end
+
+      stale_names.size
     end
 
     # Clear all circuits (useful for testing)
@@ -216,6 +195,7 @@ module BreakerMachines
       @mutex.synchronize do
         @circuits.clear
         @named_circuits.clear
+        @named_last_used.clear
       end
     end
 

data/lib/breaker_machines/storage/cache.rb

@@ -15,6 +15,9 @@ module BreakerMachines
         @bucket_seconds = Integer(options[:bucket_seconds] || 1)
         raise ArgumentError, 'bucket_seconds must be positive' unless @bucket_seconds.positive?
 
+        @max_events = Integer(options[:max_events] || 100)
+        raise ArgumentError, 'max_events must be positive' unless @max_events.positive?
+
         @warned_windows = Concurrent::Set.new
       end
 
@@ -67,28 +70,23 @@ module BreakerMachines
         keys = [success_key(circuit_name), failure_key(circuit_name)].flat_map do |key|
           bucket_keys(key, bucket_count(@expires_in) + 1)
         end
-        delete_counters(keys)
+        delete_counters(keys + [event_sequence_key(circuit_name)] + event_slot_keys(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
+        return @cache.delete_matched(prefix_matcher) if @cache.respond_to?(:delete_matched)
+
+        warn_clear_all_unsupported
+      rescue NotImplementedError
+        warn_clear_all_unsupported
       end
 
       def record_event_with_details(circuit_name, type, duration, error: nil, new_state: nil)
-        events = @cache.fetch(events_key(circuit_name)) { [] }
-
+        now = monotonic_time
         event = {
           type: type,
-          timestamp: monotonic_time,
+          timestamp: now,
+          timestamp_epoch: BreakerMachines.monotonic_to_epoch(now),
           duration_ms: (duration * 1000).round(2)
         }
 
@@ -96,15 +94,24 @@ module BreakerMachines
         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)
+        return append_event(circuit_name, event) unless @cache.respond_to?(:increment)
 
-        @cache.write(events_key(circuit_name), events, expires_in: @expires_in)
+        sequence = @cache.increment(event_sequence_key(circuit_name), 1, expires_in: @expires_in)
+        return false unless sequence
+
+        @cache.write(event_slot_key(circuit_name, sequence % @max_events),
+                     event.merge(sequence: sequence), expires_in: @expires_in)
       end
 
       def event_log(circuit_name, limit)
-        events = @cache.read(events_key(circuit_name)) || []
-        events.last(limit)
+        events = if @cache.respond_to?(:increment)
+                   read_values(event_slot_keys(circuit_name)).sort_by do |event|
+                     [event[:timestamp_epoch], event[:sequence]]
+                   end
+                 else
+                   @cache.read(events_key(circuit_name)) || []
+                 end
+        events.last(limit).map { |event| local_event(event) }
       end
 
       def with_timeout(_timeout_ms)
@@ -165,9 +172,39 @@ module BreakerMachines
 
       # read_multi is a single round trip; stores without it read each bucket.
       def read_counters(keys)
-        return @cache.read_multi(*keys, raw: true).values if @cache.respond_to?(:read_multi)
+        read_values(keys, raw: true)
+      end
+
+      def read_values(keys, **options)
+        return @cache.read_multi(*keys, **options).values if @cache.respond_to?(:read_multi)
+
+        keys.filter_map { |key| @cache.read(key, options) }
+      end
 
-        keys.filter_map { |key| @cache.read(key) }
+      def append_event(circuit_name, event)
+        events = @cache.fetch(events_key(circuit_name)) { [] }
+        events << event
+        events.shift while events.size > @max_events
+        @cache.write(events_key(circuit_name), events, expires_in: @expires_in)
+      end
+
+      def local_event(event)
+        epoch = event[:timestamp_epoch]
+        local = event.except(:sequence)
+        epoch ? local.merge(timestamp: BreakerMachines.epoch_to_monotonic(epoch)) : local
+      end
+
+      def prefix_matcher
+        return "#{@prefix.gsub(/[?*\[\]\\]/) { |char| "\\#{char}" }}:*" if @cache.respond_to?(:redis)
+
+        /^#{Regexp.escape(@prefix)}:/
+      end
+
+      def warn_clear_all_unsupported
+        BreakerMachines.logger&.warn(
+          "[BreakerMachines] #{@cache.class} doesn't support delete_matched. " \
+          'Individual circuit data must be cleared manually.'
+        )
       end
 
       def delete_counters(keys)
@@ -210,6 +247,18 @@ module BreakerMachines
         "#{@prefix}:#{circuit_name}:events"
       end
 
+      def event_sequence_key(circuit_name)
+        "#{@prefix}:#{circuit_name}:event_sequence"
+      end
+
+      def event_slot_key(circuit_name, slot)
+        "#{@prefix}:#{circuit_name}:event:#{slot}"
+      end
+
+      def event_slot_keys(circuit_name)
+        Array.new(@max_events) { |slot| event_slot_key(circuit_name, slot) }
+      end
+
       def monotonic_time
         BreakerMachines.monotonic_time
       end

data/lib/breaker_machines/storage/memory_support.rb

@@ -46,9 +46,11 @@ module BreakerMachines
       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 }
 
+        now = monotonic_time
         event = {
           type: type,
-          timestamp: monotonic_time,
+          timestamp: now,
+          timestamp_epoch: BreakerMachines.monotonic_to_epoch(@start_time + now),
           duration_ms: (duration * 1000).round(2)
         }
 

data/lib/breaker_machines/storage/native.rb

@@ -24,6 +24,7 @@ module BreakerMachines
         super
         # Native extension is guaranteed to be available when this class is loaded
         @backend = BreakerMachinesNative::Storage.new
+        @epoch_origin = BreakerMachines.monotonic_to_epoch(BreakerMachines.monotonic_time)
       end
 
       # Check if using native backend
@@ -67,21 +68,14 @@ module BreakerMachines
         @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
+      # The caller has already recorded the outcome; this backend keeps no
+      # error or state detail, so there is nothing further to store.
+      def record_event_with_details(_circuit_name, _type, _duration, error: nil, new_state: nil); end
 
       def event_log(circuit_name, limit)
-        @backend.event_log(circuit_name.to_s, limit)
+        @backend.event_log(circuit_name.to_s, limit).map do |event|
+          event.merge(timestamp_epoch: @epoch_origin + event[:timestamp])
+        end
       end
 
       def with_timeout(_timeout_ms)

data/lib/breaker_machines/version.rb

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

data/lib/breaker_machines.rb

@@ -3,6 +3,8 @@
 require 'zeitwerk'
 require 'active_support'
 require 'active_support/core_ext'
+require 'chrono_machines'
+require 'deadline_machines'
 require 'state_machines'
 require_relative 'breaker_machines/errors'
 require_relative 'breaker_machines/types'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: breaker_machines
 version: !ruby/object:Gem::Version
-  version: 0.21.2
+  version: 0.23.0
 platform: aarch64-linux
 authors:
 - Abdelkader Boudih
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-10-14 00:00:00.000000000 Z
+date: 2026-11-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -38,6 +38,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.10'
+- !ruby/object:Gem::Dependency
+  name: deadline_machines
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
   requirement: !ruby/object:Gem::Requirement