Cached snapshot store
此内容尚不支持你的语言。
CachedSnapshotStore is a decorator — wrap any
SnapshotStore to add a TTL-based read-through cache for
loadLatest, backed by any Cache (in-memory, Redis, or
Memcached).
import { ActorSystem, ActorSystemOptions,} from 'actor-ts';import { CachedSnapshotStore, CachedSnapshotStoreOptions, ObjectStorageSnapshotStore, ObjectStorageSnapshotStoreOptions,} from 'actor-ts/persistence';
const objectStorageSnapshotStoreOptions = ObjectStorageSnapshotStoreOptions.create().withBackend(backend);const underlying = new ObjectStorageSnapshotStore( objectStorageSnapshotStoreOptions, // S3 / filesystem backend);
const cachedSnapshotStoreOptions = CachedSnapshotStoreOptions.create() .withCache(cache) // backing cache (typically Redis) .withTtlMs(60_000);const cached = new CachedSnapshotStore( underlying, cachedSnapshotStoreOptions, // optional TTL);
const actorSystemOptions = ActorSystemOptions.create().withPersistence({ journal: myJournal, snapshotStore: cached,});const system = ActorSystem.create('app', actorSystemOptions);When you need it
Section titled “When you need it”Three patterns:
- Slow underlying store — object storage with multi-hop network latency, encrypted state with expensive decryption. For the encrypted case read Security — the cache holds plaintext first: it is the strongest reason to reach for the cache and the one that needs a decision.
- Frequent actor churn — sharded entities passivating / re-spawning constantly, each load re-reading the same snapshot.
- Recovery storms — full-cluster restart, every actor loads its snapshot at once. Cache reduces redundant loads when the same snapshot is queried during the storm.
For local SQLite-backed snapshots (sub-millisecond reads), the cache adds overhead with no benefit. Use it only when the underlying store has measurable read latency.
Configuration
Section titled “Configuration”type CachedSnapshotStoreOptionsType = { cache: Cache; // backing cache (required) ttlMs?: number; // cache TTL in ms, default 5 minutes keyPrefix?: string; // key prefix, default 'snap:' allowPlaintextCache?: boolean; // cache encrypted state anyway, default false};| Field | What |
|---|---|
cache | Backing cache (required) — typically Redis in production. Any Cache: in-memory, Redis, or Memcached. |
ttlMs | Cache TTL in milliseconds. Default: 5 minutes. |
keyPrefix | Key prefix (default 'snap:') — prevents collisions in shared caches. |
allowPlaintextCache | Acknowledge that the cache may hold the plaintext of state the wrapped store encrypts at rest, and cache it anyway. Default false — see below. |
The underlying store is the constructor’s first argument —
new CachedSnapshotStore(underlying, options) — not an option.
Security — the cache holds plaintext
Section titled “Security — the cache holds plaintext”What gets cached is whatever loadLatest returns, and that is the
decoded domain state: decompressed, and for the object-storage
stores decrypted. Compose this decorator with
client-side snapshot encryption
and the deployment holds two copies of the state — one encrypted in
the bucket, one in plaintext in a cache you own, share with other
subsystems, and often run unauthenticated on a “private” network.
Reading the second copy needs neither the bucket nor the master key,
and a Redis RDB dump keeps it readable afterwards.
Nothing at rest in the bucket is weakened by this; the second copy is the whole exposure. That makes it a composition hazard rather than a flaw in either piece — and the composition is one this page recommends, which is why it is spelled out here.
So a loadLatest whose state the wrapped store keeps encrypted at
rest is served straight from the wrapped store, uncached, and
the decorator warns once. It also evicts whatever the cache
already holds under that persistenceId: an entry cached before the
actor gained its encryption() hook, or before the store was
configured to encrypt, would otherwise stay readable in plaintext
until the next save or the end of ttlMs. The price is one cache
round-trip per refused load — every refused load, not only the one
that warns — on a path that already pays the wrapped store’s full
read. Both routes to the refusal count — a per-call encryption
directive with a mode other than 'none', and the store’s own
withEncryption(...), which never appears in any call’s options:
persistence: CachedSnapshotStore caches decoded snapshot state, and on'ObjectStorageSnapshotStore' this loadLatest asked for encryption — …
persistence: CachedSnapshotStore caches decoded snapshot state, and on'ObjectStorageSnapshotStore' the store's own configuration keeps thispersistenceId encrypted — …withAllowPlaintextCache(true) is your acknowledgement that the
cache is as protected as the bucket, and restores the caching:
const cachedSnapshotStoreOptions = CachedSnapshotStoreOptions.create() .withCache(cache) .withTtlMs(60_000) .withAllowPlaintextCache(true);Reasonable answers to the question it asks:
- In-process
InMemoryCache— the plaintext never leaves the node that already decrypted it. Set the flag. - Redis or Memcached inside the same trust boundary, with authentication, encryption in transit and no persistence to disk — set the flag, and record the reasoning where your other key-management decisions live.
- A shared cache that also backs HTTP middleware, or one whose operators are not the operators of the bucket — do not set the flag. Give the encrypted store its own cache, or accept the cold-start cost.
What the check sees, and what it does not
Section titled “What the check sees, and what it does not”It sees both routes a deployment can take to confidentiality: the
per-call PersistenceOptions your actor’s encryption() hook
produces, and the wrapped store’s own configuration, which it
reads through the optional encryptsAtRest(persistenceId) member of
SnapshotStore. ObjectStorageSnapshotStore implements that from
the same encryption config its codec uses, per persistenceId, so
a resolver that encrypts one prefix and not another is decided per
entity rather than once for the store.
A per-call directive wins over the store’s config, here as
everywhere else, so an explicit per-call { mode: 'none' } is an
opt-out even over a store configured to encrypt.
Two things it still cannot see:
- A store that encrypts and declares nothing. The member is
optional, absence means unknown, and unknown never refuses —
the rule the whole capability family follows, so that a
third-party store does not change behaviour on upgrade for
having declared nothing. A store of your own that encrypts
should implement
encryptsAtRest. - Encryption applied below the store — a bucket’s server-side default, or a backend that encrypts on the way out. No member of this contract reports it, and the decorator has nothing to warn about; that decision is yours alone.
Cache semantics
Section titled “Cache semantics”loadLatest(persistenceId)— read-through with TTL. Check cache; on hit, return. On miss, load from underlying, cache the result withttlMs, return. A load the security section refuses skips the lookup, deletes the entry instead, and is served from the underlying store.save(persistenceId, seq, state)— write-through-with-invalidate: delegate to the underlying store, then delete the cache entry. It deliberately does not write the new snapshot back — in a cluster two nodes may race on save, and a local write would leave a stale entry. The next read repopulates.loadBefore(persistenceId, seq)— not cached (too many possibleseqvalues, and it’s used rarely — only during recovery).delete(persistenceId, toSeq)— delegate to the underlying store, then invalidate the cache entry.
After a save, the cache entry is invalidated, so the next
loadLatest re-fetches from the underlying store and returns the
just-saved snapshot. TTL is the safety net: even if a node crashes
between the underlying write and the cache invalidation, the stale
entry expires within ttlMs.
Performance
Section titled “Performance”For a slow underlying store (say, 50 ms per load), the cache turns subsequent loads of the same snapshot into sub-microsecond operations. A typical sharded-entity workload sees 80-95 % hit rate after warm-up.
The cache can be shared across nodes — back it with Redis or Memcached and every node reads from the same cache, so a snapshot loaded on one node is a hit on all the others. Back it with an in-memory cache instead and each node keeps its own copy; misses on a fresh node pay the full underlying-load cost.
Pitfalls
Section titled “Pitfalls”Where to next
Section titled “Where to next”- Snapshots — the policy this is in service of.
- Object storage snapshot store — the common slow underlying store.
- In-memory snapshot store — for tests.
- SQLite snapshot store — the single-node default.
