Zum Inhalt springen
Deutsch

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

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.

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.

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.

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.

Terminal-Fenster
npm install express
# oder: bun add express

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

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.

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.