Zum Inhalt springen
Deutsch

Nachrichten

Eine Nachricht ist jeder Wert, der an einen Actor gesendet wird. Das Typsystem erzwingt, welche Nachrichten ein gegebener Actor akzeptiert (über den Actor<TMessage>-Typparameter), und die Runtime liefert Nachrichten eine nach der anderen an das onReceive des Actors aus.

Diese Seite deckt die Konventionen ab, denen actor-ts-Code beim Strukturieren von Nachrichten folgt — wie sie aussehen, wie du auf ihnen dispatched, was du NICHT in sie packen solltest und welche Muster am häufigsten vorkommen.

Das wichtigste einzelne Muster in dieser Codebasis: Nachrichten sind Discriminated Unions, getaggt mit einem kind-Feld.

type CounterCommand =
| { readonly kind: 'increment' }
| { readonly kind: 'decrement' }
| { readonly kind: 'set'; readonly to: number }
| { readonly kind: 'get'; readonly replyTo: ActorRef<number> };

Diese Form bringt drei Dinge:

  1. Compile-time-Exhaustiveness. match(command).with(...).exhaustive() (über ts-pattern) weigert sich zu kompilieren, wenn du einen neuen kind hinzufügst und vergisst, ihn zu behandeln. Die actor-ts-Codebasis verwendet dieses Muster überall — siehe Pattern Matching.
  2. Typ-Narrowing innerhalb von Handlern. Innerhalb des .with({ kind: 'set' }, ...)-Arms ist m.to automatisch als number typisiert — keine Casts, kein as never.
  3. Stabilität des Wire-Formats. Die Leitung trägt keine eigene Typidentität — sobald eine Nachricht, die eine Prozess- oder Cluster-Grenze überquert hat, geparst ist, ist kind das, worauf das match(...) des empfangenden Actors dispatcht. Genau deshalb muss der Diskriminator innerhalb der Payload mitreisen. Siehe Serialisierung.

Die Konvention ist kind: string, klein geschrieben, kebab-case für mehrere Wörter. Großgeschriebenes Kind funktioniert auch, ist aber nicht das, was das Framework verwendet.

import { Actor, ActorSystem, type ActorRef } from 'actor-ts';
import { match } from 'ts-pattern';
type IncrementCommand = { readonly kind: 'increment' };
type DecrementCommand = { readonly kind: 'decrement' };
type GetCommand = { readonly kind: 'get'; readonly replyTo: ActorRef<number> };
type CounterCommand = IncrementCommand | DecrementCommand | GetCommand;
class Counter extends Actor<CounterCommand> {
private count = 0;
override onReceive(command: CounterCommand): void {
match(command)
.with({ kind: 'increment' }, () => this.onIncrement())
.with({ kind: 'decrement' }, () => this.onDecrement())
.with({ kind: 'get' }, (m) => this.onGet(m))
.exhaustive();
}
private onIncrement(): void { this.count++; }
private onDecrement(): void { this.count--; }
private onGet(m: GetCommand): void { m.replyTo.tell(this.count); }
}
const system = ActorSystem.create('counters');
const counter = system.spawnAnonymous(Counter);
counter.tell({ kind: 'increment' });
counter.tell({ kind: 'increment' });
counter.tell({ kind: 'increment' });
// Später nach dem Count über eine Reply-to-Ref fragen — siehe Ask-Pattern.

Wenn du später eine kind: 'reset'-Variante zu CounterCommand hinzufügst, schlägt das .exhaustive()-Compile fehl, bis du einen .with({ kind: 'reset' }, ...)-Arm hinzufügst. Kein Runtime-Crash, keine still verschluckte Nachricht — der Compiler fängt es ab.

Nachrichten sollten unveränderlich sein, sobald sie eingereiht sind. Zwei Gründe:

  1. Dieselbe Nachricht kann in manchen Szenarien zweimal verarbeitet werden — Restart-nach-Fehler spielt gepufferte Nachrichten erneut ab; Reliable-Delivery sendet unbestätigte erneut. Mutation zwischen Auslieferungen führt zu “Phantom”-Zustandsänderungen.
  2. Cross-Process-Sends serialisieren die Nachricht beim Senden und deserialisieren sie beim Empfangen. Der Empfänger bekommt eine Kopie; das Mutieren des Sender-Objekts nach tell hat keinen Effekt auf die Kopie — aber diese Asymmetrie erzeugt verwirrende Bugs (der lokale Fall sieht die Mutation, der Remote-Fall nicht).

Praktische Faustregeln:

  • Verwende readonly-Eigenschaften (readonly kind, readonly replyTo, …). Der TypeScript-Compiler fängt dann versehentliche Schreibzugriffe ab.
  • Bevorzuge schlichte Objekte ({ kind: 'x', n: 1 }) gegenüber Klassen — sie serialisieren trivial, keine Methoden-Verluste über Prozessgrenzen hinweg.
  • Behandle Arrays / verschachtelte Objekte innerhalb einer Nachricht als tief unveränderlich. Wenn du “updaten” musst, gib eine neue Nachricht zurück; mutiere nicht die eingehende.

tell ist Fire-and-Forget. Für Request/Response ist die Konvention, ein replyTo: ActorRef<ReplyType>-Feld in der Request-Nachricht zu inkludieren:

type Get = { readonly kind: 'get'; readonly replyTo: ActorRef<number> };
type ReplyOK = { readonly kind: 'reply-ok'; readonly value: number };
class Counter extends Actor<Get> {
private count = 42;
override onReceive(command: Get): void {
command.replyTo.tell(this.count);
}
}

Der Aufrufer liefert eine Ref, an die der Actor die Antwort sendet. Drei Quellen für diese Ref:

  • this.self, wenn der Aufrufer ein anderer Actor ist, der die Antwort an sich selbst geliefert haben will.
  • this.sender, wenn der Aufrufer auf eine frühere Nachricht reagiert und die Antwort an den ursprünglichen Frager gehen soll. Hinweis: this.sender ist Option<ActorRef> — leer, wenn die Nachricht von außerhalb des Actor-Systems kam.
  • Eine wegwerfbare “Ask”-Probe — was das Ask-Pattern für dich baut. Gibt ein Promise<Reply> zurück.

Das Reply-to-Ref-Idiom ist umständlicher als ein Methodenaufruf, bringt aber drei Dinge: Requests und Replies sind zeitlich entkoppelt (kein await-Chain), die Antwort kann von einem anderen Actor kommen als dem, der gefragt wurde, und derselbe Code funktioniert lokal und cross-Cluster.

Ein häufiger Formfehler: replyTo: ActorRef<number> zu deklarieren, wenn der Actor manchmal mit { kind: 'reply-ok' } und manchmal mit { kind: 'reply-error' } antwortet.

Verwende eine Discriminated Union auch für den Reply-Typ:

type GetReply =
| { readonly kind: 'reply-ok'; readonly value: number }
| { readonly kind: 'reply-error'; readonly reason: string };
type Get = { readonly kind: 'get'; readonly replyTo: ActorRef<GetReply> };

Das onReceive des Aufrufers kann dann auf dem kind der Antwort match()en, um die Erfolgs- und Fehlerpfade auf dieselbe Weise zu unterscheiden, wie es seine eigenen Befehle dispatched.

Für Actors, die Events persistieren (PersistentActor), trennt das Framework Commands (was zu tun ist) von Events (was bereits passiert ist):

import { match } from 'ts-pattern';
type DepositCommand = { readonly kind: 'deposit'; readonly amount: number };
type Deposited = { readonly kind: 'deposited'; readonly amount: number; readonly timestamp: number };
class Account extends PersistentActor<DepositCommand, Deposited, { balance: number }> {
// Command-Handler: validieren + Event persistieren
async onCommand(state, command: DepositCommand): Promise<void> {
await match(command)
.with({ kind: 'deposit' }, (c) => this.onDeposit(c))
.exhaustive();
}
private async onDeposit(command: DepositCommand): Promise<void> {
const event: Deposited = { kind: 'deposited', amount: command.amount, timestamp: Date.now() };
await this.persist(event, () => { /* Seiteneffekte nach dem Persistieren */ });
}
// Event-Handler: nur Zustands-Update — läuft sowohl beim Schreiben als auch bei Recovery
onEvent(state, event: Deposited): { balance: number } {
// Ein Fold, der einen Wert berechnet — Arme bleiben inline.
return match(event)
.with({ kind: 'deposited' }, (e) => ({ balance: state.balance + e.amount }))
.exhaustive();
}
}

Der Split ist wichtig, weil Events der dauerhafte Record sind, die beim Restart erneut abgespielt werden. Commands sind transient (die Anfrage, die das Event erzeugt hat); Events sind ewig (der Journal-Eintrag). Sie eindeutig zu benennen — Vergangenheitsform für Events (Deposited), Imperativ für Commands (DepositCommand) — hält die konzeptionelle Linie klar.

Siehe PersistentActor für die vollständige Event-Sourcing-Geschichte.

Drei Grenzen, und der Check, der für sie einsteht

Abschnitt betitelt „Drei Grenzen, und der Check, der für sie einsteht“

Eine Nachricht überquert bis zu drei Grenzen, und jede macht etwas anderes mit ihr:

GrenzeMechanismusWas ankommt
In-ProcessReferenzdasselbe Objekt — Prototyp intakt, Methoden funktionieren
Worker-Hop (Parallelität)Structured Cloneein plain Object: Prototyp weg, Methoden weg; ein Feld mit einer Funktion wirft DataCloneError
Cluster-Wireder Serializerwas der registrierte Serializer daraus macht — eine Klasse ohne Binding ist wieder ein plain Object

Eine Testsuite übt fast ausschließlich die erste Grenze, sodass ein Nachrichtentyp lokal grün sein kann, beim ersten Umschalten von actor-ts.parallelism.workers still degradiert und auf der Wire fehlschlägt. Der mittlere Fall ist der gefährliche: Eine an einen Worker gesendete Klasseninstanz wirft nicht. Sie kommt als plain Object an und scheitert später — als match-Arm, der nie feuert, als .exhaustive(), das woanders wirft, als Methode, die undefined ist. Die Discriminated-Union-Konvention oben ist genau die Form, die alle drei Grenzen überlebt.

Der Message-Boundary-Check lässt den lokalen Pfad für die anderen beiden geradestehen. Mit eingeschaltetem Modus wird jedes lokale tell beim Senden so geprüft, wie die Grenze es prüfen würde, und was verloren ginge, wird mit Nachrichtentyp und Empfänger gemeldet — solange der Sender noch auf dem Stack ist:

actor-ts.diagnostics.message-boundary {
structured-clone = off # off | warn | fail — the worker hop
serializer-round-trip = off # off | warn | fail — the cluster wire
}
const messageBoundary = MessageBoundaryOptions.create().withStructuredClone('fail');
const systemOptions = ActorSystemOptions.create().withMessageBoundary(messageBoundary);

warn loggt einmal pro Nachrichtentyp; fail wirft einen MessageBoundaryError aus dem tell heraus. Beide sind in Produktion aus — der Check läuft über jede Nachricht, und ein laufendes System hat niemanden auf dem Stack, dem es etwas sagen könnte —, und TestKit schaltet structured-clone auf fail, weil ein Test der Ort ist, an dem das gefunden werden soll. Eine Suite, deren Nachrichten eine Cluster-Wire überqueren sollen, schaltet zusätzlich serializer-round-trip ein; es ist selbst im Kit aus, weil der Round-Trip für jede Klasse, die eine Anwendung sendet, ein Serializer-Binding braucht und die meisten Anwendungen für Nachrichten, die den Prozess nie verlassen, keines haben.

Was der Clone-Check meldet: jeden erreichbaren Wert, dessen Prototyp der Clone-Algorithmus nicht erhält — eine Klasseninstanz, eine Unterklasse von Error — und jeden Wert, der sich gar nicht klonen lässt — eine Funktion, ein Symbol. Date, RegExp, Map, Set, Typed Arrays und die eingebauten Fehler sind in Ordnung, und ebenso eine ActorRef irgendwo in der Nachricht: Die Wire schreibt Refs um, bevor der Port sie sieht. Die Klassen des Frameworks selbst — PoisonPill, Terminated, ein Cluster-Event, ein Listing — sind ausgenommen; jede überquert die Grenzen, die sie überqueren muss, auf eigenem Weg.

  • Pattern Matching — das match().exhaustive()-Idiom, das in jedem Beispiel auf dieser Seite verwendet wird.
  • Ask-Pattern — ref.ask(message, timeout) gibt ein Promise für die Antwort zurück und vermeidet den manuellen Reply-to-Ref-Tanz.
  • Actor — die Basisklasse, die onReceive-Signatur, die Context-Referenzen, die Reply-Refs produzieren.
  • Serialisierung — was mit deinen Nachrichten passiert, wenn sie eine Prozess-/Cluster-Grenze überqueren; wie du eigene Serializer registrierst, wenn der JSON-Default nicht passt.
  • PersistentActor — wo der Command-vs-Event-Split tragend wird.