Zum Inhalt springen
Deutsch

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 Fastify

Um das Backend explizit zu machen:

import { FastifyBackend } from 'actor-ts/http';
await http.newServerAt('0.0.0.0', 8080)
.useBackend(new FastifyBackend())
.bind(routes);
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.

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
});

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.

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.

1. new FastifyBackend() — der Konstruktor erzeugt die Fastify-Instanz
2. Das Framework registriert jede kompilierte Route bei Fastify
3. Fastify.listen() — öffnet den Port
4. Beim Shutdown: Fastify.close() — drained In-Flight-Requests, dann Exit

Fastify.close() wartet auf den Abschluss laufender Requests, bevor es resolved — passt zur service-unbind-Phase des Coordinated Shutdown.

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

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.