Request-ID

requestId() gibt jedem Request eine stabile ID — zur Log-Korrelation und zum Weiterreichen. Es leitet die ID an den Handler weiter (über den angereicherten Request) und echot sie auf der Response.

import { requestId, withMiddleware } from 'actor-ts/http';

const routes = withMiddleware(requestId(), appRoutes);

// in einem Handler:
get((req) => completeJson(Status.OK, { id: req.headers['x-request-id'] }));

Eine eingehende ID wird nur übernommen, wenn sie wohlgeformt ist (^[A-Za-z0-9._-]{1,64}$) — ein bösartiger Wert erreicht nie einen Response-Header; andernfalls wird eine frische ID mit randomUuid erzeugt.

Ein Short-Circuit, der wirft, wird ebenfalls geechot: Die 401 oder 403, die eine Auth- oder CSRF-Schicht darunter wirft, kommt mit der ID zurück — und genau zu dieser Response sucht später jemand die Log-Zeile. Die Ausnahme ist ein unbehandelter Wurf: Er wird auf die generische 500 gemappt, die bewusst nichts aus dem geworfenen Wert übernimmt, und kommt daher ohne ID an.

Die ID wieder auslesen

requestIdOf(request) liefert die ID, die der Request trägt, oder undefined — wenn er keine trägt oder das Getragene dieselbe Formprüfung nicht besteht. Nimm sie überall dort statt eines rohen Header-Zugriffs, wo der Wert auf einer Logzeile landet: Ein client-kontrollierter String kann über einen eingebetteten Zeilenumbruch ganze Log-Einträge fälschen, und genau die Prüfung verhindert das.

import { requestIdOf } from 'actor-ts/http';

system.log.error(`[http] ${req.method} ${req.path} (${requestIdOf(req) ?? '-'})`, err);

Zurück kommt, was der Request behauptet hat. Bei trustIncoming: false — wo die Middleware stromabwärts ihre eigene ID einsetzt — nenne daher den Header, statt den Wert als die ID auszugeben. Einen umbenannten Header übergibst du als zweites Argument.

Konfiguration

Builder-Methode	Feld	Default
`withHeaderName(n)`	`headerName`	`'x-request-id'`
`withTrustIncoming(flag?)`	`trustIncoming`	`true`
`withGenerate(generate)`	`generate`	`randomUuid`

Wie weiter

Sicherheit — requestId an den Anfang des Stacks setzen.
Fehlerbehandlung — die ID im withErrorHandler loggen.