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.
Verglichen mit PersistentActor:
| Aspekt | PersistentActor | DurableStateActor |
|---|---|---|
| Was gespeichert wird | Jedes je geschriebene Event | Der aktuelle State-Snapshot |
| Recovery | Events abspielen | Snapshot laden |
| Storage-Kosten | Wächst mit Events | Konstant pro Actor |
| Historie | Ja | Nein |
| Audit / Time Travel | Ja | Nein |
| Gleichzeitige Writes | Sequenziell | Optimistisch (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.
Ein minimales Beispiel
Abschnitt betitelt „Ein minimales Beispiel“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'].Die Settings
Abschnitt betitelt „Die Settings“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 beiPersistentActoreine 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.DurableStateOptionsValidatorprüft sie im Konstruktor — früher alspreStart, 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ß alsOptionsErrorauf dem FeldpersistenceId.store— dieDurableStateStore-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).
Den Store aus der Konfiguration wählen
Abschnitt betitelt „Den Store aus der Konfiguration wählen“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.
State-Zugriff + Persistenz
Abschnitt betitelt „State-Zugriff + Persistenz“Innerhalb der Actor-Handler:
this.state // aktueller State-Wert — überall lesbarthis.revision // monoton wachsender Counter, wird bei jedem Persist erhöhtthis.persist(s) // überschreibt den gespeicherten State mit `s`, gibt Promise<DurableStateRecord<S>> zurückthis.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.
Optimistische Concurrency
Abschnitt betitelt „Optimistische Concurrency“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
persistenceIdschreibt. Das ist meistens trivial: jedercart-user-42hat 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.
Wann Durable State gegen Persistent Actor gewinnt
Abschnitt betitelt „Wann Durable State gegen Persistent Actor gewinnt“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.
State-Migration
Abschnitt betitelt „State-Migration“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.
Verschlüsselung + Kompression + Integrität
Abschnitt betitelt „Verschlüsselung + Kompression + Integrität“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.
Häufige Stolperfallen
Abschnitt betitelt „Häufige Stolperfallen“Wie geht’s weiter
Abschnitt betitelt „Wie geht’s weiter“- Persistenz im Überblick — die Entscheidung Durable State vs. Event Sourcing.
- PersistentActor — wenn die Historie wichtig ist.
- Migration im Überblick — State-Schemas weiterentwickeln.
- Object Storage — S3- + Filesystem-Backends für Durable State.
Die DurableStateActor-API-Referenz
deckt die vollständige Oberfläche ab.
