Fastify backend
Ce contenu n’est pas encore disponible dans votre langue.
FastifyBackend is the default HTTP backend for actor-ts.
Wraps Fastify — fast, well-maintained, with a huge ecosystem of
plugins (JWT auth, validation, swagger, etc.).
import { ActorSystem } from 'actor-ts';import { HttpExtensionId } from 'actor-ts/http';
const http = system.extension(HttpExtensionId);
await http.newServerAt('0.0.0.0', 8080).bind(routes);// ↑ Fastify by defaultTo make the backend explicit:
import { FastifyBackend } from 'actor-ts/http';
await http.newServerAt('0.0.0.0', 8080) .useBackend(new FastifyBackend()) .bind(routes);Configuration
Section titled “Configuration”new FastifyBackend({ logger: false, // Fastify's built-in logger — leave off; use actor-ts log bodyLimit: 1_048_576, // 1 MiB request body cap});Most settings pass through to Fastify’s FastifyServerOptions.
The framework configures route registration; you tune Fastify’s
own knobs.
bodyLimit is the one it fills in for you. Left unset it is 1 MiB —
the same cap the Express and Hono backends apply, so which requests are
accepted does not change with the backend. Passing your own still wins.
The server-wide actor-ts.http.server.max-content-length sets that cap for
every backend at once, and Fastify takes it as bodyLimit — at construction,
like everything in this bag. The framework-built backend is built with it. A
backend you build yourself adopts it only through
fastifyFactoryOptions(serverOptions), and one whose bodyLimit differs from a
set key — the built-in 1 MiB of a bare new FastifyBackend() included — is
refused at bind(), naming the key. max-header-bytes takes the same road as
maxHeaderSize. Fastify hands its server factory the https bag once TLS is
on and the http bag otherwise, so fastifyFactoryOptions puts the cap in the
one Fastify reads, and a hand-built backend whose server holds a different
cap — or none, which is what a cap in http on a TLS instance amounts to — is
refused as well:
import { FastifyBackend, fastifyFactoryOptions, HttpExtensionId, HttpServerOptions } from 'actor-ts/http';
const serverOptions = HttpServerOptions.create() .withMaxContentLength(8 * 1024 * 1024) .withMaxHeaderBytes(32 * 1024);
const backend = new FastifyBackend({ logger: false, ...fastifyFactoryOptions(serverOptions), // { bodyLimit, http: { maxHeaderSize } }});
await system.extension(HttpExtensionId) .newServerAt('0.0.0.0', 8080) .useBackend(backend) .withServerOptions(serverOptions) .bind(routes);Leave the backend to the framework and none of that is needed: it is built from the resolved options, HOCON included.
The timeouts and max-connections under
actor-ts.http.server are installed on
fastify.server after listen(), so they hold here whether the framework
built this backend or you did. Two of Fastify’s own defaults differ from
node:http’s and are worth knowing: keepAliveTimeout is 72 s rather than
5 s — deliberately, so the server outlives a load balancer’s idle window — and
requestTimeout is 0, no bound at all. The framework now publishes
request-timeout = 300s, so on this backend that is a receive deadline where
there previously was none. Set it back to 0 in your config to restore the old
behaviour; idle-timeout ships no value, so Fastify’s 72 s is untouched.
Under Deno, which this backend does not support, the header deadline and
max-connections never hold: its node:http shim emits no connection event
for them to count. idle-timeout and request-timeout hold from deno 2.7.13
on, as on Node; before it the shim accepts keepAliveTimeout and
requestTimeout without applying either. Measured on deno 2.6.8 under
idle-timeout = 600ms: a keep-alive connection was still open 3 s after its
response, where deno 2.7.13, Node and Bun closed it at 1.6 s. Each one that
does not hold is reported not in effect, and bind() names the ones you set in
a warning.
On the HTTP/2 listener (withHttp2()) Fastify’s 72 s reaches an idle session
as Fastify’s own session timer, which counts quiet time on the connection: it
closes an idle session at 72 s on Node but 144 s on Bun, which fires it at
twice its value, and on Bun a PING frame resets it, so a client pinging once a
second keeps a session with no request on it open indefinitely (still open at
170 s, bun 1.4.2). Setting idle-timeout replaces that timer with
actor-ts’s own, which closes a session that has had no stream open for the
value — the same on both runtimes, PINGs or not — and request-timeout gives
every HTTP/2 stream its own receive deadline. Two bounds hold for one protocol
only on that listener, and bind() warns about each one you set: on Bun,
idle-timeout and request-timeout bound HTTP/2 but not a connection that
negotiates HTTP/1.1 on the same port; on Node, max-header-bytes caps the
HTTP/1.1 requests but not an HTTP/2 stream’s header list, which only Node’s own
64 KiB limit bounds. The security page has the numbers.
Behind a reverse proxy
Section titled “Behind a reverse proxy”HttpRequest.remoteAddress comes from Fastify’s req.ip, which without
trustProxy is the socket peer. Because the constructor’s options pass
straight through to Fastify, trustProxy is configurable here — and if
you set it, give it the addresses of your proxies:
new FastifyBackend({ trustProxy: '10.9.9.0/24', // ✓ trusted-subnet form});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 FastifyBackend()) .withSecurityHeaders(false) // or a SecurityHeadersOptions bundle .bind(routes);Set it where every backend takes it, on the server options (see TLS and HTTP/2):
const serverOptions = HttpServerOptions.create() .withTls({ cert: fs.readFileSync('./tls/cert.pem'), key: fs.readFileSync('./tls/key.pem') }) .withHttp2();
await system.extension(HttpExtensionId) .newServerAt('0.0.0.0', 8443) .withServerOptions(serverOptions) .bind(routes);Fastify is the one backend that takes TLS and HTTP/2 as factory
options — Fastify({ https, http2 }) — not at listen(). The
framework-built backend is constructed with them, because bind()
resolves the server options before it constructs the backend. A backend
you construct yourself and hand to useBackend(...) has to carry them
itself, and fastifyFactoryOptions turns the same server options into
the factory shape:
import { FastifyBackend, fastifyFactoryOptions } from 'actor-ts/http';
const backend = new FastifyBackend({ logger: false, ...fastifyFactoryOptions(serverOptions), // { https: { cert, key, … }, http2 }});A hand-built backend without TLS that is then handed withTls(...) is
refused at bind() rather than bound as plain HTTP under a setting
that says otherwise, and so is one built with TLS but without
http2: true that is handed withHttp2(): it would answer HTTP/1.1 over
TLS where the setting says HTTP/2. So is one whose https verifies client
certificates differently from the server options — built without the
requestClientCert demand, or with it but without the same ca: it would
verify the way it was built, not the way the setting says. (Earlier versions of this page showed
new FastifyBackend({ tls: … }); tls is not a Fastify option and was
spread in and ignored — the server it described was never terminating
TLS.)
A client-certificate demand (requestClientCert) is enforced on Node and
Bun, where the certificate verifies against the ca you configure. On
Deno it is refused at bind(): Fastify serves through Deno’s
node:https, which accepts requestCert and enforces nothing — measured on
deno 2.6.8, the framework-built backend answered a client that presented no
certificate. Fastify is the default backend, so this is where a demand lands
when nothing else is configured; terminate TLS in front of the process, or
run on Node or Bun. The rule every backend follows is under
Client certificates.
For most production setups TLS still terminates at the load balancer and the app speaks plain HTTP internally; in-app TLS is for the single-process and development cases.
Accessing the raw Fastify instance
Section titled “Accessing the raw Fastify instance”const backend = new FastifyBackend();await http.newServerAt('0.0.0.0', 8080) .useBackend(backend) .bind(routes);
// After bind, register a native plugin via the escape hatch...await backend.withPlugin(fastifyJwt, { secret: '...' });// ...or reach the raw Fastify instance for lower-level hooks:backend.fastify.addHook('onRequest', authHook);Use for plugins not exposed via the framework’s DSL:
- OAuth / OpenID Connect login flows.
- Request validation (
@fastify/swagger). - Compression.
JWT verification and CORS need no plugin: the
JwtAuth middleware and the
cors() directive belong to the framework and
behave the same way on every backend.
The actor-ts DSL handles routing; Fastify plugins handle cross-cutting concerns. They compose cleanly.
Lifecycle
Section titled “Lifecycle”1. new FastifyBackend() — the constructor creates the Fastify instance2. The framework registers each compiled route on Fastify3. Fastify.listen() — opens the port4. On shutdown: Fastify.close() — drains in-flight requests, then exitsFastify.close() waits for in-flight requests to complete
before resolving — pairs with
coordinated shutdown’s
service-unbind phase.
Bundled dependency
Section titled “Bundled dependency”Fastify is a hard dependency of actor-ts — it installs with the framework, so there’s nothing extra to add. (The Express and Hono backends, by contrast, are optional peer dependencies you install on demand.)
Performance
Section titled “Performance”Rough numbers for trivial routes:
- 150K-200K req/sec on Bun (with
bun:testbenchmark). - 80K-120K req/sec on Node 22.
- P50 latency sub-millisecond for trivial handlers; higher for routes that ask actors.
Fastify is one of the fastest Node HTTP frameworks; the framework’s actor-routing overhead is the next bottleneck for hot routes.
Where to next
Section titled “Where to next”- HTTP overview — the bigger picture.
- Route DSL — what gets registered with Fastify.
- Express backend — the alternative.
- Hono backend — the lightweight alternative.
