Zum Inhalt springen
Deutsch

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.

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>;
};
FeldZweck
cacheDas Cache-Backend. InMemoryCache für Single-Node; Redis für geteilt.
ttlMsWie 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.
keyPrefixCache-Key-Namespace. Default 'rsp:', damit sich mehrere Response-Caches im selben Redis nicht überschneiden.
cacheStatusesWelche 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.

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.

GET /api/products → cache (stable, read-heavy)
POST /api/orders → passes straight through — only GET is stored
GET /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.

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 miss
const routes = withMiddleware(JwtAuth(jwtOptions),
path('me', get(profileCache(loadProfile))),
);
// ✗ a check inside loadProfile is skipped by every hit

Darüber hinaus verweigert der Wrapper von sich aus jeden Fall, in dem die Response eines Aufrufers einen anderen erreichen könnte:

RegelWarum
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.

cached invalidiert nicht automatisch bei Writes — die Veraltung ist durch ttlMs begrenzt.

Für stärkere Konsistenz zwei Muster:

cached({ cache, ttlMs: 1_000, key }); // 1 second

Sub-Sekunden-TTLs begrenzen die Veraltung. Gut für „echtzeit-nahe” APIs.

// After a write that affects products:42, invalidate the cache:
await cache.delete('rsp:products:42'); // 'rsp:' is the default keyPrefix

Der 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.

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.

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.