skip to content

In Rails 8.1, what is the per-request local cache that stores such as :solid_cache_store and :redis_cache_store wrap around themselves, and when does it surprise you?

level: seniorimportance: nice to knowfreq 16%

answer

  1. a hash in front of the store
  2. Strategy::LocalCache middleware
  3. inserted before Rack::Runtime
  4. misses are memoized too
  5. jobs need with_local_cache

basics

~20 s

Stores that include ActiveSupport::Cache::Strategy::LocalCache keep a per-request, per-thread hash in front of the backend: the first read of a key hits the store, later reads in the same request come from memory, including recorded misses, and writes update both.

solid answer

~40 s

`ActiveSupport::Cache::Strategy::LocalCache` is prepended into `RedisCacheStore`, `MemCacheStore`, `NullStore`, `SolidCache::Store` and, since 8.1.2, `MemoryStore`; `FileStore` does not have it. At boot Rails inserts the store's `middleware` before `Rack::Runtime`; for each request it creates an in-memory `LocalStore` keyed per thread or fiber and discards it when the response body closes. The first read of a key goes to the backend and the result, hit or miss, is memoized; repeated reads are served locally; writes and deletes go to both. Surprises: a value another process changes mid-request is not seen; under `:null_store` in a test request, a write followed by a read returns the value; and jobs, the console and runners get no local cache unless you wrap code in `Rails.cache.with_local_cache`.

code

ruby · 10 lines
ruby
class RebuildDigestsJob < ApplicationJob
  def perform(petition_ids)
    Rails.cache.with_local_cache do
      petition_ids.each do |id|
        settings = Rails.cache.fetch("digest-settings") { DigestSettings.load }
        DigestBuilder.new(id, settings).call
      end
    end
  end
end

go deeper

for a junior

Know that Rails keeps a short-lived in-memory copy of cache reads for each web request, so reading the same key twice in one request costs one trip to the store.

for a middle

Explain how the middleware sets the local store up and tears it down, why misses are memoized, and why writes update both the local hash and the backend.

for a senior

Use it to explain odd behaviour: stale values within long requests, :null_store tests that seem to cache, and jobs that hammer the store until wrapped in with_local_cache.

for a principal

Consider the local cache when budgeting backend round trips per request, and set guidelines for long-running jobs so repeated cache reads stay cheap without hiding staleness.

## What the local cache is A networked store pays a round trip for every read. Pages often read the same key several times, for example a feature flag or a settings hash read by several partials. **`ActiveSupport::Cache::Strategy::LocalCache`** removes the repeats: it keeps a small in-memory hash, a **`LocalStore`**, in front of the real store for the duration of a block, and the web request is that block. ## Which stores have it | Store | Local cache | |---|---| | `:redis_cache_store` | yes | | `:mem_cache_store` | yes | | `:solid_cache_store` | yes (`SolidCache::Store` prepends it) | | `:null_store` | yes | | `:memory_store` | yes since Rails 8.1.2, added so it answers the same interface | | `:file_store` | no | ## How Rails wires it into requests 1. The `initialize_cache` initializer builds `Rails.cache` and, if the store responds to `middleware`, inserts it before `Rack::Runtime`. It appears in `bin/rails middleware` as `ActiveSupport::Cache::Strategy::LocalCache::Middleware`. 2. For each request the middleware calls `new_local_cache`, which registers a fresh `LocalStore` in `ActiveSupport::IsolatedExecutionState`, so each thread (or fiber, depending on the isolation level) serving a request has its own. 3. When the response body is closed, a `Rack::BodyProxy` calls `unset_local_cache`, so nothing outlives the request. ## Read and write rules - **First read** of a key: the local store has nothing, so the real store is queried and whatever comes back, an entry or `nil`, is saved locally. - **Repeated reads** in the same request: answered from the hash. That includes a recorded **miss**: a second read of a missing key returns `nil` without asking the backend again. - **Writes**: go to the backend; if it accepts the write, the payload is also stored locally, otherwise the local entry is deleted. - **Deletes**: remove the local entry and the backend entry. - **`increment` / `decrement`**: bypass the local copy, run on the backend, then store the new value locally. - **`clear`, `cleanup`, `delete_matched`**: empty the local store as well. Expired or version-mismatched local entries are thrown away on read, so `expires_in:` and `version:` still hold within a request. ## When it surprises people 1. **Stale within a request.** If another process writes the key after this request first read it, this request keeps the value it saw. For a long request that reads a value, waits on something slow, then reads it again expecting a change, the second read will not see the change. 2. **`:null_store` that seems to store.** `NullStore` accepts writes and returns `true`, so inside a request the local cache keeps the payload. An integration test that writes and then reads in the same request sees the value even though the generated test store is `:null_store`; the next request sees nothing. 3. **No local cache outside requests.** Only the middleware creates one. Active Job jobs, `bin/rails runner` and the console run without it, so a job that reads the same key in a loop hits the backend every time. Wrapping the work in **`Rails.cache.with_local_cache { ... }`** gives it the same memoization. 4. **Different stores, different behaviour.** Because `:file_store` has no local cache and `:memory_store` gained one only in 8.1.2, code that read a key repeatedly can behave differently after switching stores or upgrading. ## Why it matters in interviews It explains logs that show one cache read where the code makes three, test results that differ between a request spec and a model test under the same `:null_store`, and job performance that is worse than the same code in a controller. Knowing the mechanism, a middleware plus a per-thread hash, is enough to reason through all three.

  • Why does a request spec under the generated `:null_store` see a value it wrote, while a model test does not?
    The request runs through the `LocalCache` middleware, so the `NullStore` write, which returns `true`, is memoized in the request's local store and the next read returns it. A model test calls `Rails.cache` outside any request, where no local cache exists, so the null store's read misses.
  • Can the local cache leak data between two users' requests on the same Puma server?
    Not by design. Each request gets a new `LocalStore` registered per thread or fiber in `IsolatedExecutionState`, and the middleware unsets it when the response body closes. Values cross requests only through the shared backend, as they would without the local cache.

  • Every Rails cache store, including :file_store, has a local cache.
  • The local cache keeps values between requests to save backend trips.
  • Background jobs get a local cache automatically, like web requests.
  • A miss is never memoized, so every repeated read of a missing key queries the backend.
  • :null_store can never return a value, even inside a request.

Assumes Rails 8.1.4; MemoryStore gained the LocalCache strategy in Rails 8.1.2, and FileStore still has none.