Zum Inhalt springen
Deutsch

Durable State

DurableStateActor<Command, S> ist das “Ich will einfach, dass der aktuelle Wert überlebt”-Persistenz-Modell. Kein Event-Log, kein Replay — nur ein Snapshot des States, bei jedem persist(newState) überschrieben.

DurableStateActor

onCommand(command)

this.state lesen

next = transform(...)

await this.persist(next)

revision++

Durable State Store

Verglichen mit PersistentActor:

AspektPersistentActorDurableStateActor
Was gespeichert wirdJedes je geschriebene EventDer aktuelle State-Snapshot
RecoveryEvents abspielenSnapshot laden
Storage-KostenWächst mit EventsKonstant pro Actor
HistorieJaNein
Audit / Time TravelJaNein
Gleichzeitige WritesSequenziellOptimistisch (Revisions-Check)

Wähle Durable State, wenn die Historie nicht nützlich ist — Feature Flags, last-known Configs, “aktuelle Cart-Inhalte” ohne den Audit-Trail.

import { ActorSystem } from 'actor-ts';
import { DurableStateActor, DurableStateOptions } from 'actor-ts/persistence';
import { InMemoryDurableStateStore } from 'actor-ts/persistence';
import { match } from 'ts-pattern';
type AddCommand = { kind: 'add'; sku: string };
type RemoveCommand = { kind: 'remove'; sku: string };
type ViewCommand = { kind: 'view'; replyTo: ActorRef<State> };
type CartCommand = AddCommand | RemoveCommand | ViewCommand;
type State = { items: string[]; };
class Cart extends DurableStateActor<CartCommand, State> {
constructor(options: DurableStateOptions<State>) { super(options); }
override async onCommand(command: CartCommand): Promise<void> {
await match(command)
.with({ kind: 'add' }, (c) => this.onAdd(c))
.with({ kind: 'remove' }, (c) => this.onRemove(c))
.with({ kind: 'view' }, (c) => this.onView(c))
.exhaustive();
}
private onAdd(c: AddCommand): Promise<void> {
return this.persist({ items: [...this.state.items, c.sku] });
}
private onRemove(c: RemoveCommand): Promise<void> {
return this.persist({ items: this.state.items.filter(s => s !== c.sku) });
}
private onView(c: ViewCommand): void {
c.replyTo.tell(this.state);
}
}
// Setup:
const system = ActorSystem.create('demo');
const store = new InMemoryDurableStateStore();
const durableStateOptions = DurableStateOptions.create<State>()
.withPersistenceId('cart-user-42')
.withStore(store)
.withEmptyState(() => ({ items: [] }));
const cart = system.spawn(
() => new Cart(durableStateOptions),
'cart',
);
cart.tell({ kind: 'add', sku: 'book-1' });
cart.tell({ kind: 'add', sku: 'book-2' });
// Nach einem Neustart: `this.state.items` ist wieder ['book-1', 'book-2'].
type DurableStateOptionsType<S> = {
persistenceId: string;
store?: DurableStateStore;
emptyState: () => S;
};

Drei Felder, eines davon optional:

  • persistenceId — der Schlüssel, unter dem der State gespeichert ist. Wie bei PersistentActor eine ID pro logischer Entity (cart-user-42, flags-region-eu, …) — und denselben Regeln unterworfen, was eine ID enthalten darf: nicht leer, höchstens 255 Zeichen, kein / oder \, keine Control-Zeichen. DurableStateOptionsValidator prüft sie im Konstruktor — früher als preStart, weil eine ID, die nie einen Eintrag adressieren kann, es wert ist, zurückgewiesen zu werden, bevor der Actor an einen Store gebunden wird — und meldet einen Verstoß als OptionsError auf dem Feld persistenceId.
  • store — die DurableStateStore-Implementierung (in-memory, SQLite, Object Storage, benutzerdefiniert). Optional: bleibt es ungesetzt, nutzt der Actor den Store, den das System ausgewählt hat — siehe Den Store aus der Konfiguration wählen.
  • emptyState() — Factory, die aufgerufen wird, wenn noch kein Eintrag existiert (erste Ausführung, gelöschter State). Stellt den Initialwert bereit.

Reiche sie durch die () => new Cart({...})-Factory. Die Settings können pro Actor-Inkarnation variieren (unterschiedliche IDs für unterschiedliche User, derselbe Store).

Durable State war bislang der einzige Persistence-Vertrag ohne Plugin-Registry: jeder registerXxxPlugins(...)-Helper baute seinen Store eifrig und gab ihn zurück, ihn zu erreichen ging also nur, indem man diese Instanz durch den eigenen Code fädelte. Jetzt wird er genauso ausgewählt wie Journal und Snapshot Store seit jeher:

actor-ts.persistence.durable-state {
plugin = "actor-ts.persistence.durable-state.sqlite"
sqlite { path = "/var/lib/my-app/app.db" }
}
const systemOptions = ActorSystemOptions.create().withPersistence({
plugins: [(persistence) => registerSqlitePlugins(persistence)],
});
const system = ActorSystem.create('demo', systemOptions);
// No store in the options — the actor takes the configured one.
const cartFactory = () => new Cart(
DurableStateOptions.create<State>()
.withPersistenceId('cart-user-42')
.withEmptyState(() => ({ items: [] })),
);

Der Default ist der In-Memory-Referenz-Store, exakt wie beim Journal — eine App, die nichts konfiguriert, verhält sich also wie bisher. Ein withStore(...) in den Options gewinnt weiterhin; das ist die richtige Wahl für einen Store, den die Anwendung selbst besitzt: ein mit etwas anderem geteiltes Handle, einer von mehreren Stores in einem Prozess, oder ein Spy im Test. Geändert hat sich nur, dass es nicht mehr der einzige Weg ist.

Jedes Backend, das einen Durable-State-Store mitbringt, registriert ihn auch: SQLite, die fünf relationalen Backends, MongoDB, DynamoDB und Object-Storage. Cassandra ist die eine Ausnahme, und zwar eine ehrliche — das Framework hat gar keinen Cassandra-Durable-State-Store, dieses Backend hat also zwei Plugin-Achsen, wo die übrigen drei haben.

Eine nicht registrierte Plugin-Id wird abgelehnt statt still ersetzt: ext.durableStateStore wirft Unknown durable-state plugin '…' und benennt die Id — dasselbe Fehlerverhalten, das die beiden anderen Achsen seit #377 haben. Mit dem Öffnen beim Start, dem Default, löst das System die ausgewählten Stores innerhalb von create auf, die Ablehnung lässt also den Start scheitern — siehe Stores beim Start öffnen.

Ein Wert an der Stelle des Blocks wird ebenfalls abgelehnt und nennt den Schlüssel. actor-ts.persistence.durable-state = "actor-ts.persistence.durable-state.sqlite" sieht aus wie eine Auswahl, ersetzt aber den Block, der den Selektor enthält, und wurde früher als gar keine Auswahl gelesen: Der Store blieb im Speicher, der Start meldete Bereitschaft, und der Zustand war beim nächsten Neustart weg. Jetzt lässt er den Start mit einem ConfigError scheitern, der sagt, dass actor-ts.persistence.durable-state ein Block mit einem plugin-Feld sein muss — schreib plugin = "…" in den Block, wie oben. Dasselbe gilt für den Journal- und den Snapshot-Store-Block und für actor-ts.persistence selbst, und ein Selektor, der gar keine Id hält — null, ein Block, eine Liste —, lässt jede Achse scheitern, nicht nur seine eigene.

Ein vertippter Schlüssel wird ebenfalls abgelehnt und mit vollem Namen genannt. plugn = "…" im Block liest niemand, und früher ließ es plugin auf der In-Memory-Id, die reference.conf mitbringt, also startete das System ohne Fehler und ohne Warnung mit dem In-Memory-Store, genau als wäre nichts ausgewählt. Jetzt lässt es den Start mit einem ConfigError scheitern, der actor-ts.persistence.durable-state.plugn nennt, und ebenso jeder andere Wert im Block neben plugin — darunter eine Einstellung eines Plug-ins, eine Ebene zu hoch geschrieben — und jeder Schlüssel direkt unter actor-ts.persistence, den das Framework nicht liest. Korrigiere die Schreibweise, oder verschiebe die Einstellung in den Block ihres Plug-ins. Ein vertipptes Leaf im eigenen Block eines Plug-ins abzulehnen ist Sache dieses Plug-ins.

Ein ausgewählter SQLite-Store ohne Pfad wird ebenfalls abgelehnt, und zwar früher: registerSqlitePlugins prüft schon beim Registrieren jeden Store, den die Konfiguration auswählt — außer einem, den withPersistence im Code setzt, der die Auswahl ersetzt und sie ungebaut lässt —, sodass create mit einem Fehler wirft, der actor-ts.persistence.durable-state.sqlite.path nennt. Gib dem Block einen Pfad — ":memory:" für eine In-Memory-Datenbank — oder übergib dem Plugin im Code eine Datenbank.

Innerhalb der Actor-Handler:

this.state // aktueller State-Wert — überall lesbar
this.revision // monoton wachsender Counter, wird bei jedem Persist erhöht
this.persist(s) // überschreibt den gespeicherten State mit `s`, gibt Promise<DurableStateRecord<S>> zurück

this.state ist synchron — das Framework lädt den State in preStart, und state gibt zurück, was gerade im Speicher steht. Vor dem ersten Persist (oder Load) gibt es emptyState() zurück.

this.persist(next) schreibt den neuen State in den Store mit der aktuellen Revision + 1. Kehrt zurück, sobald der Store bestätigt. Innerhalb von onCommand warte mit await darauf, bevor du den nächsten State als autoritativ behandelst.

State wird auf jedem Backend im getaggten JSON-Tree-Format gespeichert, sodass Date / Map / Set / bigint / Uint8Array als echte Instanzen round-trippen — siehe was Events und State enthalten dürfen.

try {
await this.persist(next);
} catch (e) {
if (e instanceof DurableStateConcurrencyError) {
// Ein anderer Writer war schneller — neu laden und erneut versuchen oder zum User durchreichen.
}
}

Wenn zwei Writer gleichzeitig dieselbe persistenceId aktualisieren, lehnt der Revisions-Check des Stores den zweiten mit DurableStateConcurrencyError ab. Strategien:

  • Das Problem vermeiden — stelle sicher, dass immer nur ein Actor zur selben Zeit in eine gegebene persistenceId schreibt. Das ist meistens trivial: jeder cart-user-42 hat einen Actor auf einem Node (per Sharding oder Singleton).
  • Neu laden und erneut versuchen — den Fehler fangen, State neu laden, den neuen Wert neu berechnen, erneut persistieren. Funktioniert, wenn die Operation idempotent ist.
  • Zum Aufrufer durchreichen — mit einem Fehler antworten; den Aufrufer entscheiden lassen, ob er erneut versuchen will.

Bei den meisten Actor-System-Mustern sollten gleichzeitige Writes nicht passieren — eine Entity pro persistenceId, über Routing oder Sharding adressiert. Wenn du Concurrency-Fehler in Produktion siehst, bedeutet das meist, dass zwei Actors denselben Key schreiben, was ein Routing-Bug ist.

Drei Signale, dass du das richtige Werkzeug gewählt hast:

  • Die State-Form ist einfach (ein einzelnes Objekt, eine kleine Map). Das Ganze zu überschreiben ist billig.
  • Du brauchst keinen Event-Stream — keine Projektionen, kein Audit-Log, keine “zeig mir, wie wir hier gelandet sind”- Anforderungen.
  • Reads dominieren Writes — jedes Read ist ein synchrones this.state, kein Replay.

Drei Signale, dass du stattdessen zu PersistentActor greifen solltest:

  • Die Historie ist wichtig — Auditing, regulatorisch, “zeig dem User ein Changelog.”
  • Der State ist groß und Änderungen sind klein — den gesamten State bei jeder Änderung zu schreiben ist verschwenderisch; kleine Events anzuhängen ist billiger.
  • Du willst Projektionen — Read-Side-Views, die den Event-Stream brauchen.

Wie bei PersistentActor unterstützt Durable State Schema-Evolution durch einen Adapter:

import { StateAdapter } from 'actor-ts/persistence';
const v1ToV2Adapter: StateAdapter<StateV2> = {
manifest: () => 'Cart',
toJournal: (state) => ({ manifest: 'Cart', version: 2, payload: state }),
fromJournal: (stored) => stored.version === 1
? migrate(stored.payload as StateV1)
: stored.payload as StateV2,
};
class Cart extends DurableStateActor<...> {
protected stateAdapter() { return v1ToV2Adapter; }
}

Der persistierte Eintrag wird in einen { _v, _t, _e }-Envelope verpackt; beim Laden läuft fromJournal des Adapters, um ältere Versionen zu migrieren. Siehe Migration im Überblick für die vollständige Story.

Drei Per-Actor-Overrides sind verfügbar:

class Sensitive extends DurableStateActor<Command, State> {
protected encryption() {
return { mode: 'client-aes256-gcm' as const, masterKey, info: 'acme/prod/durable-state/v1' };
}
protected compression() { return { algorithm: 'gzip' as const }; }
protected integrity() {
return { mode: 'hmac-sha256' as const, integrityKey };
}
}

Die Object-Storage- und SQL-Durable-State-Stores lesen diese. Der Object-Storage-Store und die SQL-Familie — SQLite, Postgres, MariaDB, MSSQL, libSQL und D1 (#1802) — honorieren alle drei Hooks auf Schreib- und Lesepfad. Die SQL-Stores behalten das Schema: Der Datensatz landet in derselben payload-Spalte, als Object-Storage-Frame in Base64 hinter einem ats1:-Präfix, gebunden an Persistence-ID und Revision, sodass ein Payload, der mit einer anderen Revision gepaart wird, sich nicht entschlüsseln lässt. Ein Actor mit encryption() verweigert eine Zeile, die nicht verschlüsselt ist, Klartext-JSON eingeschlossen, denn diese Zeile ist entweder älter als der Hook oder wurde von jemandem mit Zugriff auf die Tabelle geschrieben. Um einen Hook über bestehenden Datensätzen einzuschalten, baust du den Store mit withAllowPlaintextRows(true): Der nächste persist schreibt jede Zeile versiegelt neu, danach kommt die Option wieder heraus. Was kein Schlüssel erkennen kann, ist eine ganze Zeile — Revision und Payload zusammen —, die auf eine ältere Kopie zurückgesetzt wird.

Die übrigen drei Durable-State-Stores nehmen die Optionen entgegen und sehen sie nie an — aber sie sagen es, über eine persistenceOptionSupport-Deklaration, die das Framework beim Actor-Start prüft (#960). Auf In-Memory, Mongo und DynamoDB verweigern encryption() oder integrity() den Actor vor dem Start, mit einem UnsupportedPersistenceOptionError, der Store und Feld benennt. Die Verweigerung liegt bewusst vor dem Load in preStart und nicht erst beim ersten Write: Ein Durable-State-Actor liest, bevor er schreibt, und ein Lesen gegen einen Store, der nicht entschlüsseln kann, würde ihm einen Klartext-Datensatz geben, den er für Chiffrat hält. compression() ist ein Performance-Hinweis, warnt also einmal, und der Datensatz wird unkomprimiert geschrieben; { mode: 'none' } wird überall akzeptiert.

Einen der beiden Authentifikatoren zu konfigurieren — client-aes256-gcm oder hmac-sha256 — erkauft neben Vertraulichkeit und Manipulationserkennung noch etwas Zweites: Erst dadurch bekommt der Object-Storage-Store eine Verschiebungserkennung. Jeder Write bindet den Body an den Storage-Key, auf den er geht; ein Datensatz, der später unter dem Key einer anderen Entity auftaucht, wird abgelehnt, und dafür ist nichts einzuschalten. Ohne einen davon — der Standard — bemerkt es auf dieser Ebene nichts: Ein Durable-State-Body ist { revision, state, timestamp } und nennt keine Entity, und load antwortet mit der persistenceId, nach der gefragt wurde. Der Snapshot-Store steht nicht an derselben Stelle; Was Verschlüsselung nicht abdeckt legt den Unterschied dar.

Siehe Object-Storage-Verschlüsselung für die Durable-State-Verschlüsselungs-Story und Policies pro Actor für alle drei Hooks.

Die DurableStateActor-API-Referenz deckt die vollständige Oberfläche ab.