콘텐츠로 이동
한국어

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);

Three patterns:

  1. 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.
  2. Frequent actor churn — sharded entities passivating / re-spawning constantly, each load re-reading the same snapshot.
  3. 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.

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
};
FieldWhat
cacheBacking cache (required) — typically Redis in production. Any Cache: in-memory, Redis, or Memcached.
ttlMsCache TTL in milliseconds. Default: 5 minutes.
keyPrefixKey prefix (default 'snap:') — prevents collisions in shared caches.
allowPlaintextCacheAcknowledge 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.

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 this
persistenceId 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.

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.
  • loadLatest(persistenceId) — read-through with TTL. Check cache; on hit, return. On miss, load from underlying, cache the result with ttlMs, 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 possible seq values, 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.

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.