跳转到内容
简体中文

Snapshot store backend

此内容尚不支持你的语言。

ObjectStorageSnapshotStore is the snapshot-store implementation that uses object storage as its backing layer.

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 written by every PersistentActor go to the S3 bucket; compressed + encrypted per the config.

Three patterns:

  1. Cluster-wide shared snapshots — sharded entities that move between nodes need any node to be able to load any entity’s snapshot. Object storage works; SQLite per-node doesn’t.
  2. Encrypted snapshots — server-side and/or client-side encryption at rest required for compliance.
  3. Cheap snapshot storage — object storage is far cheaper per GB than SQL stores for read-rarely-rewrite-occasionally data.

For single-node deployments, SqliteSnapshotStore is faster + simpler.

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
};
FieldPurpose
backendFilesystem or S3 backend.
prefixObject-key prefix. Useful for sharing buckets.
keepNSnapshots retained per persistenceId; older ones are pruned on save. Default 3.
compressionAt-rest compression — see Compression.
encryptionAt-rest encryption — see Encryption.
integrityHMAC-SHA256 tag over each snapshot body — signs writes and requires a tag on reads. See Body integrity.
allowUntaggedBodiesAccept untagged snapshots while integrity is set — the migration window for a bucket written before integrity. Default false.
requireContextBindingRefuse snapshots not bound to the key they were read from — closes replay onto another persistenceId or sequence number. Turn on once the bucket is rewritten. See Binding a body to its key. Default false.
maxDecompressedBytesDecompression-bomb guard — cap on a decoded snapshot’s size. Default 512 MiB.

Constructing the store by hand, as above, is one of two routes. The other is registerObjectStoragePlugins, which builds this store and the durable-state store over one shared backend and can take every field from HOCON:

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.

The plug-in runs inside ActorSystem.create, and the startup waits for the promise it returns, so a codec probe that fails fails the startup rather than the first snapshot — see opening the stores at startup.

prefix, keepN, compression, encryption and maxDecompressedBytes map one-to-one onto the leaves of that block; explicit ObjectStoragePluginOptions still win field by field. Two fields in the table above are deliberately absent from HOCON: allowUntaggedBodies and requireContextBinding do nothing without an integrity or client-side encryption config, and neither of those can come from a config file, because both need a 32-byte key. A knob that could never do anything from HOCON is worse than no knob, so it is not published there — set them in code alongside the key that makes them meaningful. See Configuration reference.

<prefix>snapshots/<persistenceId>/<seqNr padded to 20 digits>.json

Examples, with prefix: 'acme/':

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

Three segments, each doing one job.

  • <prefix> is yours — a deployment, an environment, a tenant. It is what a body is bound to along with the rest of the key, so staging state cannot be replayed into production.
  • snapshots/ is the namespace this store owns. ObjectStorageDurableStateStore owns state/ and writes <prefix>state/<persistenceId>/state.json. The two stores are handed the same prefix by registerObjectStoragePlugins, and the namespace is what keeps their corpora from sharing a directory — see Two stores, one prefix.
  • <persistenceId>/ is the per-entity directory that bounds every LIST.

The framework lists keys under <prefix>snapshots/<persistenceId>/ to find the latest snapshot. The listing is ascending by key and carries no limit: the zero-padded sequence number makes the last entry the newest one, so a limit: 1 would hand back the oldest instead.

What the store takes from that listing is the last entry shaped like one of its own snapshots — this entity’s directory, then exactly twenty digits and .json. Prefix membership is not evidence of ownership: a bucket can have a second writer, and a marker file or a half-finished migration under the same prefix used to be read as a snapshot, deleted by delete, and counted towards keepN at the cost of a real snapshot. A body that names a different persistenceId is not returned either; the store reports no snapshot, and recovery replays the journal.

For very-large persistenceId spaces, listing per-pid is typically fast in S3 (per-prefix throughput). Avoid putting all entity types under the same prefix without per-pid subdirectories — that directory segment is the only thing bounding what a load has to enumerate.

registerObjectStoragePlugins wires the snapshot store and the durable-state store onto one backend with one prefix, on purpose. Their key namespaces are disjoint anyway:

acme/snapshots/account-42/00000000000000000300.json snapshot
acme/state/account-42/state.json durable state

Without the namespaces both landed in acme/account-42/, and state.json sorts after every zero-padded sequence key — so an entity persisted both ways had its durable-state record returned as its newest snapshot. That body carries no sequenceNr, so recovery rejected it and the actor could not start. No invalid persistenceId was needed: one call to wire the plugin up, and one entity used both ways.

That collision is closed twice over, and the namespaces are the second of the two. The leaf-shape filter above already rejects state.json on its own — a leaf this store reads is exactly twenty digits and .json, and state.json is ten characters — so a shared directory would no longer produce the wrong answer. What the namespaces add is a corpus that is disjoint by prefix, which is what lets lifecycle rules, backup selections and a re-encryption sweep be scoped to one store’s objects in terms your bucket can evaluate, rather than in terms of a filename failing a length check inside the framework.

What neither the split nor the filter gives is a check on which entity a body belongs to once it sits at a well-formed key of this store’s own — and there the two stores differ. ObjectStorageSnapshotStore compares the persistenceId its body carries against the one asked for, which is the “a body that names a different persistenceId” sentence above. ObjectStorageDurableStateStore has no such field to compare: its body is { revision, state, timestamp }, so a record that ends up under another entity’s key loads as that entity’s state. Move detection on that side comes from binding the body to its storage key, which is what configuring client-aes256-gcm or hmac-sha256 buys; a store with neither authenticator has none. See What encryption does not cover.

Snapshot writes go through object-storage’s PUT; reads through GET. Numbers for S3 same-region:

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

That LIST is what the per-persistenceId directory in the key buys. Both shipped backends scope it to <prefix>snapshots/<persistenceId>/ — S3 through Prefix / MaxKeys, the filesystem backend by reading only that directory — so a load costs one entity’s own snapshots and stays flat as the number of entities grows. keepN pruning issues the same LIST after every save, so a backend that did not scope it would put that growth on the write path too.

For hot-path snapshot loading (frequent actor restarts), wrap with CachedSnapshotStore:

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

Reduces redundant S3 GETs to sub-microsecond cache hits.

If the snapshots are encrypted, read Security — the cache holds plaintext before wiring this up. What the cache holds is the decoded state, so the composition puts a plaintext copy of every recently active entity in the cache while the bucket stays encrypted. This store declares its own encryption config through encryptsAtRest(persistenceId), so the decorator refuses to cache those loads — whether the encryption is configured here with withEncryption(...) or per call by an actor’s encryption() hook — until withAllowPlaintextCache(true) says the cache is as protected as the 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 configuration applies to snapshots the same way as durable state — and to nothing else. encryption() and integrity() on a PersistentActor protect its snapshots only: every journal stores events as plaintext JSON, nothing detects an event edited in place, and database-side controls — transparent data encryption, an encrypted volume, access control — are the only protection for events today. See Per-actor policies.

PersistentActor.persist(event) succeeds
↓ check snapshotPolicy()
↓ if true → take snapshot
backend.put('<prefix>snapshots/<pid>/<seq>.json', serialized state)
PersistentActor.preStart
↓ list '<prefix>snapshots/<pid>/' — that directory only, ascending
↓ last well-formed key = latest seq
↓ backend.get(latest) → decode → onEvent from seq+1 onwards

The framework handles snapshot saves + loads via this layout; you set the policy.

const objectStorageSnapshotStoreOptions = ObjectStorageSnapshotStoreOptions.create()
.withBackend(backend)
.withKeepN(5);
new ObjectStorageSnapshotStore(objectStorageSnapshotStoreOptions); // keep 5 most recent; delete older

Pruning is on by default: keepN defaults to 3, so each save retains only the most-recent snapshots per persistenceId and deletes the older ones. Raise or lower the bound with withKeepN; set keepN: 0 to disable pruning and keep every snapshot.

The framework doesn’t auto-delete during reads — there’s a small window where old snapshots co-exist with new ones.

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

The journal and snapshot store are independent. Common patterns:

  • SQLite journal + ObjectStorage snapshots — local event-rate, shared snapshots for sharded entities.
  • Cassandra journal + ObjectStorage snapshots — both shared across the cluster.
  • ObjectStorage everything — when S3 is your only storage. Slower per-op but cheap.