resilient_call 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1b6710bbb609417fc8131a025b0a6064bac8bbd1e71d55e87b8a506d90709375
-  data.tar.gz: 106f9defb53a23687ca85e7186e90cdf2732bf5cffeab86472be6521d2478b56
+  metadata.gz: 241b883a4916ae4e5847d47485005391f3ce1366fca15830d4cef1efe34c55ba
+  data.tar.gz: de5aa926f966d68cd92ca89a7e5fac3da22b2c4776fdc4c738f2a147dd6976dc
 SHA512:
-  metadata.gz: 61edc4419731654f9b6c0d19f3cbae025766fb2048d6f17e0fad9d177c729ce8580dcdb4f5b5ea6f9eef25209a335fa97c15c5f400c4e95a8fa347435b4fd381
-  data.tar.gz: a63fad56c64a7c4e93ba76837140dea471f09a2e0368fde195db068934155cc1f8020607d5bb20e0285a6a2ddeed1b4db67980ad0900445a3a925c5cbc4a13fc
+  metadata.gz: e2e7e07d4044973eb64aab0d9d49d1341807b5f828f2e5b02df653b3061785e5b1d15c532d0c190cd0d21a2fb65ad37a530ddad51d4db3f2cdab21a70994198c
+  data.tar.gz: 16922ff209347a4608988154489c8d26182dd5dbcc9a87fdcb2bf56dd4c8b91ddfe801420149c6188f7534608f4044ef299fb95b6544b9cd49a03cf2cd4e14a1

data/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-07-10
+
+### Added
+
+- Pluggable circuit storage via `ResilientCall::Storage::Base` — lets the circuit
+  breaker share state across processes instead of a per-process in-memory Hash.
+- `ResilientCall::Storage::Memory`, the default backend, extracted from the
+  `Circuit`/`CircuitBreaker` internals with no behavior change.
+- `circuit_storage` global config option to swap the storage backend.
+
+### Changed
+
+- `Circuit` now delegates state persistence to the configured storage instead of
+  holding `@state`/`@failure_count` as instance variables.
+
 ## [0.1.0] - 2026-06-12
 
 ### Added
@@ -32,5 +47,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `ResilientCall::RetriesExhaustedError` (the latter preserves the native
   `#cause` chain).
 
-[Unreleased]: https://github.com/VorynLabs/resilient_call/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/VorynLabs/resilient_call/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/VorynLabs/resilient_call/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/VorynLabs/resilient_call/releases/tag/v0.1.0

data/README.md

@@ -242,12 +242,16 @@ end
 
 ## Roadmap
 
-| Version | Feature                                                          |
+Current release: **v0.1.0** — see the [CHANGELOG](CHANGELOG.md) for what shipped.
+
+The versions below are planned, not yet released:
+
+| Version | Planned feature                                                 |
 | ------- | --------------------------------------------------------------- |
 | `v0.2`  | Pluggable storage for circuit state (Redis for multi-process)   |
-| `v0.3`  | `ActiveSupport::Notifications` instrumentation and metrics      |
-| `v0.4`  | Mountable Rack dashboard for live circuit state                 |
-| `v0.5`  | Native timeout integrated into the retry loop                   |
+| `v0.3`  | Native timeout integrated into the retry loop                   |
+| `v0.4`  | `ActiveSupport::Notifications` instrumentation and metrics      |
+| `v0.5`  | Mountable Rack dashboard for live circuit state                 |
 | `v1.0`  | Stable API, full documentation, published benchmarks            |
 
 ## Contributing

data/lib/resilient_call/circuit.rb

@@ -1,8 +1,15 @@
 # frozen_string_literal: true
 
+require_relative "storage/memory"
+
 module ResilientCall
   # Holds the state of a single named circuit and manages its transitions.
-  # Thread-safe: every public method runs under an internal Mutex.
+  # The mutable state lives in the injected `storage` (memory by default, Redis
+  # for multi-process setups); this class owns only the transition rules.
+  #
+  # Thread-safe within a process: every read-modify-write runs under an internal
+  # Mutex, so concurrent calls on the same instance stay consistent. Across
+  # processes, consistency is bounded by the storage backend (see Storage::Redis).
   #
   #   closed --(threshold failures)--> open --(reset_timeout elapsed)--> half_open
   #     ^                                                                     |
@@ -11,86 +18,71 @@ module ResilientCall
   class Circuit
     attr_reader :name, :threshold, :reset_timeout
 
-    def initialize(name, threshold: 5, reset_timeout: 60)
+    def initialize(name, threshold: 5, reset_timeout: 60, storage: nil)
       @name          = name
       @threshold     = threshold
       @reset_timeout = reset_timeout
-      @state         = :closed
-      @failure_count = 0
-      @opened_at     = nil
+      @storage       = storage || Storage::Memory.new
       @last_failure  = nil
       @mutex         = Mutex.new
     end
 
     def state
-      @mutex.synchronize { @state }
+      read_field(:status)
     end
 
     def failure_count
-      @mutex.synchronize { @failure_count }
+      read_field(:failure_count)
     end
 
+    # The full Exception object captured most recently *in this process*. State
+    # shared through Redis only carries its message/class, so a fresh process
+    # reading an open circuit sees nil here — use CircuitOpenError for details.
     def last_failure
       @mutex.synchronize { @last_failure }
     end
 
     def opened_at
-      @mutex.synchronize { @opened_at }
+      read_field(:opened_at)
     end
 
     # Whether a request may pass right now. An :open circuit whose reset_timeout
     # has elapsed transitions to :half_open and lets a single probe through.
     def allow_request?
       @mutex.synchronize do
-        case @state
-        when :closed
-          true
-        when :half_open
-          true
-        when :open
-          if Time.now - @opened_at >= @reset_timeout
-            @state = :half_open
-            true
-          else
-            false
-          end
+        state = read_state
+
+        case state[:status]
+        when :closed, :half_open then true
+        when :open               then attempt_half_open(state)
         end
       end
     end
 
     def record_success!
-      @mutex.synchronize do
-        case @state
-        when :half_open
-          @state         = :closed
-          @failure_count = 0
-        when :closed
-          @failure_count = 0
+      transition do |state|
+        case state[:status]
+        when :half_open then state.merge!(status: :closed, failure_count: 0)
+        when :closed    then state[:failure_count] = 0
         end
       end
     end
 
     def record_failure!(error)
-      @mutex.synchronize do
-        @failure_count += 1
-        @last_failure   = error
-
-        if @state == :half_open
-          @state     = :open
-          @opened_at = Time.now
-        elsif @state == :closed && @failure_count >= @threshold
-          @state     = :open
-          @opened_at = Time.now
-        end
+      transition do |state|
+        @last_failure = error
+        state[:failure_count]       += 1
+        state[:last_failure_message] = error.message
+        state[:last_failure_class]   = error.class.name
+
+        trip_open!(state) if should_open?(state)
       end
     end
 
     def reset!
       @mutex.synchronize do
-        @state         = :closed
-        @failure_count = 0
-        @opened_at     = nil
-        @last_failure  = nil
+        @last_failure = nil
+        @storage.reset(@name)
       end
     end
 
@@ -102,5 +94,60 @@ module ResilientCall
         @reset_timeout = reset_timeout unless reset_timeout.nil?
       end
     end
+
+    private
+
+    def read_field(key)
+      @mutex.synchronize { read_state[key] }
+    end
+
+    # Reads the persisted state, yields it for mutation, then writes it back —
+    # the read-modify-write cycle shared by every state-changing method.
+    def transition
+      @mutex.synchronize do
+        state = read_state
+        yield state
+        write_state(state)
+      end
+    end
+
+    # Trips an elapsed :open circuit into :half_open so one probe can pass.
+    def attempt_half_open(state)
+      return false unless Time.now - state[:opened_at] >= @reset_timeout
+
+      state[:status] = :half_open
+      write_state(state)
+      true
+    end
+
+    def should_open?(state)
+      state[:status] == :half_open ||
+        (state[:status] == :closed && state[:failure_count] >= @threshold)
+    end
+
+    def trip_open!(state)
+      state[:status]    = :open
+      state[:opened_at] = Time.now
+    end
+
+    # Current persisted state, or a fresh :closed state when the circuit has no
+    # record yet. Callers mutate the returned Hash and persist via write_state.
+    def read_state
+      @storage.read(@name) || default_state
+    end
+
+    def write_state(state)
+      @storage.write(@name, state)
+    end
+
+    def default_state
+      {
+        status:               :closed,
+        failure_count:        0,
+        opened_at:            nil,
+        last_failure_message: nil,
+        last_failure_class:   nil
+      }
+    end
   end
 end

data/lib/resilient_call/circuit_breaker.rb

@@ -7,10 +7,12 @@ module ResilientCall
     @mutex    = Mutex.new
 
     # Returns the circuit for `name`, creating it on first access. Created with
-    # the scope-3 defaults (threshold: 5, reset_timeout: 60); scope 4 will inject
-    # configured values through the entry point.
+    # default thresholds and the globally configured storage; the entry point
+    # injects the configured thresholds through Circuit#update_config.
     def self.[](name)
-      @mutex.synchronize { @registry[name] ||= Circuit.new(name) }
+      @mutex.synchronize do
+        @registry[name] ||= Circuit.new(name, storage: ResilientCall.configuration.circuit_storage)
+      end
     end
 
     def self.reset_all!

data/lib/resilient_call/configuration.rb

@@ -1,14 +1,21 @@
 # frozen_string_literal: true
 
+require_relative "storage/memory"
+
 module ResilientCall
   # Holds the global defaults and the registry of named profiles.
   class Configuration
     # retry
     attr_accessor :retries, :wait, :base_wait, :max_wait, :jitter, :on
+
     # circuit breaker
     attr_accessor :threshold, :reset_timeout
+
     # callbacks
     attr_accessor :on_retry, :on_failure, :on_success
+    # circuit state backend (Storage::Memory by default, Storage::Redis for
+    # multi-process setups); shared by every named circuit
+    attr_accessor :circuit_storage
     # named profiles registry
     attr_accessor :profiles
 
@@ -19,14 +26,14 @@ module ResilientCall
       @max_wait      = 30.0
       @jitter        = true
       @on            = [StandardError]
-
       @threshold     = 5
       @reset_timeout = 60
-
       @on_retry      = nil
       @on_failure    = nil
       @on_success    = nil
 
+      @circuit_storage = Storage::Memory.new
+
       @profiles      = {}
     end
 

data/lib/resilient_call/retrier.rb

@@ -30,44 +30,62 @@ module ResilientCall
       @on_success = opts[:on_success]
     end
 
-    # Runs the block. Returns its result, or raises RetriesExhaustedError once
-    # every attempt has been consumed.
     def call
       attempt = 0
 
       begin
         attempt += 1
         result = yield
-        @on_success&.call(result, attempt)
+        on_success&.call(result, attempt)
         result
-      rescue *@on => err
-        if attempt <= @retries
-          @on_retry&.call(attempt, err)
-          sleep(wait_time(attempt))
-          retry
-        end
+      rescue *on => err
+        raise_exhausted(err, attempt) unless retryable?(attempt)
 
-        @on_failure&.call(err)
-        # Raised inside the rescue so Ruby populates #cause with `err`.
-        raise RetriesExhaustedError.new(attempts: attempt)
+        on_retry&.call(attempt, err)
+        sleep(wait_time(attempt))
+        retry
       end
     end
 
     private
 
-    # 1-based attempt number. Applies jitter before capping at max_wait.
+    attr_reader :retries, :wait, :base_wait, :max_wait, :jitter,
+                :on, :on_retry, :on_failure, :on_success
+
+    # True while retries remain. `attempt` is the 1-based number that just ran.
+    def retryable?(attempt)
+      attempt <= retries
+    end
+
+    def raise_exhausted(err, attempt)
+      on_failure&.call(err)
+      # Raised inside the rescue so Ruby populates #cause with `err`.
+      raise RetriesExhaustedError.new(attempts: attempt)
+    end
+
     def wait_time(attempt)
-      raw = case @wait
-            when :exponential then @base_wait * (2**attempt)
-            when :linear      then @base_wait * attempt
-            when :fixed       then @base_wait
-            when Proc         then @wait.call(attempt)
-            else
-              raise ArgumentError, "unknown wait strategy: #{@wait.inspect}"
-            end
+      [with_jitter(base_delay(attempt)), max_wait].min
+    end
+
+    def base_delay(attempt)
+      case wait
+      when :exponential
+        base_wait * (2**attempt)
+      when :linear
+        base_wait * attempt
+      when :fixed
+        base_wait
+      when Proc
+        wait.call(attempt)
+      else
+        raise ArgumentError, "unknown wait strategy: #{wait.inspect}"
+      end
+    end
+
+    def with_jitter(delay)
+      return delay unless jitter
 
-      raw += rand(0..@base_wait * 0.3) if @jitter
-      [raw, @max_wait].min
+      delay + rand(0..base_wait * 0.3)
     end
   end
 end

data/lib/resilient_call/storage/base.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module ResilientCall
+  module Storage
+    # Contract every storage backend must implement. A storage persists the
+    # mutable state of each named circuit as a serializable Hash:
+    #
+    #   { status:, failure_count:, opened_at:, last_failure_message:, last_failure_class: }
+    #
+    # Backends decide *where* that state lives (process memory, Redis, ...); the
+    # Circuit stays agnostic and only reads/writes through this interface.
+    class Base
+      def read(circuit_name)
+        raise NotImplementedError, "#{self.class}#read"
+      end
+
+      def write(circuit_name, state)
+        raise NotImplementedError, "#{self.class}#write"
+      end
+
+      def reset(circuit_name)
+        raise NotImplementedError, "#{self.class}#reset"
+      end
+
+      def reset_all
+        raise NotImplementedError, "#{self.class}#reset_all"
+      end
+    end
+  end
+end

data/lib/resilient_call/storage/memory.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module ResilientCall
+  module Storage
+    # Default storage: keeps circuit state in a Hash in the current process.
+    # Thread-safe on its own operations via an internal Mutex. State is not
+    # shared across processes — use Storage::Redis for multi-worker setups.
+    class Memory < Base
+      def initialize
+        @data  = {}
+        @mutex = Mutex.new
+      end
+
+      def read(circuit_name)
+        @mutex.synchronize { @data[circuit_name] }
+      end
+
+      def write(circuit_name, state)
+        @mutex.synchronize { @data[circuit_name] = state }
+      end
+
+      def reset(circuit_name)
+        @mutex.synchronize { @data.delete(circuit_name) }
+      end
+
+      def reset_all
+        @mutex.synchronize { @data.clear }
+      end
+    end
+  end
+end

data/lib/resilient_call/storage/redis.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "base"
+
+module ResilientCall
+  module Storage
+    # Shares circuit state across processes through Redis. The Redis client is
+    # injected, so this class has no hard dependency on the `redis` gem itself —
+    # any object answering to get/set/del/keys works (including fakes in tests).
+    #
+    # Concurrency note: read + write are separate round-trips, so two processes
+    # can race on the failure counter. The worst case is an occasional missed
+    # increment, never state corruption. Atomic Lua updates are a v0.3 concern.
+    class Redis < Base
+      KEY_PREFIX = "resilient_call:circuit:"
+
+      def initialize(redis_client)
+        @redis = redis_client
+      end
+
+      def read(circuit_name)
+        raw = @redis.get(key_for(circuit_name))
+
+        raw ? deserialize(raw) : nil
+      end
+
+      def write(circuit_name, state)
+        @redis.set(key_for(circuit_name), serialize(state))
+      end
+
+      def reset(circuit_name)
+        @redis.del(key_for(circuit_name))
+      end
+
+      def reset_all
+        keys = @redis.keys("#{KEY_PREFIX}*")
+        @redis.del(*keys) unless keys.empty?
+      end
+
+      private
+
+      def key_for(circuit_name)
+        "#{KEY_PREFIX}#{circuit_name}"
+      end
+
+      def serialize(state)
+        JSON.generate(state.merge(opened_at: state[:opened_at]&.to_i))
+      end
+
+      def deserialize(raw)
+        parsed = JSON.parse(raw, symbolize_names: true)
+        parsed[:status]    = parsed[:status].to_sym if parsed[:status]
+        parsed[:opened_at] = Time.at(parsed[:opened_at]) if parsed[:opened_at]
+        parsed
+      end
+    end
+  end
+end

data/lib/resilient_call/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ResilientCall
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/resilient_call.rb

@@ -2,6 +2,8 @@
 
 require_relative "resilient_call/version"
 require_relative "resilient_call/errors"
+require_relative "resilient_call/storage/base"
+require_relative "resilient_call/storage/memory"
 require_relative "resilient_call/configuration"
 require_relative "resilient_call/circuit"
 require_relative "resilient_call/circuit_breaker"
@@ -9,6 +11,12 @@ require_relative "resilient_call/retrier"
 require_relative "resilient_call/mixin"
 
 module ResilientCall
+  # Redis storage is optional — loaded only when explicitly referenced, so the
+  # gem stays usable in plain Ruby without pulling in a Redis client.
+  module Storage
+    autoload :Redis, "resilient_call/storage/redis"
+  end
+
   class << self
     # Runs `block` with retry and, when `circuit:` is given, circuit-breaker
     # protection. Option precedence: inline > profile > global config > defaults.
@@ -16,11 +24,7 @@ module ResilientCall
       options = resolve_options(options)
       circuit = circuit_for(options)
 
-      if circuit && !circuit.allow_request?
-        return options[:fallback].call if options[:fallback]
-
-        raise circuit_open_error(circuit, options)
-      end
+      return reject_open_circuit(circuit, options) if circuit_blocking?(circuit)
 
       run_with_retry(options, circuit, &block)
     end
@@ -67,6 +71,19 @@ module ResilientCall
       end
     end
 
+    # True when a circuit exists and is currently rejecting requests.
+    def circuit_blocking?(circuit)
+      circuit && !circuit.allow_request?
+    end
+
+    # Handles a request blocked by an open circuit: runs the fallback if one
+    # was given, otherwise raises CircuitOpenError.
+    def reject_open_circuit(circuit, options)
+      return options[:fallback].call if options[:fallback]
+
+      raise circuit_open_error(circuit, options)
+    end
+
     def circuit_open_error(circuit, options)
       CircuitOpenError.new(
         circuit_name: options[:circuit],

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: resilient_call
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Wesley Sena
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-06-12 00:00:00.000000000 Z
+date: 2026-07-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -38,6 +38,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: mock_redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.30'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.30'
 description: Wrapper for any Ruby block with configurable retries, jitter, named circuit
   breaker, declarative fallback, and service class mixin support.
 email:
@@ -56,6 +84,9 @@ files:
 - lib/resilient_call/errors.rb
 - lib/resilient_call/mixin.rb
 - lib/resilient_call/retrier.rb
+- lib/resilient_call/storage/base.rb
+- lib/resilient_call/storage/memory.rb
+- lib/resilient_call/storage/redis.rb
 - lib/resilient_call/version.rb
 homepage: https://github.com/VorynLabs/resilient_call
 licenses: