safe_memoize 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 62f1dae5d57d99d59fe20d981bca17d04bd1ff5b9dd09175770a51bf3d49dd03
-  data.tar.gz: fade31de5124ed4b4f5d88f8bd62aaf750ec03cb22bdf97889fed2283ad3a58d
+  metadata.gz: 0b47b6031a8f395991376eec0407b93d1cf02caecad23f4d77e4d68234ef87b5
+  data.tar.gz: 7542678912a0a39425a75e3addfc718f2abb35068e28e0cdc0444c294dd4c4c1
 SHA512:
-  metadata.gz: e742795adaef41bc07e32d1ffb0a1f78335eae46daca57dca3b6b27cf4fc1eb6a58e1636e05d21814336ab3e54468b6ffbe0a4ea52f017c00b0df1a70b98eaeb
-  data.tar.gz: 92b1cb813ed3c54e18408fed0f79f2e9f4983672660f6ee1cf6c0ec9628577fbebf1055797e9d9a4c53ca5b293427c66d9c946a770a443e77b98c77c0937d244
+  metadata.gz: a304040bf86b1bc359c91f3d687a9f45e020bdaddded53b82a87e473553491aa9daba1ac45f8abadffb8ede8af270479f73762ab47357486aef9b46043afacde
+  data.tar.gz: 79d6a552f98f9f2ef1482832c211cc7b0a58f6481c989320c19db63b870a1723b482304955a133c661a0082a07c17de539258a9f869da0b5cbd0aaa2acacd96a

data/CHANGELOG.md

@@ -8,6 +8,17 @@ from v1.0.0 onwards. Prior 0.x releases may include breaking changes between min
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-05-22
+
+### Added
+
+- `ActiveSupport::Notifications` integration — opt-in via `SafeMemoize.configure { |c| c.active_support_notifications = true }`; emits `cache_hit.safe_memoize`, `cache_miss.safe_memoize`, `cache_evict.safe_memoize`, `cache_expire.safe_memoize`, and `cache_store.safe_memoize` events; each payload includes `:method`, `:key`, and `:class`; zero overhead when ActiveSupport is not loaded
+- `SafeMemoize::Adapters::StatsD` — thin optional adapter that routes lifecycle events to any StatsD client via `SafeMemoize.configure { |c| c.statsd_client = my_client }`; emits `safe_memoize.hit`, `safe_memoize.miss`, `safe_memoize.evict`, `safe_memoize.expire`, and `safe_memoize.store` with `method:` and `class:` tags; client errors are rescued and warned rather than raised
+- Formal benchmark suite (`benchmarks/benchmark.rb`) — six scenarios covering zero-arg cache hit/miss, with-argument hit, fast vs locked path, shared vs instance cache, and concurrent throughput under 8-thread contention; optional comparisons against `memery` and `memo_wise`; run with `bundle exec ruby benchmarks/benchmark.rb`
+- Concurrency stress test suite (`spec/concurrency_spec.rb`) — 18 barrier-synchronized examples hammering the fast path, locked path, and shared cache under 30 concurrent threads; covers exactly-once computation, LRU size invariant, hook count integrity, metric accuracy, TTL pruning, and deadlock detection (10-second timeout per run)
+- `SafeMemoize::Adapters::OpenTelemetry` — optional adapter that wraps each cache-miss computation in an OpenTelemetry span; configure via `SafeMemoize.configure { |c| c.opentelemetry_tracer = OpenTelemetry.tracer_provider.tracer("safe_memoize") }`; span name is `"safe_memoize.compute"` with attributes `safe_memoize.method`, `safe_memoize.class`, and `safe_memoize.cache_hit`; falls back to untraced execution when the tracer is absent or does not respond to `in_span`
+- `SafeMemoize::Rails` — opt-in request-scope helpers (`require "safe_memoize/rails"`): `SafeMemoize::Rails::RequestScoped` concern auto-registers `after_action :reset_all_memos` in controllers and exposes `reset_request_memos` elsewhere; `SafeMemoize::Rails::Middleware` Rack middleware resets all thread-tracked instances (`SafeMemoize::Rails.track(self)`) at the end of each request even on error
+
 ## [0.8.0] - 2026-05-21
 
 ### Added

data/README.md

@@ -14,7 +14,7 @@ Beyond the basics, SafeMemoize ships with TTL expiration (including sliding wind
 
 ## The Problem
 
-Ruby's common memoization pattern breaks with falsy values:
+Ruby's common memoization pattern breaks with falsy values: 
 
 ```ruby
 def user
@@ -51,6 +51,22 @@ SafeMemoize uses Ruby's `prepend` mechanism. When you call `memoize :method_name
 - [Bulk memoization via `memoize_all` (public, protected, and private)](#bulk-memoization)
 - [Custom cache key generation per method](#custom-cache-keys)
 - [TTL introspection via `memo_ttl_remaining`](#cache-inspection)
+- [Deep single-entry inspection via `memo_inspect`](#cache-inspection)
+- [`ArgumentError` at definition time when memoizing an undefined method](#basic-memoization)
+- [Hook error isolation — hook exceptions never propagate to callers](#lifecycle-hooks)
+- [Deprecation infrastructure for gem authors](#deprecation)
+- [Optional `ActiveSupport::Notifications` integration for Rails observability](#activesupportnotifications)
+- [Optional StatsD adapter for metrics pipelines](#statsd)
+- [Optional OpenTelemetry adapter for distributed tracing](#opentelemetry)
+- [Rails request-scope helpers for controllers and service objects](#rails-request-scope)
+- [Batch cache warm-up via `memo_preload`](#cache-warm-up-and-persistence)
+- [`on_memo_store` hook fires on every cache write](#lifecycle-hooks)
+- [Global default TTL and max size via `SafeMemoize.configure`](#global-configuration)
+- [`memo_touch` resets the expiry clock without recomputing](#ttl-expiration)
+- [`memo_refresh` force-recomputes and re-caches in one call](#cache-inspection)
+- [`memo_age` and `memo_stale?` for TTL introspection](#cache-inspection)
+- [Class-level `key:` option for shared cache key generation](#custom-cache-keys)
+- [`shared_memo_age` and `shared_memo_stale?` for shared cache TTL inspection](#shared-cache)
 
 ## Installation
 
@@ -88,6 +104,10 @@ class UserService
 end
 ```
 
+Calling `memoize` on a method name that does not exist raises `ArgumentError` immediately at class definition time rather than at the first runtime call.
+
+[↑ Back to features](#features)
+
 ### With arguments
 
 Results are cached per unique argument combination:
@@ -109,6 +129,10 @@ calc.compute(1, 2)  # returns cached result
 calc.compute(3, 4)  # computes and caches (different args)
 ```
 
+Argument arrays, hashes, and strings are deep-frozen into an independent copy when the cache key is built, so mutating arguments after a call cannot corrupt or miss a cached entry.
+
+[↑ Back to features](#features)
+
 ### Nil and false safety
 
 ```ruby
@@ -123,6 +147,8 @@ class Config
 end
 ```
 
+[↑ Back to features](#features)
+
 ### Works with private methods
 
 ```ruby
@@ -142,6 +168,8 @@ class TokenProvider
 end
 ```
 
+[↑ Back to features](#features)
+
 ### Cache reset
 
 ```ruby
@@ -152,6 +180,8 @@ obj.reset_memo(:search, "ruby", page: 2)       # Clears one positional/keyword c
 obj.reset_all_memos                             # Clears all memoized values
 ```
 
+[↑ Back to features](#features)
+
 ### Lifecycle hooks
 
 Register callbacks that fire when cached entries are evicted or expire.
@@ -188,6 +218,14 @@ obj.on_memo_expire do |cache_key, record|
 end
 ```
 
+**`on_memo_store`** fires whenever a value is written to the cache — on a miss, via `warm_memo`, or via `load_memo`:
+
+```ruby
+obj.on_memo_store do |cache_key, record|
+  Rails.logger.debug("Stored #{cache_key[0]}: #{record[:value].inspect}")
+end
+```
+
 Multiple hooks of the same type can be registered and all will fire. Remove them with `clear_memo_hooks`:
 
 ```ruby
@@ -200,6 +238,28 @@ obj.clear_memo_hooks              # Clears all hooks
 
 Hooks are per-instance and do not affect other objects of the same class.
 
+#### Hook error isolation
+
+Exceptions raised inside a hook never propagate to the caller. By default a warning is emitted to stderr:
+
+```
+[SafeMemoize] Hook error in on_miss: undefined method `log' for nil
+```
+
+Configure a custom handler via `SafeMemoize.configure`:
+
+```ruby
+SafeMemoize.configure do |c|
+  c.on_hook_error = ->(error, hook_type, cache_key) {
+    MyErrorTracker.capture(error, context: { hook: hook_type, key: cache_key })
+  }
+end
+```
+
+Set `c.on_hook_error = :raise` to re-raise exceptions instead of swallowing them.
+
+[↑ Back to features](#features)
+
 ### TTL expiration
 
 ```ruby
@@ -215,6 +275,23 @@ end
 
 With a TTL, cached values expire automatically after the given number of seconds. The next call recomputes and refreshes the cache.
 
+Use `memo_touch` to reset the expiry clock on a cached entry without recomputing its value:
+
+```ruby
+obj.memo_touch(:current_quote)               # Resets TTL to the original duration
+obj.memo_touch(:current_quote, ttl: 120)     # Resets TTL to a new duration
+# => true on success, false if the entry is not cached or already expired
+```
+
+Use `memo_refresh` to force-recompute a cached entry immediately and store the new value:
+
+```ruby
+obj.memo_refresh(:current_quote)             # Recomputes and re-caches
+obj.memo_refresh(:find, 42)                  # Recomputes for one argument combination
+```
+
+[↑ Back to features](#features)
+
 ### Sliding window TTL
 
 Add `ttl_refresh: true` to reset the expiry clock on every cache hit, so the entry only expires after a full TTL of inactivity:
@@ -232,6 +309,8 @@ end
 
 Without `ttl_refresh:`, the entry expires 300 seconds after it was first cached. With it, the clock resets on every read — the entry is evicted only if the method goes 300 seconds without being called. `ttl_refresh: true` requires `ttl:` to be set and works with both per-instance and `shared: true` memoization.
 
+[↑ Back to features](#features)
+
 ### LRU cache size limit
 
 Pass `max_size:` to cap how many entries a method can hold. When the limit is reached the least-recently-used entry is evicted to make room:
@@ -265,6 +344,8 @@ memoize :find, max_size: 50, ttl: 300
 
 The `on_evict` hook fires for LRU-evicted entries the same way it does for manual `reset_memo` calls.
 
+[↑ Back to features](#features)
+
 ### Conditional caching
 
 Use `if:` to cache a result only when the predicate returns truthy, or `unless:` to skip caching when it returns truthy. Calls that don't satisfy the condition recompute every time until they do.
@@ -299,8 +380,25 @@ Both options accept any callable and compose with `ttl:` and `max_size:`:
 memoize :find, if: ->(result) { !result.nil? }, ttl: 60, max_size: 500
 ```
 
+[↑ Back to features](#features)
+
 ### Cache warm-up and persistence
 
+#### Batch warm-up via `memo_preload`
+
+Use `memo_preload` to warm multiple argument combinations in one call. It calls the memoized method for each argument set, caches all results, and returns them in input order:
+
+```ruby
+obj.memo_preload(:find, [1], [2], [3])
+# => [<User id=1>, <User id=2>, <User id=3>]
+```
+
+Each element is a separate argument list passed to the method, so keyword arguments work too:
+
+```ruby
+obj.memo_preload(:search, ["ruby"], ["rails"], ["rspec"])
+```
+
 #### Warming individual entries
 
 Use `warm_memo` to pre-populate a cache entry without calling the method. The block provides the value:
@@ -348,6 +446,8 @@ obj.load_memo(Marshal.load(raw)) if raw
 
 Loaded entries have no TTL — they persist until explicitly reset. Expired entries are excluded from `dump_memo` output, so snapshots never contain stale data.
 
+[↑ Back to features](#features)
+
 ### Shared cache
 
 Pass `shared: true` to store results on the class instead of per-instance. All instances share one cache, so the method is computed only once regardless of how many objects exist.
@@ -382,6 +482,8 @@ ConfigService.shared_memoized?(:database_url)         # => true
 ConfigService.shared_memoized?(:find, user_id)        # Checks one argument combination
 ConfigService.shared_memo_count                       # Total shared cached entries
 ConfigService.shared_memo_count(:find)                # Entries for one method
+ConfigService.shared_memo_age(:feature_flags)         # => 42.1  (seconds since cached)
+ConfigService.shared_memo_stale?(:feature_flags)      # => false (TTL not yet elapsed)
 ```
 
 `shared: true` supports `ttl:`, `ttl_refresh:`, `if:`, `unless:`, and `max_size:` options.
@@ -394,6 +496,8 @@ memoize :find, shared: true, max_size: 500
 
 Hooks (`on_memo_hit`, `on_memo_miss`, `on_memo_expire`, `on_memo_evict`) fire on the calling instance as usual.
 
+[↑ Back to features](#features)
+
 ### Bulk memoization
 
 Use `memoize_all` to memoize every public method defined on the class in one call:
@@ -432,6 +536,14 @@ Use `except:` to skip specific methods:
 memoize_all except: [:version, :name]
 ```
 
+Use `only:` to explicitly list the methods to memoize and skip all others:
+
+```ruby
+memoize_all only: [:database_url, :redis_url]
+```
+
+`only:` and `except:` are mutually exclusive — passing both raises `ArgumentError`.
+
 By default only public methods defined directly on the class are memoized. Use `include_protected:` or `include_private:` to opt those visibilities in:
 
 ```ruby
@@ -442,9 +554,11 @@ memoize_all include_protected: true, include_private: true
 
 Inherited methods are never affected regardless of visibility.
 
+[↑ Back to features](#features)
+
 ### Custom cache keys
 
-By default the cache key is derived from the method name and all arguments. Use `memoize_with_custom_key` on an instance to control exactly what makes two calls equivalent:
+By default the cache key is derived from the method name and all arguments. Use the `key:` option on `memoize` to set a class-level key generator that applies to every instance:
 
 ```ruby
 class ReportService
@@ -453,9 +567,18 @@ class ReportService
   def generate(user_id, options)
     build_report(user_id, options)
   end
-  memoize :generate
+  memoize :generate, key: ->(user_id, _options) { user_id }
 end
 
+# All instances share the same key logic — calls with the same user_id share one cache entry
+svc = ReportService.new
+svc.generate(42, {format: :pdf})  # computes and caches under key 42
+svc.generate(42, {format: :csv})  # cache hit — same key
+```
+
+For per-instance key overrides, use `memoize_with_custom_key` on an instance (takes priority over the class-level `key:` option):
+
+```ruby
 svc = ReportService.new
 
 # Cache only by user_id — ignore the options hash entirely
@@ -480,6 +603,8 @@ svc.clear_custom_keys(:generate)  # Remove generator for one method
 svc.clear_custom_keys             # Remove all custom key generators
 ```
 
+[↑ Back to features](#features)
+
 ### Cache inspection
 
 ```ruby
@@ -500,8 +625,32 @@ obj.memo_values(:search)                  # Cached signatures and values for one
 obj.memo_ttl_remaining(:current_quote)           # => 47.231 (seconds until expiry)
 obj.memo_ttl_remaining(:current_user)            # => nil    (no TTL set)
 obj.memo_ttl_remaining(:find, 42)                # => 0      (not cached or already expired)
+
+obj.memo_age(:current_quote)                     # => 12.8   (seconds since cached; nil if not cached)
+obj.memo_stale?(:current_quote)                  # => false  (cached but TTL not yet elapsed)
+obj.memo_stale?(:current_user)                   # => false  (no TTL — never stale)
 ```
 
+`memo_inspect` returns all metadata for one cached entry in a single mutex-held read:
+
+```ruby
+obj.memo_inspect(:find, 42)
+# => {
+#      cached: true,
+#      value: <result>,
+#      hits: 5,
+#      misses: 1,
+#      ttl_remaining: 47.2,
+#      age: 12.8,
+#      custom_key: nil,
+#      lru_position: 1
+#    }
+```
+
+Returns `nil` when the entry is not cached.
+
+[↑ Back to features](#features)
+
 ### Cache metrics
 
 Each instance tracks hits, misses, and computation time automatically.
@@ -521,18 +670,237 @@ obj.cache_stats
 #      ]
 #    }
 
-obj.cache_stats_for(:find)   # Stats scoped to one method
-obj.cache_hit_rate           # => 84.0  (percentage)
-obj.cache_miss_rate          # => 16.0  (percentage)
-obj.cache_metrics_reset      # Clears all collected metrics
+obj.cache_stats_for(:find)        # Stats scoped to one method
+obj.cache_hit_rate                # => 84.0  (percentage)
+obj.cache_miss_rate               # => 16.0  (percentage)
+obj.cache_metrics_reset           # Clears all collected metrics
+obj.cache_metrics_reset(:find)    # Clears metrics for one method only
 ```
 
 Metrics are per-instance and reset independently from the cache itself — clearing metrics does not evict cached values.
 
+[↑ Back to features](#features)
+
+### Global configuration
+
+Use `SafeMemoize.configure` to set defaults that apply to all subsequently memoized methods. Per-call options always take precedence over global defaults.
+
+```ruby
+SafeMemoize.configure do |c|
+  c.default_ttl      = 300   # All memoized methods expire after 5 minutes unless overridden
+  c.default_max_size = 100   # All memoized methods cap at 100 entries unless overridden
+end
+```
+
+Both settings apply at definition time — methods already memoized before `configure` is called are not affected. Reset all defaults back to `nil` with:
+
+```ruby
+SafeMemoize.reset_configuration!
+```
+
+The configure block also accepts `on_hook_error`, `on_deprecation`, `active_support_notifications`, and `statsd_client` (covered in [Hook error isolation](#hook-error-isolation), [Deprecation](#deprecation), [ActiveSupport::Notifications](#activesupportnotifications), and [StatsD](#statsd)).
+
+[↑ Back to features](#features)
+
+### ActiveSupport::Notifications
+
+Enable opt-in integration with `ActiveSupport::Notifications` for Rails and other ActiveSupport-based stacks:
+
+```ruby
+SafeMemoize.configure do |c|
+  c.active_support_notifications = true
+end
+```
+
+Once enabled, SafeMemoize emits the following events through the standard notification pipeline:
+
+| Event | Fires when |
+|---|---|
+| `cache_hit.safe_memoize` | A cached value is returned |
+| `cache_miss.safe_memoize` | The method is called and no cached value exists |
+| `cache_store.safe_memoize` | A value is written to the cache (miss, `warm_memo`, or `load_memo`) |
+| `cache_evict.safe_memoize` | An entry is removed via `reset_memo`, `reset_all_memos`, or LRU eviction |
+| `cache_expire.safe_memoize` | An expired TTL entry is pruned |
+
+Each event payload includes:
+
+```ruby
+{
+  method: :method_name,   # Symbol
+  key:    cache_key,      # Array — the full cache key
+  class:  "ClassName"     # String — the host class name
+}
+```
+
+Subscribe to all SafeMemoize events via the standard ActiveSupport pattern:
+
+```ruby
+ActiveSupport::Notifications.subscribe(/\.safe_memoize$/) do |event|
+  Rails.logger.debug("[cache] #{event.name} #{event.payload[:class]}##{event.payload[:method]}")
+end
+```
+
+The integration is a no-op when ActiveSupport is not loaded — there is no overhead for non-Rails projects. `active_support_notifications` defaults to `false`.
+
+[↑ Back to features](#features)
+
+### StatsD
+
+Route cache lifecycle events to any StatsD-compatible client via `SafeMemoize::Adapters::StatsD`. Assign the client once in your initializer:
+
+```ruby
+SafeMemoize.configure do |c|
+  c.statsd_client = Datadog::Statsd.new("localhost", 8125)
+end
+```
+
+SafeMemoize then calls `client.increment(metric, tags: [...])` on every cache event:
+
+| Metric | Fires when |
+|---|---|
+| `safe_memoize.hit` | A cached value is returned |
+| `safe_memoize.miss` | The method is called and no cached value exists |
+| `safe_memoize.store` | A value is written to the cache (miss, `warm_memo`, or `load_memo`) |
+| `safe_memoize.evict` | An entry is removed via `reset_memo`, `reset_all_memos`, or LRU eviction |
+| `safe_memoize.expire` | An expired TTL entry is pruned |
+
+Each call includes two tags: `method:method_name` and `class:ClassName`. The client must respond to `increment(metric, tags: [...])` — the interface used by `dogstatsd-ruby`, `statsd-instrument`, and most modern StatsD clients.
+
+If the client raises, the error is rescued and a warning is emitted to stderr rather than propagated to the caller. `statsd_client` defaults to `nil` (disabled).
+
+[↑ Back to features](#features)
+
+### OpenTelemetry
+
+`SafeMemoize::Adapters::OpenTelemetry` wraps the computation on each cache miss in an OpenTelemetry span, making memoized call costs visible in distributed traces. Assign a tracer once in your initializer:
+
+```ruby
+SafeMemoize.configure do |c|
+  c.opentelemetry_tracer = OpenTelemetry.tracer_provider.tracer(
+    "safe_memoize",
+    SafeMemoize::VERSION
+  )
+end
+```
+
+SafeMemoize then wraps every cache miss (the actual method call, not cache hits) in a span named `"safe_memoize.compute"` with the following attributes:
+
+| Attribute | Value |
+|---|---|
+| `safe_memoize.method` | Name of the memoized method |
+| `safe_memoize.class` | Name of the host class |
+| `safe_memoize.cache_hit` | Always `false` — only misses are traced |
+
+Cache hits produce no spans, so tracing overhead is zero for cached calls. The adapter is compatible with any tracer that responds to `in_span(name, attributes:, &block)` — the interface provided by `opentelemetry-sdk`, `opentelemetry-api`, and no-op tracers alike. If `opentelemetry_tracer` is `nil` (the default), the adapter is completely bypassed.
+
+[↑ Back to features](#features)
+
+### Rails request-scope
+
+SafeMemoize ships optional Rails integration as a separate require (zero overhead in non-Rails apps):
+
+```ruby
+require "safe_memoize/rails"
+```
+
+#### Controller concern
+
+Include `SafeMemoize::Rails::RequestScoped` in any Rails controller that also `prepend SafeMemoize`. It automatically registers `after_action :reset_all_memos` so every instance memo is cleared at the end of each request — preventing state from leaking between requests when the controller object is reused:
+
+```ruby
+class ApplicationController < ActionController::Base
+  prepend SafeMemoize
+  include SafeMemoize::Rails::RequestScoped
+
+  memoize :current_user
+end
+```
+
+#### Service objects and non-controller classes
+
+In plain classes (service objects, Active Model objects), include `RequestScoped` to gain `reset_request_memos` and call it manually at the appropriate point:
+
+```ruby
+class ReportService
+  prepend SafeMemoize
+  include SafeMemoize::Rails::RequestScoped
+
+  def summary(id)
+    # ...
+  end
+  memoize :summary
+end
+
+svc = ReportService.new
+svc.summary(1)
+svc.reset_request_memos  # clears all instance memos
+```
+
+#### Middleware for tracked instances
+
+For service objects that should be reset automatically at request boundaries, use the Rack middleware together with `SafeMemoize::Rails.track`:
+
+```ruby
+# config/application.rb
+config.middleware.use SafeMemoize::Rails::Middleware
+```
+
+```ruby
+class ReportService
+  prepend SafeMemoize
+
+  def initialize
+    SafeMemoize::Rails.track(self)  # register for auto-reset
+  end
+
+  def summary(id)
+    # ...
+  end
+  memoize :summary
+end
+```
+
+`SafeMemoize::Rails::Middleware` calls `reset_all_memos` on every tracked instance in the current thread at the end of the request, even if the app raises. Tracking is thread-local, so concurrent requests never interfere. The tracked list is cleared automatically after each reset.
+
+[↑ Back to features](#features)
+
+### Deprecation
+
+SafeMemoize ships a structured deprecation helper for gem authors who build on top of it:
+
+```ruby
+SafeMemoize.deprecate(
+  "MyGem::OldHelper",
+  message: "Use MyGem::NewHelper instead",
+  horizon: "2.0.0"
+)
+# => [SafeMemoize] DEPRECATED: MyGem::OldHelper — Use MyGem::NewHelper instead (removal horizon: 2.0.0)
+```
+
+The warning is emitted to stderr by default. Configure a custom handler via `SafeMemoize.configure`:
+
+```ruby
+SafeMemoize.configure do |c|
+  c.on_deprecation = ->(msg) { Rails.logger.warn(msg) }
+end
+```
+
+To raise on deprecation warnings in test environments:
+
+```ruby
+SafeMemoize.configure do |c|
+  c.on_deprecation = ->(msg) { raise msg }
+end
+```
+
+[↑ Back to features](#features)
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rspec` to run the tests. You can also run `bin/console` for an interactive prompt.
 
+To run the benchmark suite: `bundle exec ruby benchmarks/benchmark.rb`. Install `memery` and `memo_wise` first if you want comparison columns against those gems.
+
 GitHub Actions also runs the full `bundle exec rake` suite automatically for pull requests, manual workflow runs, and pushes to `main` via `.github/workflows/ci.yml`.
 
 ## Releasing

data/ROADMAP.md

@@ -10,12 +10,12 @@ This document tracks the planned evolution of SafeMemoize through v1.0.0 and bey
 
 | Feature | Description | Status |
 |---|---|---|
-| ActiveSupport::Notifications integration | Emit `cache.hit`, `cache.miss`, `cache.evict`, and `cache.expire` events when ActiveSupport is available (opt-in via configuration) | Planned |
-| StatsD adapter | Thin optional module (`SafeMemoize::Adapters::StatsD`) that routes lifecycle hooks to a StatsD client with sensible metric names and tags | Planned |
-| OpenTelemetry spans | Optional adapter (`SafeMemoize::Adapters::OpenTelemetry`) wrapping computation time in a trace span for distributed tracing pipelines | Planned |
-| Rails request-scope helper | Guide + optional mixin for resetting instance memos at the end of each request (controller concern, middleware, or Active Model pattern) | Planned |
-| Formal benchmark suite | `benchmarks/` directory with comparisons against `memery`, `memo_wise`, and raw `||=`, covering single-threaded throughput and contention under concurrent load | Planned |
-| Concurrency stress tests | Dedicated spec suite hammering shared-cache paths and LRU eviction under high thread counts to surface race conditions | Planned |
+| ActiveSupport::Notifications integration | Emit `cache.hit`, `cache.miss`, `cache.evict`, and `cache.expire` events when ActiveSupport is available (opt-in via configuration) | Shipped |
+| StatsD adapter | Thin optional module (`SafeMemoize::Adapters::StatsD`) that routes lifecycle hooks to a StatsD client with sensible metric names and tags | Shipped |
+| OpenTelemetry spans | Optional adapter (`SafeMemoize::Adapters::OpenTelemetry`) wrapping computation time in a trace span for distributed tracing pipelines | Shipped |
+| Rails request-scope helper | Guide + optional mixin for resetting instance memos at the end of each request (controller concern, middleware, or Active Model pattern) | Shipped |
+| Formal benchmark suite | `benchmarks/` directory with comparisons against `memery`, `memo_wise`, and raw `||=`, covering single-threaded throughput and contention under concurrent load | Shipped |
+| Concurrency stress tests | Dedicated spec suite hammering shared-cache paths and LRU eviction under high thread counts to surface race conditions | Shipped |
 
 ---
 

data/benchmarks/README.md

@@ -0,0 +1,68 @@
+# SafeMemoize Benchmarks
+
+Measures throughput for cache hits, cache misses, argument-keyed lookups, and concurrent access. Optional comparison against `memery` and `memo_wise`.
+
+## Running
+
+```bash
+bundle exec ruby benchmarks/benchmark.rb
+```
+
+### With comparison gems
+
+```bash
+gem install memery memo_wise
+bundle exec ruby benchmarks/benchmark.rb
+```
+
+## Sections
+
+| # | Scenario | What it measures |
+|---|---|---|
+| 1 | Zero-arg cache hit | Steady-state throughput on a primed cache |
+| 2 | Zero-arg cache miss | First-call overhead (new instance per iteration) |
+| 3 | With-argument cache hit | Key construction + hash lookup with one positional arg |
+| 4 | Fast path vs locked path | Cost of `max_size:` (adds a Mutex for LRU promotion) |
+| 5 | Shared vs instance cache | Class-level vs per-instance cache throughput |
+| 6 | Concurrent cache hits | 8 threads × 50 000 iterations under contention |
+
+## Interpreting results
+
+**Cache hits are ~50–70× slower than raw `||=`** on a single thread — an expected trade-off. SafeMemoize does significantly more work per call: prepended-module dispatch, deep-frozen key construction, hook dispatch, and metrics tracking. The `||=` pattern is also incorrect for `nil`/`false` return values, which is the whole reason this gem exists.
+
+**The fast path vs locked path gap is ~1.3×.** The locked path (used when `max_size:`, `if:`, or `ttl_refresh:` is set) holds the Mutex for the full read-compute-write cycle; the fast path only acquires it for the write step.
+
+**Shared and instance caches are effectively identical in throughput.** Both paths go through the same Mutex; the class-level cache has one shared Mutex rather than one per instance.
+
+**Concurrent throughput is bounded by the Mutex.** Under 8-thread contention, all threads compete for the per-instance Mutex on every read, serialising access. This is the cost of correctness under concurrent writes; in read-heavy workloads where the cache is pre-warmed the contention is minimal.
+
+## Representative results (Apple M-series, Ruby 3.4, MRI)
+
+```
+1. Zero-arg cache HIT (primed cache)
+   raw safe ivar    ~22 M i/s
+   safe_memoize     ~335 K i/s  (65× slower than raw)
+
+2. Zero-arg cache MISS (new instance each iteration)
+   raw safe ivar    ~8 M i/s
+   safe_memoize     ~227 K i/s  (36× slower than raw)
+
+3. With-argument cache HIT
+   raw safe ivar    ~15 M i/s
+   safe_memoize     ~314 K i/s  (47× slower than raw)
+
+4. Fast path vs locked path
+   fast path        ~310 K i/s
+   max_size: 100    ~234 K i/s  (1.32× slower)
+
+5. Shared vs instance cache
+   instance cache   ~323 K i/s
+   shared cache     ~324 K i/s  (same-ish)
+
+6. Concurrent (8 threads × 50 000 iterations)
+   raw safe ivar         ~12 M i/s
+   safe_memoize (fast)  ~327 K i/s
+   safe_memoize (shared) ~323 K i/s
+```
+
+Results vary by hardware, Ruby version, and GVL scheduling. Run on your own hardware for authoritative numbers.

data/benchmarks/benchmark.rb

@@ -0,0 +1,225 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Run with: bundle exec ruby benchmarks/benchmark.rb
+#
+# Optional comparison gems (install separately if desired):
+#   gem install memery memo_wise
+#
+# Each section prints iterations/second and a comparison table.
+# Higher i/s is better.
+
+require "benchmark/ips"
+require_relative "../lib/safe_memoize"
+
+# ── Optional comparison gems ──────────────────────────────────────────────────
+
+HAS_MEMERY = begin
+  require "memery"
+  true
+rescue LoadError
+  warn "  [skip] memery not installed (gem install memery to include)"
+  false
+end
+
+HAS_MEMO_WISE = begin
+  require "memo_wise"
+  true
+rescue LoadError
+  warn "  [skip] memo_wise not installed (gem install memo_wise to include)"
+  false
+end
+
+# ── Subject classes ───────────────────────────────────────────────────────────
+
+# Raw patterns — no gem, for baseline reference
+class RawIvarUnsafe
+  # Classic ||= — fast but silently broken for nil/false return values
+  def compute = (@compute ||= 42)
+end
+
+class RawIvarSafe
+  # Safe raw pattern — correct but verbose
+  def compute
+    return @compute if defined?(@compute)
+    @compute = 42
+  end
+
+  def fetch(n)
+    @fetch ||= {}
+    return @fetch[n] if @fetch.key?(n)
+    @fetch[n] = n * 2
+  end
+end
+
+# SafeMemoize
+class SmZeroArg
+  prepend SafeMemoize
+  def compute = 42
+  memoize :compute
+end
+
+class SmWithArg
+  prepend SafeMemoize
+  def fetch(n) = n * 2
+  memoize :fetch
+end
+
+class SmLruPath
+  prepend SafeMemoize
+  def fetch(n) = n * 2
+  memoize :fetch, max_size: 100
+end
+
+class SmShared
+  prepend SafeMemoize
+  def compute = 42
+  memoize :compute, shared: true
+end
+
+# memery
+if HAS_MEMERY
+  class MemeryZeroArg
+    include Memery
+    memoize def compute = 42
+  end
+
+  class MemeryWithArg
+    include Memery
+    memoize def fetch(n) = n * 2
+  end
+end
+
+# memo_wise
+if HAS_MEMO_WISE
+  class MemoWiseZeroArg
+    prepend MemoWise
+    def compute = 42
+    memo_wise :compute
+  end
+
+  class MemoWiseWithArg
+    prepend MemoWise
+    def fetch(n) = n * 2
+    memo_wise :fetch
+  end
+end
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+IPS_CONFIG = {time: 5, warmup: 2}
+
+def section(title)
+  puts
+  puts "=" * 62
+  puts "  #{title}"
+  puts "=" * 62
+end
+
+# ── 1. Zero-arg cache HIT — steady-state throughput ──────────────────────────
+
+section "1. Zero-arg cache HIT  (steady-state, primed cache)"
+
+raw_unsafe = RawIvarUnsafe.new.tap(&:compute)
+raw_safe   = RawIvarSafe.new.tap(&:compute)
+sm_zero    = SmZeroArg.new.tap(&:compute)
+mem_zero   = MemeryZeroArg.new.tap(&:compute) if HAS_MEMERY
+mw_zero    = MemoWiseZeroArg.new.tap(&:compute) if HAS_MEMO_WISE
+
+Benchmark.ips do |x|
+  x.config(**IPS_CONFIG)
+  x.report("raw ||= (unsafe)")  { raw_unsafe.compute }
+  x.report("raw safe ivar")     { raw_safe.compute }
+  x.report("safe_memoize")      { sm_zero.compute }
+  x.report("memery")            { mem_zero.compute } if HAS_MEMERY
+  x.report("memo_wise")         { mw_zero.compute } if HAS_MEMO_WISE
+  x.compare!
+end
+
+# ── 2. Zero-arg cache MISS — first-call overhead ──────────────────────────────
+
+section "2. Zero-arg cache MISS  (new instance each iteration)"
+
+Benchmark.ips do |x|
+  x.config(**IPS_CONFIG)
+  x.report("raw safe ivar")  { RawIvarSafe.new.compute }
+  x.report("safe_memoize")   { SmZeroArg.new.compute }
+  x.report("memery")         { MemeryZeroArg.new.compute } if HAS_MEMERY
+  x.report("memo_wise")      { MemoWiseZeroArg.new.compute } if HAS_MEMO_WISE
+  x.compare!
+end
+
+# ── 3. With-argument cache HIT ────────────────────────────────────────────────
+
+section "3. With-argument cache HIT  (single fixed argument)"
+
+raw_arg  = RawIvarSafe.new.tap { |o| o.fetch(1) }
+sm_arg   = SmWithArg.new.tap { |o| o.fetch(1) }
+mem_arg  = MemeryWithArg.new.tap { |o| o.fetch(1) } if HAS_MEMERY
+mw_arg   = MemoWiseWithArg.new.tap { |o| o.fetch(1) } if HAS_MEMO_WISE
+
+Benchmark.ips do |x|
+  x.config(**IPS_CONFIG)
+  x.report("raw safe ivar")  { raw_arg.fetch(1) }
+  x.report("safe_memoize")   { sm_arg.fetch(1) }
+  x.report("memery")         { mem_arg.fetch(1) } if HAS_MEMERY
+  x.report("memo_wise")      { mw_arg.fetch(1) } if HAS_MEMO_WISE
+  x.compare!
+end
+
+# ── 4. Fast path vs locked path ───────────────────────────────────────────────
+
+section "4. Fast path vs locked path  (max_size: adds mutex for LRU)"
+
+sm_fast = SmWithArg.new.tap { |o| o.fetch(1) }
+sm_lru  = SmLruPath.new.tap { |o| o.fetch(1) }
+
+Benchmark.ips do |x|
+  x.config(**IPS_CONFIG)
+  x.report("fast path (no max_size)")   { sm_fast.fetch(1) }
+  x.report("locked path (max_size:100)") { sm_lru.fetch(1) }
+  x.compare!
+end
+
+# ── 5. Shared cache vs instance cache ────────────────────────────────────────
+
+section "5. Shared cache vs instance cache  (class-level vs instance-level)"
+
+sm_inst   = SmZeroArg.new.tap(&:compute)
+sm_shared = SmShared.new.tap(&:compute)
+
+Benchmark.ips do |x|
+  x.config(**IPS_CONFIG)
+  x.report("instance cache")  { sm_inst.compute }
+  x.report("shared cache")    { sm_shared.compute }
+  x.compare!
+end
+
+# ── 6. Concurrent cache hits under thread contention ─────────────────────────
+
+section "6. Concurrent cache hits  (8 threads × 50_000 iterations)"
+
+THREADS   = 8
+ITERS     = 50_000
+TOTAL     = THREADS * ITERS
+
+def bench_threaded(label, obj, method, *args)
+  ts = THREADS.times.map { Thread.new { ITERS.times { obj.public_send(method, *args) } } }
+  t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  ts.each(&:join)
+  elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0
+  ips = TOTAL / elapsed
+  label_str = ips >= 1_000_000 ? format("%.2fM", ips / 1_000_000.0) : format("%.1fK", ips / 1_000.0)
+  printf "  %-34s %6.3fs  (%s i/s)\n", label, elapsed, label_str
+end
+
+puts
+
+bench_threaded("raw safe ivar",         raw_safe,   :compute)
+bench_threaded("safe_memoize (fast)",   sm_inst,    :compute)
+bench_threaded("safe_memoize (shared)", sm_shared,  :compute)
+bench_threaded("memery",                mem_zero,   :compute) if HAS_MEMERY
+bench_threaded("memo_wise",             mw_zero,    :compute) if HAS_MEMO_WISE
+
+puts
+puts "Done."

data/codecov.yml

@@ -0,0 +1,17 @@
+# Configure Pull Request Bot Comments
+comment:
+  layout: "reach, diff, flags, files"
+  behavior: default
+  # Only post or update the comment if the coverage drops
+  require_changes: "coverage_drop"
+
+# Configure Commit Status Checks (the green checkmark/red X list)
+coverage:
+  status:
+    project:
+      default:
+        # Prevent "Informational" mode so a drop causes an actual red failure check
+        informational: false
+    patch:
+      default:
+        informational: false

data/lib/safe_memoize/adapters/opentelemetry.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module Adapters
+    module OpenTelemetry
+      SPAN_NAME = "safe_memoize.compute"
+
+      def self.trace(tracer, method_name, class_name)
+        return yield unless tracer&.respond_to?(:in_span)
+
+        tracer.in_span(SPAN_NAME, attributes: {
+          "safe_memoize.method" => method_name.to_s,
+          "safe_memoize.class" => class_name.to_s,
+          "safe_memoize.cache_hit" => false
+        }) { yield }
+      end
+    end
+  end
+end

data/lib/safe_memoize/adapters/statsd.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module Adapters
+    module StatsD
+      METRIC_NAMES = {
+        on_hit: "safe_memoize.hit",
+        on_miss: "safe_memoize.miss",
+        on_evict: "safe_memoize.evict",
+        on_expire: "safe_memoize.expire",
+        on_store: "safe_memoize.store"
+      }.freeze
+
+      def self.dispatch(client, hook_type, cache_key, class_name)
+        metric = METRIC_NAMES[hook_type]
+        return unless metric
+
+        tags = ["method:#{cache_key[0]}", "class:#{class_name}"]
+        client.increment(metric, tags: tags)
+      rescue => error
+        warn "[SafeMemoize] StatsD dispatch error: #{error.message}"
+      end
+    end
+  end
+end

data/lib/safe_memoize/class_methods.rb

@@ -88,7 +88,7 @@ module SafeMemoize
                 call_memo_hooks(:on_expire, cache_key, record) if record && !record_live
 
                 start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-                value = super(*args, **kwargs)
+                value = Adapters::OpenTelemetry.trace(SafeMemoize.configuration.opentelemetry_tracer, method_name, klass.name) { super(*args, **kwargs) }
                 elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
 
                 new_record = memo_record(value, expires_at: memo_expires_at(ttl))
@@ -147,7 +147,7 @@ module SafeMemoize
                 memo_record_value(record)
               else
                 start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-                value = super(*args, **kwargs)
+                value = Adapters::OpenTelemetry.trace(SafeMemoize.configuration.opentelemetry_tracer, method_name, self.class.name) { super(*args, **kwargs) }
                 elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
 
                 new_record = memo_record(value, expires_at: memo_expires_at(ttl))
@@ -174,7 +174,9 @@ module SafeMemoize
 
             # Cache miss - compute and store
             start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-            result = memo_fetch_or_store(cache_key, ttl: ttl) { super(*args, **kwargs) }
+            result = memo_fetch_or_store(cache_key, ttl: ttl) do
+              Adapters::OpenTelemetry.trace(SafeMemoize.configuration.opentelemetry_tracer, method_name, self.class.name) { super(*args, **kwargs) }
+            end
             elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
 
             with_memo_lock do

data/lib/safe_memoize/configuration.rb

@@ -2,13 +2,17 @@
 
 module SafeMemoize
   class Configuration
-    attr_accessor :default_ttl, :default_max_size, :on_deprecation, :on_hook_error
+    attr_accessor :default_ttl, :default_max_size, :on_deprecation, :on_hook_error,
+      :active_support_notifications, :statsd_client, :opentelemetry_tracer
 
     def initialize
       @default_ttl = nil
       @default_max_size = nil
       @on_deprecation = nil
       @on_hook_error = nil
+      @active_support_notifications = false
+      @statsd_client = nil
+      @opentelemetry_tracer = nil
     end
   end
 end

data/lib/safe_memoize/hooks_methods.rb

@@ -2,6 +2,14 @@
 
 module SafeMemoize
   module HooksMethods
+    NOTIFICATION_EVENT_NAMES = {
+      on_hit: "cache_hit.safe_memoize",
+      on_miss: "cache_miss.safe_memoize",
+      on_evict: "cache_evict.safe_memoize",
+      on_expire: "cache_expire.safe_memoize",
+      on_store: "cache_store.safe_memoize"
+    }.freeze
+
     private
 
     def memo_hook_store
@@ -29,6 +37,28 @@ module SafeMemoize
           warn "[SafeMemoize] Hook error in #{hook_type}: #{error.message}"
         end
       end
+
+      safe_memo_notify(hook_type, cache_key) if SafeMemoize.configuration.active_support_notifications
+
+      if (client = SafeMemoize.configuration.statsd_client)
+        Adapters::StatsD.dispatch(client, hook_type, cache_key, self.class.name)
+      end
+    end
+
+    def safe_memo_notify(hook_type, cache_key)
+      return unless defined?(ActiveSupport::Notifications)
+
+      asn = ActiveSupport::Notifications
+      return unless asn.respond_to?(:instrument)
+
+      event = NOTIFICATION_EVENT_NAMES[hook_type]
+      return unless event
+
+      asn.instrument(event, {
+        method: cache_key[0],
+        key: cache_key,
+        class: self.class.name
+      })
     end
 
     def _clear_memo_hooks(hook_type = nil)

data/lib/safe_memoize/rails/middleware.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module Rails
+    # Rack middleware that resets all thread-tracked memoized instances at the
+    # end of each request. Useful for service objects that are instantiated
+    # per-request and register themselves via `SafeMemoize::Rails.track(self)`.
+    #
+    # Add to your Rack stack in config/application.rb:
+    #   config.middleware.use SafeMemoize::Rails::Middleware
+    class Middleware
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        @app.call(env)
+      ensure
+        SafeMemoize::Rails.reset_tracked!
+      end
+    end
+  end
+end

data/lib/safe_memoize/rails/request_scoped.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module Rails
+    # Include in a Rails controller to automatically reset instance memos after
+    # each request. In non-controller classes (service objects, models), include
+    # it to gain `reset_request_memos` and call it manually at the end of a
+    # request or job.
+    #
+    # The class must also `prepend SafeMemoize` for `reset_all_memos` to exist.
+    #
+    # Example — controller:
+    #   class ApplicationController < ActionController::Base
+    #     prepend SafeMemoize
+    #     include SafeMemoize::Rails::RequestScoped
+    #   end
+    #
+    # Example — service object with middleware tracking:
+    #   class ReportService
+    #     prepend SafeMemoize
+    #     include SafeMemoize::Rails::RequestScoped
+    #
+    #     def initialize
+    #       SafeMemoize::Rails.track(self)
+    #     end
+    #   end
+    module RequestScoped
+      def self.included(base)
+        base.after_action :reset_all_memos if base.respond_to?(:after_action)
+      end
+
+      def reset_request_memos
+        reset_all_memos
+      end
+    end
+  end
+end

data/lib/safe_memoize/rails.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "safe_memoize"
+require_relative "rails/request_scoped"
+require_relative "rails/middleware"
+
+module SafeMemoize
+  # Optional Rails integration. Not auto-required — add to your initializer:
+  #   require "safe_memoize/rails"
+  module Rails
+    # Register an instance to have its memos reset at the end of the current
+    # request (via Middleware). Thread-local; each thread maintains its own list.
+    def self.track(instance)
+      (Thread.current[:safe_memoize_tracked] ||= []) << instance
+    end
+
+    # Reset all tracked instances and clear the list. Called automatically by
+    # Middleware after each request. Safe to call with an empty list.
+    def self.reset_tracked!
+      instances = Thread.current[:safe_memoize_tracked] || []
+      instances.each do |instance|
+        instance.reset_all_memos if instance.respond_to?(:reset_all_memos)
+      end
+    ensure
+      Thread.current[:safe_memoize_tracked] = []
+    end
+  end
+end

data/lib/safe_memoize/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SafeMemoize
-  VERSION = "0.8.0"
+  VERSION = "0.9.0"
 end

data/lib/safe_memoize.rb

@@ -2,6 +2,8 @@
 
 require_relative "safe_memoize/version"
 require_relative "safe_memoize/configuration"
+require_relative "safe_memoize/adapters/statsd"
+require_relative "safe_memoize/adapters/opentelemetry"
 require_relative "safe_memoize/class_methods"
 require_relative "safe_memoize/public_methods"
 require_relative "safe_memoize/cache_store_methods"

data/sig/safe_memoize.rbs

@@ -7,6 +7,7 @@ module SafeMemoize
   type memo_key = default_memo_key | custom_memo_key
   type memo_record = { value: untyped, expires_at: Float?, cached_at: Float }
 
+  @configuration: Configuration?
   @__safe_memo_cache__: Hash[memo_key, memo_record]?
   @__safe_memo_mutex__: Mutex?
   @__safe_memo_shared_cache__: Hash[memo_key, memo_record]?
@@ -24,6 +25,9 @@ module SafeMemoize
     attr_accessor default_max_size: Integer?
     attr_accessor on_deprecation: (^(String message) -> void)?
     attr_accessor on_hook_error: (^(Exception error, Symbol hook_type, untyped cache_key) -> void)?
+    attr_accessor active_support_notifications: bool
+    attr_accessor statsd_client: untyped
+    attr_accessor opentelemetry_tracer: untyped
 
     def initialize: () -> void
   end
@@ -190,5 +194,27 @@ module SafeMemoize
     include PublicCustomKeyMethods
     include LruMethods
   end
+
+  module Adapters
+    module OpenTelemetry
+      SPAN_NAME: String
+      def self.trace: (untyped tracer, Symbol | String method_name, String? class_name) { () -> untyped } -> untyped
+    end
+  end
+
+  module Rails
+    def self.track: (untyped instance) -> void
+    def self.reset_tracked!: () -> void
+
+    module RequestScoped
+      def self.included: (Module base) -> void
+      def reset_request_memos: () -> void
+    end
+
+    class Middleware
+      def initialize: (untyped app) -> void
+      def call: (untyped env) -> untyped
+    end
+  end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: safe_memoize
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -46,7 +46,12 @@ files:
 - README.md
 - ROADMAP.md
 - Rakefile
+- benchmarks/README.md
+- benchmarks/benchmark.rb
+- codecov.yml
 - lib/safe_memoize.rb
+- lib/safe_memoize/adapters/opentelemetry.rb
+- lib/safe_memoize/adapters/statsd.rb
 - lib/safe_memoize/cache_metrics_methods.rb
 - lib/safe_memoize/cache_record_methods.rb
 - lib/safe_memoize/cache_store_methods.rb
@@ -60,6 +65,9 @@ files:
 - lib/safe_memoize/public_custom_key_methods.rb
 - lib/safe_memoize/public_methods.rb
 - lib/safe_memoize/public_metrics_methods.rb
+- lib/safe_memoize/rails.rb
+- lib/safe_memoize/rails/middleware.rb
+- lib/safe_memoize/rails/request_scoped.rb
 - lib/safe_memoize/release_tooling.rb
 - lib/safe_memoize/version.rb
 - sig/safe_memoize.rbs