Response cache middleware
Este conteúdo não está disponível em sua língua ainda.
cached wraps a handler with response caching keyed by a
user-supplied key(req) function. A cache hit serves the
stored response without invoking the underlying handler.
import { cached, path, get } from 'actor-ts/http';import { InMemoryCache } from 'actor-ts/cache';
const productCache = cached({ cache: new InMemoryCache(), ttlMs: 30_000, key: (req) => `products:${pathParam(req, 'id')}`,});
const routes = path('api', path('products', get(productCache(async (req) => /* expensive lookup */)), ),);Cache for 30 seconds per product ID. First request hits the
handler; subsequent GETs in the next 30 s return the cached
response. A request that carries credentials bypasses the cache
until identity is set — see what is never shared.
Configuration
Section titled “Configuration”type ResponseCacheOptions = { cache: Cache; ttlMs: number; key: (req: HttpRequest) => string | Promise<string>; keyPrefix?: string; // default 'rsp:' cacheStatuses?: ReadonlyArray<number>; // default [200] identity?: (req: HttpRequest) => string | Promise<string>;};| Field | Purpose |
|---|---|
cache | The Cache backend. InMemoryCache for single-node; Redis for shared. |
ttlMs | How long each cached response stays valid. |
key(req) | Derive the cache key from the request — typically includes URL params, tenant ID, accept header etc. Required. |
keyPrefix | Cache-key namespace. Default 'rsp:' so multiple response-caches in the same Redis don’t collide. |
cacheStatuses | Which status codes are cacheable. Default [200] — only 2xx responses get cached. |
identity(req) | Optional per-caller scope folded into the key, so a response is only replayed to the caller it was produced for. Also the opt-in for caching requests that carry credentials — see what is never shared. Derive it from a verified identity, never from a raw header. |
Cache key composition
Section titled “Cache key composition”The key(req) function is the entire cache-key contract — what
you include there determines what’s cached separately. Common
patterns:
// Per-URL-path key:key: (req) => req.path,
// Per-tenant:key: (req) => `${req.headers['x-tenant-id'] ?? 'public'}:${req.path}`,
// Per-locale + content type:key: (req) => `${req.headers['accept-language']}:${req.headers['accept']}:${req.path}`,
// Query-sensitive — the query is NOT part of req.path:key: (req) => `${req.path}|page=${req.query.page ?? '1'}`,req.path is the pathname only — /api/products, never
/api/products?page=2. An endpoint whose response varies by a query
parameter has to fold that parameter into the key itself; otherwise
every page shares one entry and page 2 is served page 1.
Build the key to be deterministic across equivalent requests but unique across responses you want cached separately.
When to cache
Section titled “When to cache”GET /api/products → cache (stable, read-heavy)POST /api/orders → passes straight through — only GET is storedGET /api/users/me → cache only with identity (per-caller scope)GET /api/feed?cursor=X → cache (one entry per cursor)The wrapper is a handler-level decision — you choose which
handlers to wrap. Mutations should typically use
idempotent instead.
What is never shared
Section titled “What is never shared”A cache hit returns before the wrapped handler runs. Any check
inside the handler — authentication, authorization, a per-caller
lookup — therefore runs for the first caller only. Authorization
has to wrap cached(...), never sit inside it:
import { cached, get, JwtAuth, jwtClaimsOf, path, withMiddleware } from 'actor-ts/http';
const profileCache = cached({ cache: ext.cache('response-cache'), ttlMs: 30_000, key: () => 'users:me', identity: (req) => jwtClaimsOf(req)?.sub ?? 'anonymous',});
// ✓ JwtAuth verifies the token on every request, hit or missconst routes = withMiddleware(JwtAuth(jwtOptions), path('me', get(profileCache(loadProfile))),);// ✗ a check inside loadProfile is skipped by every hitBeyond that, the wrapper refuses on its own every case in which one caller’s response could reach another:
| Rule | Why |
|---|---|
Only GET is stored; only GET and HEAD are answered from the cache. | A replayed POST is never right. HEAD reads a GET entry but never writes one, because a HEAD answer may carry no body. |
A request carrying Authorization, Proxy-Authorization or Cookie bypasses the cache unless identity is set. | Nothing else in the key says whose response it is. Setting identity is the explicit opt-in; for an endpoint that genuinely does not depend on the caller, identity: () => 'public' says exactly that. |
A response carrying Set-Cookie is not stored. | There is no correct way to hand one caller’s cookie to another. |
Cache-Control: no-store, no-cache or private on the response suppresses storing. | The handler said the response is not for a shared cache. |
A response carrying Vary is stored with a SHA-256 digest of the request’s values of the named headers and served only to a request whose values digest the same; Vary: * is not stored. | The handler said the response depends on those headers. Only the digests are written, so a Vary: Authorization response never puts a bearer token or cookie into the backing cache. The digest is unsalted, so every process sharing the backend computes the same one — a high-entropy token cannot be recovered from it, but a weak password inside Basic credentials stays guessable offline by whoever can read the backend. |
| A streaming body is not stored. | A stream is one-shot. |
These rules are about sharing, not a full Cache-Control
implementation: freshness directives such as max-age=0 or
must-revalidate are not interpreted, and ttlMs alone bounds how
long an entry is served.
The same rules govern stampede protection: a request waiting on
another request’s in-flight handler takes that response only when the
rules above would let the two share it, and otherwise runs the handler
itself. cacheStatuses decides what is stored, not what is
shared — a 404 outside it is never written to the cache, but the
concurrent waiters still take it. Cache-Control on the request
is deliberately ignored — a client must not be able to force the
handler past the cache.
Cache invalidation
Section titled “Cache invalidation”cached doesn’t auto-invalidate on writes — staleness is
bounded by ttlMs.
For stronger consistency, two patterns:
Short TTLs
Section titled “Short TTLs”cached({ cache, ttlMs: 1_000, key }); // 1 secondSub-second TTLs limit staleness. Good for “real-time-ish” APIs.
Manual invalidation
Section titled “Manual invalidation”// After a write that affects products:42, invalidate the cache:await cache.delete('rsp:products:42'); // 'rsp:' is the default keyPrefixThe cache is just a Cache — you can delete the prefixed key
directly when a write should invalidate it. With identity set, the
key is <keyPrefix><scope>:<key> with the scope URI-encoded, so build
it the same way:
// After a write to the profile of the caller whose identity scope is `sub`:await cache.delete(`rsp:${encodeURIComponent(sub)}:users:me`);A scope like auth0|abc is stored as auth0%7Cabc; a key spelled with
the raw scope deletes nothing.
Shared cache across pods
Section titled “Shared cache across pods”import { RedisCache, RedisCacheOptions } from 'actor-ts/cache';
const redisCacheOptions = RedisCacheOptions.create().withUrl('redis://...');const productCache = cached({ cache: new RedisCache(redisCacheOptions), ttlMs: 30_000, key: (req) => `products:${pathParam(req, 'id')}`,});With a Redis-backed cache, all pods share the same cache — useful for multi-pod deployments where you want consistent caching.
For per-pod caches (each pod has its own InMemoryCache), pods may serve different cached responses briefly until TTLs align. Often acceptable; depends on consistency requirements.
A shared cache outlives a deploy, so it can hold entries written
before the sharing rules existed. Each one is re-checked before it is
served, and one carrying Set-Cookie, an unshareable Cache-Control,
Vary: * or a Vary without recorded request values is treated as a
miss — but an entry minted from a credentialed request whose response
carried neither Set-Cookie nor Vary looks exactly like a public one
and is served until it expires. When upgrading from a version without
these rules, wait until the last old pod is gone — it keeps writing
such entries — and then flush the keyPrefix (rsp: by default) or
let ttlMs elapse before relying on them.
Caching different status codes
Section titled “Caching different status codes”cached({ cache, ttlMs: 30_000, key, cacheStatuses: [200, 404], // cache both hits AND "not found"s});Cache 404s when you’ve got many lookups for IDs that don’t
exist — saves repeat DB hits. Defaults to [200] only so a
transient 500 never sticks around for 30 seconds.
Where to next
Section titled “Where to next”- HTTP overview — the bigger picture.
- Rate limit middleware — complementary middleware.
- Idempotency-key middleware — for write-dedup.
- Cache overview — the backend this middleware uses.
