safe_memoize 1.4.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e34f9a8aaa025eca2f817b633409686788e99442f10de2fede62f30443f9a0fc
-  data.tar.gz: 21560a08d7060ee77da109da4a91024899674da14ec41e051ff5cb08a5d913f2
+  metadata.gz: 1920c31de4a855b818c5a4f37f35260f38489b7ff6ffe221b43d91e862133bde
+  data.tar.gz: 948979dfc49f4e42b16d21926344869fc06a39da3252ab1033697a5748a7362a
 SHA512:
-  metadata.gz: '0408a2a2322c7861ec0eab88a62e02a15c59c552301e8fe3b7712691d03f385c81a2efbcf8ef06da57b50ae304edc18a7794001c43093b9fc49c180449a68199'
-  data.tar.gz: 421ad6f07416395bef2723fd00a20d7e20c4becd2fec0da9f774ca476d370b1bb459b8d895c2cb7535da9898e27afcfdfcf3d089923ff8aac426dee0c89c5aa8
+  metadata.gz: 415c4095ce702b5823a887858f342fdf5742887394dc2cc113ccf711ef1f5789430e036d69ee3660d663a2153f34375f3622f1ff92d73143072e2376d2ae087b
+  data.tar.gz: 1fed071b0feb6591d4b95c69604f4c14440c88cefbdb13ce9f2e50a2eba5fad4723b28c1584f2cb7aaa33f7ba4e2140b5a16c45b99ba0cd9b13f47b2a16b0d58

data/CHANGELOG.md

@@ -8,6 +8,30 @@ from v1.0.0 onwards. Prior 0.x releases may include breaking changes between min
 
 ## [Unreleased]
 
+## [1.6.0] - 2026-06-02
+
+### Added
+
+- `SafeMemoize::Stores::CircuitBreaker` — a `Stores::Base` wrapper that protects any external store adapter with a three-state circuit breaker (`:closed` → `:open` → `:half_open`). When the wrapped store raises on `read` or `write`, the error is swallowed: reads return `MISS` (triggering the per-instance in-process fallback cache) and writes are no-ops (the return value is unaffected). After a configurable number of consecutive failures (`error_threshold:`, default 5) the circuit opens and all store calls are bypassed until a probe interval elapses (`probe_interval:`, default 30 s), at which point a single probe request is let through; success closes the circuit, failure resets the timer. Any successful call in `:closed` state resets the consecutive error counter, so transient blips do not accumulate toward the threshold.
+  - `state` — returns `:closed`, `:open`, or `:half_open`
+  - `open?` — `true` when the circuit is not fully closed
+  - `error_count` — current consecutive error count
+  - `reset!` — manually close the circuit and clear the counter
+  - `wrapped_store`, `error_threshold`, `probe_interval` — readers
+- `circuit_breaker:` option on `memoize` — syntactic sugar that auto-wraps the configured `store:` adapter in a `CircuitBreaker`. Pass `true` to use defaults, or a `Hash` with `:error_threshold` and/or `:probe_interval` keys to customise. Raises `ArgumentError` if no store is configured. Does not double-wrap a store that is already a `CircuitBreaker`. Accepted by `safe_memoize_options` as a class-wide default.
+
+## [1.5.0] - 2026-06-02
+
+### Added
+
+- `group:` option on `memoize` — assigns a method to a named invalidation group (`memoize :find, group: :database`). Groups are stored on the class and survive re-memoization; a method can belong to at most one group at a time (re-memoizing with a different group moves it). Accepts any non-empty Symbol or String. Can be set as a class default via `safe_memoize_options group: :my_group`.
+- `reset_memo_group(group_name)` instance method — clears all per-instance cached entries for every method in the named group in a single call; each evicted entry fires the `:on_evict` hook. A no-op for unknown groups.
+- `reset_shared_memo_group(group_name)` class method — the shared-cache equivalent of `reset_memo_group`; clears all shared-cache entries for every method in the group that was memoized with `shared: true`.
+- `memo_group_methods(group_name)` instance method — returns the array of method names belonging to the given group on the instance's class (empty array for unknown groups).
+- `memo_groups` instance method — returns all group names registered on the instance's class.
+- `safe_memo_group_methods(group_name)` class method — class-level equivalent of `memo_group_methods`.
+- `safe_memo_groups` class method — class-level equivalent of `memo_groups`.
+
 ## [1.4.0] - 2026-06-02
 
 ### Added

data/README.md

@@ -79,6 +79,8 @@ SafeMemoize uses Ruby's `prepend` mechanism. When you call `memoize :method_name
 - [Plugin / extension architecture — `SafeMemoize::Extension` DSL for adding custom `memoize` options and global lifecycle handlers without monkey-patching](#plugin--extension-architecture)
 - [Per-class default options via `safe_memoize_options` — set TTL, max size, copy-on-read, and other defaults for every `memoize` call on the class without repeating them](#per-class-default-options-safe_memoize_options)
 - [Copy-on-read via `copy_on_read: true` — returns a `dup`/`deep_dup` on every cache read to protect shared cached state from caller mutation](#copy-on-read)
+- [Cache invalidation groups via `group:` — tag related methods with a group name and bust them all with a single `reset_memo_group` call](#cache-invalidation-groups)
+- [Circuit breaker for external stores — `Stores::CircuitBreaker` wraps any store adapter and falls back to the per-instance cache when the store is down; configurable error threshold and probe interval](#circuit-breaker-for-external-stores)
 
 ## Installation
 
@@ -194,6 +196,79 @@ obj.reset_all_memos                             # Clears all memoized values
 
 [↑ Back to features](#features)
 
+### Cache invalidation groups
+
+Tag related methods with `group:` and bust them all at once with a single `reset_memo_group` call:
+
+```ruby
+class RepoService
+  prepend SafeMemoize
+
+  def find_user(id) = db.query("SELECT * FROM users WHERE id=?", id)
+  def find_post(id) = db.query("SELECT * FROM posts WHERE id=?", id)
+  def site_config    = db.query("SELECT * FROM config LIMIT 1")
+
+  memoize :find_user,  group: :database
+  memoize :find_post,  group: :database
+  memoize :site_config                    # no group — unaffected by group reset
+end
+
+svc = RepoService.new
+svc.find_user(1)
+svc.find_post(42)
+svc.site_config
+
+svc.reset_memo_group(:database)          # invalidates find_user and find_post only
+svc.memoized?(:site_config)              # => true — unaffected
+```
+
+For `shared: true` methods, use the class method:
+
+```ruby
+class CatalogService
+  prepend SafeMemoize
+
+  def products = fetch_all_products
+  def categories = fetch_all_categories
+
+  memoize :products,   shared: true, group: :catalog
+  memoize :categories, shared: true, group: :catalog
+end
+
+CatalogService.reset_shared_memo_group(:catalog)    # clears shared cache for both methods
+```
+
+#### Introspection
+
+```ruby
+svc.memo_groups                              # => [:database]  — all groups on the class
+svc.memo_group_methods(:database)            # => [:find_user, :find_post]
+CatalogService.safe_memo_groups              # => [:catalog]
+CatalogService.safe_memo_group_methods(:catalog)  # => [:products, :categories]
+```
+
+#### Class-wide group default
+
+Use `safe_memoize_options` to assign all subsequently memoized methods to the same group:
+
+```ruby
+class ApiClient
+  prepend SafeMemoize
+  safe_memoize_options group: :api
+
+  def users  = http.get("/users")
+  def orders = http.get("/orders")
+
+  memoize :users               # group: :api
+  memoize :orders              # group: :api
+  memoize :health, group: nil  # override — no group
+end
+```
+
+A method belongs to at most one group at a time; re-memoizing with a different `group:` moves it.
+
+[↑ Back to features](#features)
+
 ### Lifecycle hooks
 
 Register callbacks that fire when cached entries are evicted or expire.
@@ -1374,6 +1449,90 @@ end
 
 [↑ Back to features](#features)
 
+## Circuit breaker for external stores
+
+`SafeMemoize::Stores::CircuitBreaker` wraps any `Stores::Base` adapter and silently falls back to the per-instance in-process cache when the external store is unavailable, rather than propagating exceptions to callers.
+
+### How it works
+
+The breaker moves through three states:
+
+| State | Behaviour |
+|---|---|
+| `:closed` | Normal — every call passes through to the wrapped store; consecutive errors are counted |
+| `:open` | Tripped — reads return `MISS` (triggering the per-instance fallback), writes are no-ops; no calls reach the store until the probe interval elapses |
+| `:half_open` | Probe — calls are let through; the first success closes the circuit; any failure re-opens it and resets the timer |
+
+Any successful call in `:closed` state resets the consecutive error counter, so transient blips do not accumulate toward the threshold.
+
+### Usage
+
+**Direct wrapping:**
+
+```ruby
+redis = SafeMemoize::Stores::CircuitBreaker.new(
+  MyRedisStore.new,
+  error_threshold: 5,   # trip after 5 consecutive failures (default)
+  probe_interval:  30   # wait 30 s before probing (default)
+)
+
+class CatalogService
+  prepend SafeMemoize
+
+  def products = fetch_from_redis
+  memoize :products, store: redis
+end
+```
+
+**Via the `circuit_breaker:` option** (auto-wraps the configured store):
+
+```ruby
+class CatalogService
+  prepend SafeMemoize
+
+  def products = fetch_from_redis
+  memoize :products, store: MyRedisStore.new, circuit_breaker: true
+
+  def orders = fetch_orders
+  memoize :orders,
+    store: MyRedisStore.new,
+    circuit_breaker: { error_threshold: 3, probe_interval: 60 }
+end
+```
+
+When the store raises, `products` falls back to the per-instance in-memory hash — callers see no exceptions and computation still runs once per instance until the circuit closes.
+
+### Introspection and manual control
+
+```ruby
+cb = SafeMemoize::Stores::CircuitBreaker.new(store)
+
+cb.state           # => :closed | :open | :half_open
+cb.open?           # => false
+cb.error_count     # => 0
+cb.error_threshold # => 5
+cb.probe_interval  # => 30.0
+cb.wrapped_store   # => the inner adapter
+cb.reset!          # manually close the circuit and clear error count
+```
+
+### Class-wide default
+
+```ruby
+class ApiService
+  prepend SafeMemoize
+  safe_memoize_options circuit_breaker: { error_threshold: 3, probe_interval: 15 }
+
+  def users  = http.get("/users")
+  def orders = http.get("/orders")
+
+  memoize :users,  store: redis
+  memoize :orders, store: redis   # both get the circuit breaker
+end
+```
+
+[↑ Back to features](#features)
+
 ## Per-class default options (`safe_memoize_options`)
 
 `safe_memoize_options` sets option defaults for every `memoize` call on the class, eliminating repetition when many methods share the same TTL, LRU cap, or other option. Per-call options still take precedence; class defaults take precedence over global `SafeMemoize.configure` defaults.
@@ -1611,6 +1770,8 @@ Anything **not** listed here — internal modules, private methods, `@__safe_mem
 | `shared_cache:` | `String \| nil` | `nil` | Name of a globally-registered shared store; incompatible with `shared:`, `store:`, `fiber_local:`, `ractor_safe:`, and `max_size:` |
 | `cache_bust:` | `Proc \| Symbol \| nil` | `nil` | Version-token callable; invoked on the instance at each lookup; token is folded into the key; incompatible with `key:` |
 | `copy_on_read:` | `Boolean` | `false` | Return a `dup`/`deep_dup` of the cached value on every read; protects shared state from caller mutation; nil and frozen values pass through; incompatible with `ractor_safe:` |
+| `group:` | `Symbol \| String \| nil` | `nil` | Assigns the method to a named invalidation group; call `reset_memo_group` / `reset_shared_memo_group` to bust all methods in the group at once; a method belongs to at most one group |
+| `circuit_breaker:` | `true \| Hash \| nil` | `nil` | Wraps the configured `store:` in a `Stores::CircuitBreaker`; `true` uses defaults (`error_threshold: 5`, `probe_interval: 30`); pass a Hash to customise; requires a store to be set; does not double-wrap |
 | *(extension options)* | any | — | Unknown kwargs are validated against registered extensions; raise `ArgumentError` if unclaimed |
 
 ### `memoize_all` options (class method)
@@ -1628,7 +1789,7 @@ All `memoize` option keys above, plus:
 
 | Option key | Type | Default | Notes |
 |---|---|---|---|
-| any `memoize` key except mode-switches | — | — | Accepts `ttl:`, `max_size:`, `ttl_refresh:`, `if:`, `unless:`, `key:`, `cache_bust:`, `copy_on_read:`, `namespace:`, `store:`; raises `ArgumentError` for `shared:`, `fiber_local:`, `ractor_safe:`, `shared_cache:` |
+| any `memoize` key except mode-switches | — | — | Accepts `ttl:`, `max_size:`, `ttl_refresh:`, `if:`, `unless:`, `key:`, `cache_bust:`, `copy_on_read:`, `namespace:`, `store:`, `group:`, `circuit_breaker:`; raises `ArgumentError` for `shared:`, `fiber_local:`, `ractor_safe:`, `shared_cache:` |
 
 ### Instance methods (public)
 
@@ -1650,10 +1811,18 @@ All `memoize` option keys above, plus:
 | Method | Returns |
 |---|---|
 | `reset_memo(method_name, *args, **kwargs)` | `nil` |
+| `reset_memo_group(group_name)` | `nil` |
 | `reset_all_memos` | `nil` |
 | `memo_touch(method_name, *args, ttl: nil, **kwargs)` | `Boolean` |
 | `memo_refresh(method_name, *args, **kwargs)` | cached value |
 
+**Group introspection**
+
+| Method | Returns |
+|---|---|
+| `memo_groups` | `Array<Symbol>` — all group names on the class |
+| `memo_group_methods(group_name)` | `Array<Symbol>` — methods in the group |
+
 **Warm-up and persistence**
 
 | Method | Returns |
@@ -1705,11 +1874,19 @@ All `memoize` option keys above, plus:
 |---|---|
 | `reset_shared_memo(method_name, *args, **kwargs)` | `nil` |
 | `reset_all_shared_memos` | `nil` |
+| `reset_shared_memo_group(group_name)` | `nil` |
 | `shared_memoized?(method_name, *args, **kwargs)` | `Boolean` |
 | `shared_memo_count(method_name = nil)` | `Integer` |
 | `shared_memo_age(method_name, *args, **kwargs)` | `Numeric \| nil` |
 | `shared_memo_stale?(method_name, *args, **kwargs)` | `Boolean` |
 
+### Group class methods (available on any class that uses `group:`)
+
+| Method | Returns |
+|---|---|
+| `safe_memo_groups` | `Array<Symbol>` — all group names on the class |
+| `safe_memo_group_methods(group_name)` | `Array<Symbol>` — methods belonging to the group |
+
 **Ractor-safe shared cache (added when any method uses `ractor_safe: true`)**
 
 | Method | Returns |

data/ROADMAP.md

@@ -4,26 +4,6 @@ This document tracks the planned evolution of SafeMemoize through v1.0.0 and bey
 
 ---
 
-## v1.5.0 — Cache Invalidation
-
-*Goal: group-level cache invalidation so related methods can be busted in one operation.*
-
-| Feature | Description | Status |
-|---|---|---|
-| Memoization groups | `memoize :find, group: :database` then `reset_memo_group(:database)` to invalidate all methods tagged with the same group at once; groups can span multiple methods on the same class | Planned |
-
----
-
-## v1.6.0 — Resilience
-
-*Goal: make external-store memoization resilient to infrastructure failures.*
-
-| Feature | Description | Status |
-|---|---|---|
-| Circuit breaker for external stores | When a `store:` adapter raises on `read` or `write`, automatically fall back to the per-instance in-process hash rather than propagating the exception; configurable error threshold and recovery probe interval | Planned |
-
----
-
 ## v1.7.0 — Advanced Store Features
 
 *Goal: multi-process performance patterns for high-traffic deployments.*

data/lib/safe_memoize/class_methods.rb

@@ -64,6 +64,16 @@ module SafeMemoize
     #   itself. Prevents callers from mutating shared cached state. Frozen and +nil+
     #   values are returned as-is. Incompatible with +ractor_safe:+ (ractor values are
     #   always frozen; use that guarantee instead).
+    # @param group [Symbol, String, nil] assigns the method to a named invalidation
+    #   group. Call {PublicMethods#reset_memo_group} on an instance (or
+    #   {.reset_shared_memo_group} for shared-mode methods) to bust every method in the
+    #   group at once. A method may belong to at most one group; re-memoizing with a
+    #   different group moves it. Must be a non-empty Symbol or String.
+    # @param circuit_breaker [Boolean, Hash, nil] wraps the configured +store:+ adapter
+    #   in a {Stores::CircuitBreaker}. Pass +true+ to use defaults (+error_threshold: 5+,
+    #   +probe_interval: 30+), or a +Hash+ with +:error_threshold+ and/or +:probe_interval+
+    #   keys to customise. Requires a +store:+ to be set (per-method, class-level, or
+    #   global default); raises +ArgumentError+ otherwise.
     # @return [void]
     # @raise [ArgumentError] if the method does not exist, or option values are invalid
     #
@@ -84,7 +94,7 @@ module SafeMemoize
     # @example With a custom store
     #   STORE = SafeMemoize::Stores::Memory.new
     #   memoize :fetch, store: STORE, ttl: 300
-    def memoize(method_name, ttl: UNSET, max_size: UNSET, ttl_refresh: UNSET, if: UNSET, unless: UNSET, shared: UNSET, key: UNSET, store: UNSET, fiber_local: UNSET, ractor_safe: UNSET, namespace: UNSET, shared_cache: UNSET, cache_bust: UNSET, copy_on_read: UNSET, **extension_options)
+    def memoize(method_name, ttl: UNSET, max_size: UNSET, ttl_refresh: UNSET, if: UNSET, unless: UNSET, shared: UNSET, key: UNSET, store: UNSET, fiber_local: UNSET, ractor_safe: UNSET, namespace: UNSET, shared_cache: UNSET, cache_bust: UNSET, copy_on_read: UNSET, group: UNSET, circuit_breaker: UNSET, **extension_options)
       method_name = method_name.to_sym
 
       unless method_defined?(method_name) || private_method_defined?(method_name) || protected_method_defined?(method_name)
@@ -126,6 +136,8 @@ module SafeMemoize
         copy_on_read = cls_defaults[:copy_on_read] if copy_on_read.equal?(UNSET) && cls_defaults.key?(:copy_on_read)
         namespace = cls_defaults[:namespace] if namespace.equal?(UNSET) && cls_defaults.key?(:namespace)
         store = cls_defaults[:store] if store.equal?(UNSET) && cls_defaults.key?(:store)
+        group = cls_defaults[:group] if group.equal?(UNSET) && cls_defaults.key?(:group)
+        circuit_breaker = cls_defaults[:circuit_breaker] if circuit_breaker.equal?(UNSET) && cls_defaults.key?(:circuit_breaker)
       end
 
       # Normalize remaining UNSET to original per-call defaults
@@ -141,6 +153,8 @@ module SafeMemoize
       shared_cache = nil if shared_cache.equal?(UNSET)
       cache_bust = nil if cache_bust.equal?(UNSET)
       copy_on_read = false if copy_on_read.equal?(UNSET)
+      group = nil if group.equal?(UNSET)
+      circuit_breaker = nil if circuit_breaker.equal?(UNSET)
       cond_if = nil if cond_if.equal?(UNSET)
       cond_unless = nil if cond_unless.equal?(UNSET)
 
@@ -213,6 +227,15 @@ module SafeMemoize
         __safe_memo_method_namespaces__[method_name] = namespace
       end
 
+      if group
+        unless group.is_a?(Symbol) || group.is_a?(String)
+          raise ArgumentError, "group: must be a Symbol or String (got #{group.class})"
+        end
+        group = group.to_sym
+        raise ArgumentError, "group: must not be empty" if group.empty?
+        __safe_memo_register_group__(method_name, group)
+      end
+
       if shared_cache
         raise ArgumentError, "shared_cache: must be a String (got #{shared_cache.class})" unless shared_cache.is_a?(String)
         raise ArgumentError, "shared_cache: must not be empty" if shared_cache.empty?
@@ -244,6 +267,19 @@ module SafeMemoize
         end
       end
 
+      if circuit_breaker
+        unless circuit_breaker == true || circuit_breaker.is_a?(Hash)
+          raise ArgumentError, "circuit_breaker: must be true or a Hash of options (got #{circuit_breaker.class})"
+        end
+        unless effective_store
+          raise ArgumentError, "circuit_breaker: requires a store: to be configured (no store is set for :#{method_name})"
+        end
+        unless effective_store.is_a?(Stores::CircuitBreaker)
+          cb_opts = circuit_breaker.is_a?(Hash) ? circuit_breaker : {}
+          effective_store = Stores::CircuitBreaker.new(effective_store, **cb_opts)
+        end
+      end
+
       __safe_memo_class_key_generators__[method_name] = key if key
       __safe_memo_class_cache_bust_generators__[method_name] = cache_bust if cache_bust
 
@@ -763,6 +799,35 @@ module SafeMemoize
       end
     end
 
+    # Clears all shared-cache entries for every method in the given group.
+    #
+    # Only affects methods memoized with +shared: true+. For per-instance cache
+    # invalidation use {PublicMethods#reset_memo_group} on the instance.
+    #
+    # @param group_name [Symbol, String]
+    # @return [void]
+    def reset_shared_memo_group(group_name)
+      group_name = group_name.to_sym
+      (__safe_memo_groups__[group_name] || []).each { |m| reset_shared_memo(m) }
+    end
+
+    # Returns the method names belonging to the given invalidation group, or an
+    # empty array when the group is unknown.
+    #
+    # @param group_name [Symbol, String]
+    # @return [Array<Symbol>]
+    def safe_memo_group_methods(group_name)
+      group_name = group_name.to_sym
+      (__safe_memo_groups__[group_name] || []).dup
+    end
+
+    # Returns all group names registered on this class.
+    #
+    # @return [Array<Symbol>]
+    def safe_memo_groups
+      __safe_memo_groups__.keys
+    end
+
     private
 
     def __safe_memo_shared_cache__
@@ -793,6 +858,17 @@ module SafeMemoize
       @__safe_memoize_defaults__
     end
 
+    def __safe_memo_groups__
+      @__safe_memo_groups__ ||= {}
+    end
+
+    def __safe_memo_register_group__(method_name, group)
+      groups = __safe_memo_groups__
+      # Remove method from any prior group it belonged to
+      groups.each_value { |methods| methods.delete(method_name) }
+      (groups[group] ||= []) << method_name
+    end
+
     # Resolves the effective first-element key sym for a given bare method name,
     # applying the active namespace. Used by class-level cache operations where
     # instance methods (compute_cache_key) are unavailable.

data/lib/safe_memoize/public_methods.rb

@@ -359,6 +359,37 @@ module SafeMemoize
       end
     end
 
+    # Clears all per-instance cached entries for every method belonging to the
+    # given invalidation group (declared via +memoize :method, group: :name+).
+    #
+    # A no-op when the group is unknown or has no members. Each evicted entry
+    # fires the +:on_evict+ hook. For shared-mode methods use the class-level
+    # {ClassMethods.reset_shared_memo_group} instead.
+    #
+    # @param group_name [Symbol, String]
+    # @return [void]
+    def reset_memo_group(group_name)
+      group_name = group_name.to_sym
+      (self.class.send(:__safe_memo_groups__)[group_name] || []).each { |m| reset_memo(m) }
+    end
+
+    # Returns the method names belonging to the given invalidation group on
+    # this instance's class, or an empty array when the group is unknown.
+    #
+    # @param group_name [Symbol, String]
+    # @return [Array<Symbol>]
+    def memo_group_methods(group_name)
+      group_name = group_name.to_sym
+      (self.class.send(:__safe_memo_groups__)[group_name] || []).dup
+    end
+
+    # Returns all invalidation group names registered on this instance's class.
+    #
+    # @return [Array<Symbol>]
+    def memo_groups
+      self.class.send(:__safe_memo_groups__).keys
+    end
+
     # Clears all cached entries for every method on this instance.
     # Each evicted entry fires the +:on_evict+ hook.
     #

data/lib/safe_memoize/stores/circuit_breaker.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module Stores
+    # Wraps any {Base} store adapter with a circuit breaker that silently falls
+    # back to the per-instance in-process cache when the external store is
+    # unavailable, rather than propagating exceptions to callers.
+    #
+    # === States
+    #
+    # * +:closed+    — normal; every call goes through to the wrapped store;
+    #                  consecutive errors are counted
+    # * +:open+      — tripped; reads return {MISS} and writes are no-ops so the
+    #                  memoize wrapper falls back to the per-instance hash; no
+    #                  calls reach the wrapped store until the probe interval elapses
+    # * +:half_open+ — probe period (probe interval elapsed); calls are let
+    #                  through to the wrapped store; the first success closes the
+    #                  circuit, any failure re-opens it and resets the timer
+    #
+    # Any successful call while the circuit is +:closed+ resets the consecutive
+    # error counter, so transient blips do not accumulate toward the threshold.
+    #
+    # @example Wrap a custom Redis store
+    #   store = SafeMemoize::Stores::CircuitBreaker.new(
+    #     MyRedisStore.new,
+    #     error_threshold: 5,
+    #     probe_interval:  30
+    #   )
+    #   memoize :fetch, store: store
+    #
+    # @example Via the circuit_breaker: option (auto-wraps the configured store)
+    #   memoize :fetch, store: MyRedisStore.new, circuit_breaker: true
+    #   memoize :fetch, store: MyRedisStore.new,
+    #                   circuit_breaker: { error_threshold: 3, probe_interval: 60 }
+    class CircuitBreaker < Base
+      DEFAULT_ERROR_THRESHOLD = 5
+      DEFAULT_PROBE_INTERVAL = 30.0
+
+      # @return [Stores::Base] the wrapped inner store
+      attr_reader :wrapped_store
+      # @return [Integer] number of consecutive errors that trip the circuit
+      attr_reader :error_threshold
+      # @return [Float] seconds after tripping before a probe is attempted
+      attr_reader :probe_interval
+
+      # @param store [Stores::Base] the backing store to protect
+      # @param error_threshold [Integer] consecutive errors that trip the circuit (default 5)
+      # @param probe_interval [Numeric] seconds to wait before probing (default 30)
+      # @raise [ArgumentError] if +store+ is not a {Stores::Base} instance, or
+      #   if threshold / interval are invalid
+      def initialize(store, error_threshold: DEFAULT_ERROR_THRESHOLD, probe_interval: DEFAULT_PROBE_INTERVAL)
+        unless store.is_a?(Base)
+          raise ArgumentError, "CircuitBreaker requires a Stores::Base instance (got #{store.class})"
+        end
+
+        @wrapped_store = store
+        @error_threshold = Integer(error_threshold)
+        @probe_interval = Float(probe_interval)
+
+        raise ArgumentError, "error_threshold must be positive" unless @error_threshold > 0
+        raise ArgumentError, "probe_interval must be positive" unless @probe_interval > 0
+
+        @mutex = Mutex.new
+        @error_count = 0
+        @opened_at = nil
+      end
+
+      # Read from the wrapped store, returning {MISS} on error or when the
+      # circuit is open instead of raising.
+      def read(key)
+        st = current_state
+        return MISS if st == :open
+
+        result = @wrapped_store.read(key)
+        record_success(st)
+        result
+      rescue
+        record_failure
+        MISS
+      end
+
+      # Write to the wrapped store, silently swallowing errors so the caller's
+      # return value is unaffected. A no-op when the circuit is open.
+      def write(key, value, expires_in: nil)
+        st = current_state
+        return if st == :open
+
+        @wrapped_store.write(key, value, expires_in: expires_in)
+        record_success(st)
+      rescue
+        record_failure
+      end
+
+      # Delete from the wrapped store. A no-op when the circuit is open.
+      def delete(key)
+        return if current_state == :open
+
+        @wrapped_store.delete(key)
+      rescue
+        record_failure
+      end
+
+      # Clear the wrapped store. Errors are recorded but not re-raised.
+      def clear
+        @wrapped_store.clear
+      rescue
+        record_failure
+      end
+
+      # Returns live keys from the wrapped store, or an empty array when the
+      # circuit is open or the store raises.
+      def keys
+        return [] if current_state == :open
+
+        @wrapped_store.keys
+      rescue
+        record_failure
+        []
+      end
+
+      # Returns the current circuit state: +:closed+, +:open+, or +:half_open+.
+      # @return [Symbol]
+      def state
+        current_state
+      end
+
+      # Returns +true+ when the circuit is not fully closed (i.e. open or half-open).
+      # @return [Boolean]
+      def open?
+        current_state != :closed
+      end
+
+      # Returns the current consecutive error count.
+      # @return [Integer]
+      def error_count
+        @mutex.synchronize { @error_count }
+      end
+
+      # Manually resets the circuit to +:closed+, clearing the error counter.
+      # @return [void]
+      def reset!
+        @mutex.synchronize do
+          @error_count = 0
+          @opened_at = nil
+        end
+      end
+
+      private
+
+      def current_state
+        @mutex.synchronize do
+          next :closed if @opened_at.nil?
+
+          elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - @opened_at
+          (elapsed >= @probe_interval) ? :half_open : :open
+        end
+      end
+
+      def record_success(prior_state)
+        return unless prior_state == :half_open || @error_count > 0
+
+        @mutex.synchronize do
+          @error_count = 0
+          @opened_at = nil
+        end
+      end
+
+      def record_failure
+        @mutex.synchronize do
+          @error_count += 1
+          if @error_count >= @error_threshold || !@opened_at.nil?
+            @opened_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/safe_memoize/version.rb

@@ -2,5 +2,5 @@
 
 module SafeMemoize
   # The current gem version string.
-  VERSION = "1.4.0"
+  VERSION = "1.6.0"
 end

data/lib/safe_memoize.rb

@@ -5,6 +5,7 @@ require_relative "safe_memoize/configuration"
 require_relative "safe_memoize/extension"
 require_relative "safe_memoize/stores/base"
 require_relative "safe_memoize/stores/memory"
+require_relative "safe_memoize/stores/circuit_breaker"
 require_relative "safe_memoize/adapters/statsd"
 require_relative "safe_memoize/adapters/opentelemetry"
 require_relative "safe_memoize/adapters/concurrent_ruby"

data/sig/safe_memoize.rbs

@@ -17,6 +17,7 @@ module SafeMemoize
   @__safe_memo_shared_cache__: Hash[memo_key, memo_record]?
   @__safe_memo_shared_mutex__: Mutex?
   @__safe_memo_shared_lru_order__: Hash[Symbol, Hash[memo_key, true]]?
+  @__safe_memo_groups__: Hash[Symbol, Array[Symbol]]?
 
   UNSET: untyped
   SHARED_CACHE_REGISTRY: Hash[String, Stores::Base]
@@ -65,7 +66,7 @@ module SafeMemoize
   end
 
   module ClassMethods
-    def memoize: (Symbol | String method_name, ?ttl: Numeric?, ?max_size: Integer?, ?ttl_refresh: bool, ?if: (^(untyped result) -> boolish)?, ?unless: (^(untyped result) -> boolish)?, ?shared: bool, ?key: (^(*untyped args, **untyped kwargs) -> untyped)?, ?store: Stores::Base?, ?fiber_local: bool, ?ractor_safe: bool, ?namespace: String?, ?shared_cache: String?, ?cache_bust: (^() -> untyped) | Symbol | nil, ?copy_on_read: bool, **untyped extension_options) -> void
+    def memoize: (Symbol | String method_name, ?ttl: Numeric?, ?max_size: Integer?, ?ttl_refresh: bool, ?if: (^(untyped result) -> boolish)?, ?unless: (^(untyped result) -> boolish)?, ?shared: bool, ?key: (^(*untyped args, **untyped kwargs) -> untyped)?, ?store: Stores::Base?, ?fiber_local: bool, ?ractor_safe: bool, ?namespace: String?, ?shared_cache: String?, ?cache_bust: (^() -> untyped) | Symbol | nil, ?copy_on_read: bool, ?group: Symbol | String | nil, ?circuit_breaker: bool | Hash[Symbol, untyped] | nil, **untyped extension_options) -> void
     def safe_memoize_store: () -> Stores::Base?
     def safe_memoize_store=: (Stores::Base?) -> Stores::Base?
     def safe_memoize_namespace: () -> String?
@@ -78,6 +79,9 @@ module SafeMemoize
     def shared_memo_count: (?Symbol | String method_name) -> Integer
     def shared_memo_age: (Symbol | String method_name, *untyped args, **untyped kwargs) -> Float?
     def shared_memo_stale?: (Symbol | String method_name, *untyped args, **untyped kwargs) -> bool
+    def reset_shared_memo_group: (Symbol | String group_name) -> void
+    def safe_memo_group_methods: (Symbol | String group_name) -> Array[Symbol]
+    def safe_memo_groups: () -> Array[Symbol]
 
     private
 
@@ -88,6 +92,8 @@ module SafeMemoize
     def __safe_memo_method_namespaces__: () -> Hash[Symbol, String]
     def __safe_memo_class_cache_bust_generators__: () -> Hash[Symbol, Proc | Symbol]
     def __safe_memoize_defaults__: () -> Hash[Symbol, untyped]?
+    def __safe_memo_groups__: () -> Hash[Symbol, Array[Symbol]]
+    def __safe_memo_register_group__: (Symbol method_name, Symbol group) -> void
     def memoized_method_visibility: (Symbol method_name) -> Symbol
   end
 
@@ -114,6 +120,9 @@ module SafeMemoize
     def memo_age: (Symbol | String method_name, *untyped args, **untyped kwargs) -> Float?
     def memo_stale?: (Symbol | String method_name, *untyped args, **untyped kwargs) -> bool
     def reset_memo: (Symbol | String method_name, *untyped args, **untyped kwargs) -> void
+    def reset_memo_group: (Symbol | String group_name) -> void
+    def memo_group_methods: (Symbol | String group_name) -> Array[Symbol]
+    def memo_groups: () -> Array[Symbol]
     def reset_all_memos: () -> void
     def memo_inspect: (Symbol | String method_name, *untyped args, **untyped kwargs) -> { cached: bool, value: untyped, hits: Integer, misses: Integer, ttl_remaining: Float?, age: Float?, custom_key: untyped, lru_position: Integer? }?
   end
@@ -291,6 +300,32 @@ module SafeMemoize
 
       def expired?: ({ expires_at: Float?, value: untyped, cached_at: Float }) -> bool
     end
+
+    class CircuitBreaker < Base
+      DEFAULT_ERROR_THRESHOLD: Integer
+      DEFAULT_PROBE_INTERVAL: Float
+
+      attr_reader wrapped_store: Base
+      attr_reader error_threshold: Integer
+      attr_reader probe_interval: Float
+
+      def initialize: (Base store, ?error_threshold: Integer, ?probe_interval: Numeric) -> void
+      def read: (untyped key) -> untyped
+      def write: (untyped key, untyped value, ?expires_in: Numeric?) -> void
+      def delete: (untyped key) -> void
+      def clear: () -> void
+      def keys: () -> Array[untyped]
+      def state: () -> Symbol
+      def open?: () -> bool
+      def error_count: () -> Integer
+      def reset!: () -> void
+
+      private
+
+      def current_state: () -> Symbol
+      def record_success: (Symbol prior_state) -> void
+      def record_failure: () -> void
+    end
   end
 
   module Adapters

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: safe_memoize
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.6.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -77,6 +77,7 @@ files:
 - lib/safe_memoize/rails/request_scoped.rb
 - lib/safe_memoize/release_tooling.rb
 - lib/safe_memoize/stores/base.rb
+- lib/safe_memoize/stores/circuit_breaker.rb
 - lib/safe_memoize/stores/memory.rb
 - lib/safe_memoize/stores/rails_cache.rb
 - lib/safe_memoize/stores/redis.rb