Zum Inhalt springen
Deutsch

Replikation

DistributedData repliziert Zustand via Gossip:

  • Alle gossipInterval wä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.

node-Bnode-Anode-Bnode-Alokales Update angewendet — sofortin lokalen Zustand mergenper-CRDT-Merge-Funktionfalls sich der lokale Wert geändert hatSubscriber benachrichtigenGossip-Tick — vollständiger Snapshot kommt an

Lokale Writes sind sofort. Gossip ist für die Propagation.

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:

WorkloadIntervall
Latenz-empfindlicher Shared State (Online-Präsenz)250-500 ms
Default für die meisten Apps1 s
Counter / Flags, die sich selten ändern2-5 s
Sehr große Cluster, wo Bandbreite zählt5-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 = 2s

Den Rest des Blocks findest du unter Konfiguration.

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.

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.

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.

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

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 erfährt von Änderungen über einen Latest-Value-Slot, einen pro Subscriber und Key:

  • Eine Benachrichtigung auf einmal → höchstens ein DistributedDataChanged pro 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-interval zu 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 Terminated aus 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 subscribe zurü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 TypeError abgelehnt, 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. Eine TestProbe, die keine Mailbox hat, die das Tempo vorgeben könnte, bekommt jede Änderung direkt.

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 subscribe zurü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 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.

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-bytes an 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-interval treibt, wie oft du sie zahlst, und max-gossip-bytes begrenzt 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).

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

Wenn dich das überrascht:

  1. Warte eine Gossip-Runde (Default 1 s). Die meiste sichtbare Veraltung löst sich in 1-2 Gossip-Zyklen.
  2. Prüfe gossipInterval — wenn höher als der Default gesetzt, ist die Wartezeit proportional.
  3. Nutze getAsync mit consistency: 'majority' für Reads, die den letzten bekannten Stand über die Replikas hinweg reflektieren müssen.
  4. Prüfe Cluster-Membership — wenn node-B von node-A aus unerreichbar ist, fließt kein Gossip.