Перейти к содержимому
Русский

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

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.

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

See Security best practices.

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.

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.

Terminal window
npm install express
# or: bun add express

For Express 5+ recommendation; older versions may work but aren’t tested.

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.

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.