Snapshots
Ein PersistentActor liest sein gesamtes Event-Log, um sich
wiederherzustellen. Für einen Actor, der jahrelang gelebt und
100 000 Events emittiert hat, ist das ein langsamer Start.
Snapshots sind ein periodischer Dump des aktuellen States — bei
der Recovery lädt das Framework den neuesten Snapshot und spielt nur
Events danach ab.
Journal: E1 E2 E3 E4 E5 ... E150 ... E1000 ← alle je geschriebenen Events ↑ ↑ Recovery neuester Snapshot startet hier gespeichert bei seqNr=500
Ohne Snapshots: 1000 Events abspielen. Mit Snapshot @500: Snapshot laden, dann E501..E1000 abspielen.Der Trade-off: Snapshots kosten Disk-Platz und Schreib-Durchsatz, aber kaufen begrenzte Recovery-Zeit.
Eine Snapshot-Policy konfigurieren
Abschnitt betitelt „Eine Snapshot-Policy konfigurieren“Der Actor deklariert wann gesnappshottet werden soll, per
snapshotPolicy():
import { PersistentActor, everyNEvents } from 'actor-ts/persistence';
class Account extends PersistentActor<Command, Event, State> { // ... override snapshotPolicy() { return everyNEvents(100); // Snapshot alle 100 Events }}everyNEvents(N) ist die häufigste Policy. Das Framework ruft die
Policy-Funktion nach jeder Event-Anwendung auf; true zurückgeben
löst einen Snapshot des aktuellen States in den Snapshot Store aus.
Für individuelle Policies:
override snapshotPolicy() { return (seqNr, state, event) => { // Snapshot bei einer bestimmten Event-Art: if (event.kind === 'finalized') return true; // Oder bei einer State-Eigenschaft: if (state.balance > 1_000_000) return true; return false; };}Die Signatur: (seqNr, state, event) => boolean. seqNr ist die
Sequenznummer des gerade angewendeten Events, state ist der State
nach dem Anwenden, event ist das Event, das den Aufruf
ausgelöst hat.
Das Snapshot-Intervall wählen
Abschnitt betitelt „Das Snapshot-Intervall wählen“everyNEvents(N)Die Zahlen, die zählen:
- Recovery-Zeit — wie lange Replay-from-Snapshot dauert. Niedrigeres N bedeutet schnellere Recovery.
- Snapshot-Schreibkosten — jeder Snapshot serialisiert den vollständigen State. Für große States ist das nicht-triviale Arbeit. Höheres N amortisiert diese Kosten über mehr Events.
- Storage — Snapshots brauchen Platz, sogar mit der “Ältere löschen”-Policy.
Typische Zahlen:
- Kleiner State, niedrige Schreibrate —
everyNEvents(1000). Ein Tausend-Event-Replay ist immer noch schnell; Snapshots sind selten. - Mittlerer State, moderate Schreibrate —
everyNEvents(100). Sinnvoller Default. - Großer State, hohe Schreibrate —
everyNEvents(1000)mit schnellem Journal, ODER überlege, zuDurableStateActorzu wechseln, wenn Events nicht nützlich sind.
Nicht übertunen. everyNEvents(100) ist ein vernünftiger
Startpunkt; miss die Recovery-Latenz in Produktion, bevor du
änderst.
Wo Snapshots leben
Abschnitt betitelt „Wo Snapshots leben“Snapshots werden in einem separaten Snapshot Store gespeichert,
bei der System-Erstellung via withPersistence verdrahtet:
import { ActorSystemOptions } from 'actor-ts';import { InMemoryJournal, InMemorySnapshotStore } from 'actor-ts/persistence';
const actorSystemOptions = ActorSystemOptions.create().withPersistence({ journal: new InMemoryJournal(), snapshotStore: new InMemorySnapshotStore(),});Eingebaute Snapshot Stores. Die dritte Spalte ist die
persistenceOptionSupport-Deklaration des Stores selbst — ob er für
die Snapshots, die er hält, auf die Hooks compression() /
encryption() / integrity() reagiert oder sie bloß entgegennimmt.
Keine Zeile deckt Events ab: Die liegen im Journal, das keiner der
Hooks erreicht — siehe das Ende dieses Abschnitts:
| Store | Wann | Honoriert die drei Hooks |
|---|---|---|
InMemorySnapshotStore | Tests, Dev. | Nein. |
SqliteSnapshotStore | Single-Node-Produktion. | Ja — alle drei, beim Schreiben und beim Lesen, als versiegelte Zeile (unten). |
PostgresSnapshotStore | PostgreSQL-gestützte Produktion. | Ja — alle drei, beim Schreiben und beim Lesen, als versiegelte Zeile (unten). |
MariaDbSnapshotStore | MariaDB / MySQL-gestützte Produktion. | Ja — alle drei, beim Schreiben und beim Lesen, als versiegelte Zeile (unten). |
LibSqlSnapshotStore | libSQL / Turso — entferntes SQLite über HTTP. | Ja — alle drei, beim Schreiben und beim Lesen, als versiegelte Zeile (unten). |
MsSqlSnapshotStore | Microsoft SQL Server-gestützte Produktion. | Ja — alle drei, beim Schreiben und beim Lesen, als versiegelte Zeile (unten). |
MongoSnapshotStore | MongoDB-gestützte Produktion. | Nein. |
DynamoDbSnapshotStore | DynamoDB-gestützte Produktion. | Nein. |
D1SnapshotStore | Cloudflare D1 — SQLite am Edge. | Ja — alle drei, beim Schreiben und beim Lesen, als versiegelte Zeile (unten). |
CassandraSnapshotStore | Verteilt — Cassandra / ScyllaDB. | Nein. |
ObjectStorageSnapshotStore | Filesystem / S3 mit optionaler Verschlüsselung. | Ja — alle drei, beim Schreiben und beim Lesen, für die Snapshots, die er hält. |
CachedSnapshotStore | Wickelt einen anderen Store mit einem Read-Through-Cache ein. | Was der eingewickelte Store deklariert; ein encryption()-Hook umgeht außerdem den Cache — siehe unten. |
Versiegelte Zeilen in den SQL-Stores (#1802). Die sechs
SQL-Snapshot-Stores behalten ihr Schema: Ein Snapshot, der unter einem
der Hooks geschrieben wird, landet in derselben payload-Spalte, als
Frame der Object-Storage-Stores in Base64 hinter einem
ats1:-Präfix — dasselbe AES-256-GCM, dieselbe Schlüsselableitung
pro Persistence-ID, derselbe Master-Key-Ring. Der Frame ist an seine
Persistence-ID und Sequenznummer gebunden, eine unter eine andere
kopierte Zeile lässt sich also nicht entschlüsseln, statt als dieser
Snapshot geladen zu werden. Das Lesen schließt gegen den Hook ab:
Unter encryption() oder integrity() wird eine Zeile verweigert,
die Klartext-JSON ist oder ein Frame ohne Verschlüsselung bzw. ohne
Tag — sie ist entweder älter als der Hook oder wurde von jemandem mit
Zugriff auf die Tabelle geschrieben. Um einen Hook über bestehenden
Snapshots einzuschalten, baust du den Store mit
withAllowPlaintextRows(true), bis der nächste Save sie abgelöst
hat, und nimmst es danach wieder heraus. sse-s3 und sse-kms
bitten einen Object Store, auf seiner Seite zu verschlüsseln, und
werden von einem SQL-Store verweigert.
Ein Nein in dieser Spalte ist durchgesetzt, nicht nur dokumentiert.
encryption() oder integrity() auf einem Actor zu setzen, der von
einem dieser Stores getragen wird, verweigert den Actor beim Start
mit einem UnsupportedPersistenceOptionError, der Store und Feld
benennt — das sind Sicherheitskontrollen, und Klartext zu schreiben,
statt die Lücke zu melden, ist genau der Fehler, den die Verweigerung
verhindern soll. compression() ist ein Performance-Hinweis, also
gibt es eine einzelne Warnung mit dem Store-Namen und der Snapshot
wird unkomprimiert geschrieben. { mode: 'none' } wird überall
akzeptiert: So sagst du “bewusst ungeschützt”.
Ein Store, der gar nichts deklariert — eine Fremdimplementierung aus
der Zeit vor der Deklaration — gilt als unbekannt und wird nie
verweigert, aus derselben Überlegung wie bei storageLocality: Ein
Store darf nicht an einer Vorgabe gemessen werden, die er nicht
gewählt hat.
CachedSnapshotStore ist die eine Zeile, deren Antwort nicht die
ganze Geschichte ist. Er reicht die drei Hooks unverändert an den
eingewickelten Store weiter, die Spalte liest sich also wie dessen —
aber der Cache, den er füllt, hält den dekodierten State. Ein
Actor, der encryption() deklariert, oder ein eingewickelter Store,
der at rest verschlüsselt, wird deshalb am Cache vorbei bedient, mit
einem einmaligen Hinweis, bis
CachedSnapshotStoreOptions.withAllowPlaintextCache(true) bestätigt,
dass der Cache so geschützt ist wie der Store; siehe
Cached-Snapshot-Store — Sicherheit.
Das Journal und der Snapshot Store sind unabhängig; du kannst sie
mischen (z. B. Cassandra-Journal + Object-Storage-Snapshot-Store).
Das Mischen trägt den Schutz des Object-Storage-Stores aber nicht
auf die Events über. encryption() und integrity() an einem
PersistentActor schützen nur seine Snapshots: Jedes Journal
speichert Events als Klartext-JSON, nichts erkennt ein an Ort und
Stelle manipuliertes Event, und datenbankseitige Kontrollen —
Transparent Data Encryption, ein verschlüsseltes Volume,
Zugriffskontrolle — sind heute der einzige Schutz für Events. Kein
Journal wird gefragt, also startet dieser Actor ohne Verweigerung
und ohne Warnung.
Was gespeichert wird
Abschnitt betitelt „Was gespeichert wird“Ein Snapshot ist { persistenceId, sequenceNr, state }. Der Store
behält typischerweise:
- Den neuesten Snapshot pro
persistenceId. - Optional ein paar ältere, falls der neueste korrupt ist (pro Store konfigurierbar).
Wenn der Actor sich wiederherstellt, gibt der Store den neuesten
Snapshot für die persistenceId des Actors zurück. Ältere
Snapshots werden nicht geladen, es sei denn, du fragst explizit
über die Lower-Level-API des Stores.
State wird auf jedem Backend im getaggten JSON-Tree-Format
gespeichert, sodass Date / Map / Set / bigint /
Uint8Array in einem Snapshot als echte Instanzen recovern —
siehe
was Events und State enthalten dürfen.
Aufbewahrung ist Best-Effort, der Schreibvorgang nicht
Abschnitt betitelt „Aufbewahrung ist Best-Effort, der Schreibvorgang nicht“Stores, die die Aufbewahrung begrenzen (keepN), räumen bei jedem
Speichern auf. Dieser Aufräumdurchlauf ist auf jedem Backend
Best-Effort: Sobald der Snapshot selbst dauerhaft ist, ist save
erfolgreich, und ein danach fehlschlagendes Aufräumen wird
geschluckt statt nach oben gereicht.
Die beiden Hälften bedeuten im Fehlerfall Gegensätzliches, weshalb sie nicht gleich gemeldet werden:
- Ein fehlgeschlagener Schreibvorgang heißt, dass dein Snapshot
nicht existiert. Ein erneuter Versuch ist die richtige Reaktion,
und
saveschlägt fehl, damit du das tun kannst. - Ein fehlgeschlagenes Aufräumen heißt, dass eine Zeile zu viel
existiert. Das ist harmlos,
loadLatestsieht sie nicht, und das nächste Speichern versucht es erneut.
Das Zweite wie das Erste zu melden würde einem Aufrufer sagen, er
solle einen bereits erfolgreichen Schreibvorgang wiederholen — und
ein Actor, der einen Snapshot-Fehler als fatal behandelt, würde an
einem Aufräumfehler sterben. Wenn du einen eigenen SnapshotStore
implementierst, führe das Aufräumen außerhalb der Fehlerbehandlung
des Schreibvorgangs aus.
Recovery-Flow mit Snapshots
Abschnitt betitelt „Recovery-Flow mit Snapshots“onEvent ist immer noch rein — gleiche Regel wie ohne Snapshots.
Der Snapshot ist nur der Punkt, wo das Replay startet; alles
danach ist Event-Replay wie üblich.
Snapshot-Adapter — Schema-Evolution
Abschnitt betitelt „Snapshot-Adapter — Schema-Evolution“Wenn sich die State-Form ändert (ein Feld wird umbenannt, ein Wert wird restrukturiert), können alte Snapshots nicht mehr in die neue Form deserialisiert werden. Zwei Optionen:
-
Alte Snapshots löschen — die nächste Recovery spielt von Grund auf ab und baut die neue State-Form aus dem (immer noch aktuellen) Event-Log auf.
-
Einen Snapshot-Adapter verwenden, um alte Snapshots beim Laden hochzukasten:
class V1ToV2SnapshotAdapter implements SnapshotAdapter<StateV2> {manifest(_state: StateV2): string { return 'Account.State'; }toJournal(state: StateV2): OutboundFrame<StateV2> {return { manifest: 'Account.State', version: 2, payload: state };}fromJournal(stored: StoredFrame): StateV2 {if (stored.version === 1) return migrateSnapshot(stored.payload as StateV1);return stored.payload as StateV2;}}class Account extends PersistentActor<...> {override snapshotAdapter() { return new V1ToV2SnapshotAdapter(); }}
Mit einem gesetzten Adapter werden Snapshots in einem
{ _v, _t, _e }-Envelope persistiert; beim Laden migriert der
Adapter ältere Versionen, bevor er den State zurückgibt.
Siehe Migration im Überblick für die breitere Migrationsstrategie (Event-Adapter + Snapshot-Adapter zusammen).
Ohne Snapshots
Abschnitt betitelt „Ohne Snapshots“Ein PersistentActor ohne Snapshot-Policy snappshottet nie — die
Recovery spielt jedes Event vom Anfang der Zeit ab. Für einen
Actor, der insgesamt 10 Events emittiert, ist das in Ordnung; für
einen Event-sourced Cart, der über das Leben eines Users 10 000
Events akkumuliert, ist das ein Recovery-Zeit-Problem.
Das Framework snappshottet nicht automatisch. Wenn du keine Policy
setzt, bekommst du keine Snapshots — snapshotPolicy() defaultet
auf () => false.
Häufige Stolperfallen
Abschnitt betitelt „Häufige Stolperfallen“Wie geht’s weiter
Abschnitt betitelt „Wie geht’s weiter“- PersistentActor —
die Basisklasse, deren
snapshotPolicy()du überschreibst. - Snapshot Stores — In-Memory — der Dev/Test-Store.
- Snapshot Stores — SQLite — Single-Node-Produktion.
- Snapshot Stores — Cached — Read-Through-Cache über einem anderen Store.
- Migration im Überblick — State + Event-Schema-Evolution.
Die SnapshotStore- und
SnapshotPolicy-API-Referenzen
decken die vollständige Oberfläche ab.
