Zum Inhalt springen
Deutsch

Cluster-Event-Stream

system.eventStream ist auf ein ActorSystem gescoped, und das ist eine Node: ein Publish dort läuft über eine In-Process-Liste und fasst das Netzwerk nie an. cluster.eventStream ist die andere Hälfte — dieselben Channels, aber Subscriber auf jeder Node.

Der Besitzer trägt die Reichweite, damit die beiden an der Aufrufstelle auseinanderzuhalten sind und nicht über eine Konvention, die man sich merken muss:

system.eventStream.publish(event); // this node only
cluster.eventStream.publish(event); // every node

one hop

publish on node A

node-A mediator

node-A receiver

subscribers on A

node-B mediator

node-B receiver

subscribers on B

Er setzt auf demselben Mediator auf, den auch DistributedPubSub nutzt — aus einem Channel wird ein Topic. Damit erbt er dessen begrenztes Gossip, die Zustellung mit höchstens einem Hop und dessen Caps, und er fügt dem Wire-Protokoll kein neues Frame hinzu.

import { ActorSystem, Actor } from 'actor-ts';
import { Cluster, ClusterOptions } from 'actor-ts/cluster';
type OrderPlacedEvent = { readonly kind: 'order-placed'; readonly sku: string };
class Auditor extends Actor<OrderPlacedEvent> {
override onReceive(message: OrderPlacedEvent): void {
this.log.info(`[audit] ${message.sku}`);
}
}
const system = ActorSystem.create('shop');
const clusterOptions = ClusterOptions.create()
.withHost(host)
.withPort(port)
.withSeeds(seeds);
const cluster = await Cluster.join(system, clusterOptions);
const auditor = system.spawn(Auditor, 'auditor');
cluster.eventStream.subscribe(auditor, 'order-placed');
// On any node in the cluster — every auditor sees it.
cluster.eventStream.publish({ kind: 'order-placed', sku: 'XYZ-1' });

Ein kind-diskriminiertes Event braucht nichts weiter. Es ist bereits gültiges JSON und sein Diskriminant überlebt die Leitung unverändert — ein Abonnement per kind-String oder per EventKey funktioniert also ohne Zutun über Node-Grenzen hinweg. Das ist zugleich die Form, die die Message-Konventionen des Projekts ohnehin vorschreiben.

Ein Klassen-Channel kann das nicht von allein. Das Wire-Format taggt die eingebauten Typen, die es wiederherstellt — ein Date, eine Map —, und keine Klasse der Anwendung, eine Instanz geht also nur mit ihren Feldern über die Leitung und kommt auf der Gegenseite als Plain Object an, das kein instanceof matcht. Deshalb erst benennen:

class ShipmentEvent {
constructor(public readonly trackingId: string) {}
static fromJSON(body: Record<string, unknown>): ShipmentEvent {
return new ShipmentEvent(String(body.trackingId));
}
}
cluster.eventStream.register('ShipmentEvent', ShipmentEvent);
cluster.eventStream.subscribe(auditor, ShipmentEvent);
cluster.eventStream.publish(new ShipmentEvent('TRK-1'));

register nimmt ein optionales drittes Argument, falls die Klasse kein statisches fromJSON hat — eines von beiden muss existieren. Das ist Absicht und keine fehlende Bequemlichkeit: eine beliebige Klasse generisch wiederaufzubauen hieße, vom Peer gelieferte Keys auf einen frischen Prototyp zu schreiben, und genau diese Prototype-Pollution-Fläche musste dieses Projekt schon einmal entfernen. Dass die Klasse selbst sagt, wie sie rekonstruiert wird, hält die Tür zu.

bridge spiegelt einen Channel des node-lokalen Busses auf den Cluster-Bus. Hier wird „clusterweit statt lokal” entschieden — und zwar von dir, nicht vom Framework:

cluster.eventStream.bridge('cache-flushed');
const stop = cluster.eventStream.bridge(ShipmentEvent); // returns an off switch

Eine Bridge spiegelt, sie leitet nicht um. Alles, was auf system.eventStream bereits abonniert ist, behält seine Zustellung — und genau das erlaubt es, in einem laufenden Deployment eine Bridge einzuschalten, ohne vorher zu prüfen, wer dort schon zuhört.

Nichts, was das Framework publisht, liegt standardmäßig auf dem Cluster-Bus, und jedes hat seinen eigenen Grund:

EventWarum es node-lokal bleibt
ActorStarted / ActorStopped / ActorRestartedpublish läuft bei jedem Actor-Start, -Stopp und -Restart — der heißeste Pfad im System, dessen Leerfall bewusst auf einen einzigen Length-Check optimiert ist.
DeadLetterUnzustellbare Nachrichten kommen in Fluten, und eine Storm-Suppression gibt es noch nicht. Clusterweit würde aus einem lokalen Sturm ein clusterweiter.
MemberUp, MemberRemoved, …Jede Node leitet diese aus ihrem eigenen Gossip-Merge ab; clusterweit publisht sähe jeder Subscriber N Kopien einer einzigen Mitgliedschaftsänderung.
Broker-Lifecycle-EventsIhr cause kann weiterhin einen Driver-Error mit Credentials tragen, und dieser Bus hat kein Autorisierungskonzept.
DispatcherError, SchedulerErrorNode-Diagnose, und beide tragen ein cause mit derselben Exposition.

Wer eines davon trotzdem clusterweit will, bridgt es bewusst — im Rahmen der Single-Origin-Regel oben, die die Mitgliedschaftsevents ausschließt.

system.eventStream.publish stellt innerhalb des Aufrufs zu. cluster.eventStream.publish nicht: es passiert die Mailbox des Mediators, auch für einen Subscriber auf der publishenden Node. Über eine Node-Grenze hätte ohnehin nichts synchron sein können, und beide Herkünfte auf einen Pfad zu legen ist das, was lokale und entfernte Zustellung in einer Reihenfolge hält, statt sie gegeneinander laufen zu lassen.

Ein Test wartet deshalb auf die Zustellung, statt direkt nach dem Publish zu prüfen.

Drei Dinge auf dieser Seite sehen sich ähnlich und sind es nicht:

APIScopeTrägtReplay
system.eventStreamEine NodeBeliebige Klasse oder kindNein
cluster.eventStreamClusterweitBeliebige Klasse oder kindNein
cluster.subscribeEine Node, aus clusterweitem StateNur Mitgliedschaftsevents, an einen CallbackJa
DistributedPubSubClusterweitString-Topics, mit AnycastNein

cluster.subscribe wird am ehesten mit cluster.eventStream verwechselt, weil beide auf demselben Objekt sitzen. Es nimmt einen Callback statt einer Ref, trägt nur Mitgliedschaftsevents und spielt beim Abonnieren die aktuelle Mitgliedschaft nach — dieser Replay ist der Grund, warum es als eigene Sache existiert.

Greife stattdessen zu DistributedPubSub, wenn du zur Laufzeit gewählte String-Topics brauchst oder Anycast — also einen Subscriber clusterweit statt aller.

  • Event-Stream — der node-lokale Bus, seine Channel-Formen und die Events, die das Framework darauf publisht.
  • DistributedPubSub — topic-basiertes Pub/Sub und der Mediator, auf dem dieser Bus aufsetzt.
  • Cluster-Überblick — Mitgliedschaft, cluster.subscribe und die Events, die es zustellt.