Zum Inhalt springen
Deutsch

Distributed Data im Überblick

Distributed Data ist die Schicht für eventually consistent shared state im Cluster. Jeder Node hält eine lokale Replika jedes Keys. Updates werden zuerst lokal angewendet; Gossip propagiert sie; konfliktierende nebenläufige Updates mergen automatisch über die CRDT-Semantik des Datentyps.

Cluster aus 3 Nodes — jeder Node hält jeden Key

node-1 Replika von hits
GCounter a=10 b=4

node-2 Replika von hits
GCounter a=10 b=5

node-3 Replika von hits
GCounter a=10 b=5

Gossip merged kontinuierlich

node-1 konvergiert
GCounter a=10 b=5

node-2 konvergiert
GCounter a=10 b=5

node-3 konvergiert
GCounter a=10 b=5

Der geteilte Zustand ist ein CRDT — Conflict-free Replicated Data Type. Eine Handvoll sorgfältig entworfener Typen (Counter, Sets, Register, Maps), deren Merge-Operation kommutativ, assoziativ und idempotent ist: Gossip darf Updates in beliebiger Reihenfolge zustellen, sie wiederholen oder verlieren — die Replikas konvergieren trotzdem zum selben Wert.

Drei Muster:

  1. Cluster-weite Counter und Gauges — Gesamtzahl der Requests, aktive Sessions, aktuelles Rate Limit. Jeder Node kann lesen und schreiben, ohne sich abzustimmen; der gemergte Wert ist die globale Wahrheit.
  2. Mengen für Membership — “welche Sessions sind aktiv”, “welche Feature Flags sind aktiviert”. Elemente von jedem Node hinzufügen und entfernen; die Set-Semantik kümmert sich korrekt um nebenläufige Adds.
  3. Konfigurations-Register — ein einzelner Wert, den Nodes schreiben und lesen; Timestamps entscheiden bei nebenläufigen Writes über den Gewinner.
import { ActorSystem } from 'actor-ts';
import { Cluster, ClusterOptions } from 'actor-ts/cluster';
import { DistributedDataId, GCounter } from 'actor-ts/crdt';
const system = ActorSystem.create('my-app');
const clusterOptions = ClusterOptions.create()
.withHost(host)
.withPort(port)
.withSeeds(seeds);
const cluster = await Cluster.join(system, clusterOptions);
const dd = system.extension(DistributedDataId).start(cluster);
// Counter inkrementieren — keine Koordination, einfach in die lokale Replika mergen.
dd.update<GCounter>(
'request-count',
GCounter.empty,
(c) => c.increment(dd.selfReplicaId(), 1),
);
// Lokale Sicht lesen — liefert den letzten bekannten gemergten Stand.
const counter = dd.get<GCounter>('request-count');
console.log(counter?.value()); // Summe über alle bekannten Replikas

Das lokale Update ist sofort wirksam; Gossip propagiert es in den nächsten Runden zu den Peers. Reads sind immer lokal (billig, kein Netzwerk) und liefern, was die lokale Replika aktuell weiß — was zum globalen Stand konvergiert.

TypWas es istWann
GCounterGrow-only Counter. Jede Replika zählt ihren eigenen Beitrag; der Wert ist die Summe.Counts, die nur steigen — Impressions, abgeschlossene Jobs.
PNCounterCounter mit Inkrement und Dekrement (intern zwei GCounter).Counts, die in beide Richtungen gehen — aktive Sessions.
GSetGrow-only Set. Nur Adds, keine Removes.Append-only Collections — beobachtete Event-Typen, gesehene User.
ORSetObserved-Remove Set. Adds und Removes; nebenläufiges Add+Remove löst sich zu Add auf (das Add wurde beobachtet).Membership-Sets, in denen Elemente kommen und gehen.
LWWRegister<T>Last-Writer-Wins Register. Ein einzelner Wert, Gewinner ist der jüngste Timestamp.Konfig mit einem Wert — Feature Flag, letzter bekannter Leader.
MVRegister<T>Multi-Value Register. Nebenläufige Writes werden als Set gehalten; der Caller wählt.Wenn du erkennen musst, dass “zwei Replikas gleichzeitig geschrieben haben”.
LWWMap<K, V>Eine Map von K auf LWW-Werte.Konfig pro Key mit einem Wert.
ORMap<K, C>Eine Map, deren Werte selbst CRDTs sind.Counter pro Key, Sets pro Key.
GCounterMap<K>Convenience: eine Map von GCounters.Klicks pro Key, Requests pro Tenant.

Die Deep Dives zu den CRDT-Typen behandeln merge()-Semantik, wann sie passen und wann nicht — Counter, Register, Sets und Maps.

Reads und Writes haben beide einen Consistency-Parameter:

await dd.updateAsync('hits', GCounter.empty,
(c) => c.increment(dd.selfReplicaId(), 1),
{ consistency: 'majority', timeoutMs: 2_000 });
const hits = await dd.getAsync<GCounter>('hits',
{ consistency: 'majority' });
LevelWas es bedeutet
'local' (Default)Lokal anwenden; auf Gossip vertrauen, dass es propagiert. Read liefert die Sicht der lokalen Replika.
'majority'Warten, bis ⌊N/2⌋+1 Replikas geACKt haben. Read merged die Mehrheitsantworten.
'all'Auf jedes Up-Member warten. Stärkste Konsistenz, höchste Latenz.
{ from: 3 }Auf genau from ACKs warten (begrenzt auf [1, N]).

Quorum ändert die Merge-Semantik nicht — jedes Update merged irgendwann in jede Replika. Quorum gibt dir nur eine Garantie, wann genügend Replikas den Write gesehen haben.

Für die meisten Reads und Writes ist 'local' der richtige Default. Greife zu 'majority', wenn:

  • Ein Read einen kürzlich von dir geschriebenen Write reflektieren soll — 'local' funktioniert nur, wenn du auf demselben Node liest, auf dem du geschrieben hast; Majority Reads decken den knotenübergreifenden Fall ab.
  • Ein Write “durable” sein soll, bevor du dem Client antwortest — 'majority' stellt sicher, dass ein Node-Ausfall ihn nicht verliert.

Zwei Arten von Subscribern können erfahren, dass sich ein Key ändert, und beide erfahren von denselben Änderungen: von jedem Update oder Merge, der den lokalen Wert ändert — egal ob er aus einem lokalen Update, aus Gossip, aus einem Quorum-Write oder -Read oder aus einer Identity-Reparatur stammt. Wähle danach, wo die Arbeit laufen soll:

  • Ein Actor — für alles, was Arbeit macht oder Actor-State anfasst. Er bekommt ein DistributedDataChanged und verarbeitet es in seinem eigenen Turn.
  • Ein Callback — für einen billigen synchronen Read. Er läuft im Turn des Replicators, seine Zeit ist also die des Replicators.
import { match, P } from 'ts-pattern';
import { Actor } from 'actor-ts';
import { DistributedDataChanged, DistributedDataId, GCounter } from 'actor-ts/crdt';
type ResetMessage = { readonly kind: 'reset' };
type DashboardMessage = DistributedDataChanged<GCounter> | ResetMessage;
class HitsDashboard extends Actor<DashboardMessage> {
private hits = 0;
override preStart(): void {
this.system.extension(DistributedDataId).get()
.subscribe<GCounter>('hits', this.self);
}
override onReceive(message: DashboardMessage): void {
match(message)
.with(P.instanceOf(DistributedDataChanged), (m) => this.onHitsChanged(m))
.with({ kind: 'reset' }, () => this.onReset())
.exhaustive();
}
private onHitsChanged(changed: DistributedDataChanged<GCounter>): void {
this.hits = changed.value.value();
}
private onReset(): void {
this.hits = 0;
}
}

Der Actor subscribed sich selbst und verarbeitet die Änderung in seinem eigenen onReceive, wie jede andere Nachricht — er darf also seinen eigenen State anfassen, und nichts von seiner Arbeit läuft im Merge des Replicators. Ein DistributedDataChanged trägt den key und den neuen value; matche es über seine Klasse, wie hier, oder über sein kind, 'distributed-data-changed'.

Der Actor bekommt den neuesten Wert, nicht jeden Wert. Der Replicator hält pro Subscriber und Key einen Slot: Solange eine Benachrichtigung noch in der Mailbox des Actors wartet, ersetzt eine neuere Änderung den Wert, den sie trägt, statt eine zweite einzureihen, und die nächste Benachrichtigung wird erst gepostet, wenn der Actor die letzte übergeben bekommen hat. Ein beschäftigter Actor erfährt also seltener von Änderungen, statt jeden Wert verspätet zu bekommen — seine eigene Mailbox gibt das Tempo vor, es gibt also keinen Timer und kein notify-subscribers-interval zu konfigurieren. Eine begrenzte Mailbox kann die Benachrichtigung auch nicht verwerfen: Sie wird an der Schranke vorbei aufgenommen, so wie ein Terminated aus der Death Watch.

Dieses Zusammenfassen hält auch die Arbeit des Actors davon ab, den Replicator aufzuhalten. Seine Turns sind nicht die des Replicators, laufen aber auf demselben Thread — die Arbeit ist also nicht kostenlos, sondern begrenzt dadurch, wie oft der Actor benachrichtigt wird, nicht dadurch, wie oft sich der Key ändert. Zwanzig Änderungen mit je 10 ms Arbeit haben einen dahinter eingereihten Read um 203 ms aufgehalten, wenn ein Callback die Arbeit tat, und um 21 ms mit diesem Actor, der zwei der zwanzig Werte übergeben bekam.

Hält der Key schon einen Wert, bekommt der Actor auch ihn — über seine Mailbox, sobald der Replicator die Subscription verarbeitet hat, und nicht schon, bevor subscribe zurückkehrt. Denselben Actor noch einmal auf denselben Key zu subscriben, legt keine zweite Subscription an. subscribe gibt die Funktion zurück, die die Subscription beendet; eine schon eingereihte Benachrichtigung kommt trotzdem noch an, und wer vorher erneut subscribed, übernimmt sie, statt eine zweite einzureihen — wie oft sich der Actor auch ab- und wieder anmeldet, mehr als eine wartende Benachrichtigung pro Key hat er nie.

Der Actor muss auf diesem Node leben. Eine Ref auf einen Actor auf einem anderen Node zu subscriben, wirft einen TypeError: Eine Benachrichtigung trägt das lebende CRDT des lokalen Replikats, und jeder Node hält ein eigenes Replikat — die Subscription gehört also auf den Node des Subscribers. Der Replicator beobachtet den Actor per Death Watch: Stoppt er, verschwinden seine Subscriptions mit ihm, und einen Neustart des Replicators überstehen sie. Eine TestProbe, die keine Mailbox hat, die das Tempo vorgeben könnte, bekommt jede Änderung direkt.

const unsubscribe = dd.subscribe<GCounter>('hits', (counter) => {
console.log(`hits is now ${counter.value()}`);
});
// ... later
unsubscribe();

Der Callback wird einmal pro geändertem Key und Merge aufgerufen. Hält der Key schon einen Wert, ruft subscribe den neuen Callback sofort damit auf, auf deinem eigenen Stack, bevor es zurückkehrt.

Der Callback läuft synchron im eigenen Turn des Replicators, seine Zeit ist also die Zeit des Replicators: Solange er läuft, wird kein Merge, keine Gossip-Runde und keine Quorum-Antwort verarbeitet — für keinen Key. Zwanzig Aufrufe eines Callbacks, der 10 ms braucht, haben einen dahinter eingereihten lokalen Read um 203 ms aufgehalten.

Worauf der Replicator wartet, ist das, was der Callback tut, bevor er zurückkehrt. Ein Debounce hilft: Ein Callback, der nur einen nachlaufenden Timer neu stellt, läuft zwar weiter einmal pro Änderung, aber die Arbeit läuft einmal, nach dem Burst, und derselbe Read wartete unter 5 ms — nur läuft diese Arbeit in einem Timer, außerhalb jedes Actors, und darf deshalb keinen Actor-State anfassen. Ein Callback, der nur einem Actor tellt, hilft nicht: Der Actor wird einmal pro Änderung benachrichtigt, und seine Turns laufen zwischen denen des Replicators auf demselben Thread — der Read wartete also genauso lange. Beschränke einen Callback auf einen billigen synchronen Read — eine Zahl im UI auffrischen, einen Counter gegen eine Schwelle vergleichen — oder darauf, einen Debounce zu stellen, und subscribe für alles Weitere den Actor selbst, wie Replikation erklärt. Ein Callback, der wirft, wird als Warnung geloggt und bleibt subscribed.

Standardmäßig ist DistributedData nur in-memory. Wenn der ganze Cluster neu startet (Cold Start), beginnt jeder Key wieder leer.

Für Restart-überlebende Semantik nutzt du die durable-Variante:

import { DistributedDataOptions } from 'actor-ts/crdt';
import { InMemoryDurableStateStore } from 'actor-ts/persistence';
const store = new InMemoryDurableStateStore();
const distributedDataOptions = DistributedDataOptions.create().withDurableStore(store);
const dd = system.extension(DistributedDataId).start(
cluster,
distributedDataOptions,
);

withDurableStore nimmt jeden DurableStateStore (hier InMemory; ein SQL- oder Object-Storage-Backend in Produktion). Die Durable-Schicht persistiert die gesamte Sicht der Replika in den Store; beim Neustart wird der Stand wiederhergestellt, bevor sie Gossip beitritt.

Siehe Durable Storage für die Konfigurationsdetails.

Die DistributedData-API-Referenz deckt die vollständige Extension-Oberfläche ab.