Zum Inhalt springen
actor-ts
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, HttpExtensionId } from 'actor-ts';


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

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
  tls: {
    cert: fs.readFileSync('./tls/cert.pem'),
    key:  fs.readFileSync('./tls/key.pem'),
  },
});

Die meisten Settings werden an Fastifys FastifyServerOptions durchgereicht. Das Framework konfiguriert die Routen- Registrierung; du drehst an Fastifys eigenen Reglern.

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.

TLS

Abschnitt betitelt „TLS“
new FastifyBackend({
  tls: {
    cert: fs.readFileSync('./tls/cert.pem'),
    key:  fs.readFileSync('./tls/key.pem'),
    // Für mTLS:
    ca:                fs.readFileSync('./tls/ca.pem'),
    requestCert:       true,
    rejectUnauthorized: true,
  },
});

Standard-Fastify-TLS-Optionen. Für die meisten Produktions-Setups terminiert TLS am Load-Balancer — die App spricht intern einfaches HTTP — aber In-App-TLS wird unterstützt, wenn nötig.

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:

  • JWT-/OAuth-Authentifizierung.
  • Request-Validierung (@fastify/swagger).
  • CORS (@fastify/cors).
  • Komprimierung.

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

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“