Zum Inhalt springen
Deutsch

Quorum Reads und Writes

Die Default-Operationen update / get von DistributedData sind nur lokal — sie werden sofort auf die lokale Replika angewendet; die Propagation passiert via Gossip. Für Workloads, die stärkere Garantien brauchen, warten die Varianten updateAsync und getAsync auf explizite Replika-Bestätigungen.

dd.update<GCounter>(
'hits',
GCounter.empty,
(c) => c.increment(dd.selfReplicaId(), 1),
);
const counter = dd.get<GCounter>('hits');

Diese Operationen:

  • update — wende lokal an, fire-and-forget. Kehrt sofort zurück.
  • get — lese die Sicht der lokalen Replika.

Unter der Haube propagiert Gossip Updates über die nächsten Runden an andere Replikas.

Das ist der richtige Default — 99 % der DD-Operationen nutzen diese.

Drei häufige Fälle:

  1. Read-after-Write über Nodes hinweg. Node A schreibt, Node B liest sofort — der Write ist vielleicht noch nicht gegossipt, also sieht Node B veraltete Daten.
  2. Bestätigter Write. Die App will wissen “mindestens N andere Replikas haben mein Update, bevor ich weitermache” — z. B. bevor dem Client geantwortet wird.
  3. Strongest-known Read. Wenn Veraltung für diesen Read inakzeptabel ist (Saldo-Check vor einer Zahlung), zwinge den Read, die Mehrheit der Replikas zu konsultieren.
await dd.updateAsync<GCounter>(
'hits',
GCounter.empty,
(c) => c.increment(dd.selfReplicaId(), 1),
{ consistency: 'majority', timeoutMs: 2_000 },
);

Wendet lokal an + schickt an die Gossip-Schicht und wartet dann auf Bestätigungen der konfigurierten Anzahl Replikas.

consistencyWorauf gewartet wird
'local' (Default)Nur auf sich selbst — das lokale Anwenden ist das ACK.
'majority'⌊N/2⌋ + 1 Replikas haben geACKt.
'all'Jede Replika der Up-Member hat geACKt.
{ from: 3 }from Replikas haben geACKt (begrenzt auf [1, N]).

Das Promise:

  • Resolved, wenn genug ACKs innerhalb von timeoutMs eintreffen.
  • Rejected mit einem Timeout-Fehler, wenn nicht.

Ein Timeout macht den lokalen Write nicht rückgängig — der Wert ist bereits lokal angewendet und gossipt normal weiter. Der Reject signalisiert nur “ich bin mir nicht sicher, ob genug Replikas ihn innerhalb der Deadline gesehen haben”.

const counter = await dd.getAsync<GCounter>('hits',
{ consistency: 'majority' });

Dieselben consistency-Optionen. Der Replicator fragt andere Replikas nach ihrer Sicht, merged die Antworten und gibt den gemergten Wert zurück.

Das heißt, ein Majority Read sieht mindestens jeden Write, der Majority-bestätigt wurde — den letzten “confirmed”-Wert.

ja — die meisten Fälle

nein — muss von genug
Replikas bestätigt sein

absolut nicht — jedes
Up-Member muss zustimmen

Sind veraltete Daten für DIESEN
Read/Write akzeptabel?

'local'

'majority'

'all'

'majority' ist der Sweet Spot für “wichtige” Reads/Writes — deckt die meisten Failure-Szenarien zu moderater Latenz ab. 'all' garantiert Konsistenz, scheitert aber, wenn auch nur eine Replika down (oder langsam) ist — das macht es spröde.

// Mit Majority schreiben — garantiert, dass andere Replikas Bescheid wissen
await dd.updateAsync('counter', ..., { consistency: 'majority' });
// Lokal lesen — schnell, und der Wert spiegelt (eventually) wider,
// was andere Writer mit Majority geschrieben haben
const value = dd.get('counter');

Das ist das häufige Produktionsmuster. Writes zahlen die Majority-Kosten; Reads sind billig. Der Cluster konvergiert irgendwann.

// Majority lesen — den letzten bekannten Wert im Cluster sehen
const balance = await dd.getAsync<PNCounter>('balance',
{ consistency: 'majority' });
if (balance.value() < 0) {
// ... Transaktion ablehnen
}

Für einmalige Reads, bei denen Veraltung zählt, zahl die Kosten für einen starken Read. Mach nicht jeden Read zu einem Majority Read — das hebelt das Local-First-Design aus.

await dd.updateAsync('config-locked', ..., { consistency: 'all' });

Selten — wenn du brauchst, dass jede Replika die Änderung gesehen hat, bevor es weitergeht. Spröde (jede ausgefallene Replika lässt die Operation scheitern), also wirklich nur für echt-unwiderrufliche Zustandsübergänge.

await dd.updateAsync('x', ..., {
consistency: 'majority',
timeoutMs: 5_000,
});

Ein Call ohne timeoutMs wartet quorumTimeout ab — 5 Sekunden, solange du nichts anderes setzt, unter actor-ts.distributed-data oder im Code beim start:

actor-ts.distributed-data {
quorum-timeout = 2s
}
const distributedDataOptions = DistributedDataOptions.create().withQuorumTimeout(2_000);
const dd = system.extension(DistributedDataId).start(cluster, distributedDataOptions);

Die Frist ist unabhängig vom Gossip-Intervall und ebenso von actor-ts.actor.ask-timeout, obwohl beide eingebaut bei 5 Sekunden liegen: Jener Key verschiebt den Default von ActorRef.ask, und wie lange eine Replika einen Quorum-Request für die Antworten ihrer Peers offen hält, ist eine andere Wartezeit. maxQuorumTimeout (unten) begrenzt den Default genau so wie ein timeoutMs, das du übergibst, und der Default muss positiv sein — 0 wird wie jede andere Frist gestellt, sie liefe also beim nächsten Timer-Tick ab: Ein Write scheiterte dort, und ein Read begnügte sich mit dem, was diese Replika allein hält, sofern nicht jede Replika schon geantwortet hätte. Pro Call überschreiben, wenn:

  • Strengeres Latenz-Budget — niedriger setzen; früh ablehnen, wenn Konsistenz nicht erreicht werden kann.
  • Lockerer — bei cross-region Clustern mit hoher Gossip-RTT das Timeout erhöhen.

Bei Timeout wirft das Promise einen Fehler, den du fangen kannst:

try {
await dd.updateAsync('x', ..., { consistency: 'majority', timeoutMs: 1_000 });
} catch (e) {
// Der Write hat lokal funktioniert, aber das Quorum kam nicht rechtzeitig.
// Entscheide: erneut versuchen, Fehler nach oben geben, Eventual-Consistency akzeptieren.
}

Jeder Quorum-Call, der sich nicht schon mit dem Self-ACK auflösen kann, parkt einen Eintrag — ein Promise, einen Timer, die Menge der Peers, auf die er wartet — bis genug Antworten da sind oder die Deadline abläuft. Zwei Settings begrenzen diese Menge, im Code oder über actor-ts.distributed-data:

import { DistributedDataId, DistributedDataOptions } from 'actor-ts/crdt';
const distributedDataOptions = DistributedDataOptions.create()
.withMaxPendingQuorumRequests(1_000)
.withMaxQuorumTimeout(30_000);
const dd = system.extension(DistributedDataId).start(cluster, distributedDataOptions);
OptionDefaultWirkung
maxPendingQuorumRequests1000Maximal offene Quorum-Requests gleichzeitig. updateAsync und getAsync teilen sich das Budget. 0 deaktiviert es.
maxQuorumTimeout30000Obergrenze in ms für die Frist eines Calls — sein timeoutMs oder, wenn er keines nennt, quorumTimeout; ein größerer Wert wird heruntergeschnitten. 0 deaktiviert sie.

Über dem Cap lehnt der Call sofort mit einem Fehler ab, der das Setting beim Namen nennt — er wird nicht eingereiht und wartet nicht:

try {
await dd.updateAsync('x', ..., { consistency: 'majority' });
} catch (e) {
// "DistributedData refused a quorum write on "x": 1000 quorum requests
// are already pending (max-pending-quorum-requests = 1000)"
}

Wie beim Timeout macht eine Ablehnung den lokalen Write nicht rückgängig — der Wert ist vor dem Quorum angewandt und gossipt normal weiter.

Mit aktivierten Metriken veröffentlicht der Replikator vier Serien — die Label-Mengen sind fest, sie kosten also eine Handvoll Serien und nicht mehr:

MetrikArtLabels
distributed_data_quorum_pendingGauge—
distributed_data_quorum_timeouts_totalCounteroperation = write | read
distributed_data_quorum_rejected_totalCounteroperation = write | read
distributed_data_dropped_values_totalCounter—

Alarmierungswürdig ist vor allem das letzte Paar. Ein steigendes ..._rejected_total heißt, dass Aufrufer dem Cap davonlaufen — entweder ein durchgegangener Producer oder ein für die Last zu niedriges Cap. Ein steigendes ..._dropped_values_total heißt, dass ein Peer CRDT-Payloads schickt, die diese Replika nicht dekodieren kann — ein kaputter oder feindlicher Peer, kein Tuning-Problem.