Zum Inhalt springen
Deutsch

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 Event

Der 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).

// 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, ein EventKey oder ein kind-String. Gibt true zurück, wenn ein neues Abo hinzugefügt wurde, false, wenn ein Duplikat ignoriert wurde — und wirft einen TypeError, wenn der Channel unbrauchbar ist (siehe die Caution unten) oder ref keine ActorRef ist, also kein aufrufbares tell und equals und keinen path hat. Auch eine als ref übergebene Funktion wird so abgelehnt: subscribeFunction ist 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, wo subscribe die Ref zuerst nimmt, deshalb wirft es einen TypeError, der diese Reihenfolge nennt, wenn an der Stelle des Callbacks eine Klasse, ein EventKey oder 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 und tellt 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 beides
eventStream.subscribe(loginCounter, UserLoggedIn); // fängt nur die In-Events

Das macht hierarchische Event-Taxonomien einfach: Subscriber wählen ihr Level.

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 unknown
eventStream.subscribe<UserLoggedInEvent>(auditor, 'user-logged-in'); // typed, and the string is checked

Daraus 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 kind tragen. Sie selektieren überlappende Events, genau wie eine Basisklasse und ihre Subklasse — ein Actor mit beiden Abos bekommt also zwei Zustellungen pro Publish.
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 — subscribe erneut 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ßt unsubscribe und dann erneut subscribe.
  • 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.

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 sein tell bekommen 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 warn geloggt 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, dessen message-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 ActorStopped eingeschlossen, 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.

DevTools hat ein Event-Stream-Panel, das den Bus im Browser mitliest — nützlich, wenn die Frage ist, ob überhaupt etwas publiziert wird.

Drei gute Passungen:

  1. Querschnitt-Beobachtung — Logging, Metriken, Audit. Viele Subscriber, von denen der Publisher keinen kennen soll.
  2. 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.
  3. 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.

Das Framework publisht mehrere Event-Typen, die du abonnieren kannst:

EventWoher es kommt
DeadLetterJede 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.
DispatcherErrorEine 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.
SchedulerErrorEin 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.
ReachabilityChangedDer 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-EventsBrokerActor-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.

  • 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.eventStream ist, 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.