Response-Cache-Middleware
cached umhüllt einen Handler mit Response-Caching, verschlüsselt
über eine selbst gelieferte key(req)-Funktion. Ein Cache-Treffer
liefert die gespeicherte Response, ohne den darunterliegenden Handler
aufzurufen.
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 */)), ),);30 Sekunden Cache pro Produkt-ID. Der erste Request trifft den
Handler; nachfolgende GETs in den nächsten 30 s liefern die gecachte
Response. Ein Request mit Credentials umgeht den Cache, bis
identity gesetzt ist — siehe was nie geteilt wird.
Konfiguration
Abschnitt betitelt „Konfiguration“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>;};| Feld | Zweck |
|---|---|
cache | Das Cache-Backend. InMemoryCache für Single-Node; Redis für geteilt. |
ttlMs | Wie lange jede gecachte Response gültig bleibt. |
key(req) | Leitet den Cache-Key aus dem Request ab — enthält typischerweise URL-Params, Tenant-ID, Accept-Header usw. Pflicht. |
keyPrefix | Cache-Key-Namespace. Default 'rsp:', damit sich mehrere Response-Caches im selben Redis nicht überschneiden. |
cacheStatuses | Welche Status-Codes cachebar sind. Default [200] — nur 2xx-Responses werden gecacht. |
identity(req) | Optionaler Scope pro Aufrufer, der in den Key gefaltet wird, damit eine Response nur dem Aufrufer wieder ausgeliefert wird, für den sie entstand. Zugleich das Opt-in, Requests mit Credentials zu cachen — siehe was nie geteilt wird. Leite ihn aus einer verifizierten Identität ab, nie aus einem rohen Header. |
Cache-Key-Zusammensetzung
Abschnitt betitelt „Cache-Key-Zusammensetzung“Die key(req)-Funktion ist der gesamte Cache-Key-Vertrag — was du
dort aufnimmst, bestimmt, was separat gecacht wird. Gängige Muster:
// 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 ist nur der Pfadname — /api/products, nie
/api/products?page=2. Ein Endpunkt, dessen Response von einem
Query-Parameter abhängt, muss diesen Parameter selbst in den Key
falten; sonst teilen sich alle Seiten einen Eintrag und Seite 2
bekommt Seite 1 ausgeliefert.
Baue den Key so, dass er über äquivalente Requests deterministisch, aber über getrennt zu cachende Responses eindeutig ist.
Wann cachen
Abschnitt betitelt „Wann cachen“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)Der Wrapper ist eine Handler-Ebenen-Entscheidung — du wählst, welche
Handler du umhüllst. Mutationen sollten typischerweise
idempotent verwenden.
Was nie geteilt wird
Abschnitt betitelt „Was nie geteilt wird“Ein Cache-Treffer kehrt zurück, bevor der umhüllte Handler läuft.
Jede Prüfung im Handler — Authentifizierung, Autorisierung, ein
Lookup pro Aufrufer — läuft deshalb nur für den ersten Aufrufer.
Die Autorisierung muss cached(...) umhüllen, nie darin sitzen:
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 hitDarüber hinaus verweigert der Wrapper von sich aus jeden Fall, in dem die Response eines Aufrufers einen anderen erreichen könnte:
| Regel | Warum |
|---|---|
Nur GET wird gespeichert; nur GET und HEAD werden aus dem Cache beantwortet. | Ein wiederholtes POST ist nie richtig. HEAD liest einen GET-Eintrag, schreibt aber nie einen, weil eine HEAD-Antwort ohne Body auskommen darf. |
Ein Request mit Authorization, Proxy-Authorization oder Cookie umgeht den Cache, solange identity nicht gesetzt ist. | Sonst sagt nichts im Key, wessen Response es ist. identity zu setzen ist das ausdrückliche Opt-in; für einen Endpunkt, der wirklich nicht vom Aufrufer abhängt, sagt identity: () => 'public' genau das. |
Eine Response mit Set-Cookie wird nicht gespeichert. | Es gibt keinen korrekten Weg, das Cookie eines Aufrufers einem anderen zu geben. |
Cache-Control: no-store, no-cache oder private auf der Response unterdrückt das Speichern. | Der Handler hat gesagt, dass die Response nicht in einen geteilten Cache gehört. |
Eine Response mit Vary wird zusammen mit einem SHA-256-Digest der Werte der genannten Request-Header gespeichert und nur an einen Request ausgeliefert, dessen Werte denselben Digest ergeben; Vary: * wird nicht gespeichert. | Der Handler hat gesagt, dass die Response von diesen Headern abhängt. Geschrieben werden nur die Digests, eine Vary: Authorization-Response legt also nie ein Bearer-Token oder Cookie im zugrunde liegenden Cache ab. Der Digest ist ungesalzen, damit jeder Prozess am selben Backend denselben berechnet — aus einem Token mit hoher Entropie lässt er sich nicht zurückgewinnen, ein schwaches Passwort in Basic-Credentials bleibt für jeden, der das Backend lesen kann, aber offline erratbar. |
| Ein streamender Body wird nicht gespeichert. | Ein Stream ist einmalig lesbar. |
Diese Regeln betreffen das Teilen, sie sind keine vollständige
Cache-Control-Implementierung: Frische-Direktiven wie max-age=0
oder must-revalidate werden nicht ausgewertet, und allein ttlMs
begrenzt, wie lange ein Eintrag ausgeliefert wird.
Dieselben Regeln gelten für den Stampede-Schutz: Ein Request, der auf
den laufenden Handler eines anderen Requests wartet, übernimmt dessen
Response nur, wenn die Regeln oben den beiden erlauben, sie zu teilen,
und führt den Handler sonst selbst aus. cacheStatuses entscheidet,
was gespeichert wird, nicht, was geteilt wird — ein 404
außerhalb davon wird nie in den Cache geschrieben, die gleichzeitig
Wartenden übernehmen es aber trotzdem. Cache-Control auf dem
Request wird bewusst ignoriert — ein Client darf den Handler nicht
am Cache vorbei erzwingen können.
Cache-Invalidierung
Abschnitt betitelt „Cache-Invalidierung“cached invalidiert nicht automatisch bei Writes — die
Veraltung ist durch ttlMs begrenzt.
Für stärkere Konsistenz zwei Muster:
Kurze TTLs
Abschnitt betitelt „Kurze TTLs“cached({ cache, ttlMs: 1_000, key }); // 1 secondSub-Sekunden-TTLs begrenzen die Veraltung. Gut für „echtzeit-nahe” APIs.
Manuelle Invalidierung
Abschnitt betitelt „Manuelle Invalidierung“// After a write that affects products:42, invalidate the cache:await cache.delete('rsp:products:42'); // 'rsp:' is the default keyPrefixDer Cache ist einfach ein Cache — du kannst den mit Prefix
versehenen Key direkt deleten, wenn ein Write ihn invalidieren soll.
Mit gesetztem identity lautet der Key <keyPrefix><scope>:<key>
mit URI-kodiertem Scope — baue ihn also genauso:
// After a write to the profile of the caller whose identity scope is `sub`:await cache.delete(`rsp:${encodeURIComponent(sub)}:users:me`);Ein Scope wie auth0|abc wird als auth0%7Cabc gespeichert; ein Key
mit dem rohen Scope löscht nichts.
Geteilter Cache über Pods
Abschnitt betitelt „Geteilter Cache über 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')}`,});Mit einem Redis-gestützten Cache teilen sich alle Pods denselben Cache — nützlich für Multi-Pod-Deployments, in denen du konsistentes Caching willst.
Für Per-Pod-Caches (jeder Pod hat seinen eigenen InMemoryCache) können Pods kurzzeitig unterschiedliche gecachte Responses liefern, bis sich die TTLs angleichen. Oft akzeptabel; hängt von den Konsistenzanforderungen ab.
Ein geteilter Cache überdauert ein Deployment und kann deshalb
Einträge enthalten, die vor diesen Teilungsregeln geschrieben wurden.
Jeder wird vor dem Ausliefern erneut geprüft, und einer mit
Set-Cookie, einem nicht teilbaren Cache-Control, Vary: * oder
einem Vary ohne gespeicherte Request-Werte gilt als Miss — ein
Eintrag aus einem Request mit Credentials, dessen Response weder
Set-Cookie noch Vary trug, sieht aber genau wie ein öffentlicher
aus und wird ausgeliefert, bis er abläuft. Beim Upgrade von einer
Version ohne diese Regeln: warte, bis der letzte alte Pod weg ist — er
schreibt solche Einträge weiter —, und leere dann den keyPrefix
(Default rsp:) oder lass ttlMs verstreichen, bevor du dich auf die
Regeln verlässt.
Verschiedene Status-Codes cachen
Abschnitt betitelt „Verschiedene Status-Codes cachen“cached({ cache, ttlMs: 30_000, key, cacheStatuses: [200, 404], // cache both hits AND "not found"s});Cache 404s, wenn du viele Lookups für nicht existierende IDs hast —
spart wiederholte DB-Zugriffe. Default ist nur [200], damit ein
transientes 500 nicht 30 Sekunden lang hängen bleibt.
Wohin als Nächstes
Abschnitt betitelt „Wohin als Nächstes“- HTTP-Übersicht — das große Bild.
- Rate-Limit-Middleware — komplementäre Middleware.
- Idempotency-Key-Middleware — für Write-Dedup.
- Cache-Übersicht — das Backend, das diese Middleware nutzt.
