Zum Inhalt springen
Deutsch

Snapshot-Store-Backend

ObjectStorageSnapshotStore ist die Snapshot-Store- Implementierung, die Object Storage als Backing-Schicht verwendet.

import {
ActorSystem,
ActorSystemOptions,
} from 'actor-ts';
import {
ObjectStorageSnapshotStore,
ObjectStorageSnapshotStoreOptions,
S3ObjectStorageBackend,
S3ObjectStorageOptions,
} from 'actor-ts/persistence';
const s3ObjectStorageOptions = S3ObjectStorageOptions.create()
.withRegion(region)
.withBucket(bucket);
const objectStorageSnapshotStoreOptions = ObjectStorageSnapshotStoreOptions.create()
.withBackend(new S3ObjectStorageBackend(s3ObjectStorageOptions))
.withCompression({ algorithm: 'gzip' })
.withEncryption(encryption);
const snapshotStore = new ObjectStorageSnapshotStore(objectStorageSnapshotStoreOptions);
const systemOptions = ActorSystemOptions.create().withPersistence({
journal: someJournal,
snapshotStore,
});
const system = ActorSystem.create('my-app', systemOptions);

Snapshots, die von jedem PersistentActor geschrieben werden, gehen in den S3-Bucket; komprimiert + verschlüsselt gemäß der Config.

Drei Muster:

  1. Cluster-weit geteilte Snapshots — Sharded Entities, die zwischen Nodes wandern, brauchen, dass jeder Node den Snapshot jeder Entity laden kann. Object Storage funktioniert; SQLite pro Node nicht.
  2. Verschlüsselte Snapshots — Server-Side- und/oder Client-Side-Verschlüsselung at rest für Compliance erforderlich.
  3. Günstiger Snapshot-Storage — Object Storage ist pro GB viel günstiger als SQL-Stores für selten-gelesene-gelegentlich-überschriebene Daten.

Für Single-Node-Deployments ist SqliteSnapshotStore schneller + einfacher.

type ObjectStorageSnapshotStoreOptionsType = {
backend: ObjectStorageBackend;
prefix?: string; // Default ''
keepN?: number; // Default 3
compression?: CompressionConfig | CompressionResolver;
encryption?: EncryptionConfig | EncryptionResolver;
integrity?: IntegrityConfig | IntegrityResolver;
allowUntaggedBodies?: boolean; // Default false
requireContextBinding?: boolean; // Default false
maxDecompressedBytes?: number; // Default 512 MiB
};
FeldZweck
backendFilesystem- oder S3-Backend.
prefixObject-Key-Prefix. Nützlich, um Buckets zu teilen.
keepNPro persistenceId behaltene Snapshots; ältere werden beim Save entfernt. Default 3.
compressionAt-Rest-Kompression — siehe Kompression.
encryptionAt-Rest-Verschlüsselung — siehe Verschlüsselung.
integrityHMAC-SHA256-Tag über jeden Snapshot-Body — signiert Writes und verlangt beim Lesen ein Tag. Siehe Body-Integrität.
allowUntaggedBodiesSnapshots ohne Tag akzeptieren, solange integrity gesetzt ist — das Migrationsfenster für einen Bucket von vor der Integrität. Default false.
requireContextBindingSnapshots ablehnen, die nicht an den Key gebunden sind, von dem sie gelesen wurden — schließt das Einspielen auf eine andere persistenceId oder Sequenznummer. Erst einschalten, wenn der Bucket neu geschrieben ist. Siehe Einen Body an seinen Key binden. Default false.
maxDecompressedBytesSchutz vor Dekompressions-Bomben — Obergrenze für die Größe eines dekodierten Snapshots. Default 512 MiB.

Den Store wie oben von Hand zu bauen ist einer von zwei Wegen. Der andere ist registerObjectStoragePlugins: Es baut diesen Store und den Durable-State-Store über ein gemeinsames Backend und kann jedes Feld aus HOCON nehmen:

actor-ts.persistence.snapshot-store {
plugin = "actor-ts.persistence.snapshot-store.object-storage"
object-storage {
backend = "s3"
prefix = "snapshots/"
keep-n = 5
s3 {
bucket = "my-app-state"
region = "eu-central-1"
}
}
}
import { ActorSystem, ActorSystemOptions } from 'actor-ts';
import { registerObjectStoragePlugins, type ObjectStoragePluginHandles } from 'actor-ts/persistence';
let objectStorage: ObjectStoragePluginHandles | undefined;
const systemOptions = ActorSystemOptions.create().withPersistence({
plugins: [async (persistence) => {
objectStorage = await registerObjectStoragePlugins(persistence);
}],
});
const system = ActorSystem.create('my-app', systemOptions);
await system.whenReady();
// The system's snapshot store is now the configured ObjectStorageSnapshotStore;
// objectStorage.close() releases its backend once the system has terminated.

Das Plug-in läuft innerhalb von ActorSystem.create, und der Start wartet auf das Promise, das es zurückgibt, also lässt eine scheiternde Codec-Prüfung den Start scheitern statt erst den ersten Snapshot — siehe Stores beim Start öffnen.

prefix, keepN, compression, encryption und maxDecompressedBytes bilden eins zu eins auf die Blätter dieses Blocks ab; explizite ObjectStoragePluginOptions gewinnen weiterhin Feld für Feld. Zwei Felder aus der Tabelle oben fehlen in HOCON mit Absicht: allowUntaggedBodies und requireContextBinding tun ohne eine integrity- oder clientseitige encryption-Konfiguration nichts, und beide können nicht aus einer Config-Datei kommen, weil sie einen 32-Byte-Schlüssel brauchen. Ein Schalter, der aus HOCON nie etwas bewirken könnte, ist schlechter als gar keiner — deshalb wird er dort nicht veröffentlicht; setze ihn im Code, zusammen mit dem Schlüssel, der ihn sinnvoll macht. Siehe Konfigurationsreferenz.

<prefix>snapshots/<persistenceId>/<seqNr auf 20 Stellen gepolstert>.json

Beispiele, mit prefix: 'acme/':

acme/snapshots/account-42/00000000000000000100.json
acme/snapshots/account-42/00000000000000000200.json
acme/snapshots/account-42/00000000000000000300.json

Drei Segmente, jedes mit genau einer Aufgabe.

  • <prefix> gehört dir — ein Deployment, eine Umgebung, ein Mandant. Er ist Teil dessen, woran ein Body gebunden wird, also lässt sich Staging-State nicht in die Produktion einspielen.
  • snapshots/ ist der Namespace, der diesem Store gehört. ObjectStorageDurableStateStore besitzt state/ und schreibt <prefix>state/<persistenceId>/state.json. Beide Stores bekommen von registerObjectStoragePlugins denselben Prefix, und der Namespace ist das, was ihre Korpora davon abhält, sich ein Verzeichnis zu teilen — siehe Zwei Stores, ein Prefix.
  • <persistenceId>/ ist das Verzeichnis pro Entity, das jedes LIST begrenzt.

Das Framework listet Keys unter <prefix>snapshots/<persistenceId>/, um den neuesten Snapshot zu finden. Die Auflistung ist aufsteigend nach Key und trägt kein Limit: die nullgepolsterte Sequenznummer macht den letzten Eintrag zum neuesten, ein limit: 1 lieferte also den ältesten.

Was der Store aus dieser Auflistung nimmt, ist der letzte Eintrag, der wie einer seiner eigenen Snapshots geformt ist — das Verzeichnis dieser Entity, dann exakt zwanzig Ziffern und .json. Prefix-Zugehörigkeit ist kein Beleg für Eigentum: ein Bucket kann einen zweiten Schreiber haben, und eine Marker-Datei oder eine halb fertige Migration unter demselben Prefix wurde früher als Snapshot gelesen, von delete gelöscht und auf keepN angerechnet — auf Kosten eines echten Snapshots. Ein Body, der eine andere persistenceId nennt, wird ebenfalls nicht zurückgegeben; der Store meldet dann keinen Snapshot, und die Recovery spielt das Journal ab.

Für sehr große persistenceId-Räume ist das Listen pro pid in S3 typischerweise schnell (Per-Prefix-Durchsatz). Vermeide es, alle Entity-Typen unter denselben Prefix ohne Per-pid-Unterordner zu packen — dieses Verzeichnis-Segment ist das Einzige, was begrenzt, was ein Load aufzählen muss.

registerObjectStoragePlugins verdrahtet den Snapshot-Store und den Durable-State-Store absichtlich auf ein Backend mit einem Prefix. Ihre Key-Namespaces sind trotzdem disjunkt:

acme/snapshots/account-42/00000000000000000300.json Snapshot
acme/state/account-42/state.json Durable State

Ohne die Namespaces landeten beide in acme/account-42/, und state.json sortiert hinter jede nullgepolsterte Sequenznummer — eine Entity, die auf beide Arten persistiert wurde, bekam also ihren Durable-State-Record als ihren neuesten Snapshot zurück. Dieser Body trägt keine sequenceNr, die Recovery lehnte ihn ab, und der Actor konnte nicht starten. Dafür war keine ungültige persistenceId nötig: ein Aufruf, der das Plugin verdrahtet, und eine Entity, die beide Wege nutzt.

Diese Kollision ist doppelt geschlossen, und die Namespaces sind davon die zweite Hälfte. Der oben beschriebene Leaf-Form-Filter lehnt state.json bereits für sich allein ab — ein Leaf, das dieser Store liest, besteht aus exakt zwanzig Ziffern und .json, und state.json hat zehn Zeichen — ein gemeinsames Verzeichnis lieferte also ohnehin nicht mehr die falsche Antwort. Was die Namespaces hinzufügen, ist ein Korpus, der pro Prefix disjunkt ist: erst das erlaubt es, Lifecycle-Regeln, Backup-Auswahlen und einen Re-Encryption-Sweep auf die Objekte eines Stores zu begrenzen, und zwar in Begriffen, die dein Bucket auswerten kann — statt in Begriffen eines Dateinamens, der innerhalb des Frameworks eine Längenprüfung nicht besteht.

Was weder die Aufteilung noch der Filter liefert, ist eine Prüfung, welcher Entity ein Body gehört, sobald er an einem wohlgeformten Key dieses Stores liegt — und da unterscheiden sich die beiden. ObjectStorageSnapshotStore vergleicht die persistenceId, die sein Body trägt, mit der, nach der gefragt wurde; das ist der Satz weiter oben über einen Body, der eine andere persistenceId nennt. ObjectStorageDurableStateStore hat kein solches Feld zum Vergleichen: Sein Body ist { revision, state, timestamp }, ein Datensatz am Key einer anderen Entity lädt also als deren State. Die Verschiebungserkennung kommt auf dieser Seite daher, dass der Body an seinen Storage-Key gebunden wird — und das erkauft man sich, indem man client-aes256-gcm oder hmac-sha256 konfiguriert. Ein Store ohne einen der beiden Authentifikatoren hat keine. Siehe Was Verschlüsselung nicht abdeckt.

Snapshot-Writes gehen durch das PUT von Object Storage; Reads durch GET. Zahlen für S3 Same-Region:

  • Save — 20-50 ms pro Snapshot.
  • Load latest — 1 LIST + 1 GET = 30-60 ms.

Dieses LIST ist das, was das Verzeichnis pro persistenceId im Key einbringt. Beide mitgelieferten Backends schränken es auf <prefix>snapshots/<persistenceId>/ ein — S3 über Prefix / MaxKeys, das Filesystem-Backend, indem es nur dieses Verzeichnis liest —, sodass ein Load die Snapshots genau einer Entity kostet und flach bleibt, während die Zahl der Entities wächst. Das keepN-Pruning setzt dasselbe LIST nach jedem Save ab; ein Backend ohne diese Einschränkung legte das Wachstum also auch auf den Schreibpfad.

Für Hot-Path-Snapshot-Laden (häufige Actor-Neustarts) wickle es mit CachedSnapshotStore ein:

const objectStorageSnapshotStoreOptions = ObjectStorageSnapshotStoreOptions.create().withBackend(backend);
const cachedSnapshotStoreOptions = CachedSnapshotStoreOptions.create().withCache(cache);
const cached = new CachedSnapshotStore(
new ObjectStorageSnapshotStore(objectStorageSnapshotStoreOptions),
cachedSnapshotStoreOptions,
);

Reduziert redundante S3-GETs auf Sub-Mikrosekunden-Cache-Hits.

Sind die Snapshots verschlüsselt, lies Sicherheit — der Cache hält Klartext, bevor du das verdrahtest. Der Cache hält den dekodierten State — die Komposition legt also eine Klartext-Kopie jeder kürzlich aktiven Entity in den Cache, während der Bucket verschlüsselt bleibt. Dieser Store meldet seine eigene encryption-Konfiguration über encryptsAtRest(persistenceId), deshalb verweigert der Decorator das Cachen solcher Loads — ob die Verschlüsselung hier mit withEncryption(...) konfiguriert ist oder pro Call über den encryption()-Hook eines Actors — bis withAllowPlaintextCache(true) sagt, dass der Cache so geschützt ist wie der Bucket.

class Account extends PersistentActor<...> {
override compression() { return { algorithm: 'zstd' as const }; }
override encryption() {
return {
mode: 'client-aes256-gcm' as const,
masterKeys: accountKeyRing,
info: 'acme/prod/snapshot/v1',
};
}
}

Per-Actor-Konfiguration gilt für Snapshots auf dieselbe Weise wie für Durable State — und für nichts sonst. 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. Siehe Per-Actor-Policies.

PersistentActor.persist(event) gelingt
↓ snapshotPolicy() prüfen
↓ wenn true → Snapshot machen
backend.put('<prefix>snapshots/<pid>/<seq>.json', serialisierter State)
PersistentActor.preStart
↓ '<prefix>snapshots/<pid>/' auflisten — nur dieses Verzeichnis, aufsteigend
↓ letzter wohlgeformter Key = neueste seq
↓ backend.get(latest) → dekodieren → onEvent ab seq+1

Das Framework handhabt Snapshot-Saves + -Loads über dieses Layout; du setzt die Policy.

const objectStorageSnapshotStoreOptions = ObjectStorageSnapshotStoreOptions.create()
.withBackend(backend)
.withKeepN(5);
new ObjectStorageSnapshotStore(objectStorageSnapshotStoreOptions); // die 5 neuesten behalten; ältere löschen

Pruning ist standardmäßig aktiv: keepN ist per Default 3, sodass jeder Save nur die neuesten Snapshots pro persistenceId behält und die älteren löscht. Erhöhe oder senke die Grenze mit withKeepN; setze keepN: 0, um Pruning zu deaktivieren und jeden Snapshot zu behalten.

Das Framework löscht beim Lesen nicht automatisch — es gibt ein kleines Fenster, in dem alte Snapshots mit neuen koexistieren.

{
const sqliteJournalOptions = SqliteJournalOptions.create().withPath('...');
const objectStorageSnapshotStoreOptions = ObjectStorageSnapshotStoreOptions.create().withBackend(backend);
journal: new SqliteJournal(sqliteJournalOptions),
snapshotStore: new ObjectStorageSnapshotStore(objectStorageSnapshotStoreOptions),
}

Das Journal und der Snapshot-Store sind unabhängig. Häufige Muster:

  • SQLite-Journal + ObjectStorage-Snapshots — lokale Event-Rate, geteilte Snapshots für Sharded Entities.
  • Cassandra-Journal + ObjectStorage-Snapshots — beide über den Cluster geteilt.
  • ObjectStorage alles — wenn S3 dein einziger Storage ist. Langsamer pro Op, aber billig.