Per-actor policies

The object-storage backend can have store-level defaults for compression + encryption. But sometimes specific actors need different settings:

• A sensitive actor needs encryption (others don’t).
• A large-state actor benefits from high-level zstd (others use gzip).
• A small-state actor opts out of compression.

Override per-actor by implementing the compression() / encryption() methods:

class SensitiveActor extends DurableStateActor<Command, State> {
  protected encryption() {
    return {
      mode: 'client-aes256-gcm' as const,
      masterKeys: sensitiveKeyRing,
      info: 'acme/prod/sensitive/v1',
    };
  }

  protected compression() {
    return { algorithm: 'gzip' as const, level: 9 };
  }
}

The framework calls these on each persist/load and applies the returned config.

Default vs override

// Store-level config — applies to every actor unless overridden:
const objectStorageDurableStateStoreOptions = ObjectStorageDurableStateStoreOptions.create()
  .withBackend(backend)
  .withCompression({ algorithm: 'gzip', level: 6 })
  .withEncryption({ mode: 'client-aes256-gcm', masterKeys: defaultKeyRing, info: 'acme/prod/durable-state/v1' });
const store = new ObjectStorageDurableStateStore(objectStorageDurableStateStoreOptions);

// Per-actor: override
class MyActor extends DurableStateActor<...> {
  protected compression() { return { algorithm: 'none' as const }; }
  // encryption() not overridden → uses defaultKeyRing
}

Each method is independently overridable:

• Return your own config → that config applies.
• Don’t override → store’s default applies.
• Return undefined from the method → also store’s default.

Use cases

Per-actor encryption

class CreditCardActor extends DurableStateActor<...> {
  protected encryption() {
    // Separate key ring AND a separate HKDF context for PCI scope.
    return {
      mode: 'client-aes256-gcm' as const,
      masterKeys: pciKeyRing,
      info: 'acme/prod/pci/v1',
    };
  }
}

class GenericActor extends DurableStateActor<...> {
  // No override → uses store default (no encryption, or generic keyRing)
}

PCI / HIPAA / GDPR scope: data classified as sensitive uses a separate master key from non-sensitive. Compromise of one keyRing doesn’t expose the other.

Per-actor compression

class ChatTranscriptActor extends DurableStateActor<...> {
  // Large text state — high-level zstd wins meaningfully
  protected compression() {
    return { algorithm: 'zstd' as const, level: 19 };
  }
}

class CounterActor extends DurableStateActor<...> {
  // Tiny state — compression overhead exceeds savings
  protected compression() {
    return { algorithm: 'none' as const };
  }
}

Match the compression to the data shape. Default gzip is a safe middle ground; per-actor tuning extracts more.

What happens on persist

DurableStateActor.persist(state)
  ↓
serializer.toBinary(state) → JSON or CBOR bytes
  ↓
this.compression() → applies if not 'none'
  ↓
this.encryption() → applies if set
  ↓
backend.put(key, ciphertext, options)

The framework looks up the actor’s overrides at each persist — so even if you change the override values dynamically (rare), new writes use new settings.

What happens on load

DurableStateActor.preStart
  ↓
backend.get(key) → framed ATS1 body
  ↓
read the ATS1 manifest → encrypted flag set? → decrypt (key version from the manifest byte)
  ↓
read the ATS1 manifest → compression flag → decompress
  ↓
serializer.fromBinary → state

Reads use the self-describing ATS1 manifest carried in the body, not the actor’s current overrides. An object encrypted under pciKeyRing is decrypted via pciKeyRing whether or not the actor’s current encryption() says so.

This means: rotating an actor’s policy doesn’t break old data as long as the necessary keys / algorithms are available.

Migration when changing policies

// Old: no encryption.
// New: encryption under pciKeyRing.
class CreditCardActor extends DurableStateActor<...> {
  protected encryption() {
    return {
      mode: 'client-aes256-gcm' as const,
      masterKeys: pciKeyRing,
      info: 'acme/prod/pci/v1',
    };
  }
}

Old (unencrypted) reads work — no metadata → plaintext path. New writes encrypt. Eventually:

• A re-encryption sweep filtered to this actor’s persistenceIds migrates the rest.

See key rotation.

Working with the snapshot store

class Account extends PersistentActor<Command, Event, State> {
  // Per-actor compression for snapshots:
  override compression() {
    return { algorithm: 'zstd' as const };
  }

  // Per-actor encryption for snapshots:
  override encryption() {
    return {
      mode: 'client-aes256-gcm' as const,
      masterKeys: accountKeyRing,
      info: 'acme/prod/snapshot/v1',
    };
  }
}

Same methods apply when the snapshot store is backed by object-storage. Persistent actors and durable-state actors both honor them.

Different keyRings across cluster nodes

// node-A's actor uses pciKeyRing; node-B's same actor uses generic

Actors must see the same encryption config across the cluster (otherwise post-migration sharded entities can’t be read). Pass key rings from the same source on every node.

Heavy compression per-actor

// Override to zstd level 22 (ultra) for "important" actors

zstd ultra levels (20-22) are slow to encode and may be unreadable on a runtime that only has the pure-JS fzstd decompress fallback (32 MB window). If “important” actors persist frequently, profile first — and keep ≤ 19 unless every reader has native zstd.

Override returning new object each call

override compression() {
  return { algorithm: 'gzip', level: 6 };   // ← new object every call
}

Fine for correctness; mildly wasteful (allocates per persist). Hoist to a constant if perf-sensitive:

private static readonly GZIP6 = { algorithm: 'gzip' as const, level: 6 };
override compression() { return Account.GZIP6; }

Where to next

• Object storage overview — the bigger picture.
• Compression — algorithm + level details.
• Encryption — encryption setup.
• Snapshot store backend — for snapshots in object storage.