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

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:

FormWhere it livesRoutees are…
Router (local)One node, one actor system.Children of the router, created at spawn time from the same actor.
ClusterRouterAcross 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.

Four patterns:

  1. 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.ts measures exactly this). CPU work goes to context.offload or to a pool across threads.
  2. 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.
  3. 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).
  4. 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.
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-1
pool.tell({ payload: 'b' }); // → worker-2
pool.tell({ payload: 'c' }); // → worker-3
pool.tell({ payload: 'd' }); // → worker-4
pool.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.

StrategyWhat it doesBest for
round-robinOne routee per message, cycling. Even distribution by message count.Homogeneous workloads.
randomOne routee per message, uniformly random.Same as round-robin, but stateless.
broadcastEvery routee gets every message.Notifications, cache invalidations.
smallest-mailboxOne 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.

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.

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.

MechanismUnit of workThreadsOne local address?Pool sizeOn routee stop / crashCost per messageBreak-evenWhen
Local Router poolactor message1 — the router’syesfixed at spawncrash → restarted in place by the default strategy; stop → pruned, the pool is one smallerlocal tell ~320 ns (benchmarks/worker/mesh-message-cost.ts)any await in the handler — it buys concurrency, never CPUhandlers that wait on I/O
ClusterRouter over the worker mesh — the recipe belowactor messageN workersyes — the routerone routee per worker; follows membershipcrash → restarted by its own parent on the worker; stop → the router keeps sending to that node until membership changescross-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.offloadpure functiona demand-driven poolno — a call, a promise backgrows with demand, shrinks when idlea 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 actorsactor and its subtreeN workersone ref per actor, path unchangedone worker per spawn, chosen by placementsupervised by its worker’s guardian; the ref tells, asks and watches across the threadcross-thread tell ~21 µs, ask ~180 µs~100 µs of work per messageseveral different compute actors, each with its own address
Sharded entityactor per keyevery node or worker carrying the roleby key, through the shard regionexactly one live actor per keyrestarted by its shard; relocated on rebalancethe 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 stateexactly 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.

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 it
import { 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 thread
import { 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 around

whenReady() 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 — a spawn whose path matches offload throws on the caller’s stack, naming the fix. Keep the pattern off the router’s path, as /user/offloaded-* above does.
  • Without role the 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 started ClusterSharding, the sharding extension takes the unresolved envelope instead and warns [sharding] no region/coordinator registered for …), and an ask for it times out. The role is what keeps the main thread out of the pool.
  • smallest-mailbox needs the agent on every worker. The router reads mailbox depths from a small framework agent on each routee node, and a smallest-mailbox router starts that agent on its own node only. The ClusterMailboxDepthAgent.serve(context.cluster) line in setup is 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 than mailboxDepthStaleAfterMs — 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.

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