コンテンツにスキップ
日本語

Fastify backend

このコンテンツはまだ日本語訳がありません。

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 default

To make the backend explicit:

import { FastifyBackend } from 'actor-ts/http';
await http.newServerAt('0.0.0.0', 8080)
.useBackend(new FastifyBackend())
.bind(routes);
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.

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

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

See Security best practices.

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.

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.

1. new FastifyBackend() — the constructor creates the Fastify instance
2. The framework registers each compiled route on Fastify
3. Fastify.listen() — opens the port
4. On shutdown: Fastify.close() — drains in-flight requests, then exits

Fastify.close() waits for in-flight requests to complete before resolving — pairs with coordinated shutdown’s service-unbind phase.

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

Rough numbers for trivial routes:

  • 150K-200K req/sec on Bun (with bun:test benchmark).
  • 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.