Idempotency-Key-Middleware

idempotent setzt At-most-once-Schreibverarbeitung über einen vom Client gelieferten Header durch:

POST /api/payments
Idempotency-Key: tx-1684923847-abc

→ 201 Created  (erstes Mal — verarbeitet + gespeichert)
{ "txId": "tx-42" }

POST /api/payments
Idempotency-Key: tx-1684923847-abc   ← selber Key

→ 201 Created  (zweites Mal — aus Cache zurückgegeben, keine erneute Verarbeitung)
{ "txId": "tx-42" }

Der Handler läuft nur beim ersten Request. Spätere Requests mit demselben Key liefern die gecachte Response.

import { idempotent, path, post } from 'actor-ts/http';
import { InMemoryCache } from 'actor-ts/cache';

const dedup = idempotent({
  cache:         new InMemoryCache(),
  ttlMs:         24 * 60 * 60_000,   // 24 Stunden
  missingHeader: 'reject',           // 400, wenn der Header fehlt
});

const routes = path('api',
  path('payments', post(dedup(processPayment))),
);

Warum das wichtig ist

Netzwerk-Retries sind häufig. Ohne Idempotenz:

Client → POST /payments  (100 €)
         → Netzwerk-Timeout (Request war serverseitig tatsächlich erfolgreich)
Client → POST /payments  (100 €)   ← Retry; bucht doppelt ab

Mit Idempotency-Key sieht der Retry: “Key bereits verarbeitet, hier ist die ursprüngliche Response.” Keine Doppelbuchung.

Konfiguration

type IdempotencyOptions = {
  cache:          Cache;
  ttlMs?:         number;                              // Default 24 h
  headerName?:    string;                              // Default 'idempotency-key'
  keyPrefix?:     string;                              // Default 'idem:'
  maxKeyLength?:   number;                             // Default 255
  maxScopeLength?: number;                             // Default 255
  missingHeader?:  'reject' | 'pass-through';          // Default 'reject'
  identity?:       (req: HttpRequest) => string | Promise<string>;   // Scope pro Aufrufer; Default keiner
};

Feld	Zweck
cache	Backing-Store. Redis ist für Multi-Pod nötig. Gib ihm eine eigene Instanz — siehe die Warnung unten.
ttlMs	Wie lange jeder Key gemerkt wird. Default 24 Stunden.
headerName	Header-Namen anpassen (case-insensitive). Default 'idempotency-key'.
keyPrefix	Cache-Key-Namespace. Default 'idem:', damit mehrere Idempotency-Wrapper im selben Redis nicht kollidieren.
maxKeyLength	Längster akzeptierter Header-Wert. Default 255 (Stripes Schranke); ein längerer Key wird mit 400 abgelehnt.
maxScopeLength	Längstes akzeptiertes identity-Ergebnis. Default 255; ein längerer Scope wird mit 400 abgelehnt.
missingHeader	Was tun, wenn der Header fehlt. Default 'reject' (400); auf 'pass-through' setzen, um den Handler ohne Dedup laufen zu lassen, wenn nur manche Clients Idempotency nutzen.
identity	Optionaler Scope pro Aufrufer, der in den Cache-Key gefaltet wird, damit eine gecachte, identitätsspezifische Response nie an einen anderen Aufrufer ausgeliefert wird — z. B. (req) => req.headers['x-account'] ?? 'anon'. Ohne ihn teilen sich zwei Aufrufer mit gleichem Key + Methode + Pfad + Query + Body eine Response; nur für identitätsunabhängige Endpunkte sicher (security audit HTTP-4). Gib eine ID zurück, keinen Freitext — das Ergebnis unterliegt denselben zwei Regeln wie der Header-Wert.

Der Wrapper speichert zusätzlich einen SHA-256-Fingerprint des Requests — Methode, Pfad, Query-String und Body — neben jeder gecachten Response. Wenn ein zweiter Request mit demselben Key hereinkommt, sich aber in einem dieser vier Teile unterscheidet, lehnt der Wrapper mit 422 ab — das verhindert, dass ein Client (böswillig oder fehlerhaft) denselben Key für einen semantisch anderen Request wiederverwendet und so die falsche gespeicherte Response erhält. POST /refunds?amount=1 und POST /refunds?amount=9999 sind verschiedene Requests, auch wenn ihre Bodies identisch sind.

Die Query geht kanonisch ein: Parameter-Keys werden sortiert, damit ein Retry, der ?a=1&b=2 zu ?b=2&a=1 umsortiert, weiterhin abgespielt statt abgelehnt wird — Umsortieren ist kein anderer Request. Die Werte eines wiederholten Keys behalten ihre ursprüngliche Reihenfolge, sodass ?tag=a&tag=b von ?tag=b&tag=a verschieden bleibt; das zählt für jede API, die eine solche Liste positionell liest.

Der Key selbst wird validiert

Der Header-Wert ist angreiferseitig gewählt und landet unverändert in einem Cache-Key — er wird deshalb geprüft, bevor er dort ankommt. Ein Request wird mit 400 abgelehnt, wenn der Key

• länger ist als maxKeyLength (Default 255 Zeichen) oder
• ein ASCII-Steuerzeichen oder ein Leerzeichen enthält — CR und LF sind das klassische Header-Injection-Paar, und Leerzeichen plus der Steuerzeichenbereich sind Kommando-Trenner in Memcacheds Text-Protokoll; ein Key mit einem davon wäre also nur sicher, solange ein bestimmter Cache hinter der Middleware hängt.

Die Ablehnung nennt die Schranke und den betroffenen Index, nie den Key selbst — Angreifer-Bytes in einen Response-Body zurückzuspiegeln ist genau der Weg, auf dem eine Fehlermeldung zur Payload wird.

Echte Clients senden eine UUID oder ein kurzes opakes Token, keine der beiden Regeln kostet ehrlichen Traffic also etwas. Erhöhe maxKeyLength nur für eine Client-Flotte, die du kontrollierst und die tatsächlich längere Keys erzeugt.

Beide Regeln gelten auch für den identity-Scope, begrenzt durch maxScopeLength (ebenfalls Default 255), denn der Scope ist die andere Hälfte desselben zusammengesetzten Keys:

idem:<scope>:<Idempotency-Key>

Das zählt vor allem für das Rezept aus der identity-Zeile oben — einen rohen Client-Header, bei dem der Client die Größe wählt. Ein zweizeichiger Idempotency-Key mit einem 64-KiB-x-account wurde früher mit 200 akzeptiert und speicherte einen 64 KiB großen Cache-Key, unter einer Middleware mit dokumentierter Schranke 255. Leitest du den Scope stattdessen aus einer validierten Session oder einem Token ab, bleibt die Prüfung wirkungslos.

Die beiden Schranken sind getrennte Zahlen statt einer Schranke über den zusammengesetzten Key, damit ein Mandant mit langer ID nicht das Budget eines ehrlichen Clients verbraucht: 255 + 255 wird akzeptiert, und maxKeyLength bleibt exakt Stripes veröffentlichte Zahl.

Beachte, was all das begrenzt: wie viel Cache ein erzeugter Key kostet — nicht, wie viele ein Aufrufer erzeugen kann. Die Eviction-Warnung unten ist die andere Hälfte.

Was gecacht wird

{
  status:  201,
  headers: { 'content-type': 'application/json' },
  body:    '{"txId":"tx-42"}',
}

Die Middleware speichert die komplette Response. Spätere Requests mit demselben Key bekommen eine identische Response — gleicher Status, gleiche Header, gleicher Body.

Bei Fehler-Responses kommt es darauf an, ob der Handler etwas zurückgibt oder wirft. Eine zurückgegebene Response wird bedingungslos gecacht — eine 4xx oder 5xx wird beim Retry genauso abgespielt wie eine 2xx, damit ein “Payment fehlgeschlagen” nicht zu einem “Payment erfolgreich” wird. Ein Handler, der stattdessen wirft, verwirft seinen In-Flight- Anspruch und lässt den Key frei, sodass der Client erneut versuchen und den Handler nochmals ausführen kann. Es gibt keine Option, um auszuwählen, welche Statuscodes gecacht werden.

Scoping pro Mandant

Für Key-Isolation pro Mandant baue einen separaten idempotent-Wrapper pro Mandant (oder nimm den Mandanten in keyPrefix auf):

const dedupForTenant = (tenant: string) =>
  idempotent({
    cache,
    ttlMs:     24 * 60 * 60_000,
    keyPrefix: `idem:${tenant}:`,
  });

Mandant As key-123 ist dann verschieden von Mandant Bs key-123. Wichtig, wenn:

• Verschiedene Mandanten zufällig denselben Key wählen könnten.
• Du pro Mandant abrechnest oder auditest.

Multi-Pod mit Redis

import { RedisCache, RedisCacheOptions } from 'actor-ts/cache';

const redisCacheOptions = RedisCacheOptions.create().withUrl('redis://...');
idempotent({
  cache:  new RedisCache(redisCacheOptions),
  ttlMs:  24 * 60 * 60_000,
});

Mit Redis-Backing sieht jeder Pod denselben Idempotenz-State — ein Retry auf pod-2, nachdem das Original pod-1 traf, liefert die gecachte Response.

InMemoryCache → State pro Pod → Retries, die andere Pods treffen, könnten doppelt verarbeiten. In Produktion immer Redis.

Wo einsetzen

POST /api/payments        ✓ Idempotency-Key empfohlen
POST /api/orders          ✓ dasselbe
POST /api/emails          ✓ Doppelversand vermeiden
PUT  /api/users/:id       ✓ Retries sicher
GET  /api/users/me        ✗ nicht nötig (bereits idempotent)
DELETE /api/orders/:id    ✓ Retries sicher

Auf jeden mutierenden Endpoint, bei dem Doppelverarbeitung schädlich ist, anwenden.

Verantwortung auf Client-Seite

const key = `${userId}-${operation}-${Date.now()}-${random}`;

fetch('/api/payments', {
  method: 'POST',
  headers: {
    'idempotency-key': key,
    'content-type':    'application/json',
  },
  body: JSON.stringify({ amount: 100 }),
});

// Beim Retry: DENSELBEN KEY WIEDERVERWENDEN
fetch('/api/payments', {
  method: 'POST',
  headers: { 'idempotency-key': key },   // ← selber Key
  body:    JSON.stringify({ amount: 100 }),
});

Der Client muss den Key generieren + mit demselben Key retrien. Wenn der Client pro Versuch einen frischen Key erzeugt, sieht die Middleware sie als verschiedene Requests und verarbeitet jeden.

Häufiger Bug: den Key innerhalb der Retry-Schleife zu erzeugen statt einmal vor dem ersten Versuch.

In-Flight-Behandlung

Wenn zwei Requests mit demselben Key gleichzeitig ankommen (Doppelklick, paralleler Retry), beansprucht der erste den Key und führt den Handler aus; der zweite sieht den Key in flight und wird sofort mit 409 Conflict abgelehnt ({ "error": "idempotency-key in-flight; retry shortly" }) — er wird nicht eingereiht oder zum Warten gezwungen.

Der Client wiederholt nach einem kurzen Backoff; sobald der erste Request abgeschlossen ist und seine Response gecacht hat, spielt der Retry diese gespeicherte Response ab. Das schnelle Ablehnen (statt die zweite Verbindung über die gesamte Handler-Laufzeit offen zu halten) bedeutet außerdem, dass es keinen Cross-Pod-Lock zu koordinieren gibt — der In-Flight-Marker liegt im selben Cache wie die gecachten Responses.

Cache-Verlust = Doppelverarbeitung

// Cache-TTL läuft ab; Client retried den ursprünglichen Request

Nach TTL ist der Key vergessen. Ein verzögerter Retry verarbeitet jetzt erneut. Wähle TTL länger als jedes vernünftige Retry-Fenster (24 Stunden typisch für Zahlungen).

Teile den Cache niemals mit rateLimit() oder cached()

const idempotencyCache = new InMemoryCache();   // ✓ this middleware's own instance

Hier kann jeder Request einen neuen Key erzeugen, und InMemoryCache ist LRU-begrenzt (Default 10 000 Einträge). Seine Eviction nimmt zuerst Einträge, die keine Garantie tragen — ein Claim und der Record, der ihn ersetzt, zählen beide als eine — eine Flut über cached erreicht eine gespeicherte Response also nicht mehr. Zwei Dinge tun es weiterhin, beide lautlos:

• Teilst du eine ungeteilte Instanz mit rateLimit, evictet eine Flut von Zählern die Records dennoch. Beide Seiten tragen eine Garantie, und die Garantie-Aufteilung ordnet Garantien nicht gegeneinander — prefixQuotas tut das.
• Der eigene Key-Raum dieser Middleware ist angreiferkontrolliert: eine Flut eindeutiger Idempotency-Keys evictet die Records anderer Aufrufer aus derselben Instanz. maxKeyLength und maxScopeLength begrenzen, wie groß ein erzeugter Key ist, nicht wie viele es sind — und auch keine Quote hilft hier, denn Angreifer und Opfer schreiben unter demselben Präfix und teilen sich damit alles, was dafür reserviert ist.

Ein Record wird außerdem nur als zuletzt genutzt markiert, wenn er gelesen wird. setIfAbsent zählt nicht, ein beanspruchter Key, den noch niemand erneut angefragt hat, ist also das Erste, was an einer Schranke fällt.

Übergib eine eigene Instanz — oder ext.cache('idempotency') — und dimensioniere deren maxEntries für die Keys, die du innerhalb eines ttlMs erwartest, unter dem Namen dieses Caches:

actor-ts.cache.idempotency.in-memory.maxEntries = 200000

Wo eine Instanz wirklich geteilt werden muss, reserviere stattdessen den keyPrefix dieser Middleware daraus:

actor-ts.cache.shared.in-memory {
  maxEntries = 10000
  prefixQuotas { "idem:" = 8000, "rl:" = 2000 }
}

Wo die Garantie gegen einen Angreifer halten muss, der die Keys wählt, hinterlege sie mit Redis statt mit einer prozesslokalen LRU — das ist die eine Exposition, die weder eine benannte Instanz noch eine Quote beseitigt. Siehe was Eviction schützt und was nicht und eine Instanz nach Key-Präfix aufteilen.

In-Memory-Cache + mehrere Pods

// Pod-1 verarbeitet zuerst; Retry trifft Pod-2 (anderer InMemoryCache)

Pod-2s Cache sieht Pod-1s Key nicht → verarbeitet erneut. Nimm Redis.

Idempotency-Key mit nicht-idempotenten Seiteneffekten

// Handler erzeugt einen Stripe-Charge.  Beim ersten Mal erfolgreich; gecacht.
// Aber Stripe hat selbst ein Idempotency-Key-Konzept; den willst du durchreichen.

Wenn der Handler andere idempotente Services aufruft (Stripe, Payment-Processor), reich den Idempotency-Key an sie weiter. Gürtel und Hosenträger.

Wohin als Nächstes

• HTTP-Übersicht — das große Bild.
• Response-Cache-Middleware — komplementäre Lese-Seite.
• Rate-Limit-Middleware — Request-Limits pro Key.
• Cache-Übersicht — der Backing-Store.