rails_named_cache 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '079d7672d3eb5ac855a1fd954bde9831ab34bef4f529cec6d7b17b393eb57629'
+  data.tar.gz: 64193c678525fc4c28f358c8a60fe6c85d9236620025e66ffb317888650c00fa
+SHA512:
+  metadata.gz: b0ed82b9bad41e7607610f538d8df8a5d33bdf90e6eebf3ef7d19c1981aed08ad08a75eb798f64eda542a5a9bbcb38136f0974df901bdedc1bfd44a76f57ca3d
+  data.tar.gz: 6cc671bb1a3a633813db29c0eb29104b40fb6b1bc94ff70fcf917fcba44b045e513c25b9a88a48ddb453d4b861cd8258f1c72d2ff253795b3ec9970676ccbe74

data/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-30
+
+### Added
+
+- `Rails.cache(:name)` returns a named `ActiveSupport::Cache::Store`; `Rails.cache` is unchanged.
+- `config.named_cache_stores` configuration, accepting store instances or anything
+  `ActiveSupport::Cache.lookup_store` understands.
+- Thread-safe `RailsNamedCache::Registry` with O(1) lookups.
+- `RailsNamedCache::UnknownStoreError`, which lists the available stores and never falls back.
+  `Rails.cache(nil)` raises `ConfigurationError` instead of returning the default store.
+- `rails generate rails_named_cache:install` generator, creating an initializer with a 1 MB
+  `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
+[0.1.0]: https://github.com/igorkasyanchuk/rails_named_cache/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Igor Kasyanchuk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,364 @@
+# rails_named_cache
+
+[![Gem Version](https://badge.fury.io/rb/rails_named_cache.svg)](https://rubygems.org/gems/rails_named_cache)
+[![CI](https://github.com/igorkasyanchuk/rails_named_cache/actions/workflows/ci.yml/badge.svg)](https://github.com/igorkasyanchuk/rails_named_cache/actions/workflows/ci.yml)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Multiple named cache stores for Rails, through `Rails.cache(:name)`.
+
+```ruby
+Rails.cache.fetch("users") { User.all }            # default store, unchanged
+Rails.cache(:memory).fetch("countries") { ... }    # in-process, ~3 µs per read
+Rails.cache(:redis).fetch("session") { ... }       # shared across servers
+```
+
+**Why:**
+
+- **Speed.** A named `MemoryStore` read is ~3 µs — no socket, no pool checkout, no wire protocol
+  ([numbers](#why-memorystore-is-so-fast)).
+- **Isolation.** Per-domain stores, so page-fragment churn can no longer evict the pricing table.
+  `Rails.cache(:pricing).clear` touches nothing else.
+- **No new API.** `Rails.cache(:name)` returns the configured store itself — no wrapper, no proxy.
+  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) ·
+[MemoryStore speed](#why-memorystore-is-so-fast) · [Testing](#testing) ·
+[Advanced](#advanced-configuration) · [FAQ](#faq) · [Be careful](#be-careful) ·
+[Compatibility](#compatibility)
+
+## Installation
+
+```bash
+bundle add rails_named_cache
+rails generate rails_named_cache:install   # optional: a commented initializer to start from
+```
+
+Ruby >= 3.3, Rails >= 7.0. Runtime deps are `activesupport`, `railties`, `concurrent-ruby`.
+
+## Configuration
+
+One setting. Values are any `ActiveSupport::Cache::Store`:
+
+```ruby
+# config/initializers/rails_named_cache.rb
+Rails.application.configure do
+  config.named_cache_stores = {
+    memory: ActiveSupport::Cache::MemoryStore.new(size: 1.megabyte),
+    pricing: ActiveSupport::Cache::MemoryStore.new(size: 8.megabytes),
+    redis: ActiveSupport::Cache::RedisCacheStore.new(url: ENV.fetch("REDIS_URL")),
+    disk: ActiveSupport::Cache::FileStore.new(Rails.root.join("tmp/cache")),
+    null: ActiveSupport::Cache::NullStore.new
+  }
+end
+```
+
+Rails shorthand works too, resolved through `ActiveSupport::Cache.lookup_store`:
+
+```ruby
+config.named_cache_stores = {
+  memory: :memory_store,
+  redis: [:redis_cache_store, { url: ENV.fetch("REDIS_URL") }],
+  disk: [:file_store, "tmp/cache"]
+}
+```
+
+Works from `config/application.rb` or any environment file too. An app that never sets it behaves
+exactly as before. Per-environment stores, engines, boot ordering, error semantics and the registry
+API are in [Advanced configuration](#advanced-configuration).
+
+## Usage
+
+```ruby
+Rails.cache.fetch("key") { value }                                  # default store, unchanged
+Rails.cache(:memory).fetch("countries") { Country.all.to_a }
+Rails.cache(:pricing).write("product/1", price)
+Rails.cache(:null).fetch("anything") { computed }                   # never caches
+
+store = Rails.cache(:memory)   # a plain ActiveSupport::Cache::Store — full API, nothing wrapped
+```
+
+Unknown and `nil` names raise instead of falling back to another store:
+
+```ruby
+Rails.cache(:unknown)
+# RailsNamedCache::UnknownStoreError: Unknown named cache store :unknown
+#
+#   Available stores:
+#   :memory
+#   :pricing
+
+Rails.cache(nil)
+# RailsNamedCache::ConfigurationError: Cache store name must be a non-empty Symbol or String, got nil
+```
+
+`UnknownStoreError` exposes `#name` and `#available`.
+
+## Expiration
+
+Per-store defaults, so each domain gets its own policy:
+
+```ruby
+config.named_cache_stores = {
+  memory: ActiveSupport::Cache::MemoryStore.new(size: 1.megabyte, expires_in: 10.seconds),
+  pricing: [:redis_cache_store, { url: ENV.fetch("REDIS_URL"), expires_in: 1.hour }],
+  geocode: [:redis_cache_store, { url: ENV.fetch("REDIS_URL"), expires_in: 30.days }]
+}
+```
+
+Per-call overrides are ordinary ActiveSupport:
+
+```ruby
+Rails.cache(:memory).fetch("flags", expires_in: 1.second) { Flag.enabled.to_a }
+Rails.cache(:pricing).write("product/#{id}", price, expires_in: 30.seconds)
+Rails.cache(:pricing).fetch("rate", expires_in: 1.hour, race_condition_ttl: 10.seconds) { fetch_rate }
+Rails.cache(:pricing).fetch("report", expires_at: Date.tomorrow.midnight) { build_report }
+```
+
+No `expires_in` on a store means entries live until overwritten, deleted, or evicted by the backend.
+
+## L1/L2: memory in front of Redis
+
+Not a gem feature — two named stores and two nested `fetch` calls:
+
+```ruby
+# app/lib/layered_cache.rb
+module LayeredCache
+  def self.fetch(key, l1_expires_in: 5.seconds, **options, &block)
+    Rails.cache(:memory).fetch(key, expires_in: l1_expires_in) do
+      Rails.cache(:redis).fetch(key, **options, &block)
+    end
+  end
+
+  def self.delete(key)
+    Rails.cache(:redis).delete(key)
+    Rails.cache(:memory).delete(key)   # this process only
+  end
+end
+```
+
+```ruby
+LayeredCache.fetch("countries", expires_in: 1.day) { Country.order(:name).to_a }
+# L1 hit (< 5s): ~3 µs, no Redis. L1 miss: one Redis read, refills L1. Both miss: runs the block.
+```
+
+**The L1 TTL is your staleness window.** An L1 entry cannot be invalidated from another process, so
+`delete` clears Redis at once while other workers keep serving their copy until it expires. Keep it
+at seconds.
+
+## Why MemoryStore is so fast
+
+| | Redis / Memcached | `MemoryStore` |
+| --- | --- | --- |
+| Network round trip | yes | **no** |
+| Connection pool checkout | yes | **no** |
+| Wire protocol encode/decode | yes | **no** |
+| Value handling | serialize to bytes | deep-copy in memory |
+
+Reading a small hash 200,000 times, Ruby 3.4.5 on Apple silicon:
+
+```
+MemoryStore: 362,918 reads/sec —  2.8 µs/read
+FileStore:    51,202 reads/sec — 19.5 µs/read
+```
+
+Redis adds a socket round trip on top of the same bookkeeping. What is left in `MemoryStore` is the
+deep copy that keeps callers from mutating cached state (`dup` for strings, `Marshal` otherwise), so
+keep values small and plain.
+
+The cost: it is per-process and dies with the process. Use it for cheap-to-recompute, read-constantly
+data; use a shared store for anything that must agree across processes.
+
+## Testing
+
+```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
+```
+
+## Advanced configuration
+
+### Boot order
+
+Stores are registered after `config/initializers` run and before eager loading, so eager-loaded
+code can call `Rails.cache(:name)`.
+
+> **Not available inside `config/initializers`** — a lookup in an initializer body raises
+> `UnknownStoreError`. Use `config.after_initialize`, `to_prepare`, or application code.
+
+Per-environment stores are plain Rails configuration:
+
+```ruby
+# config/environments/test.rb
+config.named_cache_stores = { pricing: ActiveSupport::Cache::NullStore.new }
+```
+
+### Isolating stores that share a backend
+
+Two stores on the same Redis, Memcached or directory share one keyspace — different objects, same
+keys:
+
+```ruby
+Rails.cache(:short).write("user/1", "a")
+Rails.cache(:long).read("user/1")   # => "a"   — not isolated
+Rails.cache(:long).clear            # also wipes :short
+```
+
+Give each a `namespace`. That isolates the keys and makes the store identifiable in logs and APM —
+the `cache_read.active_support` payload carries `namespace`, otherwise both report only
+`store: "ActiveSupport::Cache::RedisCacheStore"`:
+
+```ruby
+config.named_cache_stores = {
+  short: [:redis_cache_store, { url: ENV.fetch("REDIS_URL"), namespace: "short", expires_in: 1.minute }],
+  long: [:redis_cache_store, { url: ENV.fetch("REDIS_URL"), namespace: "long", expires_in: 1.day }]
+}
+```
+
+Separate `MemoryStore` instances need no namespace.
+
+### Engines
+
+Do not set `config.named_cache_stores` from an engine — railtie config is shared, so it replaces the
+host app's stores. Register instead:
+
+```ruby
+initializer "my_engine.caches", after: "rails_named_cache.register_stores" do
+  RailsNamedCache.register(:my_engine, ActiveSupport::Cache::MemoryStore.new)
+end
+```
+
+### Configuration errors fail at boot
+
+Nothing is registered if any entry is invalid:
+
+```ruby
+config.named_cache_stores = { pricing: nil }
+# ConfigurationError: Named cache store :pricing is nil
+
+config.named_cache_stores = { "pricing" => a, pricing: b }
+# ConfigurationError: Duplicate named cache store :pricing
+```
+
+`nil` is rejected because `ActiveSupport::Cache.lookup_store(nil)` returns a fresh `MemoryStore` —
+a typo would become a cache that quietly loses data. Names are non-empty symbols or strings, and
+`"memory"` and `:memory` are the same store.
+
+### Registry API
+
+```ruby
+RailsNamedCache.register(:memory, ActiveSupport::Cache::MemoryStore.new)
+RailsNamedCache.fetch(:memory)      # => the store (UnknownStoreError if missing)
+RailsNamedCache.registered?(:redis) # => false
+RailsNamedCache.names               # => [:memory]
+RailsNamedCache.registry.to_h       # => { memory: #<MemoryStore> }
+RailsNamedCache.reset!              # empties the registry (tests)
+```
+
+Registration is by name, so stores registered by hand from an initializer survive boot unless
+`config.named_cache_stores` names the same store.
+
+## FAQ
+
+**Why not global constants?**
+Configuration ends up outside `config/`, tests stub constants, and nothing lists which caches exist.
+
+**Forking servers (Puma workers, Unicorn, `preload_app!`)?**
+Same caveat as `config.cache_store`: stores are built at boot, so with preloading they exist before
+the fork. Pass connection-based stores as configuration (`[:redis_cache_store, { url: ... }]`)
+rather than a live client — Rails connects lazily per worker, while a pre-connected socket shared
+across forks corrupts.
+
+**Do named stores get the per-request local cache?**
+No. Rails inserts `LocalCache::Middleware` for the default `Rails.cache` only, so two identical
+reads in one request hit the backend twice. Nothing leaks — the local cache is inert — and you can
+opt in with `Rails.cache(:redis).with_local_cache { ... }`.
+
+**Overhead?**
+One `Concurrent::Map` read per lookup, lock-free. Stores are instantiated once at boot.
+
+**Outside Rails?**
+`RailsNamedCache.register` / `.fetch` work anywhere; `Rails.cache(:name)` and
+`config.named_cache_stores` need an application. Requiring the gem always loads `rails/railtie`, so
+load order never matters.
+
+**Built-in L1/L2?**
+No — [five lines](#l1l2-memory-in-front-of-redis) in app code, and a built-in version would have to
+guess your staleness window. `Rails.cache(:memory, fallback: :redis)` stays possible later without
+breaking the API.
+
+## Be careful
+
+Named stores make it easy to add caches, which makes it easy to add these:
+
+- **Memory multiplies.** `MemoryStore` defaults to `size: 32.megabytes` when you omit it — five
+  named stores is up to 160 MB *per process*, times your Puma workers, times your servers. Set
+  `size:` on every `MemoryStore` explicitly and size it against the container limit, not the host.
+- **A `MemoryStore` is one lock.** A `Monitor` guards reads *and* writes, so all threads in the
+  process serialize on it; the ~3 µs above is single-threaded. Pruning also runs inside that lock
+  (bounded by `max_prune_time`, default 2 s), so an oversized store can stall every thread. Prefer
+  several small stores over one huge hot one.
+- **TTL does not reclaim memory.** Expired entries are dropped when read or on `cleanup`; eviction
+  happens on write once the store exceeds `size`, pruning back to 75%. A store full of expired
+  entries nobody reads still occupies RAM.
+- **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).
+- **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).
+- **Cache plain data, not objects.** Storing ActiveRecord instances or anything class-bound in a
+  long-lived in-process store outlives code reloading in development and keeps stale classes alive.
+  Arrays, hashes, strings and numbers stay cheap to deep-copy too.
+- **Never take a store name from user input.** `Rails.cache(params[:store])` raises, and the error
+  message lists every registered store name.
+- **Do not create a store per model.** Splitting one working set across many small caches lowers
+  the overall hit rate, and every configured store is built at boot whether anything reads it or
+  not. Add a store when a value genuinely needs a different backend, size or TTL — otherwise
+  `Rails.cache` is still the right answer.
+- **Pass connection-based stores as configuration**, not as a live client object, or a preloading
+  forking server will share one socket across workers.
+
+## Compatibility
+
+| | |
+| --- | --- |
+| Ruby | 3.3, 3.4, 4.0 |
+| Rails | 7.0, 7.1, 7.2, 8.0, 8.1 |
+
+Every combination runs in CI. Note the Ruby floor: an older Rails is only supported on a modern
+Ruby, so a Rails 7.0 app still on Ruby 3.1 cannot install this gem.
+
+Rails 6.0 and 6.1 work but are neither supported nor tested — the runtime uses no API newer than
+Rails 6.0, so relaxing the constraint locally is enough.
+
+## Development
+
+```bash
+bundle exec rake          # specs + rubocop
+
+BUNDLE_GEMFILE=gemfiles/rails_7.0.gemfile bundle exec rspec   # one Rails version
+ls gemfiles/*.gemfile     # rails_7.0 … rails_8.1
+```
+
+The suite boots a real (tiny) Rails app in a tmpdir, so boot wiring is covered end to end. Design
+rules live in [AGENTS.md](https://github.com/igorkasyanchuk/rails_named_cache/blob/main/AGENTS.md).
+
+## Contributing
+
+Bug reports and pull requests welcome at
+<https://github.com/igorkasyanchuk/rails_named_cache>. Keep `bundle exec rake` green and add a spec
+for anything that changes behaviour.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module RailsNamedCache
+  module Generators
+    # Creates +config/initializers/rails_named_cache.rb+ with a default
+    # 1 MB MemoryStore registered as +:memory+.
+    #
+    #   rails generate rails_named_cache:install
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates config/initializers/rails_named_cache.rb with a default memory store."
+
+      # @return [void]
+      def copy_initializer
+        template "rails_named_cache.rb", "config/initializers/rails_named_cache.rb"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Named cache stores, read back with Rails.cache(:name):
+#
+#   Rails.cache(:memory).fetch("key") { expensive }
+#   Rails.cache(:memory).fetch("key", expires_in: 5.minutes) { expensive }
+#
+# Each store gets its own backend, size limit and default TTL. A store without
+# expires_in keeps entries until they are overwritten, deleted or evicted.
+# Rails.cache and config.cache_store are untouched.
+
+Rails.application.configure do
+  config.named_cache_stores = {
+    # In-process and microsecond-fast, but per-process: every Puma worker has its
+    # own copy and it dies with the process. Nothing invalidates it from outside,
+    # so shorten the TTL for anything that changes and must not go stale.
+    memory: ActiveSupport::Cache::MemoryStore.new(size: 1.megabyte, expires_in: 1.day),
+
+    # Shared by every process and server. namespace: is required if another named
+    # store points at the same Redis — otherwise they share one keyspace and
+    # clearing either one wipes both.
+    # redis: ActiveSupport::Cache::RedisCacheStore.new(
+    #   url: ENV.fetch("REDIS_URL"),
+    #   namespace: "pricing",
+    #   expires_in: 1.hour
+    # ),
+
+    # On disk: survives restarts, local to one machine. Suits large payloads that
+    # are cheap to store and expensive to rebuild.
+    # disk: ActiveSupport::Cache::FileStore.new(
+    #   Rails.root.join("tmp/cache/reports"),
+    #   expires_in: 1.day
+    # ),
+
+    # Caches nothing. Useful per environment, e.g. in config/environments/test.rb.
+    # null: ActiveSupport::Cache::NullStore.new
+  }
+end

data/lib/rails_named_cache/configuration.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module RailsNamedCache
+  # Turns the raw +config.named_cache_stores+ value into cache store instances.
+  #
+  # Values may be:
+  #
+  # * an +ActiveSupport::Cache::Store+ instance (used as-is)
+  # * anything +ActiveSupport::Cache.lookup_store+ understands, e.g.
+  #   +:memory_store+ or +[:redis_cache_store, { url: ENV["REDIS_URL"] }]+
+  #
+  # Configuration only resolves and validates; it never stores anything. The
+  # {Registry} owns state.
+  #
+  # @example
+  #   RailsNamedCache::Configuration.new(
+  #     memory: ActiveSupport::Cache::MemoryStore.new(size: 1.megabyte),
+  #     redis: [:redis_cache_store, { url: ENV.fetch("REDIS_URL") }]
+  #   ).resolved_stores
+  #   # => { memory: #<MemoryStore>, redis: #<RedisCacheStore> }
+  class Configuration
+    # @return [Hash] the raw configured value
+    attr_reader :stores
+
+    # @param stores [Hash{Symbol=>Object}, nil] raw +config.named_cache_stores+
+    # @raise [ConfigurationError] if +stores+ is not a Hash
+    def initialize(stores = {})
+      stores ||= {}
+
+      unless stores.is_a?(Hash)
+        raise ConfigurationError,
+              "config.named_cache_stores must be a Hash of name => cache store, got #{stores.class}"
+      end
+
+      @stores = stores
+    end
+
+    # @return [Hash{Symbol=>ActiveSupport::Cache::Store}] name => store instance
+    # @raise [ConfigurationError] for duplicate names or values that cannot become a cache store
+    def resolved_stores
+      stores.each_with_object({}) do |(name, value), resolved|
+        key = RailsNamedCache.normalize_name(name)
+
+        # "memory" and :memory are the same store; silently keeping the last one
+        # would hide a typo in config.
+        if resolved.key?(key)
+          raise ConfigurationError,
+                "Duplicate named cache store #{key.inspect} in config.named_cache_stores"
+        end
+
+        resolved[key] = resolve(key, value)
+      end
+    end
+
+    private
+
+    # @param name [Symbol]
+    # @param value [Object]
+    # @return [ActiveSupport::Cache::Store]
+    def resolve(name, value)
+      return value if value.is_a?(ActiveSupport::Cache::Store)
+
+      # nil would make lookup_store silently hand back a MemoryStore.
+      raise ConfigurationError, "Named cache store #{name.inspect} is nil" if value.nil?
+
+      store = ActiveSupport::Cache.lookup_store(value)
+      return store if store.is_a?(ActiveSupport::Cache::Store)
+
+      raise ConfigurationError,
+            "Named cache store #{name.inspect} must be an ActiveSupport::Cache::Store, " \
+            "got #{value.class}"
+    end
+  end
+end

data/lib/rails_named_cache/rails_ext.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module RailsNamedCache
+  # Prepended onto the +Rails+ singleton class so +Rails.cache+ takes an
+  # optional store name.
+  #
+  # This is the only monkey patch in the gem.
+  #
+  #   Rails.cache          # => the default Rails cache, untouched
+  #   Rails.cache(:memory) # => the store registered as :memory
+  module RailsExt
+    # Splat rather than a +nil+ default, so +Rails.cache(name)+ with a +nil+
+    # name raises instead of quietly reading the default store.
+    #
+    # @param name [Array<Symbol, String>] zero arguments, or one registered store name
+    # @return [ActiveSupport::Cache::Store]
+    # @raise [ConfigurationError] if +name+ is present but not a non-empty Symbol or String
+    # @raise [UnknownStoreError] if +name+ was never registered
+    def cache(*name)
+      return super() if name.empty?
+
+      RailsNamedCache.fetch(*name)
+    end
+  end
+end

data/lib/rails_named_cache/railtie.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module RailsNamedCache
+  # Wires the gem into the Rails boot process.
+  #
+  # 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)+.
+  class Railtie < ::Rails::Railtie
+    config.named_cache_stores = {}
+
+    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)
+    end
+  end
+end

data/lib/rails_named_cache/registry.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "concurrent/map"
+
+module RailsNamedCache
+  # Thread-safe store of named +ActiveSupport::Cache::Store+ instances.
+  #
+  # Lookups are O(1) and lock-free; writes happen once during boot.
+  #
+  # @example
+  #   registry = RailsNamedCache::Registry.new
+  #   registry.register(:memory, ActiveSupport::Cache::MemoryStore.new)
+  #   registry.fetch(:memory) # => #<ActiveSupport::Cache::MemoryStore>
+  class Registry
+    def initialize
+      @stores = Concurrent::Map.new
+    end
+
+    # Registers +store+ under +name+, replacing any previous entry.
+    #
+    # @param name [Symbol, String] name used by +Rails.cache(name)+
+    # @param store [ActiveSupport::Cache::Store] the store instance
+    # @return [ActiveSupport::Cache::Store] the registered store
+    # @raise [ConfigurationError] if +name+ is blank or +store+ is not a cache store
+    def register(name, store)
+      key = RailsNamedCache.normalize_name(name)
+
+      unless store.is_a?(ActiveSupport::Cache::Store)
+        raise ConfigurationError,
+              "Named cache store #{key.inspect} must be an ActiveSupport::Cache::Store, " \
+              "got #{store.class}"
+      end
+
+      @stores[key] = store
+    end
+
+    # @param name [Symbol, String] registered store name
+    # @return [ActiveSupport::Cache::Store]
+    # @raise [ConfigurationError] if +name+ is not a non-empty Symbol or String
+    # @raise [UnknownStoreError] if nothing is registered under +name+
+    def fetch(name)
+      key = RailsNamedCache.normalize_name(name)
+      @stores.fetch(key) { raise UnknownStoreError.new(key, names) }
+    end
+
+    # @param name [Symbol, String]
+    # @return [Boolean]
+    # @raise [ConfigurationError] if +name+ is not a non-empty Symbol or String
+    def registered?(name)
+      @stores.key?(RailsNamedCache.normalize_name(name))
+    end
+
+    # @return [Array<Symbol>] every registered name
+    def names
+      @stores.keys
+    end
+
+    # @return [Integer] number of registered stores
+    def size
+      @stores.size
+    end
+
+    # Removes every registered store. Intended for tests and reboots.
+    #
+    # @return [void]
+    def clear
+      @stores.clear
+    end
+
+    # @return [Hash{Symbol=>ActiveSupport::Cache::Store}] snapshot of the registry
+    def to_h
+      @stores.each_pair.to_h
+    end
+  end
+end

data/lib/rails_named_cache/version.rb

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

data/lib/rails_named_cache.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require "active_support"
+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/rails_ext"
+
+# Named +ActiveSupport::Cache::Store+ instances for Rails applications.
+#
+# Register stores through +config.named_cache_stores+ and read them back with
+# +Rails.cache(:name)+.
+#
+# @example
+#   Rails.cache.fetch("users") { User.all }          # default Rails cache
+#   Rails.cache(:memory).fetch("countries") { ... }  # named store
+module RailsNamedCache
+  # Base class for every error raised by this gem.
+  class Error < StandardError; end
+
+  # Raised when +config.named_cache_stores+ holds something that cannot become
+  # a cache store.
+  class ConfigurationError < Error; end
+
+  # Raised when a named cache store is looked up but was never registered.
+  #
+  #   Rails.cache(:nope)
+  #   # => RailsNamedCache::UnknownStoreError:
+  #   #      Unknown named cache store :nope
+  #   #
+  #   #      Available stores:
+  #   #      :memory
+  class UnknownStoreError < Error
+    # @return [Symbol] the requested name
+    attr_reader :name
+
+    # @return [Array<Symbol>] the registered names
+    attr_reader :available
+
+    # @param name [Symbol] requested store name
+    # @param available [Array<Symbol>] registered store names
+    def initialize(name, available)
+      @name = name
+      # Sorted so the message is deterministic regardless of registration order.
+      @available = available.sort
+      listed = @available.empty? ? "(none registered)" : @available.map(&:inspect).join("\n")
+      super("Unknown named cache store #{name.inspect}\n\nAvailable stores:\n#{listed}")
+    end
+  end
+
+  # The process-wide registry.
+  #
+  # @return [Registry]
+  REGISTRY = Registry.new
+
+  class << self
+    # @return [Registry] the process-wide registry
+    def registry
+      REGISTRY
+    end
+
+    # Registers a cache store under +name+.
+    #
+    # @param name [Symbol, String]
+    # @param store [ActiveSupport::Cache::Store]
+    # @return [ActiveSupport::Cache::Store]
+    def register(name, store)
+      registry.register(name, store)
+    end
+
+    # @param name [Symbol, String]
+    # @return [ActiveSupport::Cache::Store]
+    # @raise [UnknownStoreError]
+    def fetch(name)
+      registry.fetch(name)
+    end
+
+    # @param name [Symbol, String]
+    # @return [Boolean]
+    def registered?(name)
+      registry.registered?(name)
+    end
+
+    # @return [Array<Symbol>] every registered name
+    def names
+      registry.names
+    end
+
+    # Registers every store described by +config.named_cache_stores+.
+    #
+    # @param stores [Hash{Symbol=>Object}, nil] raw configuration value
+    # @return [Array<Symbol>] the names that were registered
+    def load_configuration(stores)
+      Configuration.new(stores).resolved_stores.each do |name, store|
+        register(name, store)
+      end.keys
+    end
+
+    # Teaches +Rails.cache+ to accept an optional name. Idempotent, and a no-op
+    # when the gem is used outside Rails.
+    #
+    # @return [void]
+    def install!
+      return if !defined?(::Rails) || ::Rails.singleton_class.include?(RailsExt)
+
+      ::Rails.singleton_class.prepend(RailsExt)
+      nil
+    end
+
+    # Empties the registry. Intended for tests.
+    #
+    # @return [void]
+    def reset!
+      registry.clear
+    end
+
+    # Coerces a store name to a Symbol.
+    #
+    # Shared by {Registry} and {Configuration} so a bad name fails the same way
+    # whether it came from configuration or from a direct call.
+    #
+    # @api private
+    # @param name [Symbol, String]
+    # @return [Symbol]
+    # @raise [ConfigurationError] if +name+ is not a non-empty Symbol or String
+    def normalize_name(name)
+      unless (name.is_a?(Symbol) || name.is_a?(String)) && !name.to_s.empty?
+        raise ConfigurationError,
+              "Cache store name must be a non-empty Symbol or String, got #{name.inspect}"
+      end
+
+      name.to_sym
+    end
+  end
+end
+
+# Unconditional: railties is a runtime dependency, and guarding this on
+# defined?(Rails::Railtie) turns the gem into a silent no-op whenever it is
+# required before Rails.
+require_relative "rails_named_cache/railtie"
+
+RailsNamedCache.install!

metadata

@@ -0,0 +1,121 @@
+--- !ruby/object:Gem::Specification
+name: rails_named_cache
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Igor Kasyanchuk
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+description: |
+  rails_named_cache lets a Rails application register several
+  ActiveSupport::Cache::Store instances by name and read them back with
+  Rails.cache(:memory), Rails.cache(:redis), Rails.cache(:pricing) and so on.
+  Rails.cache keeps working exactly as before, stores are never wrapped, and
+  no new caching API is introduced.
+email:
+- igorkasyanchuk@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/generators/rails_named_cache/install/install_generator.rb
+- 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/rails_ext.rb
+- lib/rails_named_cache/railtie.rb
+- lib/rails_named_cache/registry.rb
+- lib/rails_named_cache/version.rb
+homepage: https://github.com/igorkasyanchuk/rails_named_cache
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/igorkasyanchuk/rails_named_cache
+  source_code_uri: https://github.com/igorkasyanchuk/rails_named_cache
+  changelog_uri: https://github.com/igorkasyanchuk/rails_named_cache/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/igorkasyanchuk/rails_named_cache/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: Multiple named cache stores for Rails, through Rails.cache(:name).
+test_files: []