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.
Wann verwenden
Abschnitt betitelt „Wann verwenden“Drei Muster:
- 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.
- Verschlüsselte Snapshots — Server-Side- und/oder Client-Side-Verschlüsselung at rest für Compliance erforderlich.
- 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.
Konfiguration
Abschnitt betitelt „Konfiguration“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};| Feld | Zweck |
|---|---|
backend | Filesystem- oder S3-Backend. |
prefix | Object-Key-Prefix. Nützlich, um Buckets zu teilen. |
keepN | Pro persistenceId behaltene Snapshots; ältere werden beim Save entfernt. Default 3. |
compression | At-Rest-Kompression — siehe Kompression. |
encryption | At-Rest-Verschlüsselung — siehe Verschlüsselung. |
integrity | HMAC-SHA256-Tag über jeden Snapshot-Body — signiert Writes und verlangt beim Lesen ein Tag. Siehe Body-Integrität. |
allowUntaggedBodies | Snapshots ohne Tag akzeptieren, solange integrity gesetzt ist — das Migrationsfenster für einen Bucket von vor der Integrität. Default false. |
requireContextBinding | Snapshots 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. |
maxDecompressedBytes | Schutz vor Dekompressions-Bomben — Obergrenze für die Größe eines dekodierten Snapshots. Default 512 MiB. |
Aus der Konfiguration
Abschnitt betitelt „Aus der Konfiguration“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.
Key-Layout
Abschnitt betitelt „Key-Layout“<prefix>snapshots/<persistenceId>/<seqNr auf 20 Stellen gepolstert>.jsonBeispiele, mit prefix: 'acme/':
acme/snapshots/account-42/00000000000000000100.jsonacme/snapshots/account-42/00000000000000000200.jsonacme/snapshots/account-42/00000000000000000300.jsonDrei 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.ObjectStorageDurableStateStorebesitztstate/und schreibt<prefix>state/<persistenceId>/state.json. Beide Stores bekommen vonregisterObjectStoragePluginsdenselben 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.
Zwei Stores, ein Prefix
Abschnitt betitelt „Zwei Stores, ein Prefix“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 Snapshotacme/state/account-42/state.json Durable StateOhne 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.
Performance
Abschnitt betitelt „Performance“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.
Per-Actor-Overrides
Abschnitt betitelt „Per-Actor-Overrides“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.
Snapshot-Lifecycle
Abschnitt betitelt „Snapshot-Lifecycle“PersistentActor.persist(event) gelingt ↓ snapshotPolicy() prüfen ↓ wenn true → Snapshot machenbackend.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+1Das Framework handhabt Snapshot-Saves + -Loads über dieses Layout; du setzt die Policy.
Cleanup alter Snapshots
Abschnitt betitelt „Cleanup alter Snapshots“const objectStorageSnapshotStoreOptions = ObjectStorageSnapshotStoreOptions.create() .withBackend(backend) .withKeepN(5);new ObjectStorageSnapshotStore(objectStorageSnapshotStoreOptions); // die 5 neuesten behalten; ältere löschenPruning 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.
Mischen mit dem Journal
Abschnitt betitelt „Mischen mit dem Journal“{ 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.
Wie geht’s weiter
Abschnitt betitelt „Wie geht’s weiter“- Object Storage im Überblick — das größere Bild.
- Snapshot Stores im Überblick — allgemeine Snapshot-Policy.
- CachedSnapshotStore — Read-Through-Cache.
- Per-Actor-Policies — Per-Actor-Kompression / -Verschlüsselung.
