Refs über Nodes hinweg
In einem Single-Node-System ist ein ActorRef ein direkter
In-Memory-Handle. In einem geclusterten System kann ein ActorRef
auf einen Actor auf jedem Node zeigen — und derselbe tell
funktioniert auf gleiche Weise:
const remote: ActorRef<Message> = /* Ref auf einen Actor auf einem anderen Node */;remote.tell({ kind: 'do-it' });// → serialisiert, über den Cluster-Transport gesendet, in die Remote-Mailbox zugestelltDas Framework versteckt die Netzwerkschicht. Aber zu verstehen, wie das funktioniert, hilft, wenn etwas schiefläuft (Nachrichten verschwinden, Latenz schießt hoch, Refs lassen sich nicht auflösen).
Das Pfad-mit-Host-Format
Abschnitt betitelt „Das Pfad-mit-Host-Format“Der Pfad eines rein-lokalen Refs sieht so aus:
actor-ts://my-app/user/api/sessions/user-42Ein Cluster-fähiger Ref enthält den host:port seines besitzenden Nodes:
actor-ts://my-app@10.0.0.5:2552/user/api/sessions/user-42| Segment | Was es ist |
|---|---|
actor-ts:// | Das Schema — wie bei lokalen Pfaden. |
my-app | Der System-Name des Clusters. |
@10.0.0.5:2552 | Die Adresse des Nodes, vergeben bei Cluster.join. |
/user/api/sessions/user-42 | Der Actor-Pfad innerhalb dieses Nodes, gleicher Aufbau wie ein Single-Node-Pfad. |
Das Host-Fragment sagt der lokalen Runtime, welcher Node diesen
Actor hostet. Wenn du einem Remote-Ref ein tell schickst, macht
das Framework:
- Liest den host:port aus dem Pfad des Refs.
- Schlägt die Verbindung des Cluster-Transports zu diesem Node nach.
- Serialisiert die Nachricht + die Lokalpfad-Segmente des Refs.
- Schreibt einen Wire-Frame.
- Der empfangende Node deserialisiert; löst lokal die
Pfad-Segmente zu einem echten Actor auf; macht ein
tellauf den lokalen Ref.
Wie Refs über die Leitung wandern
Abschnitt betitelt „Wie Refs über die Leitung wandern“In einer Nachricht serialisiert ein ActorRef-Feld als der
Pfad-mit-Host-String. Auf dem empfangenden Node rekonstruiert
der Deserializer einen RemoteActorRef, der zurück auf den
Originalknoten zeigt:
type GetMessage = { kind: 'get'; replyTo: ActorRef<number>; // ← serialisiert als Pfad-String};
remoteRegistry.tell({ kind: 'get', replyTo: this.context.self, // → "actor-ts://my-app@10.0.0.3:2552/user/asker"});Der empfangende Node sieht replyTo als RemoteActorRef, der auf
10.0.0.3:2552/.../asker zeigt. Ein tell darauf läuft umgekehrt
durch dieselbe Encoding-und-Transport-Maschinerie.
Das bedeutet, dass Request/Response zwischen Actors auf verschiedenen Nodes einfach funktioniert — die Antwort reist über den Cluster-Transport zurück zum ursprünglichen Anfrager.
Remote-Refs vergleichen
Abschnitt betitelt „Remote-Refs vergleichen“Der path eines Remote-Refs ist der Pfad des Actors, auf den er
zeigt — dadurch ist er in Logs aussagekräftig und als Map-Key
verwendbar:
remoteWorker.path.toString(); // "actor-ts://my-app/user/worker"ActorRef.equals vergleicht genau diese Darstellung — und ein Pfad
trägt den Systemnamen, nicht die Node-Adresse. Da alle Mitglieder
eines Clusters denselben Systemnamen teilen, sind zwei Refs auf
denselben Pfad auf verschiedenen Nodes weiterhin gleich:
const onNodeA = /* Ref auf /user/worker auf 10.0.0.5 */;const onNodeB = /* Ref auf /user/worker auf 10.0.0.6 */;
onNodeA.equals(onNodeB); // true — gleicher Pfad, und mehr sieht equals() nichtequals beantwortet also „derselbe Actor-Pfad?”, nicht „derselbe
Actor”. Wenn du Node-Identität brauchst — Routees deduplizieren,
nachhalten welches Mitglied einen Service registriert hat —
vergleiche toString() der Refs (node-qualifiziert) oder halte die
NodeAddress neben dem Ref.
Der Cluster-Transport
Abschnitt betitelt „Der Cluster-Transport“Der Transport (TCP per Default, In-Memory in Tests) trägt:
- Cluster-Steuerverkehr — Gossip, Heartbeats, Downing-Signale.
- Envelope-Verkehr — deine
tells, in einen Routing-Envelope gewickelt.
Beide teilen sich dieselbe TCP-Verbindung pro Peer-Paar. Das Framework multiplext sie; du siehst diesen Unterschied nicht.
Siehe Transports für die TCP- und In-Memory-Implementierungen.
Einen Remote-Ref per Pfad auflösen
Abschnitt betitelt „Einen Remote-Ref per Pfad auflösen“import { ActorSelection } from 'actor-ts';
const remote = await system.actorSelection( 'actor-ts://my-app@10.0.0.5:2552/user/api/sessions/user-42',).resolveOne(5_000);
remote.tell({ kind: 'do-it' });actorSelection parst den Pfad-mit-Host; resolveOne gibt einen
RemoteActorRef zurück, dem du tell schicken kannst. Nützlich,
wenn:
- Der Standort des Ziels per Konvention bekannt ist (ein bekannter Sharding-Pfad oder Singleton-Proxy).
- Eine Nachricht einen Pfad-String enthält (z. B. aus einem HTTP-Request).
Für Routine-Cluster-Arbeit hältst du normalerweise einen Ref aus
der eigenen Maschinerie des Clusters (Sharding-Region,
Singleton-Proxy, Event-Stream-Subscriber) — actorSelection ist
der Lookup-Notausgang.
Einen Ref von Hand bauen
Abschnitt betitelt „Einen Ref von Hand bauen“Wenn du die Adresse des Nodes und den Namen des Actors schon kennst —
mesh.refFor(address, path) eines Worker-Mesh ist genau das — lässt
sich ein RemoteActorRef direkt bauen. Sein Konstruktor akzeptiert
zwei Schreibweisen des Pfads: die nackte Form /user/name und die
volle Form actor-ts://<system>/user/name. Die nackte Form wird gegen
den System-Namen des Ziel-Nodes aufgelöst, und egal welche du
schreibst, der Ref trägt überall dort die volle Form, wo es darauf
ankommt — als Ziel des Envelopes auf der Leitung, im watch-Frame, in
ref.path und in equals — sodass beide Schreibweisen denselben
Actor benennen. (Vor #1568 wurde die nackte Form akzeptiert und
adressierte stillschweigend die System-Wurzel: jede Nachricht daran
wurde auf der Gegenseite verworfen, und ein ask lief mit
actor-ts://my-app/ als Ziel in den Timeout.)
import { Cluster, NodeAddress, RemoteActorRef } from 'actor-ts/cluster';
const cluster = await Cluster.join(system, clusterOptions);const worker = new NodeAddress('my-app', '10.0.0.6', 2552);
const bare = new RemoteActorRef<Job>(worker, '/user/worker', cluster);const full = new RemoteActorRef<Job>(worker, 'actor-ts://my-app/user/worker', cluster);bare.equals(full); // true — both carry actor-ts://my-app/user/workerWas passiert, wenn der Remote-Node verschwindet
Abschnitt betitelt „Was passiert, wenn der Remote-Node verschwindet“const remote: ActorRef = /* auf einem Node, der den Cluster gerade verlassen hat */;
remote.tell({ kind: 'do-it' });// → Nachricht landet in Dead Letters; Sender sieht den Fehler nichtEin tell an einen Remote-Ref auf einem gestoppten/unerreichbaren
Node:
- Das Framework versucht, auf den Transport zu schreiben.
- Der Transport sieht keine lebendige Verbindung (oder eine im halb-geschlossenen Zustand).
- Die Nachricht wird zu Dead Letters fallen gelassen.
Zwei Wege, das zu erkennen:
context.watch(remoteRef)— eineTerminated-Benachrichtigung empfangen, wenn der Remote-Actor stoppt oder der Remote-Node downed oder removed wird. DasTerminated.addressTerminated-Flag unterscheidet “Actor gestoppt” von “Node verloren”, undexistenceConfirmedistfalsefür einen Pfad, den der ferne Node nicht auflösen konnte.- Cluster-Events abonnieren —
MemberRemoved/MemberUnreachablefür die Adresse des Hosts sagt dir, dass der ganze Node weg ist.
Siehe Death watch für die Per-Actor-Variante.
Der Sender kommt mit
Abschnitt betitelt „Der Sender kommt mit“Eine Nachricht, die an eine RemoteActorRef geschickt wird, trägt
den Pfad ihres Senders im Envelope, und der empfangende Node baut
ihn wieder auf: im Ziel-Actor ist context.sender eine
RemoteActorRef zurück zu dem Actor, der die Nachricht geschickt
hat — auf welchem Node auch immer er lebt —, genau wie es bei einem
lokalen Sender eine lokale Ref wäre. Eine Antwort über
this.sender funktioniert also über Nodes hinweg, und ein tell
ohne Sender kommt weiterhin mit leerem context.sender an. An der
Nachricht muss sich dafür nichts ändern — der Pfad war immer auf
der Wire; er wurde bei der Zustellung nur verworfen.
Serialisierung
Abschnitt betitelt „Serialisierung“Der Cluster rahmt das Envelope als getaggten JSON-Tree —
dasselbe Format, das die Persistenz-Stores schreiben, sodass die
Typen, die einfaches JSON beschädigt, unversehrt hinüberkommen
(#450). Der einklinkbare
Serializer wird auf der Leitung
weiterhin nicht konsultiert, CBOR ist dafür also nicht wählbar.
{ kind: 'place', order: { items: ['book-1'], total: 19.99 }, replyTo: this.context.self, // ← Ref serialisiert als Pfad-String}Einfache Werte (Strings, Zahlen, Arrays, Plain Objects)
serialisieren trivial, und ebenso Date, Map, Set, bigint,
Uint8Array, RegExp, URL, Error und jedes Typed Array — jedes
kommt als echte Instanz an, genau so, wie es aus einem Journal
zurückkäme. Was weiterhin nicht überlebt:
- Funktionen / Closures — können keine Prozessgrenze überqueren.
Der Frame wird abgelehnt, nicht still gekappt: er wird mit
einer
error-Logzeile samt Peer verworfen, sodass ein Callback in einer Nachricht kein unsichtbarer Datenverlust mehr ist. - Symbols — werden genauso abgelehnt.
- Klassenidentität — Methoden gehen verloren und der Wert kommt
als Plain Object an, und von seiner Klasse reist nichts mit: das
Envelope trägt keinen Typnamen. Unterscheide Nachrichten an ihrem
kind.
Einen eigenen Serializer zu registrieren ändert nichts davon — der Cluster-Wire konsultiert die Registry nie (#450).
Siehe Nachrichten für die Unveränderlichkeits- und Wire-Format-Konventionen.
Performance
Abschnitt betitelt „Performance“Grobe Zahlen:
- Lokales
tell(dasselbe Actor-System) — 50-200 ns. - Cluster-lokales
tell(Loopback-Transport) — sub-Millisekunde. - Cluster-
tellüber LAN — 0,5-2 ms für kleine Nachrichten. - Cluster-
tellüber WAN — durch die Netzwerk-RTT begrenzt.
Das Framework batched Envelopes opportunistisch — viele Tells in schneller Folge teilen sich TCP-Writes, wo möglich.
Wohin als Nächstes
Abschnitt betitelt „Wohin als Nächstes“- Cluster-Überblick — das größere Bild: wie sich Nodes finden, Gossip, Mitgliedschaft.
- Transports — TCP- und In-Memory-Implementierungen.
- Serialisierungs-Überblick — das Wire-Format für Cross-Node-Nachrichten.
- Nachrichten — die Konventionen, die Nachrichten serialisierbar machen.
- Death watch — erkennen, dass ein Remote-Actor gestoppt hat.
Die RemoteActorRef API-Referenz
deckt die Wire-Ref-Implementierung ab.
