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,concatcompose 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/completeTextencode the response. -
The shortcut —
system.http(port).bind(routes)starts a server with the default Fastify backend. For a different backend, passbackend:(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.
The three pieces
Section titled “The three pieces”| Piece | Lives in | Page |
|---|---|---|
| Routing | actor-ts/http exports path, get, post, complete*, etc. | Route DSL |
| Marshalling | entity<T>(req) decode + completeJson encode. | Marshalling |
| Backend | Pluggable 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.
The backends
Section titled “The backends”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);| Backend | Runtime fit | When |
|---|---|---|
FastifyBackend (default) | Bun, Node | Production default — Fastify is the most-battle-tested. |
ExpressBackend | Node, Bun | Existing Express middleware ecosystem fits cleanly. |
HonoBackend | Bun, Node, Deno | Tiny + 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.
Bounds on the connection
Section titled “Bounds on the connection”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.
TLS and HTTP/2
Section titled “TLS and HTTP/2”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.
The HTTP client
Section titled “The HTTP client”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).
Bounds every call carries
Section titled “Bounds every call carries”A response is buffered in memory before you see it, so the three things the remote peer controls are bounded by default:
| Bound | Default | Per-request override |
|---|---|---|
| Deadline | 30 s | timeoutMs — 0 opts one call out entirely |
| Response body | 8 MiB | maxResponseBytes |
| Redirect hops | 5, followed | redirect, 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.
Where a redirect may take you
Section titled “Where a redirect may take you”The client follows redirects itself rather than handing them to the platform, so the decisions happen between hops:
redirect | What 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,cookieandproxy-authorization, so a redirect cannot walk a bearer token to a host you never chose. - A
303— and a301/302after aPOST— continues as aGETwith the body and itscontent-typedropped, matching the Fetch spec, so a write is never replayed against a second host. - A target that is not
http:orhttps: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.
Middleware
Section titled “Middleware”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:
| Middleware | What it does |
|---|---|
| Response cache | Caches a handler’s response keyed by a user-supplied key(request) function. |
| Rate limit | Per-IP / per-key fixed-window rate limiter. |
| Idempotency key | De-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.
Connecting HTTP to actors
Section titled “Connecting HTTP to actors”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.
Where to next
Section titled “Where to next”- Route DSL — the full DSL:
path,get/post/put/etc.,concat,complete*,redirect,reject. - Marshalling —
entity<T>, Content-Type-driven decoding, response encoding. - Fastify backend — default backend’s configuration.
- Hono backend / Express backend — alternatives.
- Response cache middleware — caching for GET responses.
- Rate limit middleware — per-key rate limiting.
- Idempotency-key middleware — write-deduplication for mutations.
The HttpExtension API
reference covers the full surface.
