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

HTTP overview

Это содержимое пока не доступно на вашем языке.

The HTTP module is separate from the I/O broker actors — HTTP servers don’t fit the “one connection many messages” shape, so they get their own DSL and backend abstraction.

import { ActorSystem } from 'actor-ts';
import { path, get, post, completeJson, entity, concat } from 'actor-ts/http';
const system = ActorSystem.create('my-app');
const routes = path('api',
path('orders',
concat(
get(async () => completeJson(200, { orders: [] })),
post(async (req) => {
const order = entity<NewOrder>(req);
// ... handle ...
return completeJson(201, { id: 'o-1' });
}),
),
),
);
const binding = await system.http(8080).bind(routes);
console.log(`bound on ${binding.host}:${binding.port}`);

Three things going on:

  • The route DSL — path, get, post, concat compose a tree of routes. Type-safe; compiles to a flat list at bind time.

  • The marshaller — entity<T>(req) decodes the request body by Content-Type; completeJson / completeText encode the response.

  • The shortcut — system.http(port).bind(routes) starts a server with the default Fastify backend. For a different backend, pass backend: (see below).

    It binds loopback — 127.0.0.1 — when you name no host, so the shortest form is reachable from the machine and nowhere else. A server that should answer from outside says so: system.http(port, { host }). This changed in #1408; it used to bind every interface, which meant the form most people copied was the one that published the server without saying so.

PieceLives inPage
Routingactor-ts/http exports path, get, post, complete*, etc.Route DSL
Marshallingentity<T>(req) decode + completeJson encode.Marshalling
BackendPluggable HTTP server — Fastify by default, Hono, Express.Backends

The DSL builds an in-memory route tree; system.http(...).bind(routes) flattens it and registers everything with the chosen backend.

import { HonoBackend } from 'actor-ts/http';
// Default — no setup needed; Fastify is a hard dependency:
await system.http(8080).bind(routes);
// Explicit override (Express / Hono are peer-deps; opt-in):
await system.http(8080, { backend: new HonoBackend() }).bind(routes);
// For full control, the underlying extension surface is still there:
import { HttpExtensionId } from 'actor-ts/http';
await system.extension(HttpExtensionId)
.newServerAt('0.0.0.0', 8080)
.useBackend(new HonoBackend())
.bind(routes);
BackendRuntime fitWhen
FastifyBackend (default)Bun, NodeProduction default — Fastify is the most-battle-tested.
ExpressBackendNode, BunExisting Express middleware ecosystem fits cleanly.
HonoBackendBun, Node, DenoTiny + edge-friendly; the most Bun-and-Deno-native option.

All three implement the same HttpServerBackend interface — the route DSL compiles identically; the backend just owns the listen/dispatch loop.

See the backend pages for the configuration options each accepts.

Whatever backend is mounted, the listening socket carries bounds of its own — the header and receive deadlines a peer is held to, how long a quiet keep-alive connection is kept, how many connections are accepted at once, and how large a request’s body and header block may be:

import { HttpExtensionId, HttpServerOptions } from 'actor-ts/http';
const serverOptions = HttpServerOptions.create()
.withIdleTimeoutMs(5_000)
.withRequestTimeoutMs(30_000)
.withMaxConnections(10_000)
.withMaxContentLength(8 * 1024 * 1024);
await system.extension(HttpExtensionId)
.newServerAt('0.0.0.0', 8080)
.withServerOptions(serverOptions)
.bind(routes);

They exist mostly to be moved without a code change, so the same six fields are readable from actor-ts.http.server — withServerOptions(...) wins per field, then the config file, then the built-in default. Only header-timeout (60 s) and request-timeout (300 s) ship a value; leaving idleTimeoutMs, maxConnections, maxContentLength and maxHeaderBytes unset keeps the backend’s own choice — “unlimited”, for the connection count — which is what every release before them did.

The three timeouts and the connection cap reach a connection through a node:http server, so Hono on Deno cannot honour them — the runtime exposes neither the server nor an equivalent knob — and Hono on Bun honours only idle-timeout, which Bun.serve takes as its own idleTimeout. That one is a wider bound there: whole-connection inactivity, so a handler that writes nothing for that long is cut too, at most 255s, and unset it follows the server’s request deadline — 36 s for the built-in 30 s — rather than Bun’s own 10 s, so a requestTimeout() 503 is written first. Two of them, header-timeout and max-connections, are held by actor-ts on top of the property, because the runtimes disagree about whether writing it does anything. Holding them takes the connection events a server emits, and Deno’s node:http emits none, so on Fastify or Express under Deno neither holds, and bind() says so for either one that is set. The two size caps are fixed when the server is built. max-content-length holds on every backend and runtime, since each backend reads its own bodies; max-header-bytes holds wherever actor-ts builds the server and the runtime keeps the option — Fastify and Express on Bun and Node, and Hono on Node; not Hono on Bun, and not on Deno, whose node:http ignores it and says so. A backend you construct yourself has to be built with them — new FastifyBackend(fastifyFactoryOptions(serverOptions)) for Fastify — or bind() refuses it. The configuration reference carries the per-backend table, that difference and the sweep caveat on request-timeout.

The same object carries the two settings that make the process itself the TLS endpoint. Off by default — behind a reverse proxy or an ingress that terminates for you, plain HTTP is still the right answer, and the security page says how to run that way. For the single-process and development cases, where standing up a terminator just to exercise a Secure cookie is the friction:

import { readFileSync } from 'node:fs';
import { HttpExtensionId, HttpServerOptions } from 'actor-ts/http';
const serverOptions = HttpServerOptions.create()
.withTls({
cert: readFileSync('./tls/cert.pem'),
key: readFileSync('./tls/key.pem'),
// client certificates, if you terminate mTLS here:
// ca: readFileSync('./tls/ca.pem'), requestClientCert: true, rejectUnauthorized: true,
})
.withHttp2(); // h2 through ALPN, HTTP/1.1 staying available on the same port
await system.extension(HttpExtensionId)
.newServerAt('0.0.0.0', 8443)
.withServerOptions(serverOptions)
.bind(routes);

The material is PEM contents or DER bytes, the raw TCP transport’s vocabulary; from the config file the same fields are paths, read once when the block is:

actor-ts.http.server {
tls {
cert-file = "/etc/actor-ts/tls/cert.pem"
key-file = "/etc/actor-ts/tls/key.pem"
}
http2 = true
}

One shape, three runtimes: Bun.serve({ tls, http2 }), https.createServer or http2.createSecureServer under @hono/node-server, and Deno.serve({ cert, key }). HTTP/2 is refused without TLS — h2c is not offered — and with it a client that speaks h2 negotiates it while one that does not still gets HTTP/1.1 on the same port. Deno negotiates h2 whenever TLS is on and has no knob for it, so there http2 records intent rather than deciding. Bun.serve learned http2 in Bun 1.4.1, and the runtime floor is 1.4.0: on an older Bun the setting is refused at bind rather than ignored, since the alternative is HTTP/1.1 served under a setting that says otherwise. Client-certificate verification (requestClientCert) is enforced on Bun and Node by every backend; on Deno every backend refuses it rather than ignore it silently — Deno.serve has no such option, and Deno’s node:https, which Fastify and Express run on there, accepts it and enforces nothing. Everywhere it needs a ca to verify against, and bind() refuses it without one: the TLS stack would otherwise check client certificates against the runtime’s default trust store and admit any certificate a public CA issued. A ca that holds no certificate — an empty ca-file, a blank secret — is refused too, demand or not; the rule is stated once, under Client certificates.

Which backend does what: Hono hands the pair to its runtime’s runner; Fastify takes both as factory options, so the framework-built instance gets them and one you construct yourself needs fastifyFactoryOptions(serverOptions) — see its page; Express terminates TLS on the node:https server it builds for itself and refuses http2, because Express does not survive the compatibility API of node:http2 — see its page.

const response = await http.singleRequest({
method: 'POST',
url: 'https://api.example.com/orders',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ sku: 'book-1' }),
});
console.log(response.status, response.body);

The shared client wraps the runtime’s native fetch. Works identically on Bun, Node, and Deno (every supported runtime has fetch built in).

A response is buffered in memory before you see it, so the three things the remote peer controls are bounded by default:

BoundDefaultPer-request override
Deadline30 stimeoutMs — 0 opts one call out entirely
Response body8 MiBmaxResponseBytes
Redirect hops5, followedredirect, maxRedirects

Past the ceiling the request is aborted while the body is still arriving and the call throws HttpResponseTooLargeError, so an oversized or endless response never finishes allocating. Past the deadline it aborts exactly as an explicit timeoutMs always did — what changed is that a call naming no deadline now has one.

Each override is checked when the call is made, not only when the client is built. Every bound is enforced by a comparison, and a NaN loses a comparison silently: a timeoutMs of NaN arms no timer, a maxResponseBytes of Infinity never trips, and neither raises anything — the bound just stops existing. So an out-of-domain value throws OptionsError before a socket is opened. timeoutMs: 0 remains the one legitimate way to have no deadline, and maxRedirects: 0 the way to refuse the first redirect.

Raise them per call when a single endpoint is the exception:

const report = await system.extension(HttpExtensionId).client.get(
'https://api.example.com/exports/daily',
{ maxResponseBytes: 64 * 1024 * 1024, timeoutMs: 120_000 },
);

Or give a whole integration its own client, instead of loosening the one every actor in the system shares:

import { HttpClientOptions } from 'actor-ts/http';
const exportClientOptions = HttpClientOptions.create()
.withMaxResponseBytes(64 * 1024 * 1024)
.withDefaultTimeoutMs(120_000);
const exportClient = system.extension(HttpExtensionId).newClient(exportClientOptions);

Or move the numbers the whole deployment inherits, without touching code, under actor-ts.http.client:

actor-ts.http.client {
max-response-bytes = 32M
default-timeout = 60s
}

Precedence is the usual one — a request beats the client it was made on, which beats HOCON, which beats the built-in defaults. The shared HttpExtensionId client reads this block too, so raising the floor does not mean abandoning it. A new HttpClient() built directly, with no system to read config from, keeps the built-in numbers.

The client follows redirects itself rather than handing them to the platform, so the decisions happen between hops:

redirectWhat happens on a 3xx with a Location
'follow' (default)Chase it, up to maxRedirects hops
'error'Throw HttpRedirectError; the target is never contacted
'manual'Return the 3xx as-is, Location readable in headers

Following is bounded at 5 hops (the platform allows 20), and a followed hop is not a blind replay of the original request:

  • A hop that crosses origins loses authorization, cookie and proxy-authorization, so a redirect cannot walk a bearer token to a host you never chose.
  • A 303 — and a 301/302 after a POST — continues as a GET with the body and its content-type dropped, matching the Fetch spec, so a write is never replayed against a second host.
  • A target that is not http: or https: is refused outright.
  • The deadline and the byte ceiling are cumulative over the whole chain, not per hop; intermediate 3xx bodies are discarded.

Refusals happen before the hop is issued — that is the point. A check on where a chain ended up has already made every request in it, and making the request is the side effect worth preventing.

const webhookClientOptions = HttpClientOptions.create()
.withRedirect('error')
.withMaxResponseBytes(256 * 1024);
const webhookClient = system.extension(HttpExtensionId).newClient(webhookClientOptions);

response.url names the hop that actually answered, which is what to assert on when it matters which host served the bytes.

For more elaborate client patterns (retries, caching), wrap the client in a retry + circuit-breaker call.

import { cached, get, path, rateLimit } from 'actor-ts/http';
import { InMemoryCache } from 'actor-ts/cache';
// One cache per middleware — never one shared instance (see below).
const limiterCache = new InMemoryCache();
const responseCache = new InMemoryCache();
const limited = rateLimit({
cache: limiterCache,
windowMs: 1_000,
max: 100,
key: (request) => request.remoteAddress ?? 'unknown',
});
const readThrough = cached({
cache: responseCache,
ttlMs: 30_000,
key: (request) => request.path,
});
const routes = path('api', get(limited(readThrough(apiHandler))));

The framework ships three:

MiddlewareWhat it does
Response cacheCaches a handler’s response keyed by a user-supplied key(request) function.
Rate limitPer-IP / per-key fixed-window rate limiter.
Idempotency keyDe-duplicates writes based on an Idempotency-Key header.

Each is a handler wrapper — you call it with the options and hand the returned function the handler you want to protect. Compose by nesting at the handler level. See middleware pages.

The route handler returns a Promise<HttpResponse> — you can freely await actor calls inside:

const routes = path('orders',
path(':id',
get(async (req) => {
const id = req.path.split('/').pop();
const order = await orderRegistry.ask({ kind: 'get', id },
5_000,);
return completeJson(200, order);
}),
),
);

This is the common pattern — HTTP handlers act as a thin adapter: parse the request, ask an actor, marshal the reply. Keep business logic in actors; HTTP handlers stay short.

The HttpExtension API reference covers the full surface.