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

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
  tls: {
    cert: fs.readFileSync('./tls/cert.pem'),
    key:  fs.readFileSync('./tls/key.pem'),
  },
});

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.

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

trustProxy: true resolves to the client-controlled entry

new FastifyBackend({ trustProxy: true });   // ✗
new FastifyBackend({ trustProxy: 2 });      // ✗ address-blind

true trusts every hop, so proxy-addr never truncates the address list and req.ip becomes the leftmost X-Forwarded-For entry — the one the client sent. A numeric hop count only compares indexes and never addresses, so it believes the header on a request that passed no proxy at all.

Or keep the decision in the allowlist

IpAllowlist’s trustedProxies applies the same trust-by-address rule one layer up, needs nothing from the backend, and therefore reads identically on Express and Hono — where trustProxy is either awkward or absent. Prefer it when the client address is a policy input rather than something every handler needs.

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

See Security best practices.

TLS

new FastifyBackend({
  tls: {
    cert: fs.readFileSync('./tls/cert.pem'),
    key:  fs.readFileSync('./tls/key.pem'),
    // For mTLS:
    ca:                fs.readFileSync('./tls/ca.pem'),
    requestCert:       true,
    rejectUnauthorized: true,
  },
});

Standard Fastify TLS options. For most production setups, TLS terminates at the load balancer — the app speaks plain HTTP internally — but in-app TLS is supported when needed.

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:

• JWT / OAuth authentication.
• Request validation (@fastify/swagger).
• CORS (@fastify/cors).
• Compression.

The actor-ts DSL handles routing; Fastify plugins handle cross-cutting concerns. They compose cleanly.

Lifecycle

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.

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

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.

Don't use Fastify's logger and actor-ts log together

new FastifyBackend({ logger: true });   // ✗ creates noise

Fastify’s built-in logger duplicates actor-ts’s logging. Disable Fastify’s logger; rely on system.log for structured logging.

Plugins that override routes

// Fastify plugin that hooks into /api/* overrides actor-ts routes

Be careful with plugins that register routes — they might conflict with the framework’s route registration. Register plugins before binding actor-ts routes if both target overlapping paths.

Where to next

• HTTP overview — the bigger picture.
• Route DSL — what gets registered with Fastify.
• Express backend — the alternative.
• Hono backend — the lightweight alternative.