Ask-Pattern
tell ist Fire-and-Forget — es kehrt sofort zurück und du siehst die
Antwort des Actors nie. Die meiste Actor-zu-Actor-Kommunikation ist
damit gut bedient. Aber manchmal brauchst du eine Antwort: ein
HTTP-Handler, der einen Actor nach Zustand fragt und ihn als Response
serialisiert; eine Saga, die das Ergebnis von Schritt N braucht, bevor
sie Schritt N+1 anstößt; ein Test, der einen Rückgabewert assertieren
will.
ask ist der Helfer für diese Fälle. Es sendet eine Nachricht an
einen Actor, hängt unter der Haube eine temporäre “Reply-to”-Ref an
und gibt ein Promise zurück, das mit der ersten Antwort resolved oder
bei Timeout rejected.
Ein minimales Beispiel
Abschnitt betitelt „Ein minimales Beispiel“import { match } from 'ts-pattern';import { Actor, ActorSystem, type ActorRef } from 'actor-ts';
type IncrementCommand = { readonly kind: 'increment' };type GetCommand = { readonly kind: 'get'; readonly replyTo: ActorRef<number> };type Command = IncrementCommand | GetCommand;
class Counter extends Actor<Command> { private count = 0; override onReceive(command: Command): void { match(command) .with({ kind: 'increment' }, () => this.onIncrement()) .with({ kind: 'get' }, (c) => this.onGet(c)) .exhaustive(); }
private onIncrement(): void { this.count++; } private onGet(command: GetCommand): void { command.replyTo.tell(this.count); }}
const system = ActorSystem.create('demo');const counter = system.spawnAnonymous(Counter);
counter.tell({ kind: 'increment' });counter.tell({ kind: 'increment' });
// Methode-auf-Ref — knapp, leitet den Reply-Typ ab:const current = await counter.ask<number>({ kind: 'get' }, 5_000);console.log(current); // 2
await system.terminate();ask ist eine Methode auf jeder ActorRef:
// Methode auf jeder ActorRef — leitet Reply aus dem Type-Argument ab:ref.ask<Reply>(message, timeoutMs?): Promise<Reply>Der Parameter-Typ OmitReplyTo<TMessage> zieht replyTo aus jeder
Variante der Message-Union ab, die es deklariert — Aufrufer schreiben
das Feld selbst nie hin. Das Framework allokiert eine
One-Shot-Reply-Ref, hängt sie sowohl als context.sender als auch
(wenn die Message-Shape es erwartet) als message.replyTo an und
löst das Promise mit der ersten Antwort auf.
Die replyTo-Feld-Konvention
Abschnitt betitelt „Die replyTo-Feld-Konvention“ask funktioniert, indem es deine Nachricht mit einer angehängten,
temporären Reply-to-Ref sendet. Der Empfänger antwortet, indem er
dieser Ref tellt.
Per Konvention verwendet das Framework replyTo als Feldnamen in
der Request-Nachricht, und der Empfänger pattern-matcht darauf wie auf
jedes andere Feld. Schau dir den Command-Typ oben an: die
'get'-Variante hat replyTo: ActorRef<number>.
Für den Empfänger ist es einfach ein normales tell auf einer
normalen Ref:
private onGet(command: GetCommand): void { command.replyTo.tell(this.count);}Innerhalb des Empfängers kannst du dieselbe Ref auch über
this.sender erreichen — es ist ein Option<ActorRef>, und ask
hängt die temporäre Ref auch über diesen Kanal an:
private onGet(command: GetCommand): void { this.sender.forEach((replyTo) => replyTo.tell(this.count));}Beides funktioniert. Ein explizites replyTo-Feld zu verwenden,
macht den Typvertrag offensichtlicher (die Request-Form deklariert,
dass eine Antwort vom Typ ActorRef<number> erwartet wird);
this.sender zu verwenden ist impliziter, funktioniert aber für
Actors, die sowohl ask-artige als auch Fire-and-Forget-Nachrichten
behandeln.
Timeouts + der AskTimeoutError
Abschnitt betitelt „Timeouts + der AskTimeoutError“import { AskTimeoutError } from 'actor-ts';
try { const result = await counter.ask({ kind: 'get' }, 1_000); console.log(result);} catch (e) { if (e instanceof AskTimeoutError) { console.log('counter did not reply in time'); } else { throw e; }}Das Timeout ist im Geiste verpflichtend — der Default von 5 Sekunden
fängt den Fall, in dem du vergessen hast, darüber nachzudenken. Dieser
Default ist systemweit über actor-ts.actor.ask-timeout einstellbar;
ein Argument pro Aufruf gewinnt immer dagegen. Tune pro Aufrufstelle:
- Günstige In-Process-Antworten: 100-500 ms.
- Cross-Cluster-Lookups: 1-5 s, je nach Netzwerkerwartungen.
- Alles, was potenziell ein langsames Downstream trifft (DB-Query, HTTP-Call innerhalb des Actors): das Timeout des unterliegenden Calls + ein kleiner Puffer.
Wenn der Timeout feuert, rejected der AskTimeoutError das Promise.
Die temporäre Reply-to-Ref ist ein One-Shot: sobald sie einmal
abgeschlossen ist — durch den Timeout oder die erste Antwort — wird
jede spätere Antwort still an Ort und Stelle verworfen (sie geht nicht
in die Dead Letters). Der Actor selbst ist nicht betroffen — er hat
keine Ahnung, dass der Asker aufgegeben hat.
Es gibt keinen „ohne Deadline”-Modus
Abschnitt betitelt „Es gibt keinen „ohne Deadline”-Modus“timeoutMs muss eine positive endliche Zahl sein. 0, ein
negativer Wert, NaN und Infinity werfen alle einen OptionsError
an der Aufrufstelle, und zwar synchron — bevor die Nachricht
verschickt wird, und als geworfener Fehler statt als rejectetes
Promise, denn ein Argument außerhalb seines Wertebereichs ist ein
Fehler im Aufrufer und kein fehlgeschlagener Request.
import { OptionsError } from 'actor-ts';
const budget = deadline - Date.now(); // negativ, sobald die Deadline durch isttry { await counter.ask({ kind: 'get' }, budget);} catch (e) { if (e instanceof OptionsError) { // budget war <= 0 — die Deadline ist bereits weg, also gar nicht erst fragen }}Das ist strenger, als es auf den ersten Blick wirkt, und das mit
Absicht. Der Timeout ist das, was den einzigen Selbstabschluss-Pfad
der Reply-Ref scharf stellt: eine Ref ohne Timer kann nur noch durch
eine Antwort abgeschlossen werden und sonst durch nichts — ein
unbeantworteter Ask würde das await also für die Lebensdauer des
Prozesses hängen lassen und im Cluster zusätzlich einen Eintrag in
der Per-Path-Handler-Map hinterlassen, gegen die jedes eingehende
Envelope geprüft wird. Keiner der beiden Werte braucht einen
Tippfehler, um dort anzukommen: ein berechnetes Budget wird negativ,
sobald seine Deadline verstrichen ist, und ein untypisierter
Konfigurationswert kommt so an, wie er geparst wurde.
Für die Default-Frist lässt du das Argument weg (oder übergibst
undefined):
const value = await counter.ask<number>({ kind: 'get' });Den Default für das ganze System ändern
Abschnitt betitelt „Den Default für das ganze System ändern“actor-ts.actor.ask-timeout ist das, worauf ein weggelassenes Argument
hinausläuft. Ausgeliefert wird 5s:
actor-ts { actor { ask-timeout = 2s }}Drei Dinge sind vor dem Setzen wissenswert.
Der Wert erreicht die meisten Refs, aber nicht alle. Eine Ref
wendet den konfigurierten Wert nur an, wenn sie das ActorSystem
erreichen kann, das ihn gelesen hat — was der gewöhnlichen lokalen Ref,
TestProbe, RemoteActorRef, ClusterSingletonProxy, den beiden
Shard-Refs und EntityRef gelingt. Die Dead-Letter-Ref, Nobody, eine
Ref auf einen nicht aufgelösten Pfad und die einmalige Antwort-Ref
können es nicht und behalten die eingebauten 5 s — ebenso zwei
Framework-interne Handles, auf die nichts antworten kann. Jede Ref
dieser Gruppe hält man genau dort, wo kein lebender Actor
dahintersteht — ein Ask darauf wartet ohnehin auf eine Antwort, die nie
kommt.
Ein Wert, der keine Frist setzt, wird abgelehnt statt geklemmt.
ask-timeout = 0 (oder ein negativer Wert) wirft in
ActorSystem.create und nennt den Key — dieselbe Regel wie beim
positionalen Argument, nur angewandt beim Lesen der Konfiguration statt
später an jeder Ask-Stelle.
Achte auf das Zusammenspiel mit dem Scatter-Gather-Routing. Ein
Router aus Router.scatterGatherFirstCompleted(…) hat 4,5 s als
Default, damit er die fehlgeschlagenen Routees benennen kann, bevor das
Ask des Aufrufers aufgibt. Ein Ask-Default unter 4,6 s dreht das um,
und du bekommst AskTimeoutError statt der Diagnose; das System
schreibt in diesem Fall beim Start eine warn-Zeile. Gib dem Router
mit ScatterGatherOptions.withTimeoutMs() seine eigene Frist, wenn die
kürzere Ask-Frist gewollt ist.
Mit einem Error antworten
Abschnitt betitelt „Mit einem Error antworten“Ein Empfänger kann einen Ask ablehnen, indem er mit einer
Error-Instanz antwortet. Das ask-Promise wird dann mit diesem
Fehler rejected, statt mit der Nachricht resolved.
class Service extends Actor<Command> { override onReceive(command: Command): void { match(command) .with({ kind: 'fetch' }, (c) => this.onFetch(c)) .exhaustive(); }
private onFetch(command: FetchCommand): void { if (this.unavailable) { command.replyTo.tell(new Error('service unavailable')); return; } command.replyTo.tell(this.data); }}
try { const data = await service.ask({ kind: 'fetch' });} catch (e) { // e ist der "service unavailable"-Error des Actors.}Das ist eine bewusste Konvention — das Framework erkennt
Error-typisierte Antworten und rejected das Promise. Trage
Domain-Fehler den normalen Weg (typisiert über die Reply-Union) für
alles andere; reserviere den Error-Reply-Pfad für echte Fehlerzustände.
Wann ask NICHT verwendet werden sollte
Abschnitt betitelt „Wann ask NICHT verwendet werden sollte“ask ist bequem, hat aber Overhead — es allokiert eine temporäre Ref,
registriert sie beim System und räumt sie auf, wenn sie resolved/timeout.
Drei Situationen, in denen einfaches tell der richtige Aufruf ist:
Wie es weitergeht
Abschnitt betitelt „Wie es weitergeht“- Nachrichten — die
replyTo: ActorRef<T>-Feld-Konvention im Detail. - Actor —
this.senderund wie das Framework es verdrahtet. - ActorSystem — wo temporäre Ask-Refs registriert und wieder abgebaut werden.
- CircuitBreaker — wenn der Downstream-Call des Asks flakey ist und du lieber schnell fehlschlagen als timen willst.
- Future-Patterns —
pipeTo,after, sequence — async-Ergebnisse zurück in die Actor-Welt komponieren, ohne mitawaitzu blockieren.
Die ActorRef-Klassen-API-Referenz
dokumentiert die volle Signatur der ask-Methode und die Error-Typen.
