Express backend
此内容尚不支持你的语言。
ExpressBackend lets you run actor-ts routes through
Express — the most-widely-used Node HTTP framework. Right
choice when:
- You already have Express middleware invested (custom auth, session handling, app-specific instrumentation).
- Team familiarity with Express > framework benefits of Fastify.
- You’re incrementally migrating an existing Express app to actor-ts.
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);Configuration
Section titled “Configuration”const expressBackendOptions = ExpressBackendOptions.create().withMaxBodyBytes(4 * 1024 * 1024);new ExpressBackend( expressBackendOptions,);Express-style settings. maxBodyBytes defaults to 1 MiB, the shared
cap every backend applies — raise it only for an endpoint that genuinely
takes more, as above. The server-wide
actor-ts.http.server.max-content-length says the same for every backend and
is the one to reach for: a backend built without withMaxBodyBytes takes the
key, and one built with a different number is refused at bind(), naming
both — one server does not hold two body caps, and picking either would leave
the other silently unenforced. That holds in both directions: an endpoint built
deliberately tighter than a looser server-wide key is refused too, never widened
to it. The same number in both places binds.
The backend builds the server it listens on — node:http, or node:https
under withTls(...) (see TLS) — handing the app over exactly as
app.listen() would, but with the server options app.listen() has no way to
take: max-header-bytes, when set, is built into it, and a request whose
header block is larger never reaches a handler. The connection-level bounds under
actor-ts.http.server are installed on the same
server, so they hold here whether the backend was built by the framework or
handed to useBackend(...) — including on a bring-your-own app. Express
touches none of them itself, so what applies without configuration is
node:http’s own: a 5 s keep-alive window, a 300 s receive deadline and a
16 KiB header cap.
Behind a reverse proxy
Section titled “Behind a reverse proxy”req.ip is the socket peer, which is what lands in
HttpRequest.remoteAddress. Express can be told to derive it from
X-Forwarded-For instead — but only on a bring-your-own app
(app.set(...), passed via .withApp(app)), because
ExpressBackendOptions has no trustProxy field.
Prefer IpAllowlist’s trustedProxies
over that route. It is the same trust-by-address rule, it does not need a
bring-your-own app, and it reads identically on all three backends —
Hono has no trust-proxy concept at all.
Security headers
Section titled “Security headers”Every response this backend writes carries
X-Content-Type-Options: nosniff — its error mapping, the fallback 404
and the body-too-large 413 included, none of which a middleware sees.
A response’s own header still wins.
Configure it per server, not per backend — one surface instead of three:
await http.newServerAt('0.0.0.0', 8080) .useBackend(new ExpressBackend()) .withSecurityHeaders(false) // or a SecurityHeadersOptions bundle .bind(routes);Adding Express middleware
Section titled “Adding Express middleware”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);
// Access the raw Express app:backend.getApp().use(express.session({ secret: '...' }));backend.getApp().use(expressRateLimitFromNpm);backend.getApp().use(customAuth);Express middleware wraps the actor-ts routes — request flows through your middleware first, then to the actor-ts handler.
This is the main reason to pick Express over Fastify: the middleware ecosystem. If you don’t need it, Fastify is faster.
WebSocket handshakes go through it too
Section titled “WebSocket handshakes go through it too”A websocket() route is registered as an ordinary Express GET,
and the upgrade is dispatched through the app — so app.use(...)
runs for the handshake exactly as it runs for a 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));A middleware that answers the request (res.status(401).end())
cancels the handshake: the socket is closed instead of upgraded and
onClientConnected never fires. A middleware that calls next()
lets it through to the framework’s own upgrade guard
(withMiddleware() / allowedOrigins), which still has the last
word — see WebSockets.
Two caveats on this path. A middleware that neither answers nor
calls next() leaves the client waiting, the same way it would
stall an ordinary request. And a rejection’s body only reaches
the client on runtimes that let a hijacked upgrade socket be written
to — Bun and Node do, Deno does not, where the client sees the
connection close instead. Either way the handshake is refused.
Set it where every backend takes it, on the server options (see TLS and 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);The backend then builds its server with https.createServer, handing the app
over the way Express’s own HTTPS recipe does, so a bring-your-own app changes
nothing: its middleware sees every request, a websocket() route upgrades as
wss:// through that same middleware, and max-header-bytes and the
connection-level bounds hold on the TLS server as they do on a plain one. The
header deadline follows each connection into TLS, so a slow-loris is answered
408 inside it. Deno is the exception, as it is for plain HTTP: its node:http
and node:https emit none of the connection events the guards rest on and
ignore the header cap, so there header-timeout, max-connections and
max-header-bytes do not hold, and bind() names each one that is set in a
warning. idle-timeout and request-timeout hold from deno 2.7.13 on, as on
Node; before it Deno accepts keepAliveTimeout and requestTimeout without
applying either, and both are reported not in effect too. Measured under
idle-timeout = 600ms and request-timeout = 2s: on deno 2.6.8 a keep-alive
connection was still open 3 s after its response, and a body that stopped
arriving was still open after 40 s with no 408; on deno 2.7.13 and later, as
on Node and Bun, the first closed at 1.6 s and the second was answered at 30 s.
requestClientCert becomes node:tls’s requestCert and
rejectUnauthorized passes through, as on the Hono backend under Node. The
demand needs a ca to verify against: without one bind() refuses it, on
every backend, because node:tls would otherwise check client certificates
against the runtime’s default trust store and admit any certificate a public
CA issued. On Deno a client-certificate demand is refused at bind()
either way, because Deno’s node:https accepts the option and enforces
nothing — measured on deno 2.6.8, a client presenting no certificate was
answered.
HTTP/2 is refused. withHttp2() fails at bind() rather than answering
HTTP/1.1 under a setting that says h2. Express reassigns every request and
response onto node:http’s own prototypes, and the compatibility objects of
node:http2 do not survive that: measured with express 5.2.1 behind
http2.createSecureServer({ allowHTTP1: true }), an h2 request was negotiated
and never answered on node v26.10.0 and bun 1.4.2, while HTTP/1.1 on the same
port was; deno 2.6.8 does not implement http2.createSecureServer at all. For
HTTP/2, use the Fastify or
Hono backend.
Wrapping a bring-your-own app in https.createServer(…, app) yourself, as
earlier versions of this page did, still does not work: the backend listens on
a server of its own, so that wrapper never receives a connection.
withTls(...) is the way in.
Behind a reverse proxy, an ingress or a load balancer that terminates TLS for
you, leave tls unset and let the backend speak plain HTTP behind it — still
how most production setups run.
Peer dependency
Section titled “Peer dependency”npm install express# or: bun add expressFor Express 5+ recommendation; older versions may work but aren’t tested.
Performance
Section titled “Performance”Rough numbers:
- 40K-60K req/sec for trivial routes (slower than Fastify).
- P50 latency similar; throughput differs.
Express’s middleware chain has more overhead than Fastify’s hooks. For high-throughput paths, prefer Fastify; for paths gated by heavy middleware, the framework choice doesn’t matter much.
Migrating from existing Express app
Section titled “Migrating from existing Express app”If you have an existing Express app and want to add actor-ts:
import express from 'express';import { ExpressBackend, ExpressBackendOptions } from 'actor-ts/http';
const app = express();
// Existing routes + middleware stay as-is:app.use('/legacy', oldLegacyRouter);
// Hand the existing app to the backend; actor-ts registers its// routes on the same app, alongside your existing ones.const expressBackendOptions = ExpressBackendOptions.create().withApp(app);const backend = new ExpressBackend(expressBackendOptions);
await http.newServerAt('0.0.0.0', 8080) .useBackend(backend) .bind(routes);Pass your existing app to the backend via .withApp(app) —
actor-ts registers its routes on the same app, so your existing
routes and middleware keep working without swapping the whole
HTTP stack.
Where to next
Section titled “Where to next”- HTTP overview — the bigger picture.
- Fastify backend — the default + recommended.
- Route DSL — what backends register.
