Snapshot store backend
Esta página aún no está disponible en tu idioma.
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.
When to use it
Section titled “When to use it”Three patterns:
- 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.
- Encrypted snapshots — server-side and/or client-side encryption at rest required for compliance.
- 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.
Configuration
Section titled “Configuration”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};| Field | Purpose |
|---|---|
backend | Filesystem or S3 backend. |
prefix | Object-key prefix. Useful for sharing buckets. |
keepN | Snapshots retained per persistenceId; older ones are pruned on save. Default 3. |
compression | At-rest compression — see Compression. |
encryption | At-rest encryption — see Encryption. |
integrity | HMAC-SHA256 tag over each snapshot body — signs writes and requires a tag on reads. See Body integrity. |
allowUntaggedBodies | Accept untagged snapshots while integrity is set — the migration window for a bucket written before integrity. Default false. |
requireContextBinding | Refuse 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. |
maxDecompressedBytes | Decompression-bomb guard — cap on a decoded snapshot’s size. Default 512 MiB. |
From configuration
Section titled “From configuration”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.
Key layout
Section titled “Key layout”<prefix>snapshots/<persistenceId>/<seqNr padded to 20 digits>.jsonExamples, with prefix: 'acme/':
acme/snapshots/account-42/00000000000000000100.jsonacme/snapshots/account-42/00000000000000000200.jsonacme/snapshots/account-42/00000000000000000300.jsonThree 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.ObjectStorageDurableStateStoreownsstate/and writes<prefix>state/<persistenceId>/state.json. The two stores are handed the same prefix byregisterObjectStoragePlugins, 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.
Two stores, one prefix
Section titled “Two stores, one prefix”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 snapshotacme/state/account-42/state.json durable stateWithout 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.
Performance
Section titled “Performance”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.
Per-actor overrides
Section titled “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 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.
Snapshot lifecycle
Section titled “Snapshot lifecycle”PersistentActor.persist(event) succeeds ↓ check snapshotPolicy() ↓ if true → take snapshotbackend.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 onwardsThe framework handles snapshot saves + loads via this layout; you set the policy.
Cleanup of old snapshots
Section titled “Cleanup of old snapshots”const objectStorageSnapshotStoreOptions = ObjectStorageSnapshotStoreOptions.create() .withBackend(backend) .withKeepN(5);new ObjectStorageSnapshotStore(objectStorageSnapshotStoreOptions); // keep 5 most recent; delete olderPruning 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.
Mixing with the journal
Section titled “Mixing with the journal”{ 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.
Where to next
Section titled “Where to next”- Object storage overview — the bigger picture.
- Snapshot stores overview — general snapshot policy.
- CachedSnapshotStore — read-through cache.
- Per-actor policies — per-actor compression / encryption.
