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 } from 'actor-ts';import { HttpExtensionId } from 'actor-ts/http';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
Abschnitt betitelt „Konfiguration“const expressBackendOptions = ExpressBackendOptions.create().withMaxBodyBytes(4 * 1024 * 1024);new ExpressBackend( expressBackendOptions,);Settings im Express-Stil. maxBodyBytes steht per Default auf 1 MiB,
dem gemeinsamen Cap aller Backends — heb ihn nur für einen Endpunkt an, der
wirklich mehr annimmt, so wie oben. Das serverweite
actor-ts.http.server.max-content-length sagt dasselbe für alle Backends und
ist das, wozu du greifen solltest: ein Backend ohne withMaxBodyBytes
übernimmt den Key, und eines mit einer anderen Zahl wird bei bind()
abgelehnt, mit beiden Zahlen in der Meldung — ein Server hält nicht zwei
Body-Caps, und welchen auch immer man wählte, der andere bliebe still
unbeachtet. Das gilt in beide Richtungen: ein Endpoint, der bewusst enger
gebaut ist als ein weiterer serverweiter Key, wird ebenfalls abgelehnt und nie
auf ihn aufgeweitet. Dieselbe Zahl an beiden Stellen bindet.
Das Backend baut den Server, auf dem es lauscht, selbst — node:http, unter
withTls(...) node:https (siehe TLS) — und übergibt die App genau
so, wie app.listen() es täte, aber mit den Server-Optionen, die
app.listen() gar nicht annehmen kann: max-header-bytes wird, wenn gesetzt,
in ihn eingebaut, und ein Request mit größerem Header-Block erreicht keinen
Handler. Die Verbindungsschranken unter
actor-ts.http.server werden auf demselben
Server installiert; sie gelten hier also unabhängig davon, ob das Framework
das Backend gebaut oder du es an useBackend(...) übergeben hast — auch bei
einer mitgebrachten App. Express selbst rührt keinen davon an; ohne
Konfiguration gilt deshalb das von node:http: ein Keep-Alive-Fenster von
5 s, eine Empfangs-Deadline von 300 s und eine Header-Grenze von 16 KiB.
Hinter einem Reverse-Proxy
Abschnitt betitelt „Hinter einem Reverse-Proxy“req.ip ist der Socket-Peer, und der landet in
HttpRequest.remoteAddress. Express kann angewiesen werden, ihn
stattdessen aus X-Forwarded-For abzuleiten — aber nur auf einer
eigenen App (app.set(...), via .withApp(app) übergeben), denn
ExpressBackendOptions hat kein trustProxy-Feld.
Nimm dafür lieber
trustedProxies von IpAllowlist.
Das ist dieselbe Trust-by-Address-Regel, braucht keine eigene App und
liest sich auf allen drei Backends gleich — Hono hat überhaupt kein
Trust-Proxy-Konzept.
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 ExpressBackend()) .withSecurityHeaders(false) // oder ein SecurityHeadersOptions-Bündel .bind(routes);Siehe Sicherheit.
Express-Middleware hinzufügen
Abschnitt betitelt „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.
WebSocket-Handshakes laufen ebenfalls hindurch
Abschnitt betitelt „WebSocket-Handshakes laufen ebenfalls hindurch“Eine websocket()-Route wird als ganz normales Express-GET
registriert, und das Upgrade wird durch die App dispatcht — also
läuft app.use(...) beim Handshake genau so wie bei einem Request:
const backend = new ExpressBackend();backend.getApp().use(customAuth); // gates /ws as well
await http.newServerAt('0.0.0.0', 8080) .useBackend(backend) .bind(websocket('/ws', chat));Eine Middleware, die den Request beantwortet
(res.status(401).end()), bricht den Handshake ab: der Socket wird
geschlossen statt hochgestuft, und onClientConnected feuert nie.
Eine Middleware, die next() aufruft, lässt ihn zum
Upgrade-Guard des Frameworks durch (withMiddleware() /
allowedOrigins), der weiterhin das letzte Wort hat — siehe
WebSockets.
Zwei Einschränkungen auf diesem Pfad. Eine Middleware, die weder
antwortet noch next() aufruft, lässt den Client warten — genauso,
wie sie einen normalen Request hängen lassen würde. Und der Body
einer Ablehnung erreicht den Client nur auf Runtimes, die das
Schreiben auf einen übernommenen Upgrade-Socket zulassen: Bun und
Node tun das, Deno nicht — dort sieht der Client stattdessen den
Verbindungsabbruch. Abgelehnt wird der Handshake in beiden Fällen.
Gesetzt wird es dort, wo jedes Backend es nimmt, in den Server-Optionen (siehe TLS und HTTP/2):
import { readFileSync } from 'node:fs';import { ExpressBackend, HttpServerOptions } from 'actor-ts/http';
const serverOptions = HttpServerOptions.create() .withTls({ cert: readFileSync('./tls/cert.pem'), key: readFileSync('./tls/key.pem') });
await http.newServerAt('0.0.0.0', 8443) .useBackend(new ExpressBackend()) .withServerOptions(serverOptions) .bind(routes);Das Backend baut seinen Server dann mit https.createServer und übergibt die
App so, wie es das HTTPS-Rezept von Express selbst tut — für eine mitgebrachte
App ändert sich also nichts: ihre Middleware sieht jeden Request, eine
websocket()-Route wird als wss:// durch dieselbe Middleware hochgestuft,
und max-header-bytes sowie die Verbindungsschranken gelten auf dem
TLS-Server wie auf einem reinen. Die Header-Deadline folgt jeder Verbindung in
TLS hinein, ein Slow-Loris bekommt sein 408 also innerhalb von TLS. Deno ist
die Ausnahme, wie schon bei reinem HTTP: sein node:http und sein node:https
senden keines der Verbindungs-Events, auf denen die Absicherungen ruhen, und
ignorieren die Header-Grenze; dort greifen also header-timeout,
max-connections und max-header-bytes nicht, und bind() nennt jede davon,
die gesetzt ist, in einer Warnung. idle-timeout und request-timeout greifen
ab deno 2.7.13 wie unter Node; davor nimmt Deno keepAliveTimeout und
requestTimeout an, ohne eines davon anzuwenden, und beide werden ebenfalls als
nicht wirksam gemeldet. Gemessen unter idle-timeout = 600ms und
request-timeout = 2s: auf deno 2.6.8 war eine Keep-Alive-Verbindung 3 s nach
ihrer Antwort noch offen, und ein Body, der nicht mehr weiterkam, war nach 40 s
noch offen, ohne 408; ab deno 2.7.13 wurde, wie unter Node und Bun, die erste
nach 1,6 s geschlossen und die zweite nach 30 s beantwortet.
requestClientCert wird zu requestCert von node:tls, und
rejectUnauthorized wird durchgereicht — wie beim Hono-Backend unter Node. Die
Forderung braucht eine ca, gegen die geprüft wird: ohne sie lehnt bind() sie
auf jedem Backend ab, weil node:tls Client-Zertifikate sonst gegen den
Standard-Trust-Store der Runtime prüfen und jedes Zertifikat einer öffentlichen
CA zulassen würde. Auf Deno wird eine Client-Zertifikats-Forderung bei bind()
in jedem Fall abgelehnt, weil das node:https von Deno die Option annimmt
und nichts davon durchsetzt — gemessen mit deno 2.6.8 wurde ein Client ohne
Zertifikat beantwortet.
HTTP/2 wird abgelehnt. withHttp2() scheitert bei bind(), statt HTTP/1.1
unter einer Einstellung zu beantworten, die h2 sagt. Express hängt jeden
Request und jede Response auf die eigenen Prototypen von node:http um, und
die Kompatibilitätsobjekte von node:http2 überstehen das nicht: gemessen mit
express 5.2.1 hinter http2.createSecureServer({ allowHTTP1: true }) wurde ein
h2-Request auf node v26.10.0 und bun 1.4.2 ausgehandelt und nie beantwortet,
HTTP/1.1 auf demselben Port dagegen schon; deno 2.6.8 implementiert
http2.createSecureServer überhaupt nicht. Für HTTP/2 nimm das
Fastify- oder das
Hono-Backend.
Eine mitgebrachte App selbst in https.createServer(…, app) zu wickeln, wie
frühere Versionen dieser Seite es taten, funktioniert weiterhin nicht: das
Backend lauscht auf einem eigenen Server, dieser Wrapper bekommt also nie eine
Verbindung. Der Weg führt über withTls(...).
Hinter einem Reverse Proxy, einem Ingress oder einem Load Balancer, der TLS für
dich terminiert, lass tls ungesetzt und das Backend dahinter reines HTTP
sprechen — so laufen die meisten Produktions-Setups nach wie vor.
Peer-Dependency
Abschnitt betitelt „Peer-Dependency“npm install express# oder: bun add expressExpress 5+ empfohlen; ältere Versionen können funktionieren, sind aber nicht getestet.
Performance
Abschnitt betitelt „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
Abschnitt betitelt „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.
Wohin als Nächstes
Abschnitt betitelt „Wohin als Nächstes“- HTTP-Übersicht — das große Bild.
- Fastify-Backend — das Default + die Empfehlung.
- Route-DSL — was die Backends registrieren.
