Zum Inhalt springen
Deutsch

ActorSystem

Das ActorSystem ist der Top-Level-Container für Actors. Eines pro logischer Anwendung — manchmal eines pro Prozess, manchmal ein paar, die nebeneinander laufen (z.B. ein Worker-Thread-Isolations-Setup). Jeder Actor lebt innerhalb eines Systems; das System besitzt den Dispatcher (der die Nachrichtenverarbeitung plant), den Scheduler (der Timer ausführt), den Supervisionsbaum (der Actor-Fehler abfängt), den Event-Stream und alle Extensions, die du registriert hast.

import { ActorSystem } from 'actor-ts';
const system = ActorSystem.create('my-app');

Der String ist der Name des Systems — er erscheint in Actor-Pfaden (actor-ts://my-app/user/...), Log-Zeilen und der Cluster-Identifikation. Verschiedene Systeme können mit verschiedenen Namen koexistieren; derselbe Name in einem Cluster-Setup bedeutet “ich trete dem bestehenden Cluster bei”, ein anderer Name bedeutet “ich bin ein separater Cluster”.

create kehrt synchron zurück. Die Root-Guardians des Systems werden eifrig erzeugt; User-Actors existieren noch nicht — du spawnst sie über spawn (unten beschrieben).

Manche Arbeit gehört zwischen create und die erste Anfrage: das Journal öffnen, eine Migration ausführen, prüfen, ob ein Dienst antwortet, von dem das System abhängt. Diese Arbeit führt das System selbst aus, als Startup-Graph — Tasks, die du ActorSystemOptions.withCoordinatedStartup übergibst und die in Phasen als letzter Schritt von create laufen. Nichts in main muss ihn starten.

import {
ActorSystem,
ActorSystemOptions,
CoordinatedStartupOptions,
StartupPhases,
} from 'actor-ts';
const startupOptions = CoordinatedStartupOptions.create().withTasks([
{
phase: StartupPhases.BeforeSystemReady,
name: 'check-inventory-service',
task: async (signal) => {
const response = await fetch('https://inventory.internal/health', { signal });
if (!response.ok) throw new Error(`inventory answered ${response.status}`);
},
},
]);
const actorSystemOptions = ActorSystemOptions.create().withCoordinatedStartup(startupOptions);
const system = ActorSystem.create('orders', actorSystemOptions);
await system.whenReady();

Zwei Phasen sind vorgegeben und laufen in dieser Reihenfolge: persistence-start, um zu öffnen, was die Persistenz braucht, dann before-system-ready für alles Übrige. Die Tasks einer Phase laufen gleichzeitig, und eine Phase beginnt, sobald die vorige fertig ist. Jede Phase hat ein Budget — 30 Sekunden, sofern withDefaultPhaseTimeoutMs nichts anderes sagt —, und jeder Task bekommt ein AbortSignal, das abbricht, wenn das Budget aufgebraucht ist oder das System terminiert wird, bevor der Start fertig ist; reich es also an alles weiter, worauf der Task wartet. withPhases gibt einer vorgegebenen Phase ein anderes Budget oder deklariert eine eigene Phase, die nennen muss, nach welcher Phase sie läuft.

Ein Deployment stimmt dieselben Budgets in seiner Konfigurationsdatei ab, unter dem, was der Code setzt:

actor-ts.coordinated-startup {
default-phase-timeout = 45s
phases {
persistence-start { timeout = 2m }
}
}

withDefaultPhaseTimeoutMs gewinnt über default-phase-timeout, und eine Phase, die withPhases nennt, gehört als Ganzes dem Code; die Kinder von phases haben die Form des Blocks des Coordinated Shutdown — siehe actor-ts.coordinated-startup.

Das Framework legt eigene Arbeit in persistence-start: Ein System, das Persistenz verdrahtet, öffnet dort sein ausgewähltes Journal, seinen Snapshot-Store und seinen Durable-State-Store, also lässt ein Store, der sich nicht öffnen lässt, den Start scheitern wie jeder Task — siehe Stores beim Start öffnen. Jeder Store, der mit actor-ts ausgeliefert wird, erreicht sein Backend schon beim Öffnen — mit abgeschaltetem auto-create-tables pingt ein relationaler Store seine Datenbank an, und ein DynamoDB-Store fragt die Beschreibung seiner Tabelle ab —, außer dem Object-Storage-Snapshot-Store und dem Object-Storage-Durable-State-Store. Die haben vorab nichts zu öffnen, also scheitert an einem Bucket, den sie nicht erreichen, ihre erste Operation und nicht der Start; genauso bei einem eigenen Store ohne start(). Schaltest du autoStart im Persistence-Verhalten ab — oder setzt actor-ts.persistence.auto-start = off in der Konfiguration —, bleiben sie bis zu ihrer ersten Operation geschlossen. Im Code abgeschaltet, bleibt auch der übrige Behaviour-Block unter actor-ts.persistence ungelesen, bis etwas ihn liest: create braucht ihn nicht, also wird ein Fehler darin dort abgelehnt, wo Persistence ihn zuerst liest, und nicht von create. Genau das setzt ein WorkerMesh-Worker, also startet ein Worker mit der Konfiguration des Main-Threads, ob er je etwas persistiert oder nicht.

system.whenReady() resolved, sobald die letzte Phase gelaufen ist. Es ist bei jedem Aufruf dasselbe Promise und für ein System ohne Startup-Tasks sofort resolved. Warten musst du darauf aber nicht: Solange der Graph läuft, hält der Readiness-Check startup den Endpunkt /ready auf false, sodass ein Load Balancer einem Knoten, der noch hochfährt, keinen Traffic schickt.

Ein fehlgeschlagener Start fährt das System herunter. Ein Task, der wirft, rejected oder das Budget seiner Phase überschreitet, stoppt den Lauf: whenReady() rejected mit einem Fehler, der Phase und Task nennt, die späteren Phasen laufen nicht, das System schreibt eine ERROR-Zeile und führt die Pipeline des Coordinated Shutdown mit einem StartupFailedReason aus, und runUntilTerminated() rejected danach mit demselben Fehler — eine main, die darauf wartet, endet also von selbst mit einem Status ungleich null, und der Orchestrator startet einen neuen Prozess.

Ein Shutdown während des Starts bricht ihn dagegen ab, denn nichts ist fehlgeschlagen: whenReady() rejected mit einem Abbruchfehler, die späteren Phasen laufen nicht, nichts wird oberhalb von debug geloggt, und es läuft kein eigener Shutdown — ein SIGTERM, während das System startet, beendet den Prozess also als Shutdown und nicht als gescheiterten Start. Das geschieht sofort, was auch immer den Shutdown gestartet hat — terminate(), ein SIGTERM, ein expliziter run()-Aufruf der Coordinated-Shutdown-Pipeline: die Signale der laufenden Tasks brechen ab, bevor die erste Phase der Pipeline läuft.

Der Graph ist versiegelt, sobald create zurückkehrt. system.extension(CoordinatedStartupId).addTask(...) wirft danach und nennt withCoordinatedStartup — ein so später Task könnte seine Phase schon vorbei finden.

ActorSystem.create nimmt ein optionales Settings-Objekt als zweites Argument:

const actorSystemOptions = ActorSystemOptions.create()
.withLogLevel(LogLevel.Info)
.withConfigFile('./application.conf');
const system = ActorSystem.create('my-app', actorSystemOptions);

Die vollständige Settings-Form:

FeldZweck
loggerEigene Logger-Instanz. Standardmäßig ein Console-Logger, der logLevel respektiert.
otelLogsBaut den System-Logger aus der OpenTelemetry-Logs-API: die OtelLogsAdapterOptions, die das System beim Konstruieren an otelLogger übergibt, mit actor-ts.tracing.logger-name / logger-version darunter gelegt — siehe OTLP-Logs-Pipeline. Sein Level ist das der Optionen, sonst logLevel, sonst actor-ts.logger.level. Die Logger-Felder werden der Reihe nach geprüft, und das erste gesetzte gewinnt: logger > otelLogs > logSinks > die Sinks, die actor-ts.logger.sinks aktiviert > der Console-Logger.
logLevelEiner von debug / info / warn / error / off.
dispatcherEigener Dispatcher. Standardmäßig der, den actor-ts.dispatcher.default wählt — HybridDispatcher, sofern nichts anderes konfiguriert ist; tausche einen Immediate- oder Throughput-basierten ein oder Dispatchers.Hybrid(n) mit einem anderen Budget, um das Scheduling anzupassen. Ein Budget ist eine ganze Zahl ab 1: Dispatchers.Hybrid(0) wird beim Bau mit einem OptionsError abgelehnt, und mit actor-ts.dispatcher.default = throughput lässt ein konfiguriertes throughput von 0 ActorSystem.create ebenso scheitern.
schedulerEigener Scheduler. Standardmäßig ein Echtzeit-Scheduler; Tests injizieren ManualScheduler, um die Zeit zu kontrollieren.
configEntweder eine vorgefertigte Config oder ein einfaches Objekt mit HOCON-Overrides. Wird über die Referenz-Defaults + einer eventuellen application.conf gelegt. Übergib eine Config selbst, nie einen Spread davon: { ...config } kopiert ihre privaten Felder, nicht ihre Konfiguration, und create lehnt ihn mit einem ConfigError ab — so wie eine Klasseninstanz (eine Map, ein Date, eine verschachtelte Config) irgendwo im Objekt.
configFileExpliziter Pfad zu einer application.conf-Datei. Überschreibt die ACTOR_TS_CONFIG-Env-Variable und das CWD-Lookup; false liest keine Anwendungsdatei.
referenceConfigFileExpliziter Pfad zur eigenen reference.conf des Projekts — seinen Defaults, über den gebündelten und unter application.conf. Überschreibt die ACTOR_TS_REFERENCE_CONFIG-Env-Variable und das CWD-Lookup; false liest keine.
secretsFileExpliziter Pfad zur Secrets-Datei, deren Werte der Konfigurations-Dump und das DevTools-Panel allesamt zurückhalten. Überschreibt die ACTOR_TS_SECRETS_CONF-Env-Variable und das CWD-Lookup; false liest keine.
environmentFileExpliziter Pfad zur .env-Datei, deren Variablen ${VAR} hinter der echten Umgebung beantworten. Überschreibt die ACTOR_TS_ENV_FILE-Env-Variable und das CWD-Lookup; false liest keine.
profileDas Konfigurations-Profil — der Block profiles.<name> jeder Datei, die der Loader liest, der reference.conf des Projekts, der application.conf und der Secrets-Datei, über die Wurzel jeder Datei gelegt. Überschreibt die ACTOR_TS_PROFILE-Env-Variable; ein Name, den keine Datei definiert, wird beim Start abgelehnt. Erreicht nur system.config, nicht die Komponenten, die ihre Konfiguration selbst laden.
persistencePersistenz, beim Erstellen verdrahtet. plugins sind Funktionen, die die PersistenceExtension des Systems erhalten und Backends registrieren — (persistence) => registerSqlitePlugins(persistence) — und innerhalb von create in der angegebenen Reihenfolge laufen, sodass sich das Plugin, das die Konfiguration auswählt, auflösen lässt, sobald create zurückkehrt. Ein Promise, das eines davon zurückgibt, wird in der Phase persistence-start des Startup-Graphen abgewartet, wo eine Ablehnung den Start scheitern lässt; eines, das wirft, lässt create werfen. journal, snapshotStore und durableStateStore sind Store-Instanzen, die jeweils Vorrang vor dem Plugin haben, das ihre Achse auswählt. behavior ist das Persistenz-Verhalten, Feld für Feld über actor-ts.persistence gelegt; sein autoStart, an, solange es nicht auf false gesetzt wird, öffnet die ausgewählten Stores in persistence-start, wo eine Auswahl, die niemand registriert hat, oder ein Store, der sich nicht öffnen lässt, den Start scheitern lässt — aus, öffnen sie bei der ersten Verwendung.
coordinatedStartupDer Startup-Graph — Tasks, die das System in Phasen als letzten Schritt von create ausführt, abzuwarten über system.whenReady(). Siehe Hochfahren.

Konstruktor-Settings gewinnen immer gegenüber allem in der Config — sie sind die expliziten Code-Level-Overrides.

Für größere Anwendungen bevorzuge eine application.conf-Datei im Projekt-Root:

actor-ts {
logger {
level = "info"
}
dispatcher {
default = "throughput" # the count below is read under this kind only
throughput = 100
}
cluster {
gossip-interval = 500ms
failure-detector.unreachable-after = 1500ms
}
}

Das Framework lädt sie automatisch, wenn vorhanden, über einer eigenen reference.conf des Projekts, wenn es eine gibt. ENV-Substitution (${?ENV_NAME}) funktioniert wie in der HOCON-Spec definiert — aus der Umgebung gezogene Werte fallen auf den Default zurück, wenn sie nicht gesetzt sind —, und eine .env-Datei daneben kann sie liefern. Eine Datei kann mehrere Umgebungen als Profile tragen, und Credentials gehören in die optionale Secrets-Datei daneben. Siehe Konfiguration für jeden Schlüssel, den das Framework liest.

Top-Level-Actors werden über system.spawn gespawnt:

const root = system.spawn(
MyRootActor,
'root', // optionaler Name; Framework wählt einen, wenn weggelassen
);

Die zurückgegebene ActorRef ist ein Handle, keine Instanz. Gib es weiter, speichere es, übergib es an andere Actors.

Innerhalb eines Actors werden Child-Actors über context.spawn gespawnt, nicht über system.spawn:

class Parent extends Actor<...> {
override onReceive(message) {
const child = this.context.spawn(Child, 'worker');
}
}

Kinder sind an den Lebenszyklus des Parents gebunden — wenn der Parent stoppt, stoppen zuerst alle Kinder. Fehler von Kindern eskalieren an die Supervisor-Strategie des Parents. Top-Level-Actors (aus system.spawn) eskalieren stattdessen an den Root-Guardian des Systems.

Jeder Actor hat einen Pfad unter dem System-Root. Drei “Guardian”-Top-Level-Actors sitzen direkt unter dem Root:

actor-ts://my-app/

/user
Actors deiner Anwendung

/system
framework-interne Actors

/deadLetters
Nachrichten an tote Refs

/system/cluster
Sharding, Singleton, PubSub, …

/system/devtools
Hub + Probes

Wenn du system.spawn(actor, name) aufrufst, wird der Actor unter /user erzeugt. /user enthält nur, was dein Code erzeugt hat; alles, was das Framework für sich selbst erzeugt, liegt unter /system — eine Gruppe pro Subsystem, siehe Actor-Pfade für das vollständige Layout. Es gibt keine öffentliche API, um in /system zu spawnen.

Beim Terminieren gehen die beiden Guardians nacheinander, nicht gleichzeitig: /user wird vollständig geleert, dann /system. Diese Reihenfolge ist es, die einem postStop eines User-Actors erlaubt, die Framework-Actors zu erreichen, von denen er abhängt — sich beim PubSub-Mediator abmelden, einen Shard zurückgeben — statt mit ihnen um Dead Letters zu rennen.

Der /deadLetters-”Actor” ist speziell — Nachrichten an ein tell auf einer gestoppten Ref oder an eine nie existierte Ref werden dorthin geleitet. Jede davon wird geloggt und als DeadLetter auf dem Event-Stream veröffentlicht und benennt den Empfänger, den sie nicht erreicht hat. Die Log-Zeile nennt Empfänger, Sender und die Klasse der Nachricht — nie die Payload — und ist nach den ersten zehn gedrosselt, damit ein Zustell-Ausfall kein Log-Ausfall wird. Aufbewahrt wird das Letter aber nicht: ohne Abonnent und ohne Queue ist die Nachricht weg, sobald die Zeile geschrieben ist. Abonniere, um programmatisch zu reagieren, oder schalte die begrenzte — optional dauerhafte — Queue ein, die sie aufbewahrt und erneut zustellt; siehe Dead Letters.

Extensions sind das Plugin-System des Frameworks. Cluster, Persistenz, DistributedData, DistributedPubSub, HTTP — sie sind alle Extensions. Du registrierst sie einmal auf System-Ebene und erreichst sie dann über system.extension(...):

import { Cluster, ClusterOptions } from 'actor-ts/cluster';
import { DistributedDataId } from 'actor-ts/crdt';
const cluster = await Cluster.join(system, ClusterOptions.create() /* ... */);
const dd = system.extension(DistributedDataId).start(cluster);

Extensions sind lazy: sie initialisieren sich nicht, bis du nach ihnen greifst. Eine App, die nie system.extension(DistributedDataId) aufruft, startet nie einen DD-Replicator. Das hält Single-Process-Apps klein; übernimm Features, indem du nach ihnen greifst, lass sie weg, indem du es nicht tust.

import { extensionId, type Extension, type ExtensionId } from 'actor-ts';
class MetricsCollector implements Extension {
constructor(private readonly system: ActorSystem) {}
incCounter(name: string): void { /* ... */ }
}
const MetricsCollectorId: ExtensionId<MetricsCollector> = extensionId(
'MetricsCollector',
(system) => new MetricsCollector(system),
);
// Lookup ist idempotent — der erste Aufruf erzeugt, folgende Aufrufe
// geben die gecachte Instanz zurück.
const metrics = system.extension(MetricsCollectorId);
metrics.incCounter('login.success');

Extensions sind nützlich, wenn:

  • Du übergreifenden Zustand brauchst, der von vielen Actors geteilt wird (ein Connection-Pool, ein Metrics-Collector).
  • Der Zustand teuer zu initialisieren ist und nicht existieren sollte, wenn niemand danach greift (ein Cluster-Join, ein DD-Replicator).
  • Du eine saubere Möglichkeit willst, Test-Doubles in Unit-Tests zu injizieren (überschreibe den ExtensionId-Resolver).
await system.terminate();

terminate führt einen geordneten Shutdown durch:

  1. /user leeren — warten, bis dort kein Actor mehr einen Turn laufen oder eine Nachricht in der Queue hat, sodass ref.tell(x); await system.terminate() das x noch verarbeitet. Das Warten ist transitiv: eine Zelle gilt in dem Moment als beschäftigt, in dem ihr jemand etwas sendet, also halten Antworten, Router-Fan-outs und Restarts den Drain am Laufen, statt jede Mailbox nur einmal durchzuspülen.
  2. /user rekursiv stoppen — deine Actors bekommen postStop, Kinder zuerst. Actors mit laufenden async onReceives beenden ihre aktuelle Nachricht, bevor sie stoppen.
  3. /system stoppen — Framework-Internas wickeln sich ab. Das beginnt erst, wenn /user vollständig geleert ist, sodass ein postStop aus Schritt 2 noch mit den Sharding-, PubSub- oder Delivery-Actors reden kann, von denen es abhängt.
  4. Dispatcher und Scheduler schließen — keine neuen Nachrichten, keine neuen Timer.
  5. Das zurückgegebene Promise resolven.

Mehr tut ein einfaches terminate() nicht. Keine Phase des Coordinated Shutdown läuft, ein gebundener HTTP-Port wird also nicht freigegeben, und ein beigetretener Cluster-Knoten verlässt den Cluster nicht — seine Peers routen weiter zu ihm, bis ihre Failure Detectors aufgeben. Der nächste Abschnitt zeigt die Aufrufe, die zuerst die Pipeline ausführen.

Der Drain in Schritt 1 ist durch actor-ts.system.shutdown-drain-timeout begrenzt (Standard 2 s) und kehrt sofort zurück, sobald der Baum ruhig ist — ein untätiges System zahlt einen Tick, nicht das Budget. Setze ihn auf 0, um das Leeren ganz zu überspringen; was beim Ablauf des Budgets noch in der Queue steht, landet über Schritt 2 in den Dead Letters — genau das passierte vor dem Drain mit dem gesamten Rückstau.

Auf drei Dinge wird bewusst nicht gewartet:

  • eine durch context.throttle(...) geparkte Mailbox und eine, die suspendiert ist, während ein Supervisor entscheidet — keine von beiden leert sich in einem Tempo, auf das ein Shutdown warten kann, also gelten beide als ruhig;
  • alles unter /system — Heartbeats, Failure Detectors und Broker-Reconnect-Schleifen sind konstruktionsbedingt nie ruhig;
  • Arbeit, die noch in keiner Mailbox liegt — ein noch nicht gefeuerter context.timers-Tick oder ein tell aus einem Promise, das ein Handler ohne await gestartet hat.

Um einen Actor nach dem Leeren seiner Mailbox zu stoppen und darauf zu warten, nimm gracefulStop(ref, timeoutMs) — siehe PoisonPill & Kill.

Laufen, bis der Prozess zum Stoppen aufgefordert wird

Abschnitt betitelt „Laufen, bis der Prozess zum Stoppen aufgefordert wird“

Für einen Service ist ein einfaches terminate() nichts, was du aufrufst — es ist das, was am Ende passiert. Die ganze main nach dem Verdrahten der Actors lautet:

await system.runUntilTerminated();

Das installiert SIGTERM/SIGINT-Handler, löst auf, sobald das System unten ist, und hängt die Handler auf dem Weg hinaus wieder ab. Ein handgeschriebenes process.on('SIGTERM', () => system.terminate()) sieht gleichwertig aus und ist es nicht: es stoppt zuerst die Actors und gibt erst danach — falls du daran gedacht hast, es zu schreiben — den HTTP-Port frei und verlässt den Cluster. runUntilTerminated() führt die Pipeline aus Coordinated Shutdown aus, die Listener abbindet, Broker schließt und den Cluster verlässt, bevor die Actors stoppen — ein Rolling Deploy nimmt den Knoten also aus der Rotation, während seine Actors noch zu Ende bringen können, was sie halten.

Es ist außerdem die Variante, die überall funktioniert: Deno stellt Signale über Deno.addSignalListener zu, nicht über process.on, und ein Listener hält dort die Event-Loop am Leben, bis er entfernt wird.

Ist der Start des Systems fehlgeschlagen, rejected das Promise mit dessen Fehler, sobald das System unten ist — und das beendet den Prozess.

Wenn der Shutdown eine Entscheidung deines Programms ist und nicht die eines Signals — ein Admin-Endpoint, das Ende eines Batch-Jobs —, bitte terminate() um dieselbe Pipeline:

await system.terminate({ runCoordinatedShutdown: true });

Zuerst läuft jede Phase, mit ActorSystemTerminateReason, und das Promise resolved, sobald die Pipeline fertig und das System unten ist. Ein terminate(), das eintrifft, während schon ein Lauf unterwegs ist — etwa aus einem seiner Tasks —, startet nichts und resolved sofort; außerhalb der Pipeline await system.whenTerminated(), wenn du das System unten brauchst — ein Task darf das nicht: Der Teardown, auf den er warten würde, läuft in der letzten Phase, das Warten hält also seine eigene Phase ihr ganzes Budget lang fest (siehe system.terminate() direkt aufrufen).

Die übliche Antwort ist eins. Ein zweites System im selben Prozess bedeutet einen separaten Cluster, einen separaten Dispatcher, einen separaten Supervisionsbaum — typischerweise mehr Overhead, als der Use Case rechtfertigt.

Zwei Situationen, in denen ein zweites System Sinn macht:

  • Worker-Thread-Isolation: der Hauptthread läuft mit einem System, ein Worker-Thread mit einem anderen, beide spannen denselben Cluster über den MessageChannelTransport auf. Das ist das Worker-Mesh-Pattern — mehrere Systeme pro OS-Prozess, alle Teil desselben Clusters.
  • Test-Fixtures: ein TestActorSystem pro Testfall, damit das Cleanup garantiert ist. Siehe TestKit.
  • Actor — die Klasse, die du in das System spawnst.
  • Coordinated Shutdown — Graceful-Shutdown-DSL jenseits eines einfachen terminate.
  • Cluster-Überblick — wenn du von einem System pro Prozess zu vielen Systemen in einem Cluster gehst.
  • Konfiguration — jeder HOCON-Schlüssel, den das Framework liest, gruppiert nach Extension.

Die ActorSystem-Klassen-API-Referenz dokumentiert jede hier diskutierte öffentliche Methode.