Replikation
DistributedData repliziert Zustand via Gossip:
- Alle
gossipIntervalwählt jeder Node einen zufälligen Peer. - Der Node sendet einen vollständigen Snapshot jedes Keys, den er aktuell hält — oder so viel davon, wie in ein Frame passt, und setzt beim nächsten Tick fort (siehe Was gegossipt wird).
- Der Peer merged jeden Eintrag; wenn sich sein Zustand geändert hat, benachrichtigt er die lokalen Subscriber.
Das bedeutet, Writes propagieren eventually — typischerweise in 1-2 Gossip-Runden (1-2 Sekunden default). Für die meisten Workloads ist das ausreichend; für Fälle, in denen es das nicht ist, siehe Quorum Reads/Writes.
Der Ablauf
Abschnitt betitelt „Der Ablauf“Lokale Writes sind sofort. Gossip ist für die Propagation.
Konfiguration
Abschnitt betitelt „Konfiguration“const distributedDataOptions = DistributedDataOptions.create().withGossipInterval(1_000);const dd = system.extension(DistributedDataId).start( cluster, distributedDataOptions, // default 1s);Der Default für gossipInterval ist 1 Sekunde — gewählt als
Balance zwischen Propagation-Geschwindigkeit und Gossip-Bandbreite.
Kleinere Intervalle → schnellere Konvergenz + mehr Traffic.
Größere → weniger Traffic, langsamere Konvergenz.
Für typische Anwendungen:
| Workload | Intervall |
|---|---|
| Latenz-empfindlicher Shared State (Online-Präsenz) | 250-500 ms |
| Default für die meisten Apps | 1 s |
| Counter / Flags, die sich selten ändern | 2-5 s |
| Sehr große Cluster, wo Bandbreite zählt | 5-10 s |
Derselbe Knopf ist auch aus der application.conf setzbar, ein Deployment
kann ihn also ohne Rebuild tunen — wo beides gesetzt ist, gewinnt weiterhin
der Builder:
actor-ts.distributed-data.gossip-interval = 2sDen Rest des Blocks findest du unter Konfiguration.
Was gegossipt wird
Abschnitt betitelt „Was gegossipt wird“Der vollständige State, auf ein Frame zugeschnitten — bei jedem
Tick serialisiert DistributedData so viele Keys, wie in
max-gossip-bytes passen, und pusht sie an einen zufälligen Peer;
beim nächsten Tick geht es dort weiter, wo dieser aufgehört hat. Es
gibt kein Delta-Tracking und keine Empfangs-Historie pro Peer — ein
Store, der ins Budget passt, reist also bei jedem Tick vollständig.
So ist das Gossip-Volumen proportional zur Gesamt-State-Größe, nicht zur Update-Rate. Eine Map mit einer Million Einträgen kostet jedes Mal, wenn sie gegossipt wird, ihre volle serialisierte Größe — egal ob sie sich geändert hat; ein kleiner Counter kostet fast nichts, egal wie oft er inkrementiert wird.
Das Zuschneiden ist sicher, weil pro Key gemerged wird und ein Key, der in einem Frame fehlt, “keine Information über ihn in dieser Runde” bedeutet — nicht “gelöscht”. CRDT-Merge ist idempotent und kommutativ: Ein Key, der einen Tick später oder zweimal ankommt, ändert nichts daran, wohin der Cluster konvergiert, nur wann.
Warum es das Budget gibt
Abschnitt betitelt „Warum es das Budget gibt“max-gossip-bytes hat den Default 1 MiB und wird immer auf
remote.max-frame-bytes heruntergeschnitten (Default 16 MiB).
Ohne das Budget erzeugte ein großer Store ein Frame jenseits des
Wire-Caps — und so ein Frame wird beim Empfänger schon an seinem
4-Byte-Längenpräfix abgelehnt, bevor ein einziger Key geparst
wird. Der empfangende Transport verwirft daraufhin die Verbindung,
und über die laufen auch Heartbeats, Membership-Gossip und jedes
tell über Knotengrenzen. Der Store konvergierte also nicht
langsam, sondern überhaupt nicht — und riss pro Tick eine
Peer-Verbindung mit.
Ein einzelner Key, dessen eigene Kodierung das Budget
überschreitet, lässt sich nicht weiter aufteilen — die Einheit ist
der vollständige State eines Keys. Er wird übersprungen, die
Replika warnt (ratenbegrenzt, mit Key-Name und beiden Größen) und
zählt distributed_data_gossip_skipped_keys_total hoch. Dieser
Key konvergiert nicht. Teile den Wert auf, oder erhöhe
max-gossip-bytes und remote.max-frame-bytes.
Wenn dein Store groß wird, verteilt ein höheres gossip-interval
die Kosten über die Zeit; ein kleineres max-gossip-bytes verteilt
die Kosten eines Ticks über mehr Ticks.
Die Frühwarnung: log-data-size-exceeding
Abschnitt betitelt „Die Frühwarnung: log-data-size-exceeding“Das Budget meldet sich erst, wenn ein Key ein ganzes Frame überschritten hat — und dann konvergiert dieser Key längst nicht mehr. Ein Key bei einem großen Bruchteil des Budgets ist im Vergleich unsichtbar und trotzdem teuer: Er gossipt einwandfrei, verbraucht aber genau diesen Bruchteil jedes Ticks, in dem er auftaucht — alles andere im Store wird also entsprechend langsamer verteilt, und nichts sagt, warum.
log-data-size-exceeding (Default 100K, ungefähr ein Zehntel des
Budgets) ist diese Frühwarnung. Ein Key darüber wird benannt,
nicht übersprungen — der Packer behandelt ihn exakt so wie zuvor:
const distributedDataOptions = DistributedDataOptions.create() .withMaxGossipBytes(1024 * 1024) .withLogDataSizeExceeding(100 * 1024);Die Warnung ist auf eine Zeile pro Minute ratenbegrenzt und trägt
eine laufende Gesamtzahl mit sich; sie hat ihre eigene
Ruhephase, statt sich die der Skip-Warnung zu teilen. Das ist
genau dann wichtig, wenn beide feuern: Ein höheres
max-gossip-bytes behebt „dieser Key lässt sich überhaupt nicht
gossipen” — und macht „dieser Key kostet ein Zehntel jedes Ticks”
relevanter, nicht weniger relevant. 0 schaltet die Meldung ab.
Da der Packer ab seinem Cursor nur so viele Keys besucht, bis das Budget voll ist, wird ein Key in einem großen Store einmal pro Sweep gemessen statt einmal pro Tick — die richtige Taktung für etwas, das ohnehin auf eine Minute ratenbegrenzt ist.
Auswahl des Peers pro Runde
Abschnitt betitelt „Auswahl des Peers pro Runde“// Bei jedem Gossip-Tick wählt der Node EINEN zufälligen erreichbaren Peer.Round-Robin-Gossip wäre vorhersagbarer, erzeugt aber synchronisierte Wellen; ein zufälliger Peer pro Tick verteilt die Last und konvergiert typischerweise in O(log N) Runden bei N Peers.
Nach K Runden ist die Wahrscheinlichkeit, dass ein bestimmter
Peer das Update nicht erhalten hat, (1 - 1/N)^K — für N=10
Nodes und K=5 Runden also < 60 % Wahrscheinlichkeit, dass ein
Peer es nicht gesehen hat; nach K=20 Runden < 13 %.
In der Praxis ist die Konvergenz viel schneller, weil Gossip multi-hop ist: Peers regossipen, was sie erhalten haben.
Auf Änderungen subscriben
Abschnitt betitelt „Auf Änderungen subscriben“import { Actor } from 'actor-ts';import { DistributedDataChanged, DistributedDataId, GCounter } from 'actor-ts/crdt';
// An actor subscribes itself, and is told on its own turn:class HitsLog extends Actor<DistributedDataChanged<GCounter>> { override preStart(): void { this.system.extension(DistributedDataId).get().subscribe<GCounter>('hits', this.self); }
override onReceive(changed: DistributedDataChanged<GCounter>): void { console.log(`hits is now ${changed.value.value()}`); }}// A callback runs on the replicator's turn:const unsubscribe = dd.subscribe<GCounter>('hits', (counter) => { console.log(`hits is now ${counter.value()}`);});
// Later:unsubscribe();Ein Subscriber ist entweder ein Actor, der ein
DistributedDataChanged bekommt und seine Arbeit in seinem eigenen
Turn erledigt, oder ein Callback, der synchron im Turn des
Replicators läuft. Subscribe einen Actor für alles, was Arbeit macht
oder Actor-State anfasst — Dashboard-Widgets, Echtzeit-UI-Updates,
Business-Logik, die auf Änderungen irgendwo im Cluster reagieren
soll. Einen Callback behältst du für einen billigen synchronen Read.
Beide erfahren nach jedem erfolgreichen Merge davon, der den lokalen
Wert ändert (Deep-Equal-Check über das toJSON des CRDT):
- Lokale Updates → wenn der Replicator das Update anwendet;
update()selbst reiht es nur ein. - Remote Updates → wenn Gossip ankommt und der Merge den lokalen Wert ändert — für jeden Key, den die Runde geändert hat.
- Quorum-Writes, Quorum-Reads und Identity-Reparaturen → genauso: Jeder Merge, der einen Key ändert, benachrichtigt dessen Subscriber, egal woher er kommt.
- Idempotente Updates → niemand erfährt etwas (keine Änderung).
Ein Actor als Subscriber
Abschnitt betitelt „Ein Actor als Subscriber“Ein Actor erfährt von Änderungen über einen Latest-Value-Slot, einen pro Subscriber und Key:
- Eine Benachrichtigung auf einmal → höchstens ein
DistributedDataChangedpro Key wartet in der Mailbox des Actors. Eine Änderung, während es wartet, ersetzt den Wert, den es trägt; das nächste wird erst gepostet, wenn der Actor das letzte übergeben bekommen hat. Der Actor verarbeitet also den neuesten Wert zum Zeitpunkt seines eigenen Dispatch, und ein Schwall von zweihundert Updates hinter einem beschäftigten Handler kommt als eine Benachrichtigung an. - Getaktet von seiner eigenen Mailbox → es gibt keinen Timer und
kein
notify-subscribers-intervalzu konfigurieren: Der Actor erfährt so oft von Änderungen, wie er die Benachrichtigungen abnimmt, und nie öfter, als der Key sich ändert. - Von keiner Schranke verworfen → die Benachrichtigung wird an
der Kapazität einer begrenzten Mailbox vorbei aufgenommen, wie ein
Terminatedaus der Death Watch. Verworfen, ließe sie den Slot auf eine Übergabe warten, die nie kommt, und der Actor erführe nie wieder etwas über den Key. - Replay über die Mailbox → wer einen Key subscribed, der schon
einen Wert hält, bekommt auch diesen Wert — asynchron, sobald der
Replicator die Subscription verarbeitet hat, nicht schon, bevor
subscribezurückkehrt. - Eine Subscription pro Actor und Key → erneutes Subscriben legt keine zweite Subscription an. Die zurückgegebene Funktion beendet die Subscription; eine schon eingereihte Benachrichtigung kommt trotzdem noch an.
- Auf diesem Node, und beobachtet → der Actor muss auf dem Node
des Replikats leben: Eine Ref auf einen Actor anderswo wird mit
einem
TypeErrorabgelehnt, weil eine Benachrichtigung das lebende CRDT dieses Replikats trägt. Der Replicator beobachtet den Actor per Death Watch, seine Subscriptions enden also, wenn er stoppt, und ein Neustart des Replicators behält sie. EineTestProbe, die keine Mailbox hat, die das Tempo vorgeben könnte, bekommt jede Änderung direkt.
Ein Callback als Subscriber
Abschnitt betitelt „Ein Callback als Subscriber“Ein Callback läuft synchron im eigenen Turn des Replicators, einmal pro geändertem Key und Merge:
- Subscribe auf einen Key, der schon einen Wert hält → der neue
Callback wird sofort damit aufgerufen, auf dem Stack des
Aufrufers, bevor
subscribezurückkehrt. Einer, der sich aus der Benachrichtigung eines anderen Subscribers heraus anmeldet, bekommt diesen Wert auf diesem Weg, genau einmal. - Ein Callback, der wirft → wird als Warnung geloggt
(
DistributedData: subscriber for "<key>" threw, mit dem Fehler); die übrigen Subscriber werden trotzdem aufgerufen, und der werfende bleibt subscribed.
Weil ein Callback im Turn des Replicators läuft, ist seine Zeit die Zeit des Replicators: Solange einer 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. Siehe Callbacks feuern bei jeder Änderung weiter unten.
Wenn ein Peer den Cluster verlässt
Abschnitt betitelt „Wenn ein Peer den Cluster verlässt“Wenn MemberRemoved für ein Cluster-Mitglied feuert, tut
DistributedData nichts — es gibt keinen Zustand pro Peer, der
aufzuräumen wäre. Gossip hält keinen Version Vector und keine
Empfangs-Historie pro Peer; jeder Tick wählt einfach einen
zufälligen Peer aus den aktuellen Up-Members, sodass ein
ausgeschiedener Node schlicht kein Gossip-Ziel mehr ist.
Der Zustand, den der Peer beigetragen hat, bleibt in der lokalen
Replika, eingemerged wie jedes andere Update. CRDT-Tombstones
(ein entferntes ORSet-Element, ein null-Register in einer
LWWMap) werden nie garbage-collected — sie bleiben dauerhaft
erhalten, damit ein veraltetes Gossip einen entfernten Key nicht
wiederauferstehen lassen kann. Über einen langlebigen Store mit
starkem Churn ist die Tombstone-Akkumulation der praktische
Kostenpunkt, den man im Auge behalten sollte.
Eine Replika, die später unter derselben Identität wieder beitritt (stabile Pod-Namen, persistente Volumes), braucht keine Sonderbehandlung — sie ist einfach wieder ein weiterer Up-Member, und Gossip lässt ihren Zustand über die nächsten paar Ticks erneut konvergieren.
Bandbreitenkosten
Abschnitt betitelt „Bandbreitenkosten“Grobe Zahlen für einen 10-Node-Cluster mit Default-Gossip von 1 Sekunde:
- Pro Tick, pro Node — eine Nachricht mit bis zu
max-gossip-bytesan serialisiertem Store geht an einen einzigen zufälligen Peer. Ihre Größe wird durch den Gesamt-State bestimmt, nicht dadurch, wie viel sich seit dem letzten Tick geändert hat, sodass ein Idle-Store das trotzdem bei jedem Tick zahlt; die Kosten wachsen nur nicht mit der Write-Rate. - Skalierungs-Stellschrauben — die Store-Größe treibt die
Kosten pro Nachricht,
gossip-intervaltreibt, wie oft du sie zahlst, undmax-gossip-bytesbegrenzt jede einzelne Zahlung. Ein großer Store bei einem schnellen Intervall ist die teure Kombination; ein großer Store bei einem kleinen Budget die langsam konvergierende.
Für sehr große Cluster (50+ Nodes) kann das Gossip-Volumen
relevant werden. Das Gossip des Frameworks ist im
Anti-Entropy-Stil — all-to-all über die Zeit — was O(N) pro
Node pro Runde skaliert. Größere Cluster wollen vielleicht ein
größeres gossipInterval oder eine andere Gossip-Topologie
(aktuell nicht konfigurierbar; bei Bedarf ein Issue).
Langsame Propagation diagnostizieren
Abschnitt betitelt „Langsame Propagation diagnostizieren“// Node-A schreibt:dd.update('hits', ..., (c) => c.increment('a', 1));
// Node-B liest, aber der Wert spiegelt es nicht wider:console.log(dd.get('hits')?.value()); // ← zeigt veralteten WertWenn dich das überrascht:
- Warte eine Gossip-Runde (Default 1 s). Die meiste sichtbare Veraltung löst sich in 1-2 Gossip-Zyklen.
- Prüfe
gossipInterval— wenn höher als der Default gesetzt, ist die Wartezeit proportional. - Nutze
getAsyncmitconsistency: 'majority'für Reads, die den letzten bekannten Stand über die Replikas hinweg reflektieren müssen. - Prüfe Cluster-Membership — wenn node-B von node-A aus unerreichbar ist, fließt kein Gossip.
Wohin als Nächstes
Abschnitt betitelt „Wohin als Nächstes“- Distributed Data im Überblick — das Gesamtbild.
- Quorum Reads/Writes — die Konsistenz-Stellschrauben für stärkere Garantien.
- Durable Storage — Replika-State für Restart-Recovery auf Disk persistieren.
- Cluster im Überblick — das Membership-Modell darunter.
