Fastify-Backend
FastifyBackend ist das Default-HTTP-Backend für actor-ts.
Umschließt Fastify — schnell, gut gewartet, mit einem riesigen
Ökosystem an Plugins (JWT-Auth, Validierung, Swagger usw.).
import { ActorSystem } from 'actor-ts';import { HttpExtensionId } from 'actor-ts/http';
const http = system.extension(HttpExtensionId);
await http.newServerAt('0.0.0.0', 8080).bind(routes);// ↑ standardmäßig FastifyUm das Backend explizit zu machen:
import { FastifyBackend } from 'actor-ts/http';
await http.newServerAt('0.0.0.0', 8080) .useBackend(new FastifyBackend()) .bind(routes);Konfiguration
Abschnitt betitelt „Konfiguration“new FastifyBackend({ logger: false, // Fastifys eingebauter Logger — aus lassen; nimm actor-ts-Log bodyLimit: 1_048_576, // 1 MiB Request-Body-Cap});bodyLimit ist das eine, das das Framework für dich setzt. Ohne eigene
Angabe steht es auf 1 MiB — demselben Cap, den auch das Express- und
das Hono-Backend anwenden; welche Requests angenommen werden, hängt damit
nicht mehr vom Backend ab. Ein eigener Wert gewinnt weiterhin.
Das serverweite actor-ts.http.server.max-content-length setzt diesen Cap
für alle Backends auf einmal, und Fastify nimmt ihn als bodyLimit — bei der
Konstruktion, wie alles in dieser Bag. Das vom Framework gebaute Backend wird
damit gebaut. Ein Backend, das du selbst baust, übernimmt ihn nur über
fastifyFactoryOptions(serverOptions), und eines, dessen bodyLimit von einem
gesetzten Key abweicht — das eingebaute 1 MiB eines blanken
new FastifyBackend() eingeschlossen —, wird bei bind() abgelehnt, mit dem
Key in der Meldung. max-header-bytes nimmt denselben Weg als
maxHeaderSize. Fastify gibt seiner Server-Factory die https-Bag, sobald TLS
an ist, sonst die http-Bag; fastifyFactoryOptions legt die Grenze deshalb
in die, die Fastify liest, und ein selbst gebautes Backend, dessen Server eine
andere Grenze hält — oder keine, und genau darauf läuft eine Grenze in http
bei einer TLS-Instanz hinaus —, wird ebenso abgelehnt:
import { FastifyBackend, fastifyFactoryOptions, HttpExtensionId, HttpServerOptions } from 'actor-ts/http';
const serverOptions = HttpServerOptions.create() .withMaxContentLength(8 * 1024 * 1024) .withMaxHeaderBytes(32 * 1024);
const backend = new FastifyBackend({ logger: false, ...fastifyFactoryOptions(serverOptions), // { bodyLimit, http: { maxHeaderSize } }});
await system.extension(HttpExtensionId) .newServerAt('0.0.0.0', 8080) .useBackend(backend) .withServerOptions(serverOptions) .bind(routes);Überlässt du das Backend dem Framework, braucht es nichts davon: es wird aus den aufgelösten Optionen gebaut, HOCON eingeschlossen.
Die Timeouts und max-connections unter
actor-ts.http.server werden nach listen()
auf fastify.server installiert und gelten hier deshalb unabhängig davon, ob
das Framework dieses Backend gebaut hat oder du. Zwei von Fastifys eigenen
Defaults weichen von denen aus node:http ab und sind es wert, gekannt zu
werden: keepAliveTimeout steht auf 72 s statt auf 5 s — absichtlich,
damit der Server das Idle-Fenster eines Load Balancers überlebt — und
requestTimeout auf 0, also gar keine Schranke. Das Framework
veröffentlicht jetzt request-timeout = 300s; auf diesem Backend ist das eine
Empfangs-Deadline, wo vorher keine war. Setz sie in deiner Config zurück auf
0, um das alte Verhalten herzustellen; idle-timeout liefert keinen Wert,
Fastifys 72 s bleiben also unangetastet.
Unter Deno, das dieses Backend nicht unterstützt, greifen die Header-Deadline
und max-connections nie: sein node:http-Shim sendet kein Verbindungs-Event,
das sie zählen könnten. idle-timeout und request-timeout greifen ab
deno 2.7.13 wie unter Node; davor nimmt der Shim keepAliveTimeout und
requestTimeout an, ohne eines davon anzuwenden. Gemessen auf deno 2.6.8 unter
idle-timeout = 600ms: eine Keep-Alive-Verbindung war 3 s nach ihrer Antwort
noch offen, wo deno 2.7.13, Node und Bun sie nach 1,6 s schlossen. Jede, die
nicht greift, wird als nicht wirksam gemeldet, und bind() nennt die
gesetzten in einer Warnung.
Auf dem HTTP/2-Listener (withHttp2()) erreichen Fastifys 72 s eine untätige
Session als Fastifys eigener Session-Timer, der die stille Zeit auf der
Verbindung zählt: er schließt eine untätige Session auf Node nach 72 s, auf
Bun aber nach 144 s, weil Bun ihn beim doppelten Wert feuern lässt, und auf
Bun setzt ein PING-Frame ihn zurück — ein Client, der einmal pro Sekunde pingt,
hält eine Session ohne jeden Request beliebig lange offen (nach 170 s noch
offen, bun 1.4.2). Ein gesetzter idle-timeout ersetzt diesen Timer durch den
von actor-ts, der eine Session schließt, die so lange keinen offenen Stream
hatte — derselbe Wert auf beiden Runtimes, mit oder ohne PINGs —, und
request-timeout gibt jedem HTTP/2-Stream eine eigene Empfangs-Deadline. Zwei
Schranken gelten auf diesem Listener nur für ein Protokoll, und bind() warnt
vor jeder, die du setzt: auf Bun begrenzen idle-timeout und
request-timeout HTTP/2, aber keine Verbindung, die auf demselben Port HTTP/1.1
aushandelt; auf Node begrenzt max-header-bytes die HTTP/1.1-Requests,
aber nicht die Header-Liste eines HTTP/2-Streams, die nur Nodes eigene
64-KiB-Grenze begrenzt. Die Sicherheitsseite hat die
Zahlen.
Die meisten Settings werden an Fastifys FastifyServerOptions
durchgereicht. Das Framework konfiguriert die Routen-
Registrierung; du drehst an Fastifys eigenen Reglern.
Hinter einem Reverse-Proxy
Abschnitt betitelt „Hinter einem Reverse-Proxy“HttpRequest.remoteAddress kommt aus Fastifys req.ip, und das ist ohne
trustProxy der Socket-Peer. Weil die Optionen des Konstruktors direkt
an Fastify durchgereicht werden, lässt sich trustProxy hier
konfigurieren — und wenn du es setzt, gib ihm die Adressen deiner
Proxys:
new FastifyBackend({ trustProxy: '10.9.9.0/24', // ✓ Trusted-Subnet-Form});Security-Header
Abschnitt betitelt „Security-Header“Jede Response, die dieses Backend schreibt, trägt
X-Content-Type-Options: nosniff — inklusive seines Fehler-Mappings, des
fallback-404 und des 413 bei zu großem Body, die keine Middleware sieht.
Ein Header aus der Response selbst gewinnt weiterhin.
Konfiguriert wird das pro Server, nicht pro Backend — eine Oberfläche statt dreier:
await http.newServerAt('0.0.0.0', 8080) .useBackend(new FastifyBackend()) .withSecurityHeaders(false) // oder ein SecurityHeadersOptions-Bündel .bind(routes);Siehe Sicherheit.
Setze es dort, wo jedes Backend es nimmt, an den Server-Optionen (siehe TLS und HTTP/2):
const serverOptions = HttpServerOptions.create() .withTls({ cert: fs.readFileSync('./tls/cert.pem'), key: fs.readFileSync('./tls/key.pem') }) .withHttp2();
await system.extension(HttpExtensionId) .newServerAt('0.0.0.0', 8443) .withServerOptions(serverOptions) .bind(routes);Fastify ist das eine Backend, das TLS und HTTP/2 als Factory-Optionen
nimmt — Fastify({ https, http2 }) — und nicht bei listen(). Das vom
Framework gebaute Backend wird damit konstruiert, weil bind() die
Server-Optionen auflöst, bevor es das Backend konstruiert. Ein selbst
konstruiertes Backend, das du useBackend(...) übergibst, muss sie selbst
tragen, und fastifyFactoryOptions macht aus denselben Server-Optionen
die Factory-Form:
import { FastifyBackend, fastifyFactoryOptions } from 'actor-ts/http';
const backend = new FastifyBackend({ logger: false, ...fastifyFactoryOptions(serverOptions), // { https: { cert, key, … }, http2 }});Ein von Hand gebautes Backend ohne TLS, das dann withTls(...) bekommt,
wird bei bind() abgelehnt, statt als reines HTTP unter einer
Einstellung gebunden zu werden, die etwas anderes behauptet — ebenso eines
mit TLS, aber ohne http2: true, das withHttp2() bekommt: Es würde
HTTP/1.1 über TLS beantworten, wo die Einstellung HTTP/2 sagt. Ebenso eines,
dessen https Client-Zertifikate anders prüft als die Server-Optionen —
ohne die Forderung requestClientCert gebaut, oder mit ihr, aber ohne
dieselbe ca: Es würde so prüfen, wie es gebaut wurde, nicht so, wie die
Einstellung es sagt. (Frühere
Fassungen dieser Seite zeigten new FastifyBackend({ tls: … }); tls ist
keine Fastify-Option, wurde hineingespreadet und ignoriert — der
beschriebene Server hat nie TLS terminiert.)
Eine Forderung nach Client-Zertifikaten (requestClientCert) wird auf Node
und Bun durchgesetzt, wo das Zertifikat gegen die konfigurierte ca geprüft
wird. Auf Deno wird sie bei bind() abgelehnt: Fastify bedient über das
node:https von Deno, das requestCert annimmt und nichts davon durchsetzt —
gemessen mit deno 2.6.8 beantwortete das vom Framework gebaute Backend einen
Client, der gar kein Zertifikat vorzeigte. Fastify ist das Standard-Backend,
hier landet eine Forderung also, wenn nichts anderes konfiguriert ist;
terminiere TLS vor dem Prozess, oder laufe auf Node oder Bun. Die Regel, der
jedes Backend folgt, steht unter
Client-Zertifikate.
Für die meisten Produktions-Setups terminiert TLS weiterhin am Load-Balancer, und die App spricht intern reines HTTP; In-App-TLS ist für den Einzelprozess- und den Entwicklungsfall.
Zugriff auf die rohe Fastify-Instanz
Abschnitt betitelt „Zugriff auf die rohe Fastify-Instanz“const backend = new FastifyBackend();await http.newServerAt('0.0.0.0', 8080) .useBackend(backend) .bind(routes);
// Nach dem Bind ein natives Plugin über die Escape-Hatch registrieren...await backend.withPlugin(fastifyJwt, { secret: '...' });// ...oder für Low-Level-Hooks die rohe Fastify-Instanz erreichen:backend.fastify.addHook('onRequest', authHook);Nutze das für Plugins, die nicht über die DSL des Frameworks exponiert sind:
- OAuth-/OpenID-Connect-Login-Flows.
- Request-Validierung (
@fastify/swagger). - Komprimierung.
JWT-Prüfung und CORS brauchen kein Plugin: Die Middleware
JwtAuth und die Direktive
cors() gehören zum Framework und verhalten
sich auf jedem Backend gleich.
Die actor-ts-DSL behandelt Routing; Fastify-Plugins behandeln Querschnittsthemen. Sie komponieren sauber.
Lifecycle
Abschnitt betitelt „Lifecycle“1. new FastifyBackend() — der Konstruktor erzeugt die Fastify-Instanz2. Das Framework registriert jede kompilierte Route bei Fastify3. Fastify.listen() — öffnet den Port4. Beim Shutdown: Fastify.close() — drained In-Flight-Requests, dann ExitFastify.close() wartet auf den Abschluss laufender Requests,
bevor es resolved — passt zur service-unbind-Phase des
Coordinated Shutdown.
Gebündelte Dependency
Abschnitt betitelt „Gebündelte Dependency“Fastify ist eine feste Dependency von actor-ts — es wird mit dem Framework installiert, es gibt also nichts extra hinzuzufügen. (Die Express- und Hono-Backends sind dagegen optionale Peer-Dependencies, die du bei Bedarf installierst.)
Performance
Abschnitt betitelt „Performance“Grobe Zahlen für triviale Routen:
- 150K–200K req/sec auf Bun (mit
bun:test-Benchmark). - 80K–120K req/sec auf Node 22.
- P50-Latenz unter einer Millisekunde für triviale Handler; höher für Routen, die Actors fragen.
Fastify ist eines der schnellsten Node-HTTP-Frameworks; der Actor-Routing-Overhead des Frameworks ist der nächste Bottleneck für heiße Routen.
Wohin als Nächstes
Abschnitt betitelt „Wohin als Nächstes“- HTTP-Übersicht — das große Bild.
- Route-DSL — was bei Fastify registriert wird.
- Express-Backend — die Alternative.
- Hono-Backend — die leichtgewichtige Alternative.
