Event-Stream
Der Event-Stream ist der Bus eines ActorSystem für
One-to-Many-Messaging, das nicht in die Eltern-Kind- oder
Sender-Empfänger-Form passt. Jeder Actor kann eine Klasse von Event
oder einen kind-diskriminierten Type abonnieren — und ebenso ein
einfacher Callback; jeder Code kann publishen; der Bus matcht, tellt
das Event an jeden abonnierten Actor und ruft jeden abonnierten
Callback auf.
Er ist node-lokal, und das ist Absicht: ein ActorSystem ist eine
Node, ein Publish hier erreicht also die Subscriber dieser Node und
sonst niemanden. Das Gegenstück über Node-Grenzen hinweg ist
cluster.eventStream — dieselben
Channel-Formen, clusterweit. Alles Weitere hier betrifft den lokalen
Bus.
import { Actor, ActorSystem } from 'actor-ts';
class UserLoggedIn { constructor(public readonly userId: string) {}}
class AuditLogger extends Actor<UserLoggedIn> { override preStart(): void { this.context.system.eventStream.subscribe(this.context.self, UserLoggedIn); } override onReceive(event: UserLoggedIn): void { this.log.info(`user ${event.userId} logged in`); }}
class MetricsCollector extends Actor<UserLoggedIn> { override preStart(): void { this.context.system.eventStream.subscribe(this.context.self, UserLoggedIn); } override onReceive(event: UserLoggedIn): void { this.incrementCounter('logins'); }}
const system = ActorSystem.create('demo');system.spawnAnonymous(AuditLogger);system.spawnAnonymous(MetricsCollector);
// Überall — auch außerhalb eines Actors:system.eventStream.publish(new UserLoggedIn('user-42'));// → beide Subscriber empfangen das EventDer Publisher weiß nicht, wie viele Subscriber existieren, und die Subscriber wissen nicht, wer publisht. Das ist der ganze Sinn — lose Kopplung für Querschnitt-Anliegen (Logging, Metriken, Audit, Fan-Out-Alerts).
Die API
Abschnitt betitelt „Die API“// A channel is named by a class, by an EventKey, or by the bare kind string.type EventChannel<TEvent> = | (abstract new (...args: any[]) => TEvent) | EventKey<TEvent> | KindOf<TEvent>;
class EventStream { subscribe<TEvent>( subscriber: ActorRef, channel: EventChannel<TEvent>, predicate?: (event: TEvent) => boolean, ): boolean;
unsubscribe<TEvent>(subscriber: ActorRef, channel?: EventChannel<TEvent>): boolean;
subscribeFunction<TEvent>( channel: EventChannel<TEvent>, callback: (event: TEvent) => void, ): () => void;
publish(event: object): void;}Vier Operationen:
subscribe(ref, channel)— das Interesse eines Actors registrieren. Der Channel ist eine Klasse, einEventKeyoder ein kind-String. Gibttruezurück, wenn ein neues Abo hinzugefügt wurde,false, wenn ein Duplikat ignoriert wurde — und wirft einenTypeError, wenn der Channel unbrauchbar ist (siehe die Caution unten) oderrefkeineActorRefist, also kein aufrufbarestellundequalsund keinenpathhat. Auch eine alsrefübergebene Funktion wird so abgelehnt:subscribeFunctionist die Form, die eine nimmt.unsubscribe(ref, channel?)— die Abos eines Actors entfernen. Mit einem Channel: nur diesen; ohne: jedes Abo für diese Ref. Wirft bei denselben beiden Fehlern, auch wenn gar nichts abonniert ist: ein Aufräumen mit einem Tippfehler darin schlägt fehl, statt zu melden, es habe nichts zu entfernen gegeben.subscribeFunction(channel, callback)— einen einfachen Callback abonnieren, ohne einen Actor zu spawnen, zu benennen oder zu stoppen. Gibt das() => void-Handle zurück, das das Abo beendet; die Regeln stehen unter Callback-Abos. Hier kommt der Channel zuerst, wosubscribedie Ref zuerst nimmt, deshalb wirft es einenTypeError, der diese Reihenfolge nennt, wenn an der Stelle des Callbacks eine Klasse, einEventKeyoder ein String steht — der Aufruf andersherum geschrieben —, wie es das auch für einen unbrauchbaren Channel und jeden anderen Callback tut, der keine Funktion ist.publish(event)— Fire-and-Forget. Der Bus läuft seine Abo-Liste durch, matcht den Channel jedes Abos undtellt jeden passenden Actor; danach ruft er jeden passenden Callback auf.
Klassen-Channels matchen via instanceof, Subklassen-Instanzen
erreichen also Base-Class-Subscriber:
class SystemEvent {}class UserLoggedIn extends SystemEvent {}class UserLoggedOut extends SystemEvent {}
eventStream.subscribe(auditor, SystemEvent); // fängt beideseventStream.subscribe(loginCounter, UserLoggedIn); // fängt nur die In-EventsDas macht hierarchische Event-Taxonomien einfach: Subscriber wählen ihr Level.
Kind-Channels
Abschnitt betitelt „Kind-Channels“Messages empfiehlt plain Objects
({ kind: 'x', n: 1 }) statt Klassen — und ein plain Type hat keinen
Konstruktor, den man subscribe übergeben könnte. Benenne ihn
stattdessen über sein kind. Ein Type und ein const gleichen
Namens geben ihm die Aufrufform, die eine Klasse geschenkt bekommt:
import { EventKey } from 'actor-ts';
export type UserLoggedInEvent = { readonly kind: 'user-logged-in'; readonly userId: string;};export const UserLoggedInEvent = EventKey.of<UserLoggedInEvent>('user-logged-in');
class AuditLogger extends Actor<UserLoggedInEvent> { override preStart(): void { this.context.system.eventStream.subscribe(this.context.self, UserLoggedInEvent); } override onReceive(event: UserLoggedInEvent): void { this.log.info(`user ${event.userId} logged in`); }}
system.eventStream.publish({ kind: 'user-logged-in', userId: 'user-42' });Der Key trägt den Event-Type, ein gegen ihn geschriebenes Predicate sieht also die echte Form, ohne dass du den Parameter annotierst:
eventStream.subscribe(auditor, UserLoggedInEvent, (event) => event.userId !== 'system');Der nackte kind-String ist die Kurzform, und er kostet den Typ —
TEvent hat nichts, woraus es inferiert werden könnte, das Predicate
sieht also unknown. Das Typargument anzugeben holt die Typisierung
zurück und macht den String selbst gegen das kind des Types
prüfbar:
eventStream.subscribe(auditor, 'user-logged-in'); // predicate sees unknowneventStream.subscribe<UserLoggedInEvent>(auditor, 'user-logged-in'); // typed, and the string is checkedDaraus folgen zwei Identitätsregeln:
- Ein Key und sein String sind derselbe Channel. Beide Wege zu
abonnieren deduppt, und jede Form unsubscribed die andere — auch
ein frisch gebautes
EventKey.of('user-logged-in'). - Eine Klasse und ein kind sind zwei Channels, selbst wenn die
Instanzen der Klasse dieses
kindtragen. Sie selektieren überlappende Events, genau wie eine Basisklasse und ihre Subklasse — ein Actor mit beiden Abos bekommt also zwei Zustellungen pro Publish.
Predicate-Filterung
Abschnitt betitelt „Predicate-Filterung“eventStream.subscribe( metricsActor, HttpResponse, (event) => event.status >= 500, // nur 5xx-Responses liefern);Für hochfrequente Channels (Cluster-Events, jede HTTP-Response,
jeder Metric-Tick) ist Filtern auf der Bus-Seite günstiger als
Filtern innerhalb des onReceive jedes Subscribers.
Drei Details:
- Kein Dedup für Predicate-tragende Abos. Ohne Predicate
deduppt der Bus pro
(subscriber, channel)-Paar —subscribeerneut aufzurufen, ist ein No-Op. Mit einem Predicate fügt jeder Aufruf ein neues Abo hinzu, weil Predicate-Funktionen keinen Identitätsvertrag haben. “Diesen Filter ersetzen” heißtunsubscribeund dann erneutsubscribe. - Ein throwendes Predicate wird als “kein Match” für diese Auslieferung behandelt. Andere Subscriber sind unberührt; das Abo bleibt aktiv. Eine Warnung wird über den System-Logger geloggt.
- Predicates laufen zur Publish-Zeit, auf dem Stack des Publishers. Halte sie schnell und rein — ein schwerer Predicate verlangsamt jedes Publish.
Callback-Abos
Abschnitt betitelt „Callback-Abos“Ein Actor ist der Standard-Subscriber: seine Mailbox ordnet, puffert und isoliert, was er empfängt. Wenn es nichts zu spawnen gibt — einen Zähler, einen Test, eine Brücke zu Code außerhalb des Actor-Baums —, abonniere stattdessen eine einfache Funktion:
import { ActorStopped, ActorSystem } from 'actor-ts';
const system = ActorSystem.create('demo');const stopped = new Set<string>();const unsubscribe = system.eventStream.subscribeFunction(ActorStopped, (event) => { stopped.add(event.actor.path.toString());});
// When the code that subscribed is torn down:unsubscribe();Der Channel wird genau wie bei subscribe benannt — eine Klasse, ein
EventKey oder ein kind-String —, und eine Klasse oder ein Key
typisiert den Parameter des Callbacks. Der Rest folgt daraus, dass es
keine Mailbox gibt:
- Die Zustellung ist synchron. Der Callback läuft innerhalb von
publish, auf dem Stack des Publishers, nachdem jeder Actor-Subscriber seintellbekommen hat. Ein langsamer Callback verlangsamt jedes Publish seines Channels, und für die eigenen Events des Frameworks heißt das: jeden Actor-Start, jeden Stopp, jeden Dead Letter. Arbeit, die Zeit braucht, gehört in einen Actor. - Das Handle beendet genau ein Abo. Jeder Aufruf abonniert neu, auch mit derselben Funktion, und ein Handle zweimal aufzurufen tut nichts. Sobald das Handle zurückgekehrt ist, wird der Callback nicht mehr aufgerufen — auch nicht mit einem Event, das gerade zugestellt wurde. Ein während einer Zustellung abonnierter Callback beginnt mit dem nächsten Event.
- Ein fehlschlagender Callback bleibt sein eigenes Problem. Ein
Throw wird auf
warngeloggt und überspringt diesen Callback für dieses Event; er bleibt abonniert, und alle anderen erhalten das Event trotzdem. Ein zurückgegebenes Promise wird nicht abgewartet, und seine Rejection wird genauso geloggt, statt als Unhandled Rejection aufzuschlagen. Das gilt für alles, was geworfen wird, wie für jeden Fehler, den der Bus abfängt: Kann der Logger den Wert nicht darstellen — etwa einen Error, dessenmessage-Getter wirft —, wird die Warnung ohne ihn geschrieben. - Kein Actor-Stopp beendet ein Callback-Abo; das Ende des Systems
schon. Der Callback sieht den ganzen Shutdown, jedes
ActorStoppedeingeschlossen, und wird nicht mehr aufgerufen, sobald das System terminiert ist. Danach zu abonnieren wirft, weil nichts mehr übrig wäre, das das Abo beendet. Solange das System noch terminiert, funktioniert das Abonnieren — es gibt keinen Actor zu spawnen.
Live zusehen
Abschnitt betitelt „Live zusehen“DevTools hat ein Event-Stream-Panel, das den Bus im Browser mitliest — nützlich, wenn die Frage ist, ob überhaupt etwas publiziert wird.
Wann den Event-Stream verwenden
Abschnitt betitelt „Wann den Event-Stream verwenden“Drei gute Passungen:
- Querschnitt-Beobachtung — Logging, Metriken, Audit. Viele Subscriber, von denen der Publisher keinen kennen soll.
- Node-weite Benachrichtigungen — “der Cluster hat ein Mitglied gewonnen”, “der Cache wurde geflusht”. Die Cluster-Extension publisht ihre eigenen Events hier; du kannst abonnieren und reagieren. Die Mitgliedschaftsevents lohnen genaues Lesen, weil sie wie eine Ausnahme aussehen und keine sind: du siehst Mitgliedschaftsänderungen anderer Nodes, weil jede Node ihre eigene Kopie publisht, abgeleitet aus dem Gossip, den sie gemerged hat — nicht weil das Event über die Leitung gegangen wäre.
- Entkoppeln von Actor-Verdrahtung in Tests — statt eine Spy-Ref durch fünf Schichten zu legen, publishe auf dem Stream und lass den Spy direkt abonnieren.
Wann NICHT verwenden
Abschnitt betitelt „Wann NICHT verwenden“Eingebaute Events, die abonniert werden können
Abschnitt betitelt „Eingebaute Events, die abonniert werden können“Das Framework publisht mehrere Event-Typen, die du abonnieren kannst:
| Event | Woher es kommt |
|---|---|
DeadLetter | Jede an /deadLetters geroutete Nachricht wird hier publisht und geloggt — eine gedrosselte info-Zeile mit Empfänger, Sender und der Klasse der Nachricht, nie der Payload. Aufbewahrt wird sie nicht, ohne Abonnent und ohne Queue ist die Nachricht also weg. Jede trägt den recipient, den sie nicht erreicht hat. Für eine begrenzte, optional dauerhafte Aufzeichnung mit erneutem Zustellen siehe Dead Letters. |
DispatcherError | Eine auf einem Dispatcher geplante Arbeitseinheit hat geworfen, wo kein Supervisor es sehen konnte. Trägt die id des Dispatchers, die cause und die ActorRef, deren Zug es war (null für Arbeit, die zu keinem Actor gehört). Von Natur aus ruhig — siehe Dispatcher. |
SchedulerError | Ein Task, der an scheduler.scheduleOnceFunction / scheduleAtFixedRateFunction übergeben wurde, hat in einem rohen Timer-Callback geworfen, wo kein Supervisor es sehen konnte. Trägt die cause — und nichts weiter, denn ein geplanter Task ist ein anonymes Closure und ein System hat genau einen Scheduler. Die Nachrichten-Zustellformen publizieren hier nicht. Siehe Timer und Scheduling. |
MemberUp, MemberRemoved, MemberUnreachable, … | Konkrete Cluster-Mitgliedschaftsevents, publisht von der Cluster-Extension. Abonniere jede Klasse direkt — ClusterEvent ist ein Union-Typ, keine abonnierbare Basisklasse. Siehe Cluster. |
ReachabilityChanged | Der Failure Detector der publishenden Node hat einen Peer aus den Augen verloren oder wiedergesehen — eine lokale Beobachtung, anders als MemberUnreachable, das auch per Gossip angekommen sein kann. Siehe Failure Detector. |
| Broker-Events | BrokerActor-Subklassen publishen Connect/Disconnect/Lag-Events. |
Alles, was das Framework selbst publisht, ist eine Klasse — Klassen-Channels bleiben also der Weg zu allem oben. Kind-Channels sind für deine eigenen Anwendungs-Events.
Ein Cluster-Event fehlt hier bewusst: CurrentClusterState geht
ausschließlich an den Listener, der danach gefragt hat — per
cluster.subscribe(listener, { replayMode: 'snapshot' }). Es sagt, wo
dieser eine Subscriber startet, und das ist für niemanden sonst eine
Neuigkeit, also erreicht es diesen Bus nie.
Siehe die Docs jeder Extension für das volle Event-Vokabular, das sie publisht.
Wie es weitergeht
Abschnitt betitelt „Wie es weitergeht“- Cluster-Event-Stream — dieser Bus,
aber clusterweit: dieselben Klassen- und
kind-Channels, auf jeder Node. Dort steht auch, wie man einen Channel dieses Busses auf jenen bridgt. - DistributedPubSub — cluster-weites Publish/Subscribe mit Topic-Routing; zur Laufzeit gewählte String-Topics und Anycast.
- Actor-System —
system.eventStreamist, wo du den Bus erreichst. - Nachrichten — die
Form-Regeln (unveränderlich, keine Method-Refs) gelten genauso
für Events, und die dort dokumentierte
kind-Konvention ist direkt abonnierbar.
Die EventStream-API-Referenz deckt
die volle Schnittstelle ab.
