Zum Inhalt springen
Deutsch

Routing — Überblick

Ein Router ist ein Actor, dessen einzige Aufgabe es ist, jede eingehende Nachricht an einen (oder mehrere) seiner Routees weiterzuleiten. Du spawnst den Router einmal; hinter ihm sitzen N Worker-Actors; Sender tellen dem Router und wissen nie, wie viele Routees existieren.

Zwei Formen liefert das Framework aus:

FormWo es lebtRoutees sind…
Router (lokal)Ein Node, ein Actor-System.Kinder des Routers, zur Spawn-Zeit erstellt aus demselben Actor.
ClusterRouterÜber Cluster-Nodes hinweg.Up-Members des Clusters, aus Mitgliedschaft abgeleitet + ein Routee-Pfad.

Beide exponieren dieselbe externe Schnittstelle: eine einzelne ActorRef<TMessage>, die Aufrufer tellen. Der Unterschied ist was auf der anderen Seite ist.

Vier Patterns:

  1. I/O-gebundene Handler am Laufen halten. Ein einzelner Actor verarbeitet eine Nachricht nach der anderen; ein Handler, der auf eine Datenbank oder einen HTTP-Aufruf awaitet, parkt also jede spätere Nachricht hinter diesem Warten. Ein 4-Routee-Round-Robin- Router lässt vier davon gleichzeitig in der Luft sein, ohne das Message-Ordering innerhalb eines Routees zu brechen. Das ist Nebenläufigkeit, keine CPU-Parallelität: Die Routees sind Kinder des Routers, auf seinem Thread, und die Runtime ist single-threaded — vier CPU-gebundene Routees sind also keinen Deut schneller fertig als einer (benchmarks/single-node/router-pool.ts misst genau das). CPU-Arbeit geht an context.offload oder an einen Pool über Threads.
  2. Last über Nodes verteilen. Ein Cluster-Router mit role-gefilterten Routees gibt dir Fan-Out über jeden Node, der die 'compute'-Rolle trägt. Füge einen Node hinzu, der Router nimmt ihn auf; entferne einen Node, der Router stoppt das Senden an ihn.
  3. Arbeit deterministisch an einen Routee pinnen. Consistent-Hashing (nur Cluster) legt jede Nachricht mit demselben Key auf denselben Routee — nützlich, wenn jeder Routee Per-Key-Zustand hält (einen Cache, eine Session, einen Zähler).
  4. N Routees um dieselbe Antwort rennen lassen. Scatter/Gather stellt jedem Routee dieselbe Frage und liefert die Antwort dessen, der zuerst antwortet — das N-Fache an Arbeit gegen das Minimum aus N Latenzen. Das ist ein anderes Ziel als die ersten drei: Tail- Latenz, nicht Durchsatz. Siehe 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)

Die pool-Ref sieht für Aufrufer wie ein einzelner Actor aus; unter der Haube zykelt der Routing-Actor durch vier Worker-Kinder.

StrategieWas sie tutAm besten für
round-robinEin Routee pro Nachricht, zyklisch. Gleichmäßige Verteilung nach Nachrichten-Count.Homogene Workloads.
randomEin Routee pro Nachricht, gleichverteilt zufällig.Wie Round-Robin, aber zustandslos.
broadcastJeder Routee bekommt jede Nachricht.Notifications, Cache-Invalidierungen.
smallest-mailboxEin Routee pro Nachricht, der mit der kürzesten Queue.Ungleiche Kosten pro Nachricht.
consistent-hashing (nur Cluster)Ein Routee pro Nachricht, Key-gepinnt.Per-Key-Zustand (Sharding-Light).

smallest-mailbox ist die Strategie, die nach Rückstau statt nach Nachrichten-Count balanciert. Round-Robin vergibt Züge blind — ein Routee, der eine teure Nachricht gezogen hat, bekommt seinen nächsten 1-aus-N trotzdem pünktlich und fällt zurück; Smallest-Mailbox liest die Queue-Tiefe jedes Routees und wählt den flachsten, ein beschäftigter Routee wird also so lange nicht mehr gewählt, bis er aufgeholt hat. Bezahlt wird das mit einer Tiefenabfrage pro Routee pro Nachricht — deshalb bleibt Round-Robin der Default.

Beide Router haben sie, aber sie erfahren die Tiefe unterschiedlich. Der lokale liest die Mailboxen seiner Routees direkt — sie sind seine eigenen Kinder, im selben Prozess. Der Cluster-Router kann das nicht: eine entfernte Mailbox liegt auf einem anderen Node, und pro Nachricht zu fragen würde den Router hinter einen Netzwerk-Roundtrip parken. Er routet stattdessen auf einer gecachten Tiefe, aufgefrischt auf einem Hintergrund-Tick — etwas Aktualität gegen eine Routing-Entscheidung eingetauscht, die synchron bleibt. Siehe Cluster-Router dazu, was dieser Nachlauf kosten kann und was nicht.

Siehe Strategien für den Deep Dive plus den Broadcast-Nachrichten-Wrapper, der die Strategie pro Nachricht überschreibt.

Alle fünf sind One-Shot: Der Router wählt Routees, leitet weiter, fertig — die Antwort, falls es eine gibt, ist Sache des Routees und des ursprünglichen Senders. Router.scatterGatherFirstCompleted ist der eine Router, der nicht in diese Form passt: Er fragt jeden Routee und antwortet dem Aufrufer selbst mit der ersten eintreffenden Antwort. Er ist deshalb keine Strategie, die du Router.custom reichen kannst, sondern eine eigene Factory — siehe Scatter/Gather.

Der lokale Router ist immer ein Pool — er erstellt seine Routees selbst. Der Cluster-ClusterRouter ist eher eine Group — die Routees existieren bereits (ein Actor pro Up-Member an einem bekannten Pfad), und der Router findet sie nur.

Für die meisten Fälle ist Pool das, was du willst. Das Group-Modell taucht auf, wenn du willst, dass bestehende Actors (z.B. Shard-Regionen, Fixed-Name-Workers, die beim Startup gespawnt wurden) gerouteten Traffic empfangen.

Siehe Pool vs Group, wann jede Form die richtige Passung ist.

Der Router ist ein regulärer Actor — er hat seine eigene Supervisor-Strategie und watcht jeden Routee. Wenn ein Routee crashed:

  • Ohne Eingriff wendet der Parent des Routees (der Router) seine Supervisor-Strategie an. Standardmäßig ist das die defaultStrategy des Frameworks — Restart bis zu 10/Minute.
  • Der neu gestartete Routee tritt dem Pool an demselben Pfad wieder bei. Der Router muss nichts Besonderes tun.
  • Alles, was während des kurzen Restart-Fensters an den Routee geroutet wurde, bleibt in seiner Mailbox — die Mailbox wird für den Restart suspendiert und danach wieder aufgenommen (dieselbe Instanz, nicht gedrained), sodass diese Nachrichten verarbeitet werden, sobald der Routee wieder läuft.

Für Per-Routee-Supervisor-Strategien konfiguriere sie auf den Routee-Options:

import { ActorOptions, stoppingStrategy } from 'actor-ts';
const routeeOptions = ActorOptions.create().withSupervisorStrategy(stoppingStrategy);
system.spawn(Router.roundRobin(4, Worker, routeeOptions), 'workers');

Jetzt wird jeder Worker, der throwt, gestoppt statt neu gestartet — und der Router, der jeden Routee watcht, entfernt die tote Ref auf ihr Terminated aus dem Pool. Der Pool ist um einen Routee kleiner, und in die Lücke wird nichts geroutet; was der Routee bereits angenommen hatte, landet durch seinen eigenen Stop in Dead Letters, wie bei jedem stoppenden Actor. Ein Pool, der heilen statt schrumpfen soll, wickelt jeden Routee in einen BackoffSupervisor — Router.roundRobin(4, BackoffSupervisor.factory({ child: Worker })) — sodass der Slot nach einem Backoff wieder gefüllt wird, statt zu verschwinden.

Router sind nicht (der einzige) Weg zur Parallelisierung

Abschnitt betitelt „Router sind nicht (der einzige) Weg zur Parallelisierung“

Ein Router gibt dir N unabhängige Actors, die jeweils eine Nachricht nach der anderen verarbeiten — auf einem Thread. Welcher der fünf Wege, Arbeit zu verteilen, passt, hängt davon ab, was die Arbeitseinheit ist, wie viele Threads sie nutzen soll und ob der Aufrufer eine Adresse oder einen Funktionsaufruf will. Jede Zahl unten steht bereits so im Baum, mit benannter Quelle; nichts ist hier neu gemessen.

MechanismusArbeitseinheitThreadsEine lokale Adresse?Pool-GrößeBei Routee-Stop / -CrashKosten pro NachrichtBreak-evenWann
Lokaler Router-PoolActor-Nachricht1 — der des Routersjafix zur Spawn-ZeitCrash → an Ort und Stelle neu gestartet durch die Default-Strategie; Stop → entfernt, der Pool ist um einen kleinerlokales tell ~320 ns (benchmarks/worker/mesh-message-cost.ts)jedes await im Handler — es kauft Nebenläufigkeit, nie CPUHandler, die auf I/O warten
ClusterRouter über das Worker-Mesh — das Rezept untenActor-NachrichtN Workerja — der Routerein Routee pro Worker; folgt der MitgliedschaftCrash → neu gestartet durch seinen eigenen Parent auf dem Worker; Stop → der Router sendet weiter an diesen Node, bis sich die Mitgliedschaft ändertCross-Thread-tell ~21 µs, ask ~180 µs (derselbe Benchmark)~100 µs Arbeit pro Nachricht (die gemessene Tabelle)N identische Rechen-Actors hinter einer Ref
OffloadPool / context.offloadreine Funktionein bedarfsgetriebener Poolnein — ein Aufruf, ein Promise zurückwächst mit der Last, schrumpft im Leerlaufein fehlgeschlagener Lauf rejected sein Promise; ein toter Worker wird innerhalb eines Restart-Budgets ersetzt~3 µs pro gepipelinetem Task (benchmarks/worker/task-offload-breakeven.ts)~10 µs pro Aufruf (wann es sich lohnt)hashen, komprimieren, transformieren — kein Actor auf der anderen Seite
actor-ts.parallelism.workers mit mehreren Top-Level-ActorsActor samt TeilbaumN Workereine Ref pro Actor, Pfad unverändertein Worker pro Spawn, gewählt durch placementsupervised vom Guardian seines Workers; die Ref tellt, askt und watcht über den ThreadCross-Thread-tell ~21 µs, ask ~180 µs~100 µs Arbeit pro Nachrichtmehrere verschiedene Rechen-Actors, jeder mit eigener Adresse
Sharded EntityActor pro Keyjeder Node oder Worker mit der Rolleper Key, durch die Shard-Regiongenau ein lebender Actor pro Keyneu gestartet durch seinen Shard; beim Rebalancing verschobender Hop des Transports: ~21 µs im Mesh, ~22 µs tell / ~245 µs ask über TCP (FAQ)dieselben ~100 µs, plus der eigene Zustand der Entitygenau ein Actor pro Key, mit Failover

DistributedPubSub steht nicht in der Tabelle, weil es eine andere Frage beantwortet: Fan-Out an eine dynamische Subscriber-Menge — Actors kommen und gehen, und jeder von ihnen kann publizierte Events empfangen —, wo die Routee-Menge eines Routers fest ist oder der Mitgliedschaft folgt.

Die zweite Zeile ist die Form, die die anderen vier nicht sind: N identische Actors über N Threads, und Aufrufer halten eine lokale Ref. Nichts liefert das als einen einzelnen Aufruf aus. Es setzt sich aus zwei Dingen zusammen, die es gibt: Das Worker-Mesh führt das setup(context) des Actor-Moduls auf jedem Worker aus, sobald dessen Node oben ist, und ein ClusterRouter ist ein Group-Router über das, was auf jedem Member mit einer Rolle unter einem Pfad lebt.

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() ist das eine Warten: Das Mesh ist oben und jedes setup ist gelaufen, der erste Rebuild des Routers sieht also jeden Worker. Routees sind lexikalisch sortiert, nach der String-Form ihrer Adresse — media@worker:10 vor media@worker:2 —, die Round-Robin-Reihenfolge ist also über Rebuilds hinweg stabil; für drei Worker lautet die Rotation :2, :3, :4, wieder :2. Die Plain-Object-Form geht ebenso — ClusterRouter.factory({ cluster, routerType: 'round-robin', routeePath: '/user/encoder', role: 'compute' }).

Drei Fallen — die ersten beiden eine Nachricht, die nirgendwohin geht, die dritte ein Router, der weniger ausgleicht, als es scheint:

  • Der Router darf offload nicht matchen. ClusterRouter.factory(…) gibt eine Factory zurück, und eine Factory ist eine Closure, die keinen Thread überqueren kann — ein spawn, dessen Pfad offload matcht, throwt auf dem Stack des Aufrufers und nennt die Lösung. Halte das Pattern vom Pfad des Routers fern, wie /user/offloaded-* oben.
  • Ohne role ist der Main-Thread ebenfalls ein Routee. Der eigene Node des Routers ist ein Member wie jeder andere, und der Main-Thread hat keinen /user/encoder — jede (N+1)-te Nachricht wird also dort verworfen, wo sie ankommt, mit einer Warnung pro Nachricht (no envelope handler registered, dropping message to …; auf einem Node, der ClusterSharding gestartet hat, übernimmt stattdessen die Sharding-Extension den nicht aufgelösten Envelope und warnt [sharding] no region/coordinator registered for …), und ein ask dafür läuft in den Timeout. Die Rolle ist, was den Main-Thread aus dem Pool hält.
  • smallest-mailbox braucht den Agenten auf jedem Worker. Der Router liest Mailbox-Tiefen von einem kleinen Framework-Agenten auf jedem Routee-Node, und ein smallest-mailbox-Router startet diesen Agenten nur auf seinem eigenen Node. Die Zeile ClusterMailboxDepthAgent.serve(context.cluster) in setup ist, was die Worker berichten lässt; ohne sie bricht nichts, aber kein Routee berichtet je, und ohne irgendeine Messung ist die Strategie schlichtes Round-Robin. Dieser Rückfall gilt ganz oder gar nicht, nicht pro Worker: Ein Worker, der stumm bleibt, während andere berichten — seine Messung fehlt oder ist älter als mailboxDepthStaleAfterMs —, wird übersprungen, statt an die Reihe zu kommen, weil der schweigende Node gerade der sein könnte, der kämpft. Cluster-Router nennt die Regel.

Was das Rezept nicht liefert: einen Pool, der mit der Last wächst und schrumpft — das ist #212, und heute skaliert nur der OffloadPool so. Was es liefert, ist ein Scrape für alles: Das Mesh leitet die Metrik-Registry jedes Workers an den Main-Thread weiter (#1570); sobald der Main-Thread also /metrics exportiert, steht die Arbeit der Encoder dort — die Werte jedes Workers als thread="worker-<slot>"-Serien neben den eigenen thread="main" des Routers, sum without (thread) für die Summe des Pools — siehe den Geltungsbereich eines Scrapes.

  • Router — die Router.roundRobin(...), .random(...), .broadcast(...), .smallestMailbox(...), .custom(...)-Factories.
  • Strategien — was jede Strategie tut, plus eigene schreiben.
  • Scatter/Gather — jeden Routee gleichzeitig fragen und mit der ersten Antwort antworten.
  • Pool vs Group — wann einen Router verwenden, der seine Routees spawnt, vs einen, der sie findet.
  • Cluster-Router — das mitgliedschafts-getriebene Cluster-Äquivalent.