Zum Inhalt springen
Deutsch

Durable Storage

Standardmäßig leben DistributedData-Replikas nur im Speicher. Ein Full-Cluster-Restart (jeder Node gleichzeitig down) verliert den gesamten State — jeder Key startet wieder bei empty.

Für State, der einen Cold Start überleben muss, gib DistributedData ein durables Backend mit DistributedDataOptions.withDurableStore(...):

import {
DistributedDataId,
DistributedDataOptions,
} from 'actor-ts/crdt';
import {
InMemoryDurableStateStore,
} from 'actor-ts/persistence';
// Any DurableStateStore works — InMemory here; a SQL / object-storage
// backend in production (see "Store choices" below).
const store = new InMemoryDurableStateStore();
const distributedDataOptions = DistributedDataOptions.create()
.withGossipInterval(1_000)
.withDurableStore(store);
const dd = system.extension(DistributedDataId).start(
cluster,
distributedDataOptions,
);

withDurableStore nimmt direkt einen DurableStateStore — keinen Wrapper. Intern umwickelt DistributedData ihn mit einem DurableDistributedDataStore, der anhand der eigenen Replika-ID dieses Nodes abgelegt wird, also ist Durability pro Replika: jedes Cluster-Mitglied besitzt einen durablen Datensatz.

Was du damit bekommst:

  • Bei preStart — bevor die Replika Gossip beitritt, lädt sie ihre persistierte Sicht aus dem Store.
  • Nach jeder Mutation — lokales update, eingehender Gossip-Merge und delete speichern die Sicht neu.

Nach einem Cold Start liefert dd.get(key) den zuletzt persistierten Wert — nicht undefined — und Gossip merged von dort über die Replikas hinweg neu.

Standardmäßig wird die gesamte lokale Sicht der Replika (jeder Key, den sie hält) serialisiert und als ein durabler Datensatz pro Replika geschrieben, unter der ID ddata|<replicaId>. Jeder Wert wird über das toJSON() des CRDT serialisiert.

Weil die gesamte Sicht ein Datensatz ist, schreibt jede Mutation den ganzen Datensatz neu — derselbe Full-State-Rewrite-Trade-off wie bei Durable-State-Actors. Für kleinen, heißen State (Counter, Flags, kleine Sets) ist das billig; für eine große Sicht unter hoher Mutationsrate kostet es Bandbreite und Write-Amplification (siehe die Cautions unten).

withDurableKeys (HOCON: actor-ts.distributed-data.durable-keys) beschränkt den Datensatz auf die Keys, die du benennst — so persistiert eine Replika mit einer großen flüchtigen Sicht nur den Teil, der einen Cold Start überleben muss:

const distributedDataOptions = DistributedDataOptions.create()
.withDurableKeys(['cart-42', 'session-*'])
.withDurableStore(store);

Ein Eintrag ist entweder ein exakter Key-Name oder ein Präfix mit einem abschließenden *. Das ist bewusst die gesamte Syntax: Ein reichhaltigeres Glob hieße, aus einer Config-Datei einen Matcher zu bauen, und new RegExp(ausConfig) über einen vom Betreiber gelieferten Text ist eine Angriffsfläche für katastrophales Backtracking — auf genau dem Pfad, der entscheidet, was einen Neustart überlebt. Alles andere wird beim Start mit einem OptionsError abgelehnt, statt still auf nichts zu passen.

Drei Dinge, die du vorher wissen solltest:

  • Eine leere Liste heißt jeder Key — der Default, und das Verhalten jedes Releases vor dieser Option. Sie heißt niemals „nichts persistieren”; nichts zu persistieren erreicht man, indem man keinen Store konfiguriert.
  • Der Filter ist eine Durability-Entscheidung, keine Sichtbarkeits-Entscheidung. Ein ausgeschlossener Key lebt weiterhin in der Sicht, gossipt, merged und beantwortet get. Er liegt schlicht nicht auf der Platte, ein Cold Start bringt ihn also nicht zurück — Gossip von einer überlebenden Replika vielleicht schon.
  • Die Liste zu verengen löscht, was sie nicht mehr benennt. Der Datensatz wird bei jedem Save vollständig ersetzt; ein Key, der nicht mehr passt, ist von der Platte verschwunden, sobald irgendetwas anderes geschrieben wird — nicht nur eingefroren. Erweitern ist gefahrlos: Der nächste Save schreibt, was die lebende Sicht hält.

Ohne durableStore ist die Liste wirkungslos; eine nicht-leere Liste ohne konfigurierten Store wird beim Start als Warnung gemeldet statt ignoriert, weil beide Hälften an verschiedenen Stellen konfiguriert werden und nur die laufende Replika sehen kann, dass sie sich widersprechen.

Jede DurableStateStore-Implementierung funktioniert — konstruiere sie genau wie für einen Durable-State-Actor und übergib sie dann an withDurableStore:

StoreVerwendung
InMemoryDurableStateStoreTests / Dev — im Prozess durable, beim Exit weg.
PostgresDurableStateStoreCluster-geteilte SQL-Durability.
MariaDbDurableStateStoreDie SQL-Alternative aus der MySQL-Familie.
ObjectStorageDurableStateStoreDateisystem- oder S3-backed Datensätze.

Siehe Durable State für die Konstruktionsoptionen jedes Stores — DistributedData verwendet dieselben Stores wieder, es gibt also nichts DD-Spezifisches zu konfigurieren.

Der Store ist nach Replika-ID indexiert, die beiden Deployment-Formen unterscheiden sich also darin, wo der Datensatz jeder Replika liegt, nicht darin, was ein Node lädt:

Per-node local store (e.g. object storage at a local path):
node-A's store ← ddata|node-A
node-B's store ← ddata|node-B
cold start → each node loads its own record; gossip reconverges
Shared backend (one Postgres / one S3 bucket):
shared store ← ddata|node-A, ddata|node-B, … (one record per replica)
cold start → each node loads its own record; gossip reconverges
  • Per-Node lokal — vollständige lokale Recovery, partitions-tolerant; aber der Datensatz eines zerstörten Nodes ist weg (Gossip + Überlebende stellen die Werte wieder her, da CRDTs konvergieren).
  • Shared — der Datensatz jeder Replika überlebt an einem Ort, selbst wenn der Node zerstört wird; kostet einen Roundtrip zum Shared Store beim Start und macht diesen Store zu einer geteilten Abhängigkeit.

Für die meisten Apps ist beides okay — CRDT-Konvergenz bedeutet, dass der Verlust des Datensatzes eines Nodes selten fatal ist.

withDurableStore ist der Weg, den du fast immer willst. Der Wrapper, den es baut, ist auch für sich nutzbar — ein positionaler Konstruktor über einem DurableStateStore plus einer Replika-ID, mit load() / save() / clear():

import { DurableDistributedDataStore, GCounter } from 'actor-ts/crdt';
import { InMemoryDurableStateStore } from 'actor-ts/persistence';
const store = new InMemoryDurableStateStore();
const durable = new DurableDistributedDataStore(store, 'replica-a');
const view = new Map([['hits', GCounter.empty().increment('replica-a', 5)]]);
await durable.save(view); // persist the whole view
const restored = await durable.load(); // Map<string, Crdt> (empty if nothing stored)
await durable.clear(); // forget this replica's record

Das ist, was das Framework unter der Haube nutzt; greife nur für Tooling oder Tests direkt darauf zu.

const distributedDataOptions = DistributedDataOptions.create()
.withDurableStore(store);
const dd = system.extension(DistributedDataId).start(
cluster,
distributedDataOptions,
);
// On preStart, before joining gossip:
// 1. load() this replica's record from the durable store.
// 2. decode each entry into its CRDT.
// 3. seed the local view.
// 4. then join the gossip layer.
const value = dd.get('hits'); // already reflects the persisted view

Der Start ist durch die Lesegeschwindigkeit des Durable Store begrenzt. Für einen lokalen Store mit einer Handvoll Keys sub-millisekündlich; für ein geteiltes SQL- / S3-Backend einstellige Sekunden.

Für At-Rest-Verschlüsselung oder Kompression konfiguriere sie am zugrunde liegenden Store, wo das Backend es unterstützt (z. B. der Object-Storage-Store — siehe Object Storage Encryption).