faulty 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70d795aa07a3ebdb6ab1d59f03b0a93d6c65c6c83c88c4700eb0e553fdf210c6
-  data.tar.gz: 25df4a11f04f0a865bf9ea1236d0ad75f4b10b5d810966894c57911126b9dfde
+  metadata.gz: 3642cb65b01572d880aec16ece320bed43b9c12ae13a2dce602c1bf2a5a250c3
+  data.tar.gz: 7116acd4f458c31a738d0f90a7ac0bc0f37e392e75105f19e7b9648af9d7b4c7
 SHA512:
-  metadata.gz: d778e63ab973c4e31c64f72af87e53d99ce744f39e28edf698d7cf32a53da77c65beccd645e6447ca5360bd821169b2700e16224127a2c287cb9c353d33f133d
-  data.tar.gz: 1bb9248883024814297780af0f2417cae07466f246714b238bf2da18f29eb0bea9c6d0f56985b7e72cc7a8b6824756da5945bd7e931addea766d1d09ae597eb3
+  metadata.gz: b7078729322061727335102869126e65348f270a71a41b624a2722d62c416672f6b39778338faf570ceac39b7355ebfbc8bf4aff7e866123aada12ba507172ad
+  data.tar.gz: 117eae9db002823c62280a7236f5a1969409b6baeffa9c51b0430205f23df5b0238890602cae2217fb19da6e22ea8ebbabf622c750bbb732cd95d0a2caa85554

data/CHANGELOG.md

@@ -9,6 +9,40 @@ 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
 ---------------------
 
@@ -349,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

@@ -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.

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.
@@ -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/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/circuit_proxy.rb

@@ -52,6 +52,7 @@ class Faulty
         open
         reopen
         close
+        reserve
         lock
         unlock
         reset

data/lib/faulty/storage/fallback_chain.rb

@@ -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)

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
 
@@ -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
@@ -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

@@ -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)

data/lib/faulty/version.rb

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

data/lib/faulty.rb

@@ -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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: faulty
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.13.0
 platform: ruby
 authors:
 - Justin Howard
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-13 00:00:00.000000000 Z
+date: 2026-05-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -152,7 +152,7 @@ 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.12.0
+  documentation_uri: https://www.rubydoc.info/gems/faulty/0.13.0
 post_install_message:
 rdoc_options: []
 require_paths: