faulty 0.11.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8604d16866bb43e4b58ebd4d9efd9e3ae2a85555bd5e2d92c1f1ec8bfa24fb69
-  data.tar.gz: a766e4e122b41e4d58cab15fc0c249a254e940e523b54e8d906d00bcefafb5e2
+  metadata.gz: 3642cb65b01572d880aec16ece320bed43b9c12ae13a2dce602c1bf2a5a250c3
+  data.tar.gz: 7116acd4f458c31a738d0f90a7ac0bc0f37e392e75105f19e7b9648af9d7b4c7
 SHA512:
-  metadata.gz: d2bf7c915310ab7eac608fc738f64df191555c7acfe1b6a28eb5a8e0519e42f2cf0512ba5bd7d13d62379783cdbefef69c9fa952d08ff78bf95d973afbd7f15e
-  data.tar.gz: 56963c2e80e34f2f56ac5a4efa405032f9eb72bd176ee0e7683a2f7dd0a4d26f06535773b9056c84c50d2d5349b2c2eb6d9dcc97fa98f3ef130245e3d65adb2b
+  metadata.gz: b7078729322061727335102869126e65348f270a71a41b624a2722d62c416672f6b39778338faf570ceac39b7355ebfbc8bf4aff7e866123aada12ba507172ad
+  data.tar.gz: 117eae9db002823c62280a7236f5a1969409b6baeffa9c51b0430205f23df5b0238890602cae2217fb19da6e22ea8ebbabf622c750bbb732cd95d0a2caa85554

data/CHANGELOG.md

@@ -9,6 +9,81 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [Unreleased]
 -------------------
 
+[0.13.0] - 2026-05-13
+---------------------
+
+### Added
+
+* Reserve half-open test runs across processes so only one process executes
+  the test block when a circuit becomes half-open. justinhoward
+
+### Changed
+
+* `Faulty::Status` now captures `current_time` once when the status is built,
+  so all predicates (`open?`, `half_open?`, `reserved?`) reason about the same
+  point in time. Previously each predicate called `Faulty.current_time`
+  independently. justinhoward
+* `Storage::Redis#close` now also clears the `reserved_at` key. justinhoward
+
+### Fixed
+
+* `Storage::Redis#reserve` uses safe navigation when serializing
+  `previous_reserved_at` for `WATCH`, so the very first CAS against a missing
+  key compares correctly. justinhoward
+* `Storage::Redis#reset` now clears the `reserved_at` key. justinhoward
+* `Status#can_run?` now treats `locked_closed?` as an unconditional override,
+  so a manually locked-closed circuit runs even when a half-open reservation
+  is still in effect from a prior cycle. justinhoward
+
+### Breaking Changes
+
+* `Storage::Interface` adds a required `#reserve(circuit, reserved_at,
+  previous_reserved_at)` method. Custom storage backends must implement it,
+  and the `Status` value object must carry the new `reserved_at` attribute.
+  See `Storage::Interface#reserve` for the contract and the conformance
+  test in `spec/storage/interface_spec.rb` for the structural guarantee.
+
+[0.12.0] - 2026-05-13
+---------------------
+
+Runtime behavior is unchanged from `0.11.0` — the version bump reflects
+support-policy and toolchain breaking changes only. Upgrading should be
+a drop-in replacement on any supported Ruby.
+
+### Breaking
+
+* Drop support for Ruby < 3.1. Ruby 2.3 – 3.0 are EOL upstream and are no
+  longer covered by CI. Faulty now requires Ruby 3.1 or newer.
+* `faulty.gemspec` declares `required_ruby_version = '>= 3.1'`, so older
+  Rubies will refuse to install the gem.
+
+### Changed
+
+* Modernize the CI matrix: Ruby `3.1`, `3.2`, `3.3`, `3.4`, `jruby-head`,
+  and `truffleruby-head`; Redis 4 and 5; OpenSearch `2.19.5` (default) and
+  `3.0.0`; Elasticsearch `7.17.x` for back-compat coverage. The
+  Elasticsearch 7.17 row runs the `elasticsearch:7.17.28` Docker image
+  (which ships a JDK that handles cgroupv2 on current runners) against
+  the `elasticsearch ~> 7.17.11` gem.
+* Pass `DISABLE_INSTALL_DEMO_CONFIG=true` to the OpenSearch service
+  container so OpenSearch 2.12+ doesn't require an admin-password env
+  var just to boot up with the security plugin disabled.
+* Replace the deprecated `:mingw` / `:x64_mingw` platform symbols in the
+  `Gemfile` with the unified `:windows` symbol Bundler now expects.
+* Upgrade development dependencies: `rubocop ~> 1.84`, `rubocop-rspec ~> 3.9`,
+  `simplecov-cobertura ~> 3.1`, `opensearch-ruby ~> 3.4`.
+* `LogListener` now lazy-requires `logger` only when constructing the
+  default `Logger.new($stderr)`. Consumers that pass their own logger or
+  run under Rails do not need the stdlib `logger` gem on the load path.
+  This keeps Faulty boot-clean on Ruby 3.5+ where `logger` is no longer a
+  default gem.
+
+### Removed
+
+* Drop Redis 3 from the test matrix.
+* Drop the Ruby 2.3 carve-out in `spec/spec_helper.rb` that conditionally
+  loaded the `mysql2` patch.
+
 [0.11.0] - 2023-04-26
 ---------------------
 
@@ -308,7 +383,9 @@ of AutoWire.
 
 Initial public release
 
-[Unreleased]: https://github.com/ParentSquare/faulty/compare/v0.11.0...HEAD
+[Unreleased]: https://github.com/ParentSquare/faulty/compare/v0.13.0...HEAD
+[0.13.0]: https://github.com/ParentSquare/faulty/compare/v0.12.0...v0.13.0
+[0.12.0]: https://github.com/ParentSquare/faulty/compare/v0.11.0...v0.12.0
 [0.11.0]: https://github.com/ParentSquare/faulty/compare/v0.10.0...v0.11.0
 [0.10.0]: https://github.com/ParentSquare/faulty/compare/v0.9.0...v0.10.0
 [0.9.0]: https://github.com/ParentSquare/faulty/compare/v0.8.7...v0.9.0

data/README.md

@@ -146,7 +146,7 @@ Faulty.init do |config|
   config.storage = Faulty::Storage::Redis.new
 
   config.listeners << Faulty::Events::CallbackListener.new do |events|
-    events.circuit_open do |payload|
+    events.circuit_opened do |payload|
       puts 'Circuit was opened'
     end
   end
@@ -1226,6 +1226,23 @@ state, Faulty allows a single execution of the block as a test run. If the test
 run succeeds, the circuit is fully closed and the circuit state is reset. If the
 test run fails, the circuit is opened and the cool-down is reset.
 
+When the storage backend supports atomic operations (the default `Memory` and
+`Redis` backends both do), the half-open test run is reserved exclusively. Other
+processes or threads that observe the half-open state while a test run is in
+progress will be skipped with `Faulty::OpenCircuitError`, just as if the circuit
+were still open. The reservation expires after `cool_down` so that a crashed
+process can't permanently wedge the circuit.
+
+This means `cool_down` does double duty: it gates how long the circuit waits
+before retrying after opening, and it bounds how long a half-open reservation
+is honored. Test runs that legitimately take longer than `cool_down` (for
+example, a slow downstream during recovery) will see their reservation expire
+mid-run, at which point another process can reserve and run the block
+concurrently. If your protected calls can run longer than `cool_down`, set
+`cool_down` to comfortably exceed the slowest expected latency for the
+protected operation, or accept that occasional duplicate half-open test runs
+are possible during slow recoveries.
+
 Each time the circuit changes state or executes the block, events are raised
 that are sent to the Faulty event notifier. The notifier should be used to track
 circuit failure rates, open circuits, etc.
@@ -1353,12 +1370,15 @@ but there are and have been many other options:
 - [circuitbox](https://github.com/yammer/circuitbox): Also uses a block syntax
   to manually define circuits. It uses Moneta to abstract circuit storage to
   allow any key-value store.
+- [stoplight](https://github.com/bolshakov/stoplight): Stoplight uses Redis for
+  leader-less coordination in distributed environments to ensure coordinated states
+  transitions and recovery and offers a built-in Admin Panel while focusing on performance
+  by utilizing Lua scripts for the Redis data store which minimizes operational overhead.
 
 ### Previous Work
 
 - [circuit_breaker-ruby](https://github.com/scripbox/circuit_breaker-ruby) (no
   recent activity)
-- [stoplight](https://github.com/orgsync/stoplight) (unmaintained)
 - [circuit_breaker](https://github.com/wsargent/circuit_breaker) (no recent
 activity)
 - [simple_circuit_breaker](https://github.com/soundcloud/simple_circuit_breaker)

data/lib/faulty/cache/auto_wire.rb

@@ -37,8 +37,8 @@ class Faulty
         # @param cache [Interface] A cache backend
         # @param options [Hash] Attributes for {Options}
         # @yield [Options] For setting options in a block
-        def wrap(cache, **options, &block)
-          options = Options.new(options, &block)
+        def wrap(cache, **options, &)
+          options = Options.new(options, &)
           if cache.nil?
             Cache::Default.new
           elsif cache.fault_tolerant?

data/lib/faulty/cache/circuit_proxy.rb

@@ -40,9 +40,9 @@ class Faulty
       # @param cache [Cache::Interface] The cache backend to wrap
       # @param options [Hash] Attributes for {Options}
       # @yield [Options] For setting options in a block
-      def initialize(cache, **options, &block)
+      def initialize(cache, **options, &)
         @cache = cache
-        @options = Options.new(options, &block)
+        @options = Options.new(options, &)
       end
 
       %i[read write].each do |method|

data/lib/faulty/cache/fault_tolerant_proxy.rb

@@ -30,19 +30,19 @@ class Faulty
       # @param cache [Cache::Interface] The cache backend to wrap
       # @param options [Hash] Attributes for {Options}
       # @yield [Options] For setting options in a block
-      def initialize(cache, **options, &block)
+      def initialize(cache, **options, &)
         @cache = cache
-        @options = Options.new(options, &block)
+        @options = Options.new(options, &)
       end
 
       # Wrap a cache in a FaultTolerantProxy unless it's already fault tolerant
       #
       # @param cache [Cache::Interface] The cache to maybe wrap
       # @return [Cache::Interface] The original cache or a {FaultTolerantProxy}
-      def self.wrap(cache, **options, &block)
+      def self.wrap(cache, ...)
         return cache if cache.fault_tolerant?
 
-        new(cache, **options, &block)
+        new(cache, ...)
       end
 
       # Read from the cache safely

data/lib/faulty/circuit.rb

@@ -49,6 +49,10 @@ class Faulty
     # @!attribute [r] cool_down
     #   @return [Integer] The number of seconds the circuit will
     #     stay open after it is tripped. Default 300.
+    #
+    #     Also bounds the half-open reservation TTL — runs longer than
+    #     `cool_down` lose exclusivity. See the "How it Works" section
+    #     of the README.
     # @!attribute [r] error_mapper
     #   @return [Module, #call] Used by patches to set the namespace module for
     #     the faulty errors that will be raised. Should be a module or a callable.
@@ -178,11 +182,11 @@ class Faulty
     # @param name [String] The name of the circuit
     # @param options [Hash] Attributes for {Options}
     # @yield [Options] For setting options in a block
-    def initialize(name, **options, &block)
+    def initialize(name, **options, &)
       raise ArgumentError, 'name must be a String' unless name.is_a?(String)
 
       @name = name
-      @given_options = Options.new(options, &block)
+      @given_options = Options.new(options, &)
       @pulled_options = nil
       @options_pushed = false
     end
@@ -266,8 +270,8 @@ class Faulty
     # @return [Result<Object, Error>] A result where the ok value is the return
     #   value of the block, or the error value is an error captured by the
     #   circuit.
-    def try_run(**options, &block)
-      Result.new(ok: run(**options, &block))
+    def try_run(...)
+      Result.new(ok: run(...))
     rescue FaultyError => e
       Result.new(error: e)
     end
@@ -308,9 +312,11 @@ class Faulty
       return cached_value if !cached_value.nil? && !cache_should_refresh?(cache)
 
       current_status = status
-      return run_skipped(cached_value) unless current_status.can_run?
-
-      run_exec(current_status, cached_value, cache, &block)
+      if current_status.can_run? && reserve(current_status)
+        run_exec(current_status, cached_value, cache, &block)
+      else
+        run_skipped(cached_value)
+      end
     end
 
     # Force the circuit to stay open until unlocked
@@ -403,6 +409,32 @@ class Faulty
       cached_value
     end
 
+    # Reserves execution for this circuit when it is half-open
+    #
+    # This prevents concurrent evaluation from allowing multiple simultaneous
+    # runs for half-open circuits. For non-half-open states this is a no-op
+    # that returns true so closed and locked-closed circuits run unconditionally.
+    #
+    # `locked_closed?` is checked before `half_open?` to mirror the operator-
+    # override hierarchy in {Status#can_run?}: a locked-closed circuit must
+    # always proceed regardless of the underlying state, even if another
+    # process is currently holding the reservation. Without this, a locked-
+    # closed circuit could lose the storage CAS to a concurrent process and
+    # be incorrectly skipped.
+    #
+    # @param status [Status] The current status of the circuit
+    # @return [Boolean] True if this call may proceed to execute the block
+    def reserve(status)
+      return true if status.locked_closed?
+      return true unless status.half_open?
+
+      # Persist a fresh Faulty.current_time, not status.current_time. The
+      # snapshot exists for predicate consistency (see Status#current_time);
+      # the stored reserved_at should reflect when the reservation was made,
+      # not when the snapshot was taken.
+      storage.reserve(self, Faulty.current_time, status.reserved_at)
+    end
+
     # Execute a run
     #
     # @param cached_value The cached value if one is available

data/lib/faulty/error.rb

@@ -8,7 +8,7 @@ class Faulty
   class UninitializedError < FaultyError
     def initialize(message = nil)
       message ||= 'Faulty is not initialized'
-      super(message)
+      super
     end
   end
 
@@ -16,7 +16,7 @@ class Faulty
   class AlreadyInitializedError < FaultyError
     def initialize(message = nil)
       message ||= 'Faulty is already initialized'
-      super(message)
+      super
     end
   end
 
@@ -24,7 +24,7 @@ class Faulty
   class MissingDefaultInstanceError < FaultyError
     def initialize(message = nil)
       message ||= 'No default instance. Create one with init or get your instance with Faulty[:name]'
-      super(message)
+      super
     end
   end
 

data/lib/faulty/events/log_listener.rb

@@ -10,8 +10,17 @@ class Faulty
       #   by default if available, otherwise it creates a new `Logger` to
       #   stderr.
       def initialize(logger = nil)
-        logger ||= defined?(Rails) ? Rails.logger : ::Logger.new($stderr)
-        @logger = logger
+        @logger = if logger
+          logger
+        elsif defined?(Rails)
+          Rails.logger
+        else
+          # Lazy-require so consumers who pass their own logger or use Rails
+          # don't need the stdlib `logger` gem on the load path. Required for
+          # Ruby >= 3.5 where `logger` was extracted from the default gems.
+          require 'logger'
+          ::Logger.new($stderr)
+        end
       end
 
       # (see ListenerInterface#handle)

data/lib/faulty/events/notifier.rb

@@ -22,11 +22,9 @@ class Faulty
         raise ArgumentError, "Unknown event #{event}" unless EVENTS.include?(event)
 
         @listeners.each do |listener|
-          begin
-            listener.handle(event, payload)
-          rescue StandardError => e
-            warn "Faulty listener #{listener.class.name} crashed: #{e.message}"
-          end
+          listener.handle(event, payload)
+        rescue StandardError => e
+          warn "Faulty listener #{listener.class.name} crashed: #{e.message}"
         end
       end
     end

data/lib/faulty/immutable_options.rb

@@ -5,12 +5,12 @@ class Faulty
   module ImmutableOptions
     # @param hash [Hash] A hash of attributes to initialize with
     # @yield [self] Yields itself to the block to set options before freezing
-    def initialize(hash, &block)
-      setup(defaults.merge(hash), &block)
+    def initialize(hash, &)
+      setup(defaults.merge(hash), &)
     end
 
-    def dup_with(hash, &block)
-      dup.setup(hash, &block)
+    def dup_with(hash, &)
+      dup.setup(hash, &)
     end
 
     def setup(hash)

data/lib/faulty/patch/base.rb

@@ -31,13 +31,13 @@ class Faulty
       #
       # @yield A block to run inside the circuit
       # @return The block return value
-      def faulty_run(&block)
+      def faulty_run(&)
         faulty_running_key = "faulty_running_#{object_id}"
         return yield unless @faulty_circuit
         return yield if Thread.current[faulty_running_key]
 
         Thread.current[faulty_running_key] = true
-        @faulty_circuit.run(&block)
+        @faulty_circuit.run(&)
       ensure
         Thread.current[faulty_running_key] = nil
       end

data/lib/faulty/patch/elasticsearch.rb

@@ -54,7 +54,7 @@ class Faulty
       }
 
       module Errors
-        PATCHED_MODULE::Transport::Transport::ERRORS.each do |_code, klass|
+        PATCHED_MODULE::Transport::Transport::ERRORS.each_value do |klass|
           MAPPED_ERRORS[klass] = const_set(klass.name.split('::').last, Module.new)
         end
       end
@@ -69,7 +69,7 @@ class Faulty
       end
       private_constant :ERROR_MAPPER, :MAPPED_ERRORS
 
-      def initialize(arguments = {}, &block)
+      def initialize(arguments = {}, &)
         super
 
         errors = [PATCHED_MODULE::Transport::Transport::Error]

data/lib/faulty/patch/redis/patch.rb

@@ -55,7 +55,7 @@ class Faulty
       #
       # The call* methods above will then raise that error, so we are able to
       # capture it with faulty_run.
-      def io(&block)
+      def io(&)
         return super unless @faulty_circuit
 
         reply = super

data/lib/faulty/patch.rb

@@ -75,7 +75,7 @@ class Faulty
       #   `:error_mapper`
       # @yield [Circuit::Options] For setting override options in a block
       # @return [Circuit, nil] The circuit if one was created
-      def circuit_from_hash(default_name, hash, **options, &block)
+      def circuit_from_hash(default_name, hash, **options, &)
         return unless hash
 
         hash = symbolize_keys(hash)
@@ -84,7 +84,7 @@ class Faulty
         error_mapper = options.delete(:patched_error_mapper)
         hash[:error_mapper] ||= error_mapper if error_mapper && patch_errors
         faulty = resolve_instance(hash.delete(:instance))
-        faulty.circuit(name, **hash, **options, &block)
+        faulty.circuit(name, **hash, **options, &)
       end
 
       # Create a full set of {CircuitError}s with a given base error class

data/lib/faulty/status.rb

@@ -16,9 +16,19 @@ class Faulty
   #   @return [:open, :closed, nil] If the circuit is locked, the state that
   #     it is locked in. Default `nil`.
   # @!attribute [r] opened_at
-  #   @return [Integer, nil] If the circuit is open, the timestamp that it was
-  #     opened. This is not necessarily reset when the circuit is closed.
-  #     Default `nil`.
+  #   @return [Float, nil] If the circuit is open, the timestamp ({Faulty.current_time})
+  #     that it was opened. This is not necessarily reset when the circuit
+  #     is closed. Default `nil`.
+  # @!attribute [r] reserved_at
+  #   @return [Float, nil] If a half-open test run was reserved, the
+  #     timestamp ({Faulty.current_time}) of that reservation. Cleared when
+  #     the circuit is closed.
+  #     Not reset by {Storage::Interface#reopen}; the value naturally expires
+  #     via `cool_down`. Default `nil`.
+  #
+  #     Only meaningful when {#state} is `:open`. If a backend race or bug
+  #     produces an inconsistent shape (`state == :closed` with a non-nil
+  #     `reserved_at`), it is normalized to `nil` at construction.
   # @!attribute [r] failure_rate
   #   @return [Float] A number from 0 to 1 representing the percentage of
   #     failures for the circuit. For exmaple 0.5 represents a 50% failure rate.
@@ -34,6 +44,7 @@ class Faulty
     :state,
     :lock,
     :opened_at,
+    :reserved_at,
     :failure_rate,
     :sample_size,
     :options,
@@ -43,6 +54,19 @@ class Faulty
   class Status
     include ImmutableOptions
 
+    # @return [Float] The point in time captured when this status was built.
+    #   All predicates (`open?`, `half_open?`, `reserved?`) reason about
+    #   this same instant so they are mutually consistent. Held as an
+    #   instance variable rather than a struct field so it does not leak
+    #   into `to_h`, `==`, or `members` — those should reflect persisted
+    #   circuit state, not a transient predicate-consistency snapshot.
+    attr_reader :current_time
+
+    def initialize(hash, &)
+      @current_time = hash[:current_time] || Faulty.current_time
+      super(hash.except(:current_time), &)
+    end
+
     # The allowed state values
     STATES = %i[
       open
@@ -66,7 +90,8 @@ class Faulty
     #   sample_size
     # @return [Status]
     def self.from_entries(entries, **hash)
-      window_start = Faulty.current_time - hash[:options].evaluation_window
+      current_time = Faulty.current_time
+      window_start = current_time - hash[:options].evaluation_window
       size = entries.size
       i = 0
       failures = 0
@@ -84,7 +109,8 @@ class Faulty
 
       new(hash.merge(
         sample_size: sample_size,
-        failure_rate: sample_size.zero? ? 0.0 : failures.to_f / sample_size
+        failure_rate: sample_size.zero? ? 0.0 : failures.to_f / sample_size,
+        current_time: current_time
       ))
     end
 
@@ -94,7 +120,7 @@ class Faulty
     #
     # @return [Boolean] True if open
     def open?
-      state == :open && opened_at + options.cool_down > Faulty.current_time
+      state == :open && opened_at + options.cool_down > current_time
     end
 
     # Whether the circuit is closed
@@ -112,7 +138,7 @@ class Faulty
     #
     # @return [Boolean] True if half-open
     def half_open?
-      state == :open && opened_at + options.cool_down <= Faulty.current_time
+      state == :open && opened_at + options.cool_down <= current_time
     end
 
     # Whether the circuit is locked open
@@ -129,15 +155,42 @@ class Faulty
       lock == :closed
     end
 
+    # Whether a half-open test run is currently reserved
+    #
+    # Process-agnostic: returns true whenever an unexpired reservation exists
+    # on this circuit, regardless of who made it. The "did someone else reserve
+    # this?" interpretation only applies when this predicate is read on a
+    # status snapshot taken *before* the caller attempts {Storage::Interface#reserve};
+    # a caller introspecting their own status after a successful reserve will
+    # also see `true` here.
+    #
+    # The reservation expires after `cool_down` to handle the case where the
+    # process that made the reservation crashes before resolving the circuit.
+    # Side effect: a legitimately-slow test run that exceeds `cool_down`
+    # loses exclusivity (another process may reserve and run concurrently).
+    # See the "How it Works" section of the README for the full trade-off.
+    #
+    # @return [Boolean] True if a reservation is in effect
+    def reserved?
+      return false unless reserved_at
+
+      state == :open && reserved_at + options.cool_down > current_time
+    end
+
     # Whether the circuit can be run
     #
-    # Takes the circuit state, locks and cooldown into account
+    # Takes the circuit state, locks and cooldown into account. Locks are
+    # operator overrides and take precedence over both state and reservation,
+    # so a `locked_closed?` circuit always runs and a `locked_open?` circuit
+    # never runs.
     #
     # @return [Boolean] True if the circuit can be run
     def can_run?
       return false if locked_open?
+      return true if locked_closed?
+      return false if reserved?
 
-      closed? || locked_closed? || half_open?
+      closed? || half_open?
     end
 
     # Whether the circuit fails the sample size and rate thresholds
@@ -155,6 +208,14 @@ class Faulty
         raise ArgumentError, "lock must be a symbol in #{self.class}::LOCKS or nil"
       end
       raise ArgumentError, 'opened_at is required if state is open' if state == :open && opened_at.nil?
+
+      # `reserved_at` is only meaningful while the circuit is open. Backends
+      # are expected to clear it on close, but if a brief race or backend bug
+      # leaves a stale value paired with `state == :closed`, normalize it
+      # here so downstream code can rely on the invariant without checking
+      # `state` first. Sanitizing rather than raising avoids turning a
+      # transient backend inconsistency into a production crash.
+      self.reserved_at = nil if state == :closed && !reserved_at.nil?
     end
 
     def required

data/lib/faulty/storage/auto_wire.rb

@@ -52,8 +52,8 @@ class Faulty
         #   of storage backends to setup.
         # @param options [Hash] Attributes for {Options}
         # @yield [Options] For setting options in a block
-        def wrap(storage, **options, &block)
-          options = Options.new(options, &block)
+        def wrap(storage, **options, &)
+          options = Options.new(options, &)
           if storage.nil?
             Memory.new
           elsif storage.is_a?(Array)

data/lib/faulty/storage/circuit_proxy.rb

@@ -40,9 +40,9 @@ class Faulty
       # @param storage [Storage::Interface] The storage backend to wrap
       # @param options [Hash] Attributes for {Options}
       # @yield [Options] For setting options in a block
-      def initialize(storage, **options, &block)
+      def initialize(storage, **options, &)
         @storage = storage
-        @options = Options.new(options, &block)
+        @options = Options.new(options, &)
       end
 
       %i[
@@ -52,6 +52,7 @@ class Faulty
         open
         reopen
         close
+        reserve
         lock
         unlock
         reset

data/lib/faulty/storage/fallback_chain.rb

@@ -42,9 +42,9 @@ class Faulty
       #   additional entries will be tried in sequence until one succeeds.
       # @param options [Hash] Attributes for {Options}
       # @yield [Options] For setting options in a block
-      def initialize(storages, **options, &block)
+      def initialize(storages, **options, &)
         @storages = storages
-        @options = Options.new(options, &block)
+        @options = Options.new(options, &)
       end
 
       # Get options from the first available storage backend
@@ -105,6 +105,16 @@ class Faulty
         end
       end
 
+      # Reserve a half-open run in the first available storage backend
+      #
+      # @param (see Interface#reserve)
+      # @return (see Interface#reserve)
+      def reserve(circuit, reserved_at, previous_reserved_at)
+        send_chain(:reserve, circuit, reserved_at, previous_reserved_at) do |e|
+          options.notifier.notify(:storage_failure, circuit: circuit, action: :reserve, error: e)
+        end
+      end
+
       # Lock a circuit in all storage backends
       #
       # @param (see Interface#lock)
@@ -189,12 +199,10 @@ class Faulty
       def send_chain(method, *args)
         errors = []
         @storages.each do |s|
-          begin
-            return s.public_send(method, *args)
-          rescue StandardError => e
-            errors << e
-            yield e
-          end
+          return s.public_send(method, *args)
+        rescue StandardError => e
+          errors << e
+          yield e
         end
 
         raise AllFailedError.new("#{self.class}##{method} failed for all storage backends", errors)
@@ -211,11 +219,9 @@ class Faulty
       def send_all(method, *args)
         errors = []
         @storages.each do |s|
-          begin
-            s.public_send(method, *args)
-          rescue StandardError => e
-            errors << e
-          end
+          s.public_send(method, *args)
+        rescue StandardError => e
+          errors << e
         end
 
         if errors.empty?

data/lib/faulty/storage/fault_tolerant_proxy.rb

@@ -9,6 +9,19 @@ class Faulty
     #
     # If the storage backend raises a `StandardError`, it will be captured and
     # sent to the notifier.
+    #
+    # The overall design preference is to keep protected code paths running
+    # when the storage backend is degraded, even when that means losing
+    # circuit-breaker protections that the storage normally provides:
+    # `#status` returns a stub closed status (so `Circuit#run` proceeds),
+    # `#reserve` returns `true` (so half-open test runs proceed), and the
+    # write paths (`#open`, `#reopen`, `#close`, `#entry`) return `false`
+    # to safe-deny the *recorded transition* without failing the in-flight
+    # call. The trade-off is that a correlated outage of the storage
+    # backend and the upstream protected by the circuit will let the fleet
+    # converge on the upstream — but that fleet would converge anyway via
+    # the stub-closed status path, so individual write methods don't make
+    # it worse.
     class FaultTolerantProxy
       extend Forwardable
 
@@ -31,9 +44,9 @@ class Faulty
       # @param storage [Storage::Interface] The storage backend to wrap
       # @param options [Hash] Attributes for {Options}
       # @yield [Options] For setting options in a block
-      def initialize(storage, **options, &block)
+      def initialize(storage, **options, &)
         @storage = storage
-        @options = Options.new(options, &block)
+        @options = Options.new(options, &)
       end
 
       # Wrap a storage backend in a FaultTolerantProxy unless it's already
@@ -41,10 +54,10 @@ class Faulty
       #
       # @param storage [Storage::Interface] The storage to maybe wrap
       # @return [Storage::Interface] The original storage or a {FaultTolerantProxy}
-      def self.wrap(storage, **options, &block)
+      def self.wrap(storage, ...)
         return storage if storage.fault_tolerant?
 
-        new(storage, **options, &block)
+        new(storage, ...)
       end
 
       # @!method lock(circuit, state)
@@ -177,6 +190,22 @@ class Faulty
         stub_status(circuit)
       end
 
+      # Safely reserve execution of a circuit
+      #
+      # Returns `true` on storage error so half-open test runs proceed when
+      # the backend is degraded. See the class-level docs for the gem's
+      # fail-open trade-off.
+      #
+      # @see Interface#reserve
+      # @param (see Interface#reserve)
+      # @return (see Interface#reserve)
+      def reserve(circuit, reserved_at, previous_reserved_at)
+        @storage.reserve(circuit, reserved_at, previous_reserved_at)
+      rescue StandardError => e
+        options.notifier.notify(:storage_failure, circuit: circuit, action: :reserve, error: e)
+        true
+      end
+
       # This cache makes any storage fault tolerant, so this is always `true`
       #
       # @return [true]

data/lib/faulty/storage/interface.rb

@@ -35,7 +35,8 @@ class Faulty
       # long as it can implement the other read methods.
       #
       # @param circuit [Circuit] The circuit that ran
-      # @param time [Integer] The unix timestamp for the run
+      # @param time [Float] The unix timestamp for the run, from
+      #   {Faulty.current_time}
       # @param success [Boolean] True if the run succeeded
       # @param status [Status, nil] The previous status. If given, this method must
       #   return an updated status object from the new entry data.
@@ -58,7 +59,8 @@ class Faulty
       # current time.
       #
       # @param circuit [Circuit] The circuit to open
-      # @param opened_at [Integer] The timestmp the circuit was opened at
+      # @param opened_at [Float] The timestamp the circuit was opened at,
+      #   from {Faulty.current_time}
       # @return [Boolean] True if the circuit transitioned from closed to open
       def open(circuit, opened_at)
         raise NotImplementedError
@@ -75,10 +77,35 @@ class Faulty
       # it may always return true, but that could result in duplicate reopen
       # notifications.
       #
+      # The backend MUST NOT clear `reserved_at` here.
+      #
+      # Preserving the prior cycle's `reserved_at` is load-bearing for
+      # half-open exclusivity. If a late-arriving caller read status while
+      # `reserved_at` was still nil (before the winning process reserved),
+      # its subsequent `reserve(circuit, T, nil)` CAS must fail. Clearing
+      # `reserved_at` in `reopen` would let that stale CAS incorrectly
+      # succeed and produce a duplicate half-open run.
+      #
+      # Beyond exclusivity, the prior reservation expires naturally at
+      # `reserved_at + cool_down`, aligned with the start of the next
+      # half-open window (since `reserved_at <= new_opened_at`). An
+      # explicit reset would be redundant with the cool-down-aligned expiry
+      # that already handles crash recovery.
+      #
+      # This invariant assumes the reservation TTL equals `cool_down`. If
+      # a separate `reservation_ttl` is ever introduced, this method must
+      # be revisited and may need to clear `reserved_at` explicitly.
+      #
       # @param circuit [Circuit] The circuit to reopen
-      # @param opened_at [Integer] The timestmp the circuit was opened at
-      # @param previous_opened_at [Integer] The last known value of opened_at.
-      #   Can be used to comare-and-set.
+      # @param opened_at [Float] The timestamp the circuit was opened at,
+      #   from {Faulty.current_time}
+      # @param previous_opened_at [Float] The last known value of opened_at.
+      #   Can be used to compare-and-set. Always non-nil — `Circuit#failure!`
+      #   only enters the reopen branch when `status.half_open?` is true,
+      #   which requires non-nil `opened_at`. Unlike `previous_reserved_at`
+      #   on {#reserve}, there is no legitimate "no prior value" call path
+      #   to `reopen`, so backends may treat this parameter as required and
+      #   are not expected to handle `nil`.
       # @return [Boolean] True if the opened_at time was updated
       def reopen(circuit, opened_at, previous_opened_at)
         raise NotImplementedError
@@ -90,6 +117,9 @@ class Faulty
       # may be called more than once. If so, this method should return true
       # only once, when the circuit transitions from open to closed.
       #
+      # The backend should reset the reserved_at value to empty when closing
+      # the circuit.
+      #
       # If the backend does not support locking or atomic operations, then
       # it may always return true, but that could result in duplicate close
       # notifications.
@@ -99,6 +129,36 @@ class Faulty
         raise NotImplementedError
       end
 
+      # Reserve an exclusive run for this circuit
+      #
+      # This is used when the circuit is half-open and the test run is being
+      # attempted. We need to make sure only a single run is allowed.
+      #
+      # The backend should store reserved_at and use it to serve future status
+      # requests. When setting reserved_at, the backend should atomically
+      # compare any existing value using previous_reserved_at. This ensures
+      # that mutltiple parallel processes can't reserve the circuit.
+      #
+      # The return value is the caller's signal to proceed with the half-open
+      # test run, not a strict report of whether atomic acquisition succeeded.
+      # Atomic backends should return `true` only when the CAS against
+      # `previous_reserved_at` succeeds. Non-atomic backends, no-op backends
+      # ({Null}), or wrappers that fail open ({FaultTolerantProxy}) may always
+      # return `true`; the caller will proceed at the cost of allowing
+      # duplicate half-open test runs.
+      #
+      # @param circuit [Circuit] The circuit to reserve
+      # @param reserved_at [Float] The timestamp of this reservation, from
+      #   {Faulty.current_time}
+      # @param previous_reserved_at [Float, nil] The last known value of
+      #   reserved_at, or nil for the first reservation in a new open cycle.
+      #   Can be used to compare-and-set.
+      # @return [Boolean] True if the caller may proceed with the half-open
+      #   test run; false if another caller already holds the reservation.
+      def reserve(circuit, reserved_at, previous_reserved_at)
+        raise NotImplementedError
+      end
+
       # Lock the circuit in a given state
       #
       # No concurrency gurantees are provided for locking

data/lib/faulty/storage/memory.rb

@@ -41,11 +41,12 @@ class Faulty
       # The internal object for storing a circuit
       #
       # @private
-      MemoryCircuit = Struct.new(:state, :runs, :opened_at, :lock, :options) do
+      MemoryCircuit = Struct.new(:state, :runs, :opened_at, :reserved_at, :lock, :options) do
         def initialize
           self.state = Concurrent::Atom.new(:closed)
           self.runs = Concurrent::MVar.new([], dup_on_deref: true)
           self.opened_at = Concurrent::Atom.new(nil)
+          self.reserved_at = Concurrent::Atom.new(nil)
           self.lock = nil
         end
 
@@ -61,6 +62,7 @@ class Faulty
               state: state.value,
               lock: lock,
               opened_at: opened_at.value,
+              reserved_at: reserved_at.value,
               options: circuit_options
             )
           end
@@ -71,9 +73,9 @@ class Faulty
 
       # @param options [Hash] Attributes for {Options}
       # @yield [Options] For setting options in a block
-      def initialize(**options, &block)
+      def initialize(**options, &)
         @circuits = Concurrent::Map.new
-        @options = Options.new(options, &block)
+        @options = Options.new(options, &)
       end
 
       # Get the options stored for circuit
@@ -139,7 +141,19 @@ class Faulty
       def close(circuit)
         memory = fetch(circuit)
         memory.runs.modify { |_old| [] }
-        memory.state.compare_and_set(:open, :closed)
+        closed = memory.state.compare_and_set(:open, :closed)
+        memory.reserved_at.reset(nil) if closed
+        closed
+      end
+
+      # Reserve an exclusive run for this circuit
+      #
+      # @see Interface#reserve
+      # @param (see Interface#reserve)
+      # @return (see Interface#reserve)
+      def reserve(circuit, reserved_at, previous_reserved_at)
+        memory = fetch(circuit)
+        memory.reserved_at.compare_and_set(previous_reserved_at, reserved_at)
       end
 
       # Lock a circuit open or closed

data/lib/faulty/storage/null.rb

@@ -46,6 +46,12 @@ class Faulty
         true
       end
 
+      # @param (see Interface#reserve)
+      # @return (see Interface#reserve)
+      def reserve(_circuit, _reserved_at, _previous_reserved_at)
+        true
+      end
+
       # @param (see Interface#lock)
       # @return (see Interface#lock)
       def lock(_circuit, _state)

data/lib/faulty/storage/redis.rb

@@ -80,8 +80,8 @@ class Faulty
 
       # @param options [Hash] Attributes for {Options}
       # @yield [Options] For setting options in a block
-      def initialize(**options, &block)
-        @options = Options.new(options, &block)
+      def initialize(**options, &)
+        @options = Options.new(options, &)
 
         # Ensure JSON is available since we don't explicitly require it
         JSON # rubocop:disable Lint/Void
@@ -174,11 +174,25 @@ class Faulty
         result = watch_exec(key, ['open']) do |m|
           m.set(key, 'closed', ex: ex)
           m.del(entries_key(circuit.name))
+          m.del(reserved_at_key(circuit.name))
         end
 
         result && result[0] == 'OK'
       end
 
+      # Reserve an exclusive run for this circuit
+      #
+      # @see Interface#reserve
+      # @param (see Interface#reserve)
+      # @return (see Interface#reserve)
+      def reserve(circuit, reserved_at, previous_reserved_at)
+        key = reserved_at_key(circuit.name)
+        result = watch_exec(key, [previous_reserved_at&.to_s]) do |m|
+          m.set(key, reserved_at, ex: options.circuit_ttl)
+        end
+        result && result[0] == 'OK'
+      end
+
       # Lock a circuit open or closed
       #
       # The circuit_ttl does not apply to locks
@@ -210,6 +224,7 @@ class Faulty
           r.del(
             entries_key(name),
             opened_at_key(name),
+            reserved_at_key(name),
             lock_key(name),
             options_key(name)
           )
@@ -228,20 +243,11 @@ class Faulty
           futures[:state] = r.get(state_key(circuit.name))
           futures[:lock] = r.get(lock_key(circuit.name))
           futures[:opened_at] = r.get(opened_at_key(circuit.name))
+          futures[:reserved_at] = r.get(reserved_at_key(circuit.name))
           futures[:entries] = r.lrange(entries_key(circuit.name), 0, -1)
         end
 
-        state = futures[:state].value&.to_sym || :closed
-        opened_at = futures[:opened_at].value ? Float(futures[:opened_at].value) : nil
-        opened_at = Faulty.current_time - options.circuit_ttl if state == :open && opened_at.nil?
-
-        Faulty::Status.from_entries(
-          map_entries(futures[:entries].value),
-          state: state,
-          lock: futures[:lock].value&.to_sym,
-          opened_at: opened_at,
-          options: circuit.options
-        )
+        build_status(circuit, futures)
       end
 
       # Get the circuit history up to `max_sample_size`
@@ -285,6 +291,26 @@ class Faulty
 
       private
 
+      # Build a {Status} from the redis values fetched by {#status}
+      def build_status(circuit, futures)
+        state = futures[:state].value&.to_sym || :closed
+        opened_at = parse_float(futures[:opened_at].value)
+        opened_at = Faulty.current_time - options.circuit_ttl if state == :open && opened_at.nil?
+
+        Faulty::Status.from_entries(
+          map_entries(futures[:entries].value),
+          state: state,
+          lock: futures[:lock].value&.to_sym,
+          opened_at: opened_at,
+          reserved_at: parse_float(futures[:reserved_at].value),
+          options: circuit.options
+        )
+      end
+
+      def parse_float(value)
+        value ? Float(value) : nil
+      end
+
       # Generate a key from its parts
       #
       # @return [String] The key
@@ -321,6 +347,11 @@ class Faulty
         ckey(circuit_name, 'opened_at')
       end
 
+      # @return [String] The key for circuit reserved_at
+      def reserved_at_key(circuit_name)
+        ckey(circuit_name, 'reserved_at')
+      end
+
       # Get the current key to add circuit names to
       def list_key
         key('list', current_list_block)
@@ -387,9 +418,9 @@ class Faulty
       #
       # @yield [Redis] Yields the connection to the block
       # @return The value returned from the block
-      def redis(&block)
+      def redis(&)
         if options.client.respond_to?(:with)
-          options.client.with(&block)
+          options.client.with(&)
         else
           yield options.client
         end

data/lib/faulty/version.rb

@@ -3,6 +3,6 @@
 class Faulty
   # The current Faulty version
   def self.version
-    Gem::Version.new('0.11.0')
+    Gem::Version.new('0.13.0')
   end
 end

data/lib/faulty.rb

@@ -41,12 +41,12 @@ class Faulty
     # @param config [Hash] Attributes for {Faulty::Options}
     # @yield [Faulty::Options] For setting options in a block
     # @return [self]
-    def init(default_name = :default, **config, &block)
+    def init(default_name = :default, **config, &)
       raise AlreadyInitializedError if @instances
 
       @default_instance = default_name
       @instances = Concurrent::Map.new
-      register(default_name, new(**config, &block)) unless default_name.nil?
+      register(default_name, new(**config, &)) unless default_name.nil?
       self
     rescue StandardError
       @instances = nil
@@ -110,8 +110,8 @@ class Faulty
     # @param (see Faulty#circuit)
     # @yield (see Faulty#circuit)
     # @return (see Faulty#circuit)
-    def circuit(name, **config, &block)
-      default.circuit(name, **config, &block)
+    def circuit(name, **config, &)
+      default.circuit(name, **config, &)
     end
 
     # Get a list of all circuit names for the default instance
@@ -125,9 +125,11 @@ class Faulty
     # The current time
     #
     # Used by Faulty wherever the current time is needed. Can be overridden
-    # for testing
+    # for testing. Returned as a Float (Unix epoch seconds with sub-second
+    # precision) so it can be stored in numeric Redis fields and compared
+    # against other timestamps without conversion.
     #
-    # @return [Time] The current time
+    # @return [Float] The current time as a Unix timestamp
     def current_time
       Time.now.to_f
     end
@@ -236,8 +238,8 @@ class Faulty
   # @see Options
   # @param options [Hash] Attributes for {Options}
   # @yield [Options] For setting options in a block
-  def initialize(**options, &block)
-    @options = Options.new(options, &block)
+  def initialize(**options, &)
+    @options = Options.new(options, &)
     @registry = CircuitRegistry.new(circuit_options)
   end
 
@@ -252,9 +254,9 @@ class Faulty
   # @param options [Hash] Attributes for {Circuit::Options}
   # @yield [Circuit::Options] For setting options in a block
   # @return [Circuit] The new circuit or the existing circuit if it already exists
-  def circuit(name, **options, &block)
+  def circuit(name, **options, &)
     name = name.to_s
-    @registry.retrieve(name, options, &block)
+    @registry.retrieve(name, options, &)
   end
 
   # Get a list of all circuit names
@@ -285,7 +287,7 @@ class Faulty
   # @return [Hash] The circuit options
   def circuit_options
     @options.to_h
-      .select { |k, _v| %i[cache storage notifier].include?(k) }
+      .slice(:cache, :storage, :notifier)
       .merge(options.circuit_defaults)
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: faulty
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.13.0
 platform: ruby
 authors:
 - Justin Howard
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-04-27 00:00:00.000000000 Z
+date: 2026-05-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -94,7 +94,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0.9'
-description: 
+description:
 email:
 - jmhoward0@gmail.com
 executables: []
@@ -152,8 +152,8 @@ licenses:
 metadata:
   rubygems_mfa_required: 'true'
   changelog_uri: https://github.com/ParentSquare/faulty/blob/master/CHANGELOG.md
-  documentation_uri: https://www.rubydoc.info/gems/faulty/0.11.0
-post_install_message: 
+  documentation_uri: https://www.rubydoc.info/gems/faulty/0.13.0
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -161,15 +161,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.3'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.5
-signing_key: 
+rubygems_version: 3.4.20
+signing_key:
 specification_version: 4
 summary: Fault-tolerance tools for ruby based on circuit-breakers
 test_files: []