Skip to content
English

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.

// 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.
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.

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.

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.

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.

// 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',
};
}
}

New writes encrypt. An old, unencrypted body of this actor is now refused on read: whether a body is encrypted is a byte in the body, so a plaintext one is indistinguishable from a forgery (#965). Open the migration window on the store with withAllowUnencryptedBodies(true), let each persistenceId be loaded and written once — the write re-encrypts it — and remove the option again. The re-encryption sweep does not encrypt plaintext bodies; it rotates encrypted ones. See Reading old payloads.

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 — to the snapshots, and to nothing else. A durable-state actor’s hooks cover its whole state; a persistent actor’s cover its snapshots and never its events, which the journal keeps in plaintext (see the danger aside below).

integrity() is the third hook, alongside compression() and encryption(). It signs the stored body with HMAC-SHA256 so tamper-in-place is detected at read time — worthwhile even for data that isn’t secret:

class LedgerActor extends DurableStateActor<Command, State> {
protected integrity() {
return { mode: 'hmac-sha256' as const, integrityKey: ledgerIntegrityKey };
}
}
class Account extends PersistentActor<Command, Event, State> {
override integrity() {
return { mode: 'hmac-sha256' as const, integrityKey: accountIntegrityKey };
}
}

Configuring hmac-sha256 makes the tag mandatory on read: a body that carries none is refused rather than waved through. For a corpus written before integrity was enabled, open the migration window with the store-level allowUntaggedBodies and drop it once the read-then-write sweep is done.