Express-Backend

ExpressBackend erlaubt dir, actor-ts-Routen durch Express laufen zu lassen — das am häufigsten genutzte Node-HTTP- Framework. Die richtige Wahl, wenn:

Du bereits in Express-Middleware investiert hast (eigene Auth, Session-Handling, app-spezifische Instrumentierung).
Die Vertrautheit deines Teams mit Express größer ist als die Framework-Vorteile von Fastify.
Du eine bestehende Express-App inkrementell zu actor-ts migrierst.

import { ActorSystem, HttpExtensionId } from 'actor-ts';
import { ExpressBackend, ExpressBackendOptions } from 'actor-ts/http';

const http = system.extension(HttpExtensionId);

await http.newServerAt('0.0.0.0', 8080)
  .useBackend(new ExpressBackend())
  .bind(routes);

Konfiguration

const expressBackendOptions = ExpressBackendOptions.create().withMaxBodyBytes(1 * 1024 * 1024);
new ExpressBackend(
  expressBackendOptions,
);
// Das X-Forwarded-*-Handling wird auf einer eigenen Express-App
// konfiguriert (`app.set('trust proxy', true)`) und via `.withApp(app)`
// übergeben.

Settings im Express-Stil.

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 ExpressBackend())
  .withSecurityHeaders(false)      // oder ein SecurityHeadersOptions-Bündel
  .bind(routes);

Siehe Sicherheit.

Express-Middleware hinzufügen

import express from 'express';
import { ExpressBackend } from 'actor-ts/http';

const backend = new ExpressBackend();
await http.newServerAt('0.0.0.0', 8080)
  .useBackend(backend)
  .bind(routes);

// Zugriff auf die rohe Express-App:
backend.getApp().use(express.session({ secret: '...' }));
backend.getApp().use(expressRateLimitFromNpm);
backend.getApp().use(customAuth);

Express-Middleware umhüllt die actor-ts-Routen — der Request fließt zuerst durch deine Middleware, dann zum actor-ts-Handler.

Das ist der Hauptgrund, Express statt Fastify zu nehmen: das Middleware-Ökosystem. Wenn du es nicht brauchst, ist Fastify schneller.

TLS

import express from 'express';
import https from 'node:https';

// TLS wird auf einer eigenen Express-App eingerichtet, in Nodes
// `https`-Server eingewickelt; die App via `.withApp(app)` übergeben.
const app = express();
https.createServer(
  {
    cert: fs.readFileSync('./tls/cert.pem'),
    key:  fs.readFileSync('./tls/key.pem'),
  },
  app,
);

const expressBackendOptions = ExpressBackendOptions.create().withApp(app);
new ExpressBackend(expressBackendOptions);

Gestützt auf das https-Modul von Node. Dieselben Vorbehalte wie beim Fastify-Backend — typischerweise terminiert TLS am Load-Balancer.

Peer-Dependency

npm install express
# oder: bun add express

Express 5+ empfohlen; ältere Versionen können funktionieren, sind aber nicht getestet.

Performance

Grobe Zahlen:

40K–60K req/sec für triviale Routen (langsamer als Fastify).
P50-Latenz ähnlich; der Durchsatz unterscheidet sich.

Die Middleware-Kette von Express hat mehr Overhead als Fastifys Hooks. Für High-Throughput-Pfade bevorzuge Fastify; für Pfade, die durch schwere Middleware ausgebremst werden, spielt die Framework-Wahl kaum eine Rolle.

Migration aus einer bestehenden Express-App

Wenn du eine bestehende Express-App hast und actor-ts hinzufügen willst:

import express from 'express';
import { ExpressBackend, ExpressBackendOptions } from 'actor-ts/http';

const app = express();

// Bestehende Routen + Middleware bleiben unverändert:
app.use('/legacy', oldLegacyRouter);

// Die bestehende App an das Backend übergeben; actor-ts registriert
// seine Routen auf derselben App, neben deinen bestehenden.
const expressBackendOptions = ExpressBackendOptions.create().withApp(app);
const backend = new ExpressBackend(expressBackendOptions);

await http.newServerAt('0.0.0.0', 8080)
  .useBackend(backend)
  .bind(routes);

Übergib deine bestehende App via .withApp(app) an das Backend — actor-ts registriert seine Routen auf derselben App, sodass deine bestehenden Routen und Middleware weiter funktionieren, ohne den ganzen HTTP-Stack auszutauschen.

// Express wählen, weil "es einfacher ist"

Aus actor-ts-Sicht sind beide einfach. Fastify ist schneller. Express hat mehr Middleware. Wähle nach der Middleware, die du brauchst, nicht nach gefühlter Einfachheit.

app.use((req, res, next) => {
  asyncWork().then(...);   // ✗ unhandled rejection
});

Die Default-Fehlerbehandlung von Express ist synchron-freundlich. Für Async-Middleware nimm express-async-errors oder wrap manuell. Die actor-ts-Routen selbst behandeln Async sauber; hier geht’s um deine eigene Middleware.

Wohin als Nächstes

HTTP-Übersicht — das große Bild.
Fastify-Backend — das Default + die Empfehlung.
Route-DSL — was die Backends registrieren.