Zum Inhalt springen
Deutsch

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.

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.

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, zu DurableStateActor zu 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.

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:

StoreWannHonoriert die drei Hooks
InMemorySnapshotStoreTests, Dev.Nein.
SqliteSnapshotStoreSingle-Node-Produktion.Ja — alle drei, beim Schreiben und beim Lesen, als versiegelte Zeile (unten).
PostgresSnapshotStorePostgreSQL-gestützte Produktion.Ja — alle drei, beim Schreiben und beim Lesen, als versiegelte Zeile (unten).
MariaDbSnapshotStoreMariaDB / MySQL-gestützte Produktion.Ja — alle drei, beim Schreiben und beim Lesen, als versiegelte Zeile (unten).
LibSqlSnapshotStorelibSQL / Turso — entferntes SQLite über HTTP.Ja — alle drei, beim Schreiben und beim Lesen, als versiegelte Zeile (unten).
MsSqlSnapshotStoreMicrosoft SQL Server-gestützte Produktion.Ja — alle drei, beim Schreiben und beim Lesen, als versiegelte Zeile (unten).
MongoSnapshotStoreMongoDB-gestützte Produktion.Nein.
DynamoDbSnapshotStoreDynamoDB-gestützte Produktion.Nein.
D1SnapshotStoreCloudflare D1 — SQLite am Edge.Ja — alle drei, beim Schreiben und beim Lesen, als versiegelte Zeile (unten).
CassandraSnapshotStoreVerteilt — Cassandra / ScyllaDB.Nein.
ObjectStorageSnapshotStoreFilesystem / S3 mit optionaler Verschlüsselung.Ja — alle drei, beim Schreiben und beim Lesen, für die Snapshots, die er hält.
CachedSnapshotStoreWickelt 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.

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 save schlägt fehl, damit du das tun kannst.
  • Ein fehlgeschlagenes Aufräumen heißt, dass eine Zeile zu viel existiert. Das ist harmlos, loadLatest sieht 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.

ja — bei seqNr=500

nein

preStart

neuesten Snapshot laden
für persistenceId

gefunden?

state = snapshot.state
seq = 500

state = initialState
seq = 0

Events aus dem Journal lesen
ab seq+1

für jedes Event:
state = onEvent(state, event)
seq++

onRecoveryComplete(state)

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.

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:

  1. 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.

  2. 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).

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.

Die SnapshotStore- und SnapshotPolicy-API-Referenzen decken die vollständige Oberfläche ab.