Routing overview
Это содержимое пока не доступно на вашем языке.
A router is an actor whose only job is to forward each incoming
message to one (or more) of its routees. You spawn the router
once; behind it sit N worker actors; senders tell the router and
never know how many routees exist.
Two shapes ship with the framework:
| Form | Where it lives | Routees are… |
|---|---|---|
Router (local) | One node, one actor system. | Children of the router, created at spawn time from the same actor. |
ClusterRouter | Across cluster nodes. | Up-members of the cluster, derived from membership + a routee path. |
Both expose the same external surface: a single ActorRef<TMessage>
that callers tell. The difference is what’s on the other side.
When to reach for a router
Section titled “When to reach for a router”Four patterns:
- Keep I/O-bound handlers flowing. A single actor processes one
message at a time, so a handler that
awaits a database or an HTTP call parks every later message behind that wait. A 4-routee round-robin router lets four of them be in flight at once, without breaking message ordering within a routee. That is concurrency, not CPU parallelism: the routees are children of the router, on its thread, and the runtime is single-threaded, so four CPU-bound routees finish no sooner than one (benchmarks/single-node/router-pool.tsmeasures exactly this). CPU work goes tocontext.offloador to a pool across threads. - Spread load across nodes. A cluster router with role-filtered
routees gives you fan-out across every node carrying the
'compute'role. Add a node, the router picks it up; remove a node, the router stops sending to it. - Pin work to a routee deterministically. Consistent-hashing (cluster only) puts every message with the same key on the same routee — useful when each routee maintains per-key state (a cache, a session, a counter).
- Race N routees for the same answer. Scatter/gather asks every routee the same question and returns whichever replies first, trading N times the work for the minimum of N latencies. That is a different goal from the other three — tail latency, not throughput. See Scatter/gather.
A minimal example
Section titled “A minimal example”import { ActorSystem, Router, Actor } from 'actor-ts';
class Worker extends Actor<{ payload: string }> { override onReceive(message: { payload: string }): void { this.log.info(`worked on ${message.payload}`); }}
const system = ActorSystem.create('demo');
const pool = system.spawn( Router.roundRobin(4, Worker), 'workers',);
pool.tell({ payload: 'a' }); // → worker-1pool.tell({ payload: 'b' }); // → worker-2pool.tell({ payload: 'c' }); // → worker-3pool.tell({ payload: 'd' }); // → worker-4pool.tell({ payload: 'e' }); // → worker-1 (round-robin wraps)The pool ref looks like a single actor to callers; under the hood
the routing actor cycles through four Worker children.
The five strategies
Section titled “The five strategies”| Strategy | What it does | Best for |
|---|---|---|
round-robin | One routee per message, cycling. Even distribution by message count. | Homogeneous workloads. |
random | One routee per message, uniformly random. | Same as round-robin, but stateless. |
broadcast | Every routee gets every message. | Notifications, cache invalidations. |
smallest-mailbox | One routee per message, the one with the shortest queue. | Uneven per-message cost. |
consistent-hashing (cluster only) | One routee per message, key-pinned. | Per-key state (sharding-lite). |
smallest-mailbox is the one that balances by backlog instead of
by message count. Round-robin hands out turns blindly, so a routee
that drew an expensive message still gets its next 1-in-N on schedule
and falls behind; smallest-mailbox reads each routee’s queue depth and
picks the shallowest, so a busy routee stops being chosen until it
catches up. It pays for that with one depth read per routee per
message, which is why round-robin remains the default.
Both routers have it, but they learn the depth differently. The local one reads its routees’ mailboxes directly — they are its own children, in the same process. The cluster one cannot: a remote mailbox is on another node, and asking per message would park the router behind a network round-trip. It routes on a cached depth instead, refreshed on a background tick, which trades a little freshness for a routing decision that stays synchronous. See Cluster router for what that lag can and cannot cost.
See Strategies for the deep dive,
plus the Broadcast message wrapper that overrides the strategy
per-message.
All five are one-shot: the router picks routees, forwards, and is
done — the reply, if there is one, is between the routee and the
original sender. Router.scatterGatherFirstCompleted is the one
router that does not fit that shape: it asks every routee and answers
the caller itself with the first reply that arrives. It is therefore
not a strategy you can hand to Router.custom, but its own factory —
see Scatter/gather.
Pool vs group
Section titled “Pool vs group”The local Router is always a pool — it creates its routees
itself. The cluster ClusterRouter is more like a group — the
routees already exist (one actor per up-member at a well-known
path), and the router just finds them.
For most cases, pool is what you want. The group model surfaces when you want existing actors (e.g. shard regions, fixed-name workers spawned at startup) to receive routed traffic.
See Pool vs group for when each shape is the right fit.
Routers and supervision
Section titled “Routers and supervision”The router is a regular actor — it has its own supervisor strategy,
and it watches each routee. When a routee crashes:
- Without intervention, the routee’s parent (the router) applies
its supervisor strategy. By default that’s the framework’s
defaultStrategy— Restart up to 10/minute. - The restarted routee re-joins the pool at the same path. The router doesn’t have to do anything special.
- Anything routed to the routee during its brief restart window stays in its mailbox — the mailbox is suspended for the restart and resumed afterwards (the same instance, not drained), so those messages are processed once the routee is running again.
For per-routee supervision strategies, configure them on the routee options:
import { ActorOptions, stoppingStrategy } from 'actor-ts';
const routeeOptions = ActorOptions.create().withSupervisorStrategy(stoppingStrategy);
system.spawn(Router.roundRobin(4, Worker, routeeOptions), 'workers');Now any worker that throws is stopped instead of restarted — and
the router, which watches every routee, prunes the dead ref from the
pool on its Terminated. The pool is one routee smaller, and nothing
is routed into the gap; what the routee had already accepted is
dead-lettered by its own stop, as with any stopping actor. A pool that
should heal rather than shrink wraps each routee in a
BackoffSupervisor —
Router.roundRobin(4, BackoffSupervisor.factory({ child: Worker })) —
so the slot is refilled after a backoff instead of vanishing.
Routers are not (the only) way to parallelize
Section titled “Routers are not (the only) way to parallelize”A router gives you N independent actors processing one message at a
time each — on one thread. Which of the five ways to spread work
fits depends on what the unit of work is, how many threads it should
use, and whether the caller wants one address or a function call.
Every figure below is one the tree already prints, with its source
named; none is re-measured here.
| Mechanism | Unit of work | Threads | One local address? | Pool size | On routee stop / crash | Cost per message | Break-even | When |
|---|---|---|---|---|---|---|---|---|
Local Router pool | actor message | 1 — the router’s | yes | fixed at spawn | crash → restarted in place by the default strategy; stop → pruned, the pool is one smaller | local tell ~320 ns (benchmarks/worker/mesh-message-cost.ts) | any await in the handler — it buys concurrency, never CPU | handlers that wait on I/O |
ClusterRouter over the worker mesh — the recipe below | actor message | N workers | yes — the router | one routee per worker; follows membership | crash → restarted by its own parent on the worker; stop → the router keeps sending to that node until membership changes | cross-thread tell ~21 µs, ask ~180 µs (same benchmark) | ~100 µs of work per message (the measured table) | N identical compute actors behind one ref |
OffloadPool / context.offload | pure function | a demand-driven pool | no — a call, a promise back | grows with demand, shrinks when idle | a failed run rejects its promise; a dead worker is replaced inside a restart budget | ~3 µs per pipelined task (benchmarks/worker/task-offload-breakeven.ts) | ~10 µs per call (when it pays) | hash, compress, transform — no actor on the far side |
actor-ts.parallelism.workers with several top-level actors | actor and its subtree | N workers | one ref per actor, path unchanged | one worker per spawn, chosen by placement | supervised by its worker’s guardian; the ref tells, asks and watches across the thread | cross-thread tell ~21 µs, ask ~180 µs | ~100 µs of work per message | several different compute actors, each with its own address |
| Sharded entity | actor per key | every node or worker carrying the role | by key, through the shard region | exactly one live actor per key | restarted by its shard; relocated on rebalance | the transport’s hop: ~21 µs on the mesh, ~22 µs tell / ~245 µs ask over TCP (FAQ) | the same ~100 µs, plus the entity’s own state | exactly one actor per key, with failover |
DistributedPubSub is not in the table because it answers a different question: fan-out to a dynamic subscriber set — actors come and go, and any of them can receive published events — where a router’s routee set is fixed or follows membership.
One address, one actor per thread
Section titled “One address, one actor per thread”The second row is the shape the other four are not: N identical
actors across N threads, and callers holding one local ref.
Nothing ships it as a single call. It composes from two things that
do ship: the worker mesh runs the actor module’s setup(context) on
every worker once its node is up, and a ClusterRouter is a group
router over whatever lives at one path on every member with a role.
actor-ts.parallelism { workers = "auto" # one worker per core, minus the main thread offload = ["/user/offloaded-*"] # the router below must not match — see the traps}actor-ts.worker-mesh.worker-roles = ["compute"]// actors.ts — next to the entry module; every worker imports itimport { Actor, type ActorRef } from 'actor-ts';import { ClusterMailboxDepthAgent } from 'actor-ts/cluster';import type { WorkerMeshSetupContext } from 'actor-ts/worker';
export type EncodeCommand = { readonly kind: 'encode'; readonly frame: Uint8Array; readonly replyTo: ActorRef<EncodedFrame>;};
export type EncodedFrame = { readonly bytes: number; /** The address of the node that did the work: which thread, in a mesh. */ readonly encodedOn: string;};
export class Encoder extends Actor<EncodeCommand> { override onReceive(command: EncodeCommand): void { // The CPU work goes here; the reply names the thread that did it. const encodedOn = this.system.cluster.map((cluster) => cluster.selfAddress.toString()).getOrElse('main'); command.replyTo.tell({ bytes: command.frame.byteLength, encodedOn }); }}
/** Runs once on every worker, after its node has joined the mesh. */export function setup(context: WorkerMeshSetupContext): void { context.system.spawn(Encoder, 'encoder'); ClusterMailboxDepthAgent.serve(context.cluster); // only 'smallest-mailbox' reads it}// main.ts — the entry module; the router stays on this threadimport { ActorSystem, ParallelismExtensionId } from 'actor-ts';import { ClusterRouter, ClusterRouterOptions } from 'actor-ts/cluster';import type { EncodeCommand, EncodedFrame } from './actors.js';
const system = ActorSystem.create('media');const parallelism = system.extension(ParallelismExtensionId);await parallelism.whenReady();
const clusterRouterOptions = ClusterRouterOptions.create<EncodeCommand>() .withCluster(parallelism.workerMesh!.cluster) .withRouterType('round-robin') .withRouteePath('/user/encoder') .withRole('compute');const encoders = system.spawn(ClusterRouter.factory(clusterRouterOptions), 'encoders');
const encoded = await encoders.ask<EncodedFrame>({ kind: 'encode', frame: new Uint8Array(4096) });console.log(encoded.encodedOn); // e.g. media@worker:2 — each ask names the next worker in address order, wrapping aroundwhenReady() is the one wait: the mesh is up and every setup has run,
so the router’s first rebuild sees every worker. Routees are sorted
lexically, by the string form of their address — media@worker:10
before media@worker:2 — so round-robin order is stable across
rebuilds; for three workers the rotation is :2, :3, :4, :2 again.
The plain-object form works too —
ClusterRouter.factory({ cluster, routerType: 'round-robin', routeePath: '/user/encoder', role: 'compute' }).
Three traps — the first two a message that goes nowhere, the third a router that balances less than it seems to:
- The router must not match
offload.ClusterRouter.factory(…)returns a factory, and a factory is a closure that cannot cross a thread — aspawnwhose path matchesoffloadthrows on the caller’s stack, naming the fix. Keep the pattern off the router’s path, as/user/offloaded-*above does. - Without
rolethe main thread is a routee too. The router’s own node is a member like any other, and the main thread has no/user/encoder— so every (N+1)-th message is dropped where it arrives, with one warning per message (no envelope handler registered, dropping message to …; on a node that has startedClusterSharding, the sharding extension takes the unresolved envelope instead and warns[sharding] no region/coordinator registered for …), and anaskfor it times out. The role is what keeps the main thread out of the pool. smallest-mailboxneeds the agent on every worker. The router reads mailbox depths from a small framework agent on each routee node, and asmallest-mailboxrouter starts that agent on its own node only. TheClusterMailboxDepthAgent.serve(context.cluster)line insetupis what makes the workers report; without it nothing breaks, but no routee ever reports, and with no reading anywhere the strategy is plain round-robin. That fallback is all-or-nothing, not per worker: a worker that stays silent while others report — its reading missing, or older thanmailboxDepthStaleAfterMs— is skipped, not dealt its turn, because the silent node may be the struggling one. Cluster router states the rule.
What the recipe does not give you: a pool that grows and shrinks with
demand — that is #212, and today only the OffloadPool scales that way.
What it does give you is one scrape for all of it: the mesh relays every
worker’s metrics registry to the main thread (#1570), so once the main
thread exports /metrics the encoders’ work is there — each worker’s
figures as thread="worker-<slot>" series beside the router’s own
thread="main" ones, sum without (thread) for the pool’s total — see
the
scope of a scrape.
Where to next
Section titled “Where to next”- Router — the
Router.roundRobin(...),.random(...),.broadcast(...),.smallestMailbox(...),.custom(...)factories. - Strategies — what each strategy does, plus writing your own.
- Scatter/gather — ask every routee at once and answer with the first reply.
- Pool vs group — when to use a router that spawns its routees vs one that finds them.
- Cluster router — the membership-driven cluster equivalent.
