rails_named_cache 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '079d7672d3eb5ac855a1fd954bde9831ab34bef4f529cec6d7b17b393eb57629'
-  data.tar.gz: 64193c678525fc4c28f358c8a60fe6c85d9236620025e66ffb317888650c00fa
+  metadata.gz: 7421605a4a8c9d7fb63fec7fb51a2376cf7fd8e58a0d7b30bf56a8a8f29d2509
+  data.tar.gz: 4c48647f995d27409ff4f6319e18f11b80557ea7d8bd67a75c2643f2212747e2
 SHA512:
-  metadata.gz: b0ed82b9bad41e7607610f538d8df8a5d33bdf90e6eebf3ef7d19c1981aed08ad08a75eb798f64eda542a5a9bbcb38136f0974df901bdedc1bfd44a76f57ca3d
-  data.tar.gz: 6cc671bb1a3a633813db29c0eb29104b40fb6b1bc94ff70fcf917fcba44b045e513c25b9a88a48ddb453d4b861cd8258f1c72d2ff253795b3ec9970676ccbe74
+  metadata.gz: b3397d1941abb8a4a3b4b71f8e8f52234e58efd3929702b92226923950260268b321e73117497f139ce4c3a9734a28a81728daf97a212b377982568f7c7167de
+  data.tar.gz: e1d39f9714e606be99ec3dcc1c126b41c936efb9a8b521ac198de7ea9be7eb222e988d4597a8b8d6524d2f7e016c3504dbe4a8f5c5e18e2185644436b2a2ecc3

data/CHANGELOG.md

@@ -6,6 +6,15 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-08-02
+
+### Added
+
+- Hit/miss logging: every `cache_read.active_support` notification is logged at `debug` level as
+  `Cache hit: <key>`. Configured with `config.named_cache_logger` — `Rails.logger`
+  by default, `false` to disable — and available outside Rails as
+  `RailsNamedCache::Logging.subscribe(logger)`.
+
 ## [0.1.0] - 2026-07-30
 
 ### Added
@@ -20,5 +29,6 @@ All notable changes to this project are documented here. The format follows
   `MemoryStore` registered as `:memory`.
 - Support for Rails 7.0 through 8.1 on Ruby 3.3 and 3.4.
 
-[Unreleased]: https://github.com/igorkasyanchuk/rails_named_cache/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/igorkasyanchuk/rails_named_cache/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/igorkasyanchuk/rails_named_cache/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/igorkasyanchuk/rails_named_cache/releases/tag/v0.1.0

data/README.md

@@ -22,7 +22,7 @@ Rails.cache(:redis).fetch("session") { ... }       # shared across servers
   Stores live in `config/` instead of global constants; `Rails.cache` is untouched.
 
 **Contents:** [Install](#installation) · [Configuration](#configuration) · [Usage](#usage) ·
-[Expiration](#expiration) · [L1/L2](#l1l2-memory-in-front-of-redis) ·
+[Expiration](#expiration) · [Logging](#hitmiss-logging) · [L1/L2](#l1l2-memory-in-front-of-redis) ·
 [MemoryStore speed](#why-memorystore-is-so-fast) · [Testing](#testing) ·
 [Advanced](#advanced-configuration) · [FAQ](#faq) · [Be careful](#be-careful) ·
 [Compatibility](#compatibility)
@@ -117,6 +117,40 @@ Rails.cache(:pricing).fetch("report", expires_at: Date.tomorrow.midnight) { buil
 
 No `expires_in` on a store means entries live until overwritten, deleted, or evicted by the backend.
 
+## Hit/miss logging
+
+Every cache read is logged to `Rails.logger` at `debug` level — nothing to configure. It lands in
+the app log next to the rest of the request, `log/development.log` locally, and stays quiet in
+production, where the level is `info`:
+
+```
+Cache hit: users/1
+Cache miss: pricing:eur
+```
+
+To turn it off, or to send it somewhere other than the app log:
+
+```ruby
+config.named_cache_logger = false                                          # log nothing
+config.named_cache_logger = Logger.new(Rails.root.join("log/cache.log"))   # a separate file
+```
+
+Two things to know:
+
+- This is a subscriber on the `cache_read.active_support` notification ActiveSupport already
+  emits — no store is wrapped, and reads through the default `Rails.cache` are logged too.
+- The line carries the key, not the store: ActiveSupport's payload has nothing that identifies
+  the instance a read came from. On Rails 7.2 and up the key is the normalized one, so give
+  stores a `namespace:` and its prefix tells them apart. Rails 7.0 and 7.1 report the key as the
+  caller wrote it, without the namespace.
+
+Outside Rails, subscribe by hand:
+
+```ruby
+RailsNamedCache::Logging.subscribe(my_logger)
+RailsNamedCache::Logging.unsubscribe
+```
+
 ## L1/L2: memory in front of Redis
 
 Not a gem feature — two named stores and two nested `fetch` calls:
@@ -171,18 +205,73 @@ data; use a shared store for anything that must agree across processes.
 
 ## Testing
 
+**Same names and the same backends in test — only the target changes.** Every name the code calls
+has to exist in every environment, since a missing one raises `UnknownStoreError` and never falls
+back. Keep each store on the backend it uses in production, pointed at a test-only Redis database,
+so a `:redis` store is always Redis and tests exercise real serialization and expiry:
+
+```ruby
+# config/initializers/rails_named_cache.rb
+Rails.application.configure do
+  # a separate Redis database in test, so a suite can never touch development keys
+  redis_url = Rails.env.test? ? ENV.fetch("REDIS_TEST_URL") : ENV.fetch("REDIS_URL")
+
+  config.named_cache_stores = {
+    memory: ActiveSupport::Cache::MemoryStore.new(size: 1.megabyte, expires_in: 1.day),
+    pricing: [:redis_cache_store, { url: redis_url, namespace: "pricing" }],
+    redis: [:redis_cache_store, { url: redis_url, namespace: "app" }]
+  }
+end
+```
+
+> **Namespace every Redis store.** `RedisCacheStore#clear` runs `FLUSHDB` when the store has no
+> namespace, so the clear-between-examples hook below would wipe the whole database — including
+> Sidekiq queues or a colleague's development data if the suite ever runs against a shared server.
+> With a namespace, `clear` deletes only that store's keys.
+
+To disable one domain's caching in test, register a `NullStore` for that name — see the per-example
+swap below — rather than backing a `:redis` name with a memory store, which makes the suite pass
+against behaviour production never runs.
+
+> Initializers load *after* `config/environments/*.rb`, so an initializer that assigns
+> `config.named_cache_stores` silently overwrites whatever `config/environments/test.rb` set. Pick
+> one: branch on `Rails.env` in the initializer, as above, or delete the initializer and configure
+> each environment file.
+
+**Clear every store between examples**, so cached state cannot leak from one example to the next:
+
+```ruby
+config.before { RailsNamedCache.names.each { |name| Rails.cache(name).clear } }
+```
+
+Do not call `RailsNamedCache.reset!` in an application suite — registration happens once at boot,
+so an emptied registry stays empty and every later lookup raises. It exists for testing this gem.
+
+**Swap one store for one example:**
+
 ```ruby
-# disable caching for one domain, restore after
 config.around(:each, :no_pricing_cache) do |example|
   original = Rails.cache(:pricing)
   RailsNamedCache.register(:pricing, ActiveSupport::Cache::NullStore.new)
   example.run
   RailsNamedCache.register(:pricing, original)
 end
+```
 
-config.before { Rails.cache(:pricing).clear }   # or clear one store between examples
+Re-registering is better than stubbing `Rails.cache`: a `receive(:cache).with(:pricing)` stub also
+intercepts the no-argument calls that Rails itself makes.
+
+**Assert against the store directly** — it is a real store, so no mocks are needed:
+
+```ruby
+it "caches the computed price" do
+  expect { PriceCalculator.call(product) }
+    .to change { Rails.cache(:pricing).exist?("product/#{product.id}") }.from(false).to(true)
+end
 ```
 
+Minitest is the same, from `setup` / `teardown` in `ActiveSupport::TestCase`.
+
 ## Advanced configuration
 
 ### Boot order
@@ -311,8 +400,9 @@ Named stores make it easy to add caches, which makes it easy to add these:
 - **No cross-process invalidation.** `Rails.cache(:memory).delete(key)` and `.clear` affect the
   calling process only — a console or rake task cannot flush the running workers. Anything that
   needs a coordinated purge belongs in a shared backend.
-- **Two stores on one backend share one keyspace**, and `clear` on either wipes both. See
-  [Isolating stores that share a backend](#isolating-stores-that-share-a-backend).
+- **Two stores on one backend share one keyspace**, and `clear` on either wipes both. Worse, a
+  `RedisCacheStore` with no `namespace` implements `clear` as `FLUSHDB` — the whole database, not
+  just your keys. See [Isolating stores that share a backend](#isolating-stores-that-share-a-backend).
 - **No per-request local cache.** Repeated reads of the same key in one request hit a named store's
   backend every time. On a Redis-backed store, wrap the work in `with_local_cache` or put a
   [memory layer in front](#l1l2-memory-in-front-of-redis).

data/lib/generators/rails_named_cache/install/templates/rails_named_cache.rb

@@ -35,4 +35,11 @@ Rails.application.configure do
     # Caches nothing. Useful per environment, e.g. in config/environments/test.rb.
     # null: ActiveSupport::Cache::NullStore.new
   }
+
+  # Cache hits and misses go to the app log (Rails.logger) at debug level:
+  # visible in development, quiet in production. Turn it off, or send it to its
+  # own file, with:
+  #
+  #   config.named_cache_logger = false
+  #   config.named_cache_logger = Logger.new(Rails.root.join("log/cache.log"))
 end

data/lib/rails_named_cache/logging.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "active_support/notifications"
+
+module RailsNamedCache
+  # Logs cache hits and misses at +debug+ level.
+  #
+  # It subscribes to the +cache_read.active_support+ notification ActiveSupport
+  # already emits, so no store is wrapped and no cache API is added:
+  #
+  #   Cache hit: users/1
+  #   Cache miss: pricing:eur
+  #
+  # Every read is logged, named or not — the notification is global. On Rails
+  # 7.2 and up the key is the normalized one, so a store's +namespace:+ shows up
+  # as its prefix; earlier versions instrument the name the caller passed.
+  module Logging
+    # The only notification carrying +:hit+.
+    EVENT = "cache_read.active_support"
+
+    class << self
+      # @return [Object, nil] the notification subscriber, or +nil+ when not subscribed
+      attr_reader :subscriber
+
+      # Starts logging. Idempotent.
+      #
+      # @param logger [Logger, nil, false] +nil+ resolves +Rails.logger+ per event,
+      #   +false+ disables logging entirely
+      # @return [Object, nil] the subscriber, or +nil+ when disabled or already subscribed
+      def subscribe(logger = nil)
+        return if logger == false || subscribed?
+
+        @logger = logger
+        @subscriber = ActiveSupport::Notifications.subscribe(EVENT) do |_name, _start, _finish, _id, payload|
+          log(payload)
+        end
+      end
+
+      # Stops logging. Intended for tests and reboots.
+      #
+      # @return [void]
+      def unsubscribe
+        return unless @subscriber
+
+        ActiveSupport::Notifications.unsubscribe(@subscriber)
+        @subscriber = nil
+        @logger = nil
+      end
+
+      # @return [Boolean]
+      def subscribed?
+        !@subscriber.nil?
+      end
+
+      # @return [Logger, nil] the configured logger, or +Rails.logger+
+      def logger
+        @logger || (::Rails.logger if defined?(::Rails))
+      end
+
+      private
+
+      # @param payload [Hash] the notification payload
+      # @return [void]
+      def log(payload)
+        # Block form: nothing is built when the logger is above debug level.
+        logger&.debug { "Cache #{payload[:hit] ? "hit" : "miss"}: #{payload[:key]}" }
+      end
+    end
+  end
+end

data/lib/rails_named_cache/railtie.rb

@@ -8,13 +8,18 @@ module RailsNamedCache
   # Adds +config.named_cache_stores+ (default +{}+) and fills the {Registry}
   # from it once, after +config/initializers+ have run and before eager loading,
   # so eager-loaded code can already call +Rails.cache(:name)+.
+  #
+  # Also adds +config.named_cache_logger+ (default +nil+, meaning +Rails.logger+;
+  # set it to +false+ to log nothing) and subscribes {Logging} to it.
   class Railtie < ::Rails::Railtie
     config.named_cache_stores = {}
+    config.named_cache_logger = nil
 
     initializer "rails_named_cache.register_stores", after: :load_config_initializers do |app|
       # Registration is by name, so manual RailsNamedCache.register calls made
       # from config/initializers survive unless config names the same store.
       RailsNamedCache.load_configuration(app.config.named_cache_stores)
+      RailsNamedCache::Logging.subscribe(app.config.named_cache_logger)
     end
   end
 end

data/lib/rails_named_cache/version.rb

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

data/lib/rails_named_cache.rb

@@ -6,6 +6,7 @@ require "active_support/cache"
 require_relative "rails_named_cache/version"
 require_relative "rails_named_cache/registry"
 require_relative "rails_named_cache/configuration"
+require_relative "rails_named_cache/logging"
 require_relative "rails_named_cache/rails_ext"
 
 # Named +ActiveSupport::Cache::Store+ instances for Rails applications.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_named_cache
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Igor Kasyanchuk
@@ -88,6 +88,7 @@ files:
 - lib/generators/rails_named_cache/install/templates/rails_named_cache.rb
 - lib/rails_named_cache.rb
 - lib/rails_named_cache/configuration.rb
+- lib/rails_named_cache/logging.rb
 - lib/rails_named_cache/rails_ext.rb
 - lib/rails_named_cache/railtie.rb
 - lib/rails_named_cache/registry.rb