breaker_machines 0.19.0-aarch64-linux → 0.21.0-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 487a558aca59fd540c58f62522a0a17fb4d09dd9b7be651dc2287b641d5234ab
-  data.tar.gz: a107fb51fe5bca08c6cee529a52c67318a59f93f152ba1cbcf56ff1485392e8c
+  metadata.gz: 7c0e53da65b311a1036acd3348580b0f06d25c24213da2bcef11ead9d17842c0
+  data.tar.gz: 62ca980cc3bd0dc4ae1a052b716f783a5a8091ddfe2491539a2cdb73d3ee26dc
 SHA512:
-  metadata.gz: f269384b44021356303e1b28d3068a3f2a47b90d4a35b318724b8bb15710a8e49ea1e5755260eb23b0b85e0b8ac92409ab0baeb2646fe7603f1116f88a93bd12
-  data.tar.gz: fc91de78c041680da7aca666462fa2a6b3ad6c3eed09eadce3f1edc20c21dbb16cceae15a4e3fad9c3047ff9a19a153c8c9366b9a7d7d37c66ff4c679b6804c8
+  metadata.gz: 8fd98bf9f3816b532669792a04af9409a345f78ea33c8e1a436d235c76cb0eb584584fa54322b7e9c8d66da23c87a06cffd770d43dbebb253abc2f9129a0ca3c
+  data.tar.gz: 9377c5397b5d363f5b8dd335a0b08565ebdb0a6e16e6115c900a252ec1e72b4a3123505774df6e0f76773e180a0890eb33e15aa1e22df277c0daed977ea3de55

data/README.md

@@ -28,6 +28,23 @@ class PaymentService
 end
 ```
 
+### Protect an existing client
+
+Use `protect` to route selected public methods through an existing circuit:
+
+```ruby
+circuit = BreakerMachines::Circuit.new(:teleporter, failure_threshold: 3)
+protected_client = circuit.protect(teleporter, methods: %i[beam_up beam_down])
+
+protected_client.beam_up('Schrödinger', destination: :sickbay)
+```
+
+The wrapper forwards arguments, keywords, blocks, and results through `circuit.call`, including its configured error handling and fallback. Other methods pass through without consulting the circuit. `methods:` must be nonempty and name public methods the client responds to; otherwise `protect` raises `ArgumentError`.
+
+The original client stays unchanged. Each call through the wrapper counts as one operation, including any internal method calls. Returned objects stay unchanged too: later calls on a returned client or lazy stream need their own protection. Wrap the object that performs the external operation.
+
+Available on Ruby and native circuits, including circuits obtained through the DSL. Multiple wrappers can share the same circuit.
+
 ## A Message to the Resistance
 
 So AI took your job while you were waiting for Fireship to drop the next JavaScript framework?

data/lib/breaker_machines/circuit/admission.rb

@@ -18,14 +18,28 @@ module BreakerMachines
 
       private
 
+      # Runs on every call: the write lock is taken only to apply a changed
+      # shared status or to start recovery.
       def attempt_recovery_if_ready
-        return unless open? && reset_timeout_elapsed?
+        changed = stored_status_changed?
+        return unless changed || (open? && reset_timeout_elapsed?)
 
         @mutex.with_write_lock do
+          restore_status_from_storage if changed
           attempt_recovery if open? && reset_timeout_elapsed?
         end
       end
 
+      # Reads the shared status before taking the write lock, so storage I/O
+      # happens under it only when there is a change to apply.
+      def with_refreshed_status
+        changed = stored_status_changed?
+        @mutex.with_write_lock do
+          restore_status_from_storage if changed
+          yield
+        end
+      end
+
       def admit_call
         @mutex.with_read_lock do
           case status_name
@@ -55,7 +69,7 @@ module BreakerMachines
       def handle_success(admission)
         return unless admission.half_open?
 
-        @mutex.with_write_lock do
+        with_refreshed_status do
           return unless admission_current?(admission) && half_open?
 
           successful_attempts = @half_open_successes.increment
@@ -68,7 +82,7 @@ module BreakerMachines
       end
 
       def handle_failure(admission)
-        @mutex.with_write_lock do
+        with_refreshed_status do
           return unless admission_current?(admission)
 
           if admission.closed? && closed? && failure_threshold_exceeded?
@@ -84,7 +98,7 @@ module BreakerMachines
       def release_abandoned_admission(admission)
         return unless admission.half_open?
 
-        @mutex.with_write_lock do
+        with_refreshed_status do
           next unless admission_current?(admission) && half_open?
           next unless @half_open_attempts.value.positive?
 

data/lib/breaker_machines/circuit/base.rb

@@ -12,6 +12,7 @@ module BreakerMachines
         include Circuit::Configuration
         include Circuit::Admission
         include Circuit::Execution
+        include Circuit::Protection
         include Circuit::HedgedExecution
         include Circuit::Introspection
         include Circuit::Callbacks
@@ -53,12 +54,50 @@ module BreakerMachines
         @semaphore = (Concurrent::Semaphore.new(@config[:max_concurrent]) if @config[:max_concurrent])
       end
 
+      # A round trip through epoch time is off by up to ~0.12µs (float64
+      # spacing near today's epoch); any larger difference is another opening.
+      OPENED_AT_TOLERANCE = 1e-6
+
+      # Reads the shared status without taking the lock. True when it differs
+      # from the last status this instance stored or observed.
+      def stored_status_changed?
+        stored_status = @storage&.get_status(@name)
+        !stored_status.nil? && !same_stored_status?(stored_status, @stored_status)
+      end
+
       def restore_status_from_storage
-        stored_status = @storage.get_status(@name)
-        return unless stored_status
+        stored_status = @storage&.get_status(@name)
+        return if stored_status.nil? || same_stored_status?(stored_status, @stored_status)
 
+        @stored_status = stored_status
         self.status = stored_status.status.to_s
-        @opened_at.value = stored_status.opened_at if stored_status.opened_at
+        @opened_at.value = stored_status.opened_at
+        @state_epoch.increment
+        @half_open_attempts.value = 0
+        @half_open_successes.value = 0
+        return unless closed?
+
+        @last_error.value = nil
+        @last_failure_at.value = nil
+      end
+
+      def same_stored_status?(stored_status, known_status)
+        return false unless known_status && stored_status.status == known_status.status
+
+        stored_at = stored_status.opened_at
+        known_at = known_status.opened_at
+        return stored_at == known_at if stored_at.nil? || known_at.nil?
+
+        (stored_at - known_at).abs <= OPENED_AT_TOLERANCE
+      end
+
+      # When the storage reports a failed write (false), keep the last status
+      # observed there: the stale entry then reads as unchanged and cannot
+      # undo this transition.
+      def persist_status(status, opened_at = nil)
+        return if @storage.nil? || @storage.set_status(@name, status, opened_at) == false
+
+        @stored_status = BreakerMachines::Status.new(status: status, opened_at: opened_at)
       end
     end
   end

data/lib/breaker_machines/circuit/native.rb

@@ -16,6 +16,8 @@ module BreakerMachines
     #
     #   circuit.call { api.fetch_data }
     class Native
+      include Circuit::Protection
+
       # @return [String] Circuit name
       attr_reader :name
 

data/lib/breaker_machines/circuit/protection.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  class Circuit
+    # Protection adds `protect`, which wraps selected public methods of an
+    # object so that each call runs through this circuit's `call`.
+    module Protection
+      def protect(object, methods:)
+        Proxy.new(object, circuit: self, methods:)
+      end
+    end
+  end
+end

data/lib/breaker_machines/circuit/proxy.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'delegate'
+
+module BreakerMachines
+  class Circuit
+    # Proxy delegates to a wrapped object and routes the configured methods
+    # through a circuit. Unlisted methods pass straight through.
+    class Proxy < SimpleDelegator
+      def initialize(object, circuit:, methods:)
+        raise ArgumentError, 'methods must not be empty' if methods.empty?
+
+        methods.each do |name|
+          raise ArgumentError, "Unknown public method: #{name}" unless object.respond_to?(name)
+        end
+
+        super(object)
+
+        methods.each do |name|
+          define_singleton_method(name) do |*args, **kwargs, &block|
+            circuit.call { __getobj__.public_send(name, *args, **kwargs, &block) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/breaker_machines/circuit/state_callbacks.rb

@@ -11,7 +11,7 @@ module BreakerMachines
       def on_circuit_open
         @state_epoch.increment
         @opened_at.value = BreakerMachines.monotonic_time
-        @storage&.set_status(@name, :open, @opened_at.value)
+        persist_status(:open, @opened_at.value)
         if @storage.respond_to?(:record_event_with_details)
           @storage.record_event_with_details(@name, :state_change, 0,
                                              new_state: :open)
@@ -25,7 +25,7 @@ module BreakerMachines
         @opened_at.value = nil
         @last_error.value = nil
         @last_failure_at.value = nil
-        @storage&.set_status(@name, :closed)
+        persist_status(:closed)
         if @storage.respond_to?(:record_event_with_details)
           @storage.record_event_with_details(@name, :state_change, 0,
                                              new_state: :closed)
@@ -38,7 +38,7 @@ module BreakerMachines
         @state_epoch.increment
         @half_open_attempts.value = 0
         @half_open_successes.value = 0
-        @storage&.set_status(@name, :half_open)
+        persist_status(:half_open, @opened_at.value)
         if @storage.respond_to?(:record_event_with_details)
           @storage.record_event_with_details(@name, :state_change, 0,
                                              new_state: :half_open)

data/lib/breaker_machines/storage/base.rb

@@ -13,6 +13,8 @@ module BreakerMachines
         raise NotImplementedError
       end
 
+      # opened_at is a BreakerMachines.monotonic_time value. Return false when
+      # the write did not happen; any other value means it was stored.
       def set_status(circuit_name, status, opened_at = nil)
         raise NotImplementedError
       end

data/lib/breaker_machines/storage/cache.rb

@@ -10,6 +10,12 @@ module BreakerMachines
         @cache = cache_store
         @prefix = options[:prefix] || 'breaker_machines'
         @expires_in = options[:expires_in] || 300 # 5 minutes default
+        # Counter resolution in seconds. Each bucket is its own cache entry, so
+        # stores that keep expired entries around (Solid Cache) want coarser buckets.
+        @bucket_seconds = Integer(options[:bucket_seconds] || 1)
+        raise ArgumentError, 'bucket_seconds must be positive' unless @bucket_seconds.positive?
+
+        @warned_windows = Concurrent::Set.new
       end
 
       def get_status(circuit_name)
@@ -18,7 +24,7 @@ module BreakerMachines
 
         BreakerMachines::Status.new(
           status: data[:status].to_sym,
-          opened_at: data[:opened_at]
+          opened_at: local_opened_at(data)
         )
       end
 
@@ -28,6 +34,7 @@ module BreakerMachines
           {
             status: status,
             opened_at: opened_at,
+            opened_at_epoch: opened_at && BreakerMachines.monotonic_to_epoch(opened_at),
             updated_at: monotonic_time
           },
           expires_in: @expires_in
@@ -55,6 +62,12 @@ module BreakerMachines
         @cache.delete(success_key(circuit_name))
         @cache.delete(failure_key(circuit_name))
         @cache.delete(events_key(circuit_name))
+        return unless @cache.respond_to?(:increment)
+
+        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)
       end
 
       def clear_all
@@ -103,10 +116,20 @@ module BreakerMachines
 
       private
 
+      # Hosts do not share a monotonic clock origin, so other hosts read the
+      # epoch copy. Entries written before it existed carry only the writer's
+      # monotonic time.
+      def local_opened_at(data)
+        epoch = data[:opened_at_epoch]
+        epoch ? BreakerMachines.epoch_to_monotonic(epoch) : data[:opened_at]
+      end
+
       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)
+          # Expiry counts from the first increment, so a bucket must outlive
+          # the retention period by its own length.
+          @cache.increment("#{key}:#{current_bucket}", 1, expires_in: @expires_in + @bucket_seconds)
         else
           # Fallback for caches without atomic increment
           current = @cache.fetch(key) { {} }
@@ -117,32 +140,58 @@ module BreakerMachines
       end
 
       def get_window_count(key, window_seconds)
+        warn_window_exceeds_retention(window_seconds)
+        count = bucket_count([window_seconds, @expires_in].min)
+
         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
+          read_counters(bucket_keys(key, count)).sum(&:to_i)
         else
-          # Bucket-based counting for accurate windows
           buckets = @cache.read(key) || {}
-          current_time = current_bucket
+          now = current_bucket
+          count.times.sum { |offset| buckets[now - offset] || 0 }
+        end
+      end
 
-          total = 0
-          window_seconds.times do |i|
-            bucket_key = current_time - i
-            total += buckets[bucket_key] || 0
-          end
+      # Counters live for expires_in, so a longer window silently undercounts.
+      def warn_window_exceeds_retention(window_seconds)
+        return if window_seconds <= @expires_in
+        return unless @warned_windows.add?(window_seconds)
 
-          total
-        end
+        BreakerMachines.logger&.warn(
+          "[BreakerMachines] Cache storage keeps counts for #{@expires_in}s, so a #{window_seconds}s " \
+          "window only sees the last #{@expires_in}s. Set expires_in to at least the window."
+        )
+      end
+
+      # 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)
+
+        keys.filter_map { |key| @cache.read(key) }
+      end
+
+      def delete_counters(keys)
+        return @cache.delete_multi(keys) if @cache.respond_to?(:delete_multi)
+
+        keys.each { |key| @cache.delete(key) }
+      end
+
+      def bucket_count(seconds)
+        (seconds.to_f / @bucket_seconds).ceil
+      end
+
+      def bucket_keys(key, count)
+        now = current_bucket
+        Array.new(count) { |offset| "#{key}:#{now - offset}" }
       end
 
       def prune_old_buckets(buckets)
-        cutoff = current_bucket - 300 # Keep 5 minutes of data
-        buckets.delete_if { |time, _| time < cutoff }
+        cutoff = current_bucket - bucket_count(@expires_in)
+        buckets.delete_if { |bucket, _| bucket < cutoff }
       end
 
       def current_bucket
-        Time.now.to_i
+        Time.now.to_i / @bucket_seconds
       end
 
       def status_key(circuit_name)

data/lib/breaker_machines/version.rb

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

data/lib/breaker_machines.rb

@@ -184,6 +184,35 @@ module BreakerMachines
     def monotonic_time
       Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end
+
+    # Converts a {monotonic_time} value to Unix epoch seconds. Each host's
+    # monotonic clock has its own origin, so shared storage must persist
+    # timestamps in epoch time for other hosts to read them.
+    #
+    # @param monotonic [Float] a value from {monotonic_time}
+    # @return [Float] Unix epoch seconds
+    def monotonic_to_epoch(monotonic)
+      monotonic + clock_offset
+    end
+
+    # Converts Unix epoch seconds to this host's {monotonic_time}.
+    #
+    # @param epoch [Float] Unix epoch seconds
+    # @return [Float] the matching {monotonic_time} value on this host
+    def epoch_to_monotonic(epoch)
+      epoch - clock_offset
+    end
+
+    private
+
+    # Wall clock minus monotonic clock. Memoized so that converting the same
+    # timestamp twice gives the same result; re-measured only when the wall
+    # clock has stepped by more than a second.
+    def clock_offset
+      offset = Process.clock_gettime(Process::CLOCK_REALTIME) - monotonic_time
+      @clock_offset = offset if @clock_offset.nil? || (offset - @clock_offset).abs > 1.0
+      @clock_offset
+    end
   end
 
   # Set up notifications on first use

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: breaker_machines
 version: !ruby/object:Gem::Version
-  version: 0.19.0
+  version: 0.21.0
 platform: aarch64-linux
 authors:
 - Abdelkader Boudih
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-10-10 00:00:00.000000000 Z
+date: 2026-10-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -16,28 +16,28 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '8.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '8.1'
 - !ruby/object:Gem::Dependency
   name: chrono_machines
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.9'
+        version: '0.10'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.9'
+        version: '0.10'
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
   requirement: !ruby/object:Gem::Requirement
@@ -86,14 +86,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.16'
+        version: '6.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.16'
+        version: '6.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -151,6 +151,8 @@ files:
 - lib/breaker_machines/circuit/hedged_execution.rb
 - lib/breaker_machines/circuit/introspection.rb
 - lib/breaker_machines/circuit/native.rb
+- lib/breaker_machines/circuit/protection.rb
+- lib/breaker_machines/circuit/proxy.rb
 - lib/breaker_machines/circuit/state_callbacks.rb
 - lib/breaker_machines/circuit/state_machine_definition.rb
 - lib/breaker_machines/circuit/state_management.rb
@@ -180,18 +182,6 @@ files:
 - lib/breaker_machines/types.rb
 - lib/breaker_machines/version.rb
 - lib/breaker_machines_native/breaker_machines_native.so
-- sig/README.md
-- sig/all.rbs
-- sig/breaker_machines.rbs
-- sig/breaker_machines/circuit.rbs
-- sig/breaker_machines/console.rbs
-- sig/breaker_machines/dsl.rbs
-- sig/breaker_machines/errors.rbs
-- sig/breaker_machines/interfaces.rbs
-- sig/breaker_machines/registry.rbs
-- sig/breaker_machines/storage.rbs
-- sig/breaker_machines/types.rbs
-- sig/manifest.yaml
 homepage: https://github.com/seuros/breaker_machines
 licenses:
 - MIT

data/sig/README.md

@@ -1,74 +0,0 @@
-# BreakerMachines RBS Type Signatures
-
-This directory contains RBS (Ruby type signatures) for the BreakerMachines gem.
-
-## Structure
-
-- `breaker_machines.rbs` - Main module and configuration
-- `breaker_machines/` - Type signatures for all classes and modules
-  - `circuit.rbs` - Circuit class and its modules
-  - `errors.rbs` - Error classes
-  - `storage.rbs` - Storage backends
-  - `dsl.rbs` - DSL module for including in classes
-  - `registry.rbs` - Global circuit registry
-  - `console.rbs` - Interactive console
-  - `types.rbs` - Common type aliases
-  - `interfaces.rbs` - Interface definitions
-
-## Usage
-
-To use these type signatures in your project:
-
-1. Add to your `Steepfile`:
-   ```ruby
-   target :app do
-     signature "sig"
-     check "lib"
-
-     library "breaker_machines"
-   end
-   ```
-
-2. Or with RBS directly:
-   ```bash
-   rbs validate
-   ```
-
-## Type Checking Examples
-
-### Basic Circuit Usage
-```ruby
-circuit = BreakerMachines::Circuit.new("api",
-  failure_threshold: 5,
-  reset_timeout: 30
-)
-
-result = circuit.call { api.fetch_data }
-```
-
-### DSL Usage
-```ruby
-class MyService
-  include BreakerMachines::DSL
-
-  circuit :database do
-    threshold failures: 10, within: 60
-    reset_after 120
-    fallback { [] }
-  end
-end
-```
-
-## Key Types
-
-- `circuit_state` - `:open | :closed | :half_open`
-- `storage_backend` - `:memory | :bucket_memory | :null | :redis`
-- `circuit_options` - Configuration hash for circuits
-- `event_record` - Structure for logged events
-
-## Interfaces
-
-The type signatures define several interfaces:
-- `_StorageBackend` - For custom storage implementations
-- `_MetricsRecorder` - For custom metrics recording
-- `_CircuitLike` - For circuit-compatible objects

data/sig/all.rbs

@@ -1,25 +0,0 @@
-# Main entry point for BreakerMachines RBS types
-#
-# This file provides a complete type definition for the BreakerMachines gem,
-# a Ruby implementation of the Circuit Breaker pattern.
-#
-# Usage:
-#   class MyService
-#     include BreakerMachines::DSL
-#
-#     circuit :api_call do
-#       threshold failures: 5, within: 60
-#       reset_after 30
-#       fallback { |error| { error: "Service unavailable" } }
-#     end
-#
-#     def fetch_data
-#       circuit(:api_call).call do
-#         # Your API call here
-#       end
-#     end
-#   end
-
-# Import all type definitions
-use BreakerMachines::*
-use BreakerMachines::Storage::*

data/sig/breaker_machines/circuit.rbs

@@ -1,179 +0,0 @@
-module BreakerMachines
-  class Circuit
-    include StateManagement
-    include Configuration
-    include Admission
-    include Execution
-    include Introspection
-    include Callbacks
-
-    # Instance variables from Configuration module
-    @name: String
-    @config: Hash[Symbol, untyped]
-    @storage: _StorageBackend?
-    @metrics: _MetricsRecorder?
-    @opened_at: Concurrent::AtomicReference[Float?]
-    @half_open_attempts: Concurrent::AtomicFixnum
-    @half_open_successes: Concurrent::AtomicFixnum
-    @state_epoch: Concurrent::AtomicFixnum
-    @mutex: Concurrent::ReentrantReadWriteLock
-    @last_failure_at: Concurrent::AtomicReference[Float?]
-    @last_error: Concurrent::AtomicReference[StandardError?]
-
-    # State machine status (from StateManagement)
-    attr_reader status: (:open | :closed | :half_open)
-  end
-
-  module Admission
-    class Call
-      attr_reader state: (:closed | :half_open)
-      attr_reader state_epoch: Integer
-
-      def self.new: (state: (:closed | :half_open), state_epoch: Integer) -> Call
-      def closed?: () -> bool
-      def half_open?: () -> bool
-    end
-
-    private
-
-    def attempt_recovery_if_ready: () -> void
-    def admit_call: () -> Call?
-    def admit_half_open_call: () -> Call?
-    def admission_current?: (Call admission) -> bool
-    def handle_success: (Call admission) -> void
-    def handle_failure: (Call admission) -> void
-    def release_abandoned_admission: (Call admission) -> void
-  end
-
-  module StateManagement
-    interface _StateManagementState
-      def status: () -> (:open | :closed | :half_open)
-      def status=: (:open | :closed | :half_open value) -> void
-      def status_name: () -> (:open | :closed | :half_open)
-      def open?: () -> bool
-      def closed?: () -> bool
-      def half_open?: () -> bool
-      def trip: () -> bool
-      def attempt_recovery: () -> bool
-      def reset: () -> bool
-      def force_open: () -> bool
-      def force_close: () -> bool
-    end
-
-    def self.included: (singleton(Circuit) base) -> void
-
-    private
-
-    def on_circuit_open: () -> void
-    def on_circuit_close: () -> void
-    def on_circuit_half_open: () -> void
-    def restore_status_from_storage: () -> void
-    def reset_timeout_elapsed?: () -> bool
-    def monotonic_time: () -> Float
-  end
-
-  module Configuration
-    extend ActiveSupport::Concern
-
-    interface _ConfigurationMethods
-      def name: () -> String
-      def config: () -> Hash[Symbol, untyped]
-      def opened_at: () -> Concurrent::AtomicReference[Float?]
-    end
-
-    type storage_type = Storage::Base | Storage::Memory | Storage::BucketMemory | Storage::Null
-    type metrics_type = untyped
-    type callback_type = Proc | nil
-    type fallback_type = Proc | Array[Proc | untyped] | untyped
-
-    type circuit_config = {
-      failure_threshold: Integer,
-      failure_window: Integer,
-      success_threshold: Integer,
-      timeout: Integer?,
-      reset_timeout: Integer,
-      reset_timeout_jitter: Float,
-      half_open_calls: Integer,
-      storage: storage_type?,
-      metrics: metrics_type?,
-      fallback: fallback_type?,
-      on_open: callback_type,
-      on_close: callback_type,
-      on_half_open: callback_type,
-      on_reject: callback_type,
-      exceptions: Array[Class],
-      owner: untyped
-    }
-
-    def initialize: (String name, ?circuit_config options) -> void
-
-    private
-
-    def default_config: () -> circuit_config
-    def create_default_storage: () -> storage_type
-  end
-
-  module Execution
-    def call: [T] () { () -> T } -> untyped
-    def wrap: [T] () { () -> T } -> untyped
-
-    private
-
-    def execute_with_state_check: [T] () { () -> T } -> untyped
-    def execute_call: [T] (Admission::Call admission) { () -> T } -> untyped
-    def execute_call_sync: [T] (Admission::Call admission) { () -> T } -> untyped
-    def execute_sync_operation: [T] () { () -> T } -> T
-    def warn_about_sync_timeout: () -> void
-    def complete_call_success: (Admission::Call admission, Float start_time) -> void
-    def complete_call_failure: (Admission::Call admission, Float start_time, Exception error) -> void
-    def reject_call: () -> untyped
-    def reject_call_bulkhead: () -> untyped
-    def failure_threshold_exceeded?: () -> bool
-    def success_threshold_reached?: () -> bool
-    def record_success: (Float duration) -> void
-    def record_failure: (Float duration, ?StandardError? error) -> void
-  end
-
-  module Introspection
-    type stats_hash = {
-      state: (:open | :closed | :half_open),
-      failure_count: Integer,
-      success_count: Integer,
-      last_failure_at: Float?,
-      opened_at: Float?,
-      half_open_attempts: Integer,
-      half_open_successes: Integer
-    }
-
-    type error_info = {
-      class: String,
-      message: String,
-      occurred_at: Float
-    }
-
-    type circuit_hash = {
-      name: String,
-      state: (:open | :closed | :half_open),
-      stats: stats_hash,
-      config: Hash[Symbol, untyped],
-      event_log: Array[untyped],
-      last_error: error_info?
-    }
-
-    def stats: () -> stats_hash
-    def configuration: () -> Hash[Symbol, untyped]
-    def event_log: (?limit: Integer) -> Array[untyped]?
-    def last_error: () -> StandardError?
-    def to_h: () -> circuit_hash
-    def summary: () -> String
-    def last_error_info: () -> error_info?
-  end
-
-  module Callbacks
-    private
-
-    def invoke_callback: (Symbol callback_name) -> void
-    def invoke_fallback: (StandardError error) -> untyped
-    def invoke_single_fallback: (Proc | untyped fallback, StandardError error) -> untyped
-  end
-end

data/sig/breaker_machines/console.rbs

@@ -1,32 +0,0 @@
-module BreakerMachines
-  class Console
-    @running: bool
-
-    def self.start: () -> void
-
-    def initialize: () -> void
-    def run: () -> void
-
-    private
-
-    def print_header: () -> void
-    def print_help: () -> void
-    def print_prompt: () -> void
-    def process_command: (String command) -> void
-
-    # Command methods
-    def list_circuits: () -> void
-    def show_stats: () -> void
-    def show_circuit: (String? name) -> void
-    def show_events: (String? name, Integer limit) -> void
-    def reset_circuit: (String? name) -> void
-    def force_open_circuit: (String? name) -> void
-    def force_close_circuit: (String? name) -> void
-    def generate_report: () -> void
-    def cleanup_registry: () -> void
-
-    # Utility methods
-    def colorize_state: (Symbol state) -> String
-    def colorize_event_type: (Symbol type) -> String
-  end
-end

data/sig/breaker_machines/dsl.rbs

@@ -1,50 +0,0 @@
-module BreakerMachines
-  module DSL
-    extend ActiveSupport::Concern
-
-    @instance_registries: Concurrent::Map[Class, Concurrent::Array[WeakRef[untyped]]]
-
-    module ClassMethods
-      @circuits: Hash[Symbol, Hash[Symbol, untyped]]
-
-      def instance_registry: () -> Concurrent::Array[WeakRef[untyped]]
-      def cleanup_instance_registry: () -> void
-      def circuit: (Symbol name) ?{ (CircuitBuilder) -> void } -> Hash[Symbol, untyped]
-      def circuits: () -> Hash[Symbol, Hash[Symbol, untyped]]
-      def circuit_definitions: () -> Hash[Symbol, Hash[Symbol, untyped]]
-      def reset_all_circuits: () -> void
-      def circuit_stats: () -> Hash[Symbol, { total: Integer, by_state: Hash[Symbol, Integer] }]
-    end
-
-    def circuit: (Symbol name) -> Circuit
-    def circuit_instances: () -> Hash[Symbol, Circuit]
-    def circuits_summary: () -> Hash[Symbol, String]
-    def circuits_report: () -> Hash[Symbol, untyped]
-    def reset_all_circuits: () -> void
-
-    class CircuitBuilder
-      attr_reader config: Hash[Symbol, untyped]
-
-      def initialize: () -> void
-
-      # Configuration methods
-      def threshold: (?failures: Integer?, ?within: Integer, ?successes: Integer?) -> void
-      def reset_after: (Integer duration, ?jitter: Float?) -> void
-      def timeout: (Integer duration) -> void
-      def half_open_requests: (Integer count) -> void
-      def storage: ((:memory | :bucket_memory | :redis | Class | Storage::Base) backend, **untyped) -> void
-      def metrics: (?untyped recorder) ?{ () -> void } -> void
-      def fallback: (?untyped value) ?{ (StandardError) -> untyped } -> void
-      def on_open: () { () -> void } -> void
-      def on_close: () { () -> void } -> void
-      def on_half_open: () { () -> void } -> void
-      def on_reject: () { () -> void } -> void
-      def notify: (Symbol service, ?String? url, ?events: Array[Symbol], **untyped options) -> void
-      def handle: (*Class exceptions) -> void
-
-      # Advanced features
-      def backends: (Array[untyped] list) -> void
-      def parallel_calls: (Integer count, ?timeout: Integer?) -> void
-    end
-  end
-end

data/sig/breaker_machines/errors.rbs

@@ -1,24 +0,0 @@
-module BreakerMachines
-  class Error < StandardError
-  end
-
-  class CircuitOpenError < Error
-    attr_reader circuit_name: String
-    attr_reader opened_at: Float?
-
-    def initialize: (String circuit_name, ?Float? opened_at) -> void
-  end
-
-  class CircuitTimeoutError < Error
-    attr_reader circuit_name: String
-    attr_reader timeout: Numeric
-
-    def initialize: (String circuit_name, Numeric timeout) -> void
-  end
-
-  class ConfigurationError < Error
-  end
-
-  class StorageError < Error
-  end
-end

data/sig/breaker_machines/interfaces.rbs

@@ -1,46 +0,0 @@
-module BreakerMachines
-  # Interface for objects that can record metrics
-  interface _MetricsRecorder
-    def record_success: (String circuit_name, Float duration) -> void
-    def record_failure: (String circuit_name, Float duration) -> void
-    def record_rejection: (String circuit_name) -> void
-  end
-
-  # Interface for storage backends
-  interface _StorageBackend
-    def get_status: (String circuit_name) -> status_record?
-    def set_status: (String circuit_name, circuit_state status, ?Float? opened_at) -> void
-    def record_success: (String circuit_name, Float duration) -> void
-    def record_failure: (String circuit_name, Float duration) -> void
-    def success_count: (String circuit_name, Integer window_seconds) -> Integer
-    def failure_count: (String circuit_name, Integer window_seconds) -> Integer
-    def clear: (String circuit_name) -> void
-    def clear_all: () -> void
-  end
-
-  # Interface for advanced storage backends with event logging
-  interface _AdvancedStorageBackend
-    def record_success: (String circuit_name, ?Float? duration) -> void
-    def record_failure: (String circuit_name, ?Float? duration) -> void
-    def success_count: (String circuit_name, ?Integer? window) -> Integer
-    def failure_count: (String circuit_name, ?Integer? window) -> Integer
-    def get_status: (String circuit_name) -> Hash[Symbol, untyped]?
-    def set_status: (String circuit_name, circuit_state status, ?Float? opened_at) -> void
-    def clear: (String circuit_name) -> void
-    def record_event_with_details: (String circuit_name, event_type event_type, Float duration, ?Hash[Symbol, untyped] details) -> void
-    def event_log: (String circuit_name, ?Integer limit) -> Array[event_record]
-  end
-
-  # Interface for circuit-like objects
-  interface _CircuitLike
-    def name: () -> String
-    def call: () { () -> untyped } -> untyped
-    def wrap: () { () -> untyped } -> untyped
-    def status_name: () -> circuit_state
-    def open?: () -> bool
-    def closed?: () -> bool
-    def half_open?: () -> bool
-    def reset: () -> bool
-    def stats: () -> Hash[Symbol, untyped]
-  end
-end

data/sig/breaker_machines/registry.rbs

@@ -1,30 +0,0 @@
-module BreakerMachines
-  class Registry
-    include Singleton
-
-    @circuits: Concurrent::Map[Integer, WeakRef[Circuit]]
-    @mutex: Mutex
-    @registration_count: Integer
-    @cleanup_interval: Integer
-
-    def initialize: () -> void
-
-    # Circuit management
-    def register: (Circuit circuit) -> void
-    def unregister: (Circuit circuit) -> void
-    def all_circuits: () -> Array[Circuit]
-    def find_by_name: (Symbol name) -> Array[Circuit]
-
-    # Reporting
-    def stats_summary: () -> { total: Integer, by_state: Hash[Symbol, Integer], by_name: Hash[Symbol, Integer] }
-    def detailed_report: () -> Array[Hash[Symbol, untyped]]
-
-    # Maintenance
-    def clear: () -> void
-    def cleanup_dead_references: () -> void
-
-    private
-
-    def cleanup_dead_references_unsafe: () -> void
-  end
-end

data/sig/breaker_machines/storage.rbs

@@ -1,65 +0,0 @@
-module BreakerMachines
-  module Storage
-    class Base
-      @options: Hash[Symbol, untyped]
-
-      def initialize: (**untyped options) -> void
-
-      # Status management
-      def get_status: (String circuit_name) -> { status: (:open | :closed | :half_open), opened_at: Float? }?
-      def set_status: (String circuit_name, (:open | :closed | :half_open) status, ?Float? opened_at) -> void
-
-      # Metrics tracking
-      def record_success: (String circuit_name, Float duration) -> void
-      def record_failure: (String circuit_name, Float duration) -> void
-      def success_count: (String circuit_name, Integer window_seconds) -> Integer
-      def failure_count: (String circuit_name, Integer window_seconds) -> Integer
-
-      # Cleanup
-      def clear: (String circuit_name) -> void
-      def clear_all: () -> void
-    end
-
-    class Memory < Base
-      @circuits: Concurrent::Map[String, untyped]
-      @events: Concurrent::Map[String, Concurrent::Array[untyped]]
-      @event_logs: Concurrent::Map[String, Concurrent::Array[untyped]]
-      @max_events: Integer
-
-      def initialize: (**untyped options) -> void
-      def record_event_with_details: (String circuit_name, (:success | :failure | :state_change) type, Float duration, ?error: StandardError?, ?new_state: (:open | :closed | :half_open)?) -> void
-      def event_log: (String circuit_name, Integer limit) -> Array[event_record]
-
-      private
-
-      def record_event: (String circuit_name, (:success | :failure) type, Float duration) -> void
-      def count_events: (String circuit_name, (:success | :failure) type, Integer window_seconds) -> Integer
-      def monotonic_time: () -> Float
-    end
-
-    class BucketMemory < Base
-      @buckets: Concurrent::Map[String, untyped]
-      @bucket_duration: Integer
-      @bucket_count: Integer
-      @lock: Concurrent::ReentrantReadWriteLock
-      @last_cleanup: Concurrent::AtomicReference[Float]
-      @cleanup_interval: Integer
-
-      def record_event_with_details: (String circuit_name, (:success | :failure | :state_change) event_type, Float duration, ?Hash[Symbol, untyped] details) -> void
-      def event_log: (String circuit_name, ?Integer limit) -> Array[event_record]
-
-      private
-
-      def circuit_buckets: (String circuit_name) -> Hash[Symbol, untyped]
-      def current_bucket_index: () -> Integer
-      def bucket_indices_for_window: (Integer window_seconds) -> Array[Integer]
-      def cleanup_old_buckets: (Hash[Symbol, untyped] buckets) -> void
-      def maybe_cleanup_all_buckets: () -> void
-    end
-
-    class Null < Base
-      def record_event_with_details: (String circuit_name, Symbol event_type, Float duration, ?Hash[Symbol, untyped] metadata) -> void
-      def event_log: (String circuit_name, ?Integer limit) -> Array[untyped]
-    end
-  end
-end

data/sig/breaker_machines/types.rbs

@@ -1,97 +0,0 @@
-# Common type aliases used throughout BreakerMachines
-
-# External dependencies type declarations not included in their gems
-module Concurrent
-  class AtomicReference[T]
-    def initialize: (?T initial_value) -> void
-    def value: () -> T
-    def value=: (T value) -> T
-    def get: () -> T
-    def set: (T value) -> T
-  end
-
-  class AtomicFixnum
-    def initialize: (?Integer initial_value) -> void
-    def value: () -> Integer
-    def value=: (Integer value) -> Integer
-    def increment: (?Integer delta) -> Integer
-    def decrement: (?Integer delta) -> Integer
-  end
-
-  class ReentrantReadWriteLock
-    def initialize: () -> void
-    def with_read_lock: [T] () { () -> T } -> T
-    def with_write_lock: [T] () { () -> T } -> T
-  end
-end
-
-class WeakRef[T]
-  def initialize: (T object) -> void
-  def weakref_alive?: () -> bool
-  def __getobj__: () -> T
-end
-
-module Zeitwerk
-  class Loader
-    def push_dir: (String path) -> void
-    def setup: () -> void
-    def eager_load: () -> void
-  end
-end
-
-module BreakerMachines
-  # Circuit states
-  type circuit_state = :open | :closed | :half_open
-
-  # Event types
-  type event_type = :success | :failure | :state_change | :rejection
-
-  # Callback names
-  type callback_name = :on_open | :on_close | :on_half_open | :on_reject
-
-  # Storage backend symbols
-  type storage_backend = :memory | :bucket_memory | :null | :redis
-
-  # Generic callback proc
-  type callback_proc = Proc | nil
-
-  # Fallback can be a proc, array of procs/values, or any static value
-  type fallback_value = Proc | Array[Proc | untyped] | untyped
-
-  # Options hash for circuits
-  type circuit_options = {
-    failure_threshold: Integer?,
-    failure_window: Integer?,
-    success_threshold: Integer?,
-    timeout: Integer?,
-    reset_timeout: Integer?,
-    reset_timeout_jitter: Float?,
-    half_open_calls: Integer?,
-    storage: (Storage::Base | storage_backend | Class)?,
-    metrics: untyped,
-    fallback: fallback_value?,
-    on_open: callback_proc,
-    on_close: callback_proc,
-    on_half_open: callback_proc,
-    on_reject: callback_proc,
-    exceptions: Array[Class]?,
-    owner: untyped
-  }
-
-  # Event record structure
-  type event_record = {
-    timestamp: Float,
-    type: event_type,
-    duration: Float,
-    duration_ms: Float?,
-    error_class: String?,
-    new_state: circuit_state?,
-    details: Hash[Symbol, untyped]?
-  }
-
-  # Status record from storage
-  type status_record = {
-    status: circuit_state,
-    opened_at: Float?
-  }
-end

data/sig/breaker_machines.rbs

@@ -1,42 +0,0 @@
-module BreakerMachines
-  VERSION: String
-
-  class Configuration
-    attr_accessor default_storage: (:memory | :bucket_memory | :null | untyped)
-    attr_accessor default_timeout: Integer?
-    attr_accessor default_reset_timeout: Integer
-    attr_accessor default_failure_threshold: Integer
-    attr_accessor log_events: bool
-    attr_accessor fiber_safe: bool
-
-    def initialize: () -> void
-  end
-
-  # Global configuration
-  self.@config: Configuration?
-  def self.config: () -> Configuration
-
-  # Class methods
-  def self.configure: () { (Configuration config) -> void } -> void
-
-  # Delegated config accessors for backward compatibility
-  def self.default_storage: () -> (:memory | :bucket_memory | :null | untyped)
-  def self.default_storage=: ((:memory | :bucket_memory | :null | untyped) value) -> void
-  def self.default_timeout: () -> Integer?
-  def self.default_timeout=: (Integer? value) -> void
-  def self.default_reset_timeout: () -> Integer
-  def self.default_reset_timeout=: (Integer value) -> void
-  def self.default_failure_threshold: () -> Integer
-  def self.default_failure_threshold=: (Integer value) -> void
-  def self.log_events: () -> bool
-  def self.log_events=: (bool value) -> void
-  def self.fiber_safe: () -> bool
-  def self.fiber_safe=: (bool value) -> void
-  def self.setup_notifications: () -> void
-  def self.logger: () -> ActiveSupport::Logger?
-  def self.logger=: (ActiveSupport::Logger? logger) -> void
-  def self.instrument: (String event, ?Hash[Symbol, untyped] payload) -> void
-  def self.console: () -> void
-  def self.registry: () -> Registry
-  def self.loader: () -> Zeitwerk::Loader
-end

data/sig/manifest.yaml

@@ -1,5 +0,0 @@
-dependencies:
-  - name: activesupport
-  - name: concurrent-ruby
-  - name: state_machines
-  - name: zeitwerk