Zum Inhalt springen
Deutsch

Sharding — Überblick

Cluster-Sharding ist die Antwort des Frameworks auf “ich habe ein paar Millionen Entities, jede braucht ihren eigenen Actor, verteilt über N Nodes.” Beispiele: Per-User-Sessions, Per-IoT-Device-Controller, Per-Order-Koordinatoren, Per-Game-Room-Actors.

Der Nutzer gibt dem Framework eine Möglichkeit, eine Entity-ID aus jeder Nachricht zu extrahieren; das Framework hasht die ID auf einen Shard; der Koordinator entscheidet, welcher Node diesen Shard hostet; die lokale Region des Nodes routet an diesen Shard, der den Entity-Actor bei Bedarf spawnt. Wenn Nodes kommen und gehen, rebalanciert der Koordinator die Shards über die neue Topologie.

Cluster aus 3 Nodes

node-1 Region

node-2 Region

node-3 Region

Shards 1-33

Shards 34-66

Shards 67-100

Entities für Keys,
die in diese Shards hashen

Entities für Keys,
die in diese Shards hashen

Entities für Keys,
die in diese Shards hashen

Jede Entity ist ein Actor, auf einem Node, zu einer Zeit — genauso wie ein Singleton, aber skaliert auf N Entities. Failover passiert automatisch: wenn ein Node geht, wandern seine Shards woandershin und die Entities werden dort neu gespawnt.

import { match } from 'ts-pattern';
import { Actor } from 'actor-ts';
import { Cluster, ClusterBootstrapOptions, StartShardingOptions } from 'actor-ts/cluster';
type AddCommand = { entityId: string; kind: 'add'; sku: string };
type ViewCommand = { entityId: string; kind: 'view'; replyTo: ActorRef<Cart> };
type CartCommand = AddCommand | ViewCommand;
class CartActor extends Actor<CartCommand> {
private items: string[] = [];
override onReceive(command: CartCommand): void {
match(command)
.with({ kind: 'add' }, (c) => this.onAdd(c))
.with({ kind: 'view' }, (c) => this.onView(c))
.exhaustive();
}
private onAdd(command: AddCommand): void { this.items.push(command.sku); }
private onView(command: ViewCommand): void { command.replyTo.tell({ items: this.items }); }
}
// Setup — einzeiliger Cluster- + Sharding-Einstieg:
const { system, cluster } = await Cluster.bootstrap(ClusterBootstrapOptions.create('my-app'));
const startShardingOptions = StartShardingOptions.create<CartCommand>().withExtractEntityId((message) => message.entityId);
const cartRegion = cluster.sharding.start('cart', CartActor,
startShardingOptions);
// Verwendung — `tell` an die Region, mit Entity-ID in der Nachricht:
cartRegion.tell({ entityId: 'user-42', kind: 'add', sku: 'book-1' });
cartRegion.tell({ entityId: 'user-42', kind: 'view', replyTo: ... });
// ^^^^^^^^^^
// Gleiche ID → gleicher Entity-Actor, jedes Mal, unabhängig vom Node.

cluster.sharding.start() akzeptiert mehrere Aufruf-Formen — nimm die, die zur Entity passt. Die kürzeste lässt die Entity ihre eigene Identität deklarieren, wodurch weder Type-Name noch Entity-ID-Extractor am Aufrufort wiederholt werden:

class CartActor extends Actor<CartCommand> {
static readonly shard = ShardKey.of<CartCommand>('cart', (command) => command.entityId);
// ...
}
const cartRegion = cluster.sharding.start(CartActor);
const cart = cluster.sharding.entityRefFor(CartActor, 'user-42');

Die Identität eines ShardKey ist allein sein typeName; der Extractor reitet mit, damit die deklarierende Klasse die einzige Wahrheitsquelle ist — ein Node, der Entities nur nachschlägt, kann denselben Typ mit ShardKey.of<CartCommand>('cart') ohne Extractor benennen. Ein extractEntityId in den Options überschreibt den auf dem Key.

Die übrigen Formen bleiben unverändert:

// 1. Klassen-Kurzform:
const startShardingOptions = StartShardingOptions.create<CartCommand>().withExtractEntityId((m) => m.entityId);
cluster.sharding.start('cart', CartActor, startShardingOptions);
// 2. Factory-Kurzform — wenn die Entity Konstruktor-Argumente braucht:
const startSharding2Options = StartShardingOptions.create<CartCommand>().withExtractEntityId((m) => m.entityId);
cluster.sharding.start('cart', () => new CartActor(deps),
startSharding2Options);
// 3. Vollform — alle Settings über den Builder:
const startSharding3Options = StartShardingOptions.create<CartCommand>()
.withTypeName('cart')
.withEntityActor(CartActor)
.withExtractEntityId((m) => m.entityId)
.withNumShards(16)
.withRole('cart-host');
cluster.sharding.start(
startSharding3Options,
);

cluster.sharding ist eine memoisierte Fassade — wiederholte Zugriffe liefern dieselbe ClusterSharding-Instanz. Die explizite Form ClusterSharding.get(system, cluster) funktioniert weiter und liefert dasselbe Objekt; greif dazu nur, wenn Du die Klasse außerhalb eines Cluster-Handles brauchst.

Aus Sicht des Aufrufers ist die cartRegion ein einzelner ActorRef. Hinter den Kulissen:

  1. Die Region berechnet aus entityId einen Shard (Default: Hash auf einen von 64 Shards).
  2. Sie fragt den Koordinator “wem gehört dieser Shard?”
  3. Wenn der Besitzer dieser Node ist, spawnt sie die Entity (falls noch nicht vorhanden) und leitet die Nachricht weiter.
  4. Wenn der Besitzer ein anderer Node ist, leitet sie über den Cluster-Transport an dessen Region, die dasselbe macht.
ActorRolle
RegionEine pro Node. Routet Nachrichten an den Besitzer des richtigen Shards und entscheidet, wann lokale Entities — und leer gewordene Shards — passiviert werden.
ShardEiner pro hier gehostetem Shard, Kind der Region. Besitzt die Entity-Actors: spawnt sie, stoppt sie, puffert für eine, die gerade geht. Verschwindet selbst, sobald er sein Fenster lang leer stand, und kommt mit der nächsten Nachricht zurück.
KoordinatorEiner pro Cluster (Singleton, auf dem Leader). Entscheidet, welcher Node welchen Shard besitzt. Behandelt Rebalancing bei Mitgliedschaftsänderungen und beim Herunterfahren einer Region.
EntityEine pro entityId. Kind ihres Shards, auf dem Node, dem aktuell der Shard gehört, in den die ID hasht.

Damit haben Entities einen echten Pfad — /system/cluster/sharding/region-counter/shard-7/entity-user-42 — und genau das macht einen Shard überhaupt adressierbar. Siehe Introspektion zum Auflisten von Shards und zum Holen von Refs darauf.

Die Region ist das Thema dieser Seite; die Entscheidungen des Koordinators haben eigene Seiten — siehe die Allokationsstrategie und Rebalance für die Mechanik.

Eine Entity braucht fast immer die ID, über die sie geroutet wurde — für den Namen ihres Journal-Streams, ihres Pub/Sub-Topics oder einer Zeile in einer fremden Datenbank. Sie liest sie an sich selbst ab:

class CartEntity extends Actor<CartCommand> {
override preStart(): void {
this.log.info(`cart ${this.entityId} woke up in shard ${this.entity.shardId}`);
}
}
this.entityIdDer Wert, den extractEntityId zurückgegeben hat — unverändert.
this.entityDieselbe ID plus typeName und shardId.
this.context.entityDie Option-Form — None, wenn dieser Actor keine Entity ist. Die beiden Getter darüber werfen stattdessen.

Der häufigste Fall ist eine persistenceId pro Entity — genau das gibt einem geshardeten PersistentActor einen Event-Stream pro Entity statt einen pro Typ:

class CartEntity extends PersistentActor<CartCommand, CartEvent, CartState> {
override get persistenceId(): string { return `cart-${this.entityId}`; }
}

Die Identität sitzt auf der Entity und sonst nirgends — die eigenen Kinder einer Entity bekommen None, this.context.entity.nonEmpty beantwortet also „bin ich die Entity?“. Ein Kind, das die ID braucht, bekommt sie explizit weitergereicht.

Um eine Entity isoliert zu testen, gibst du ihr die Identität direkt, statt einen Cluster darum herum hochzufahren:

import { ActorOptions } from 'actor-ts';
const cartOptions = ActorOptions.create()
.withEntity({ entityId: 'user-42', typeName: 'cart', shardId: 3 });
const cart = system.spawn(CartEntity, 'cart-under-test', cartOptions);

.../shard-7/entity-user-42 sieht aus, als trüge er die ID, und für einfache IDs funktioniert das Abschneiden des entity--Präfixes auch. Es ist aber nicht die ID: Actor-Namen haben ein eingeschränktes Alphabet, deshalb maskiert der Shard beim Benennen des Kindes alles, was ein Name nicht tragen kann — eine Code-Unit außerhalb von [A-Za-z0-9_-.@:+] wird zu ~ plus vier Hex-Ziffern, user/42 heißt also entity-user~002F42.

Die Maskierung ist injektiv: zwei verschiedene IDs landen nie auf einem Namen. Das ist eine Korrektheitseigenschaft, keine Feinheit — ein geteilter Name bedeutet, dass die zweite Entity unter einem schon vergebenen Namen startet, und der resultierende Fehler reißt den Shard mitsamt allen anderen Entities darin mit.

Was sie nicht ist: eine zweite Schreibweise der ID. Nichts dekodiert ein Pfadsegment, bewusst, und die Maskierung ist kein Teil der API. Der Pfad ist ein Etikett; entityId ist der Wert.

ShardingOptionsType<TMessage> — die Felder, die du am häufigsten anfasst:

type ShardingOptionsType<TMessage> = {
typeName: string;
entityActor: ActorClassOrFactory<TMessage>;
entityOptions?: ActorOptions<TMessage>;
extractEntityId: (message: TMessage) => string;
extractEntityMessage?: (message: TMessage) => unknown;
numShards?: number; // Default 64
role?: string; // auf Nodes mit dieser Rolle beschränken
proxy?: boolean; // nur Routing, keine lokalen Entities
rememberEntities?: boolean; // Entities bei Failover neu spawnen (#)
passivationIdleMs?: number; // idle Entities auto-stoppen, Default 5 min
shardPassivationIdleMs?: number; // leere Shards auto-stoppen, folgt obigem
maxEntities?: number; // Cap für residente Entities, pro Typ pro Node
passivationReplacement?: EntityReplacementPolicy; // welche Entity das Cap hergibt
};
FeldWas es steuert
typeNameEin String, der diesen sharded Typ identifiziert. Verschiedene Typen können im selben Cluster koexistieren (cart, session, order).
extractEntityId(message)Zieh die Entity-ID aus einer Nachricht. Das ist der Key, der zu einem Shard gehasht wird.
extractEntityMessage(message)(Optional) Wenn der Nachrichten-Envelope Routing-Info plus eine Payload enthält, entfernt das den Envelope, bevor die Entity ihn sieht. Default ist die Nachricht unverändert.
numShardsIn wie viele Shards der Entity-Raum aufgeteilt wird. 64 reichen für die meisten Cluster; setze auf 1000 für sehr große Cluster (>50 Nodes). Muss auf jedem Node identisch sein, der diesen Typ startet oder proxyt — siehe unten.
roleNur Mitglieder mit dieser Rolle hosten Shards dieses Typs. Nützlich, um compute-schwere Entities auf dedizierten Nodes zu platzieren. Auch node-weit setzbar als actor-ts.sharding.role — siehe Platzierung aus der Config-Datei.
proxyDieser Node leitet Nachrichten an die Region weiter, hostet aber nie lokale Entities. Wird für Client-Nodes in einem asymmetrischen Cluster verwendet.
rememberEntitiesPersistiere die Menge der aktiven Entity-IDs. Nach einem Koordinator-Failover (oder vollem Cluster-Neustart) werden diese IDs eager gespawnt, sodass Nachrichten nicht die gesamte Flotte neu erstellen müssen.
passivationIdleMsStoppt eine Entity nach so viel Leerlaufzeit. Befreit Speicher; die nächste Nachricht für dieselbe ID erstellt die Entity neu. Default sind 5 Minuten; 0 schaltet es ab.
shardPassivationIdleMsStoppt einen Shard, nachdem er so lange leer stand. Ungesetzt folgt er passivationIdleMs; 0 hält leere Shards resident, während Entities weiterhin passivieren.
maxEntitiesWie viele Entities dieses Typs auf diesem Node resident sein dürfen. Wird das überschritten, wird eine passiviert, um Platz zu machen. 0 (Default) heißt kein Cap. Nicht node-weit: zwei gestartete Typen bekommen je die volle Zahl.
passivationReplacementWelche residente Entity das Cap hergibt — 'least-recently-used' (Default), 'segmented-least-recently-used' oder 'least-frequently-used'. Bei maxEntities 0 wirkungslos; siehe Wählen, was ein voller Node hergibt.

Die Defaults sind sinnvoll für kleine Cluster. Für Produktion willst du meistens rememberEntities: true und ein passivationIdleMs passend zu deinem Verkehrsmuster.

role ist die einzige Platzierungsoption mit einem HOCON-Key, denn welche Rolle einen Typ hostet, ist über ein Deployment hinweg einheitlich:

actor-ts.sharding.role = "backend"

Der Key gilt für jeden auf dem Node gestarteten Sharded Type ohne eigenes withRole, und ein explizites withRole sticht ihn weiterhin — die übliche Reihenfolge explizite Optionen > HOCON > Built-in-Defaults, pro Feld.

Was er nicht tut: einem Node die Rolle geben. Die eigenen Rollen eines Nodes sind eine eigene Einstellung, und zwar eine pro Node, während sharding.role überall gleich ist: ClusterOptions.withRoles im Code oder actor-ts.cluster.roles in der Config des Nodes, meist aus seiner Umgebung befüllt:

actor-ts.cluster.roles = [ ${?NODE_ROLE} ]
const clusterOptions = ClusterOptions.create()
.withHost('10.0.0.7')
.withPort(2551)
.withRoles(['backend']);

Setzt du nur sharding.role und kein Mitglied passt dazu, findet der Koordinator keinen Kandidaten, es wird nie etwas zugeteilt, und jede Nachricht für den Typ staut sich im Routing-Puffer der Region. Still ist das nicht — der Koordinator warnt einmal mit der Rolle, der Zahl der ausgeschlossenen registrierten Regionen und beiden Stellen, an denen ein Node seine Rollen deklariert — aber es ist eine Warnung und kein Startfehler, also lies sie.

proxy hat bewusst keinen Key: Es ist Topologie pro Node, ein zweites start mit abweichendem Wert wirft, und ein von allen Nodes geteiltes proxy = on ließe niemanden mehr etwas hosten.

Eine Shard-ID ist hash(entityId) % numShards, und jeder Node berechnet sie für sich. Zwei Nodes mit unterschiedlichen Werten legen dieselbe Entity-ID also in unterschiedliche Shards, jeder besitzt am Ende den Shard, den seine eigene Rechnung ergeben hat, und beide betreiben eine lebende Instanz der Entity — unter shard-6/entity-user-7 und shard-50/entity-user-7, Pfaden, die niemals kollidieren. Bei einer persistenten Entity heißt das zwei Schreiber auf einer persistenceId.

Deshalb reist der Wert in der Registrierung der Region mit, und der Koordinator verweigert eine Region, die nicht übereinstimmt:

ERROR [sharding] the coordinator refused to register region 'counter':
numShards must match across the cluster, but this node is configured
with 32 and the coordinator governs the type with 64.

Eine verweigerte Region bleibt oben und puffert weiter — sie bekommt nie einen Shard zugewiesen, die Fehlkonfiguration ist also ein Stillstand mit einem Fehler daneben statt eines stillen Splits. Korrigiere den Wert und starte den Node neu.

Eine Region, die vorher schon Shards gehostet hat, gibt sie auf der Stelle ab. Dieser Fall ist nicht exotisch: Genau ihn erzeugt ein Rolling Deploy in dem Moment, in dem die Leader-Rolle einen bereits aktualisierten Node erreicht. Die Region wurde vom vorherigen Leader akzeptiert, hält also echte Shards und echte Entities, und der neue Koordinator verweigert sie. Sie stoppt jeden dieser Shards — ein richtiger Stopp, damit die Entities darunter ihr postStop durchlaufen und eine persistente flusht — und gibt im selben Schritt den Besitz ab. Das macht aus der Verweigerung einen Stillstand auf diesem Node statt einer Hälfte eines Splits. Zurück kommt nichts, bevor die Werte übereinstimmen; der gepufferte Verkehr wartet.

Das ist naturgemäß asynchron: Eine Region registriert sich, nachdem start(...) zurückgekehrt ist, versucht es erneut, bis der Koordinator antwortet, und registriert sich bei jedem Leader-Wechsel neu. Es gibt keinen Aufruf, aus dem geworfen werden könnte — deshalb kommt das Urteil als Log-Zeile und nicht als Exception.

Zwei Konsequenzen, die man kennen sollte:

  • Ein Proxy-Node zählt mit. startProxy hasht genau wie eine hostende Region und braucht deshalb dasselbe numShards; wer einen aus einem bloßen Key in einem Cluster startet, der nicht den Default verwendet, bekommt ihn verweigert.
  • actor-ts.sharding.number-of-shards in einer von allen Nodes geteilten Konfigurationsdatei zu setzen ist der fehlerärmste Weg, sie im Gleichschritt zu halten.

Die Verweigerung übersteht auch einen coordinatorStateStore. Dieser Store erlaubt einem neuen Leader, den Reallokations-Sturm zu überspringen, indem er die Allokationskarte seines Vorgängers übernimmt, und jede Shard-ID in so einem Snapshot entstand unter dem Wert des schreibenden Koordinators — deshalb trägt ein Snapshot diesen Wert jetzt als Stempel, und einer, der unter einem anderen (oder, bei einem vor dem Stempel geschriebenen Snapshot, unter einem ungenannten) Wert entstand, wird als Ganzes verworfen, mit einem WARN, das beide Zahlen nennt. Eine Region, die der Koordinator bereits verweigert hat, wird übersprungen, auch wenn der Snapshot sie nennt. Ohne diese beiden Prüfungen setzte der Ladepfad die verweigerten Regionen direkt zurück in den Platzierungs-Pool: Ein Rolling Deploy, der den Wert ändert, hätte das Split-Routing über den Snapshot wiederhergestellt statt über den Registrierungs-Handshake — die einzige Stelle, an der die Werte verglichen werden.

Einen Snapshot zu verwerfen kostet einen Reallokationsdurchlauf, also genau das, was jeder Cluster ohne Store bei einem Leader-Wechsel schon immer tut — und die nächste Allokationsänderung unter dem neuen Leader schreibt einen gestempelten Snapshot, es passiert also einmal.

Denselben Typ auf einem Node zweimal zu starten — start() nach startProxy() oder umgekehrt — wirft. Der zweite Aufruf gab bisher die Region des ersten zurück, sodass ein Node, der eine hostende Region wollte, den Proxy bekam — dessen Platzhalter-Entity-Factory wirft, sobald lokal ein Shard landet.

Fünf davon sind auch HOCON-Keys — number-of-shards, remember-entities, passivation-idle, shard-passivation-idle und max-entities — ebenso die Koordinator-Keys rebalance-interval und hand-off-timeout sowie der ganze passivation-Unterblock, der entscheidet, welche Entity das Cap hergibt. Sie setzen die node-weite Grundeinstellung für jeden sharded Typ und liegen unter dem, was start(...) explizit übergibt — ein Per-Typ-Wert im Builder gewinnt also weiterhin. Siehe Konfiguration.

actor-ts.sharding {
number-of-shards = 128
passivation-idle = 2 minutes
max-entities = 50000
passivation.replacement = segmented-least-recently-used
}

Passivierung stoppt eine idle Entity, um Speicher freizugeben; die nächste Nachricht für dieselbe ID erstellt sie neu. Wie auch immer sie ausgelöst wird — die Region puffert Nachrichten, die eintreffen, während die Entity stoppt, und spielt sie an die frische Inkarnation zurück, sodass nichts verloren geht.

Das Standard-Idle-Fenster beträgt 5 Minuten. Setze passivationIdleMs — im Code oder über actor-ts.sharding.passivation-idle —, um es zu ändern, oder 0, um es abzuschalten und jede Entity für die Lebensdauer ihres Nodes resident zu halten.

Automatisch — wenn passivationIdleMs ohne Verkehr abläuft oder maxEntities überschritten wird (verdrängt wird die Entity, die die Ersetzungsstrategie benennt), wird die Entity gestoppt. Es wird nichts an die Entity geschickt, und es gibt keine Quittung. Die Entscheidung trifft die Region, weil nur sie den Verkehr über alle Shards dieses Nodes sieht — deshalb ist maxEntities eine Obergrenze pro Typ pro Node, nicht pro Shard — und der Shard, dem die Entity gehört, führt sie aus.

Manuell (graceful) — eine Entity bittet darum, passiviert zu werden, indem sie ein Passivate an ihren Parent schickt, also an ihren Shard. Passivate trägt eine Stop-Nachricht, die an die Entity zurückgeleitet wird, sodass die Entity genau entscheidet, wann und wie sie herunterfährt (laufende Arbeit abschließen, State flushen, dann terminieren). PoisonPill als Stop-Nachricht terminiert die Entity, sobald sie zurückkommt:

import { match } from 'ts-pattern';
import { PoisonPill, Actor } from 'actor-ts';
import { Passivate } from 'actor-ts/cluster';
type AddCommand = { entityId: string; kind: 'add'; sku: string };
type CheckoutCommand = { entityId: string; kind: 'checkout' };
type CartCommand = AddCommand | CheckoutCommand;
class CartActor extends Actor<CartCommand> {
private items: string[] = [];
override onReceive(command: CartCommand): void {
match(command)
.with({ kind: 'add' }, (c) => this.onAdd(c))
.with({ kind: 'checkout' }, () => this.onCheckout())
.exhaustive();
}
private onAdd(command: AddCommand): void {
this.items.push(command.sku);
}
// Mit dem Warenkorb fertig — die Region bitten, uns zu passivieren.
private onCheckout(): void {
this.context.parent.forEach((parent) =>
parent.tell(new Passivate(PoisonPill.instance, this.self), this.self));
}
}

Die Stop-Nachricht ist eine Bitte: die Entity entscheidet, wann sie darauf reagiert. Tut sie es nie, terminiert sie nie — und ihr Platz bleibt für die Lebensdauer des Nodes gegen maxEntities belegt. passivationStopTimeoutMs (actor-ts.sharding.passivation.stop-timeout) ist die Rückfallebene dafür: danach stoppt der Shard die Entity hart, genau so, wie es eine von der Region getriebene Passivierung tut.

Sie ist standardmäßig aus (0, unbegrenztes Warten), und zwar weil der kooperative Vertrag der Punkt ist. Eine Entity mitten im Leeren — ein langer Flush, ein langsamer letzter Write — darf so lange brauchen, wie das Leeren dauert, und ein harter Stopp bricht diesen Flush ab; nur du weißt, wie lange deiner legitim laufen darf. Setze sie dort, wo eine Entity, die nie auf die Nachricht reagiert, ein Fehler wäre, den es einzudämmen gilt. Sie ist von maxEntities unabhängig: ein positiver Wert schärft sie mit oder ohne Cap.

maxEntities sagt, wie viele Entities resident bleiben; passivationReplacement sagt, welche geht, wenn eine neue dazukommt. Jeder Regler hier ist wirkungslos, solange maxEntities 0 ist — der Default.

Die Default-Strategie 'least-recently-used' hat einen blinden Fleck: Aktualität kann einmal überhaupt benutzt nicht von bis eben ständig benutzt unterscheiden. Ein Durchlauf über einen großen kalten Schlüsselraum — ein nächtlicher Export, ein Crawler, ein Backfill — verdrängt dein Arbeitsset also Entity für Entity und hinterlässt einen Node voller IDs, nach denen nie wieder jemand fragt. Zwei Optionen beheben das, und sie greifen ineinander:

const shardingOptions = StartShardingOptions.create<CartCommand>()
.withTypeName('cart')
.withEntityActor(CartActor)
.withExtractEntityId((command) => command.entityId)
.withMaxEntities(50_000)
// Bewährung für eine einmal gesehene Entity, geschützt für eine erneut
// gesehene; verdrängt wird aus der Bewährung, ein Scan kann also nur einen
// anderen Scan verdrängen.
.withPassivationReplacement('segmented-least-recently-used')
.withPassivationSegmentedProtectedProportion(0.8)
// Ein kleines Fenster vor der Strategie, damit die bei der Aufnahme
// beurteilte Entity nie die ist, auf die eine Nachricht wartet.
.withPassivationAdmissionWindowProportion(0.01)
// …und was beurteilt: ein kompakter Sketch darüber, wie oft jede ID gesehen
// wurde — er erinnert sich auch an IDs, die der Node nicht mehr hält.
.withPassivationAdmissionFilter('frequency-sketch');

'least-frequently-used' ist die dritte Strategie — die wenigsten Zugriffe verlieren, wobei die Zähler periodisch halbiert werden, damit die Rangfolge dem jüngeren Verkehr folgt statt einer Lebenszeitsumme. Sie passt zu einem Arbeitsset, das stabil, aber nicht aktuell ist, etwa eine Geräteflotte, die in langsamem Takt meldet.

Der Filter braucht ein Fenster: eine Region kann die Entity, für die gerade eine Nachricht eingetroffen ist, nicht ablehnen — 'frequency-sketch' mit passivationAdmissionWindowProportion: 0 wird deshalb bei start(...) abgelehnt, statt still nichts zu tun. Alle fünf Regler sind zugleich HOCON-Keys unter actor-ts.sharding.passivation.

Alle Entities eines Shards zu passivieren ließ früher den Shard selbst zurück — einen lebenden Actor mit einer leeren Map. Außer einem Rebalance stoppte ihn nichts, und da Entity-IDs über den Hash-Raum streuen, wurde auf einem lang laufenden Node irgendwann jeder Shard einmal angefasst und blieb dann. Bei numShards = 64 sind das 64 idle Actors ohne Inhalt.

Deshalb wird auch ein Shard gestoppt, der shardPassivationIdleMs lang leer stand. Die Region behält die Ownership — nur der Actor geht —, der Shard bleibt also routbar, und die nächste Nachricht für ihn erstellt Shard und Entity gemeinsam neu, ohne Umweg über den Koordinator. Ungesetzt folgt das Fenster passivationIdleMs, was meistens genau richtig ist: ein Shard ist leer, gerade weil seine Entities idle wurden.

const shardingOptions = StartShardingOptions.create<CartCommand>()
.withTypeName('cart')
.withEntityActor(CartActor)
.withExtractEntityId((command) => command.entityId)
.withPassivationIdleMs(120_000)
// Shards sind billig zu halten und kosten einen Respawn, wenn sie gehen —
// auf einem belebten Node ist es ein guter Handel, sie ihre Entities eine
// Weile überleben zu lassen.
.withShardPassivationIdleMs(600_000);

Setze shardPassivationIdleMs: 0, um leere Shards resident zu halten, während Entities weiterhin passivieren. Region und Koordinator sind in beiden Fällen unberührt — sie laufen für die Lebensdauer des Nodes.

Gestoppt wird immer nur ein leerer Shard, es steht also kein Entity-State auf dem Spiel, und Nachrichten, die während des Stoppens eintreffen, werden genauso gepuffert und nachgespielt wie bei einer Entity. „Leer“ ist dabei die Antwort des Shards, nicht die Vermutung der Region: Die Region bittet einen Shard, den sie für leer hält, zu stoppen, und der Shard stoppt nur, wenn er weiterhin nichts hat — keine Entity, die die Nachricht direkt vor der Bitte erstellt hat, keine gemerkte Entity, die ein Recovery-Batch gerade gestartet hat, keine Entity im Backoff. Sonst bleibt er, die Region routet wieder zu ihm, und ein späterer Sweep fragt erneut. Auch eine Shard-Ref bleibt über die Lücke hinweg gültig — siehe Introspection, wo ShardInfo zusätzlich ein resident-Flag meldet, das einen passivierten Shard von einem bloß leeren unterscheidet.

Eine Entity, die ihre Arbeit nicht tun kann — eine Poison-Nachricht, ein Store, der nicht erreichbar ist, ein Start, der wirft —, fällt jedes Mal erneut aus, wenn sie neu erstellt wird. Drei Wege erstellen sie neu, und sie verhalten sich unterschiedlich:

  1. Eine Entity in ihrem Shard. Der Shard beaufsichtigt seine Entities wie jeder Parent: Eine ausgefallene Entity wird an Ort und Stelle neu gestartet, sofort, bis zu zehnmal pro Minute. Dieses Budget gehört dem Shard, alle Entities des Shards zehren also vom selben. Ist es aufgebraucht, wird die Entity gestoppt, und der Shard erstellt sie erst nach einer Wartezeit neu, entity-restart-backoff — siehe eine Entity, die immer wieder stoppt.
  2. Ein Shard in seiner Region. Ein Fehler, den der Shard nicht auffängt — eine Entity, deren eigene Strategie eskaliert, oder ein Fehler im Shard selbst —, erreicht die Region, und die stoppt den Shard, statt ihn neu zu starten. Jede Entity unter dem Shard stoppt mit ihm, und die Region vergisst sie.
  3. Ein Shard, der zurückkommt. Ein Shard, der gestoppt ist, ohne dass die Region es verlangt hat — also alles außer einer Übergabe, einer Passivierung oder einer Freigabe —, wird nach einer Wartezeit neu erstellt, shard-failure-backoff, nicht bei der nächsten Nachricht. Ist die Wartezeit um, erstellt die Region ihn neu, spielt nach, was auf ihn gewartet hat, und fragt bei rememberEntities den Koordinator nach den Entities des Shards, sodass sie ganz ohne Verkehr zurückkommen.

Solange der Shard unten ist, behält die Region seine Ownership: Nichts wird neu vergeben, und der Koordinator platziert den Shard weiterhin hier. Nachrichten für ihn warten im Region-Puffer gegen buffer-size — jenseits des Caps geht die neueste mit ihrem Sender an die Dead Letters — und werden mit ihren Sendern zugestellt, sobald der Shard zurück ist. Das betrifft, was die Region nach dem Tod des Shards routet. Was sie schon in einen Shard geroutet hatte, der ausfällt — Fall 2 oben —, und was seine Entity noch nicht erreicht hat, geht mit dem Shard verloren: Die Region erfährt vom Ausfall erst durch den Tod des Shards, und was in einem stoppenden Shard oder seinen Entities noch wartet, geht an die Dead Letters, jede Nachricht mit ihrem Sender. Eine Nachricht an eine gesunde Entity, die genau dann geschickt wird, wenn der Fehler ihrer Geschwister-Entity eskaliert, kann also verloren gehen. Der Neustart an Ort und Stelle, den das Stoppen ersetzt hat, behielt die Mailbox des Shards, riss aber jede Entity unter dem Shard mit, ohne dass die Region davon erfuhr. Nichts anderes holt den Shard früher zurück: keine Nachricht, keine Shard-Ref aus shardRefFor() (die bis dahin über die Region weiterleitet), keine wiederholte Platzierung und keine erneut geschickte Registry. Eine Nachricht an eine Shard-Ref, die nicht für eine Entity ist — etwa GetShardStats —, geht an die Dead Letters.

Jeder Tod in Folge verdoppelt die Wartezeit, von min bis max, gestreut um random-factor in beide Richtungen; ein Shard, der seit seiner Rückkehr reset-after lang nicht ausgefallen ist, beginnt beim nächsten Tod wieder bei min — eine Passivierung dazwischen ist kein Ausfall, ein kalter Shard, den eine Poison-Nachricht neu erstellt, wird also danach beurteilt, wie lange er gesund war, nicht nach den wenigen Millisekunden seiner neuen Inkarnation. Mit den ausgelieferten Werten ist ein Shard, der ab und zu ausfällt, nach etwa 200 ms zurück, und einer, der bei jedem Start ausfällt, wird etwa alle zehn Sekunden neu erstellt statt tausende Male pro Sekunde:

actor-ts.sharding.shard-failure-backoff {
min = 200ms # the first wait; must be > 0
max = 10s # the doubling stops here
random-factor = 0.2 # each wait spread by up to 20 % either way
reset-after = 60s # no failure for this long, and the next death waits min
}

Der Builder nimmt dieselben vier, in Millisekunden und als Anteil:

const shardingOptions = StartShardingOptions.create<CartCommand>()
.withTypeName('cart')
.withEntityActor(CartActor)
.withExtractEntityId((command) => command.entityId)
.withRememberEntities(true)
// The store behind these entities takes seconds to fail over: wait at
// least one, and never more than a minute.
.withShardFailureBackoffMinMs(1_000)
.withShardFailureBackoffMaxMs(60_000);

Was das für die eigene supervisorStrategy einer Entity bedeutet, gesetzt über entityOptions:

  • Ihre Neustarts geschehen sofort und gehen vom Budget des Shards ab. Eine Entity in einer Neustart-Schleife kann das Kontingent aufbrauchen, das ihre Geschwister gebraucht hätten, und nichts bremst sie, bis dieses Budget erschöpft ist; von da an bremst sie der Entity-Restart-Backoff unten.
  • Eine Strategie, die eskaliert, übergibt den Fehler dem ganzen Shard. Jedes Geschwister stoppt mit, und alle warten den Backoff des Shards ab. Eskaliere nur bei Fehlern, die bedeuten, dass der Shard selbst nicht weiterkann.

Jenseits des Neustart-Budgets wird eine Entity gestoppt, und die nächste Nachricht für sie hat bisher eine neue erstellt: Eine Entity, die bei jeder Nachricht ausfiel, wurde pro Nachricht neu erstellt — dreißig Instanzen für dreißig Nachrichten —, und jede öffnete ihre Recovery gegen das, woran sie scheiterte. Jetzt hält der Shard sie zuerst eine Weile unten, entity-restart-backoff, und die Wartezeit wächst, solange sie immer wieder stoppt.

Ein Shard kann nicht sehen, warum eine Entity gestoppt ist, also schickt er jeden Stopp, um den er nicht gebeten hat, in den Backoff: einen Ausfall jenseits des Budgets, einen Start oder eine Recovery, die immer wieder scheitert, einen Recovery-Fehler, den die Entity verschluckt hat, ein verlorenes Lease, ein schlichtes stopSelf. Der eine Stopp, um den er bittet, ist eine Passivierung — das eigene Passivate der Entity oder die Idle- und Kapazitäts-Passivierung der Region —, und eine so gestoppte Entity kommt bei der nächsten Nachricht sofort zurück. Stoppe eine Entity also mit Passivate, wenn du es so meinst, nicht mit stopSelf.

Die Neustarts innerhalb des Budgets bleiben sofort: Eine SupervisorStrategy hat keine Verzögerung zu vergeben, und dies ist die Wartezeit danach. Währenddessen:

  • Nachrichten für die Entity werden zurückgehalten, jede mit ihrem Sender, und in Reihenfolge übergeben, sobald sie zurück ist. Das Zurückhalten ist pro Shard auf buffer-size begrenzt, über die Entities des Shards zusammen; darüber hinaus geht die neueste mit ihrem Sender an die Dead Letters, mit einer Warnung pro Episode. Ein Shard, der stoppt, während er Nachrichten zurückhält, gibt sie ebenso an die Dead Letters.
  • Der Shard bleibt für die Wartezeit stehen. Ein Shard, dessen Entity im Backoff ist, ist nicht leer, auch wenn die Entity nicht läuft: Der Sweep für leere Shards lässt ihn in Ruhe, bis die Wartezeit um und nichts mehr zurückgehalten ist. Ein shardPassivationIdleMs, das kürzer ist als die Wartezeit, verwirft also weder, was zurückgehalten wird, noch beginnt es den Backoff von vorn.
  • Auch ein Start wartet. Ein StartEntity für die Entity — etwa an eine Shard-Ref geschickt — erstellt sie, wenn ihre Wartezeit endet, nicht sofort. Ist die Wartezeit um und nichts zurückgehalten, erstellt die nächste Nachricht die Entity sofort.
  • Die Region erfährt vom Stopp weiterhin: Bei rememberEntities wird die Entity als stopped verzeichnet, und sie wird nicht wiederbelebt, bis eine Nachricht für sie kommt.

Die Wartezeiten verdoppeln sich und setzen sich zurück wie die des Shards: Eine Entity, die seit ihrer Rückkehr reset-after lang nicht ungefragt gestoppt ist, beginnt wieder bei min, und eine Passivierung dazwischen ist kein Ausfall. Mit den ausgelieferten Werten wird eine Entity, die bei jeder Nachricht ausfällt, etwa alle zehn Sekunden neu erstellt: Dreißig Nachrichten im Abstand von 5 ms ergeben jetzt zwölf Instanzen — die erste, ihre zehn Neustarts innerhalb des Budgets und eine, wenn die Wartezeit endet — statt dreißig.

actor-ts.sharding.entity-restart-backoff {
min = 200ms # the first wait after the restart budget; must be > 0
max = 10s # the doubling stops here
random-factor = 0.2 # each wait spread by up to 20 % either way
reset-after = 60s # no unasked stop for this long, and the next one waits min
}

Der Builder nimmt dieselben vier:

const shardingOptions = StartShardingOptions.create<CartCommand>()
.withTypeName('cart')
.withEntityActor(CartActor)
.withExtractEntityId((command) => command.entityId)
// A cart's recovery reads a store that takes seconds to fail over:
// give it one before the first retry, and at most half a minute.
.withEntityRestartBackoffMinMs(1_000)
.withEntityRestartBackoffMaxMs(30_000);

Wenn sich die Cluster-Topologie ändert (ein Node tritt bei oder geht) — oder wenn eine Region stoppt und sich dabei beim Koordinator abmeldet —, führt der Koordinator einen Rebalance-Lauf durch:

  1. Berechne die neue Shard-zu-Node-Zuordnung aus der aktiven Allokationsstrategie (Default: Hash modulo Regionen).
  2. Sage für jeden bewegten Shard der alten Region, sie soll den Shard übergeben.
  3. Die alte Region stoppt ihre Entities (die ihren State persistieren können), sagt dem Koordinator “Handoff abgeschlossen” und hört auf, für diesen Shard zu routen.
  4. Die neue Region spawnt Entities für diesen Shard bei Bedarf, wenn Nachrichten ankommen.

Der Handoff ist nicht sofort fertig — gepufferte Nachrichten warten auf das “Handoff abgeschlossen”-Signal, bevor sie an den neuen Besitzer weitergeleitet werden. Das verhindert, dass Nachrichten an einer halb-verschobenen Entity vorbeisausen.

Siehe Rebalance für das vollständige Protokoll.

cluster.leave() übergibt die Shards dieses Nodes, bevor es irgendwem sagt, dass der Node geht, und wartet darauf:

  1. Jede Region, die der Node gestartet hat, stoppt ihre Shards und deren Entities. Jede Entity beendet die Nachricht, die sie gerade bearbeitet — der Schreibvorgang einer persistenten Entity landet — und durchläuft postStop; danach meldet die Region dem Koordinator, dass sie weg ist, und der verteilt ihre Shards neu.
  2. Die Koordinatoren des Nodes stoppen nach seinen Regionen, sodass ein Koordinator, der auf einem gehenden Leader noch aktiv ist, das Ende seiner eigenen Regionen mitbekommt und ihre Shards sofort neu verteilt — gemerkte Entities starten auf ihrem neuen Zuhause neu, ohne dass ihnen etwas geschickt wird.
  3. Erst dann wechselt der Node zu leaving und benachrichtigt seine Peers.

So verteilt kein Peer einen Shard neu, solange er hier noch läuft: Ein Shard hat nie zwei lebende Zuhause, und eine persistente Entity nie einen zweiten Schreiber. Das Warten ist durch das hand-off-timeout jedes Typs begrenzt. Eine Region, die bis dahin nicht gestoppt hat — eine Entity, die in ihrem Handler hängt, hält sie auf —, wird angewiesen, sofort zu stoppen, eine Warnung nennt sie, und das Verlassen geht ohne sie weiter; bis sie weg ist, kann diese eine Entity noch laufen, wenn ihr neues Zuhause sie startet.

Die Coordinated-Shutdown-Pipeline tut dasselbe in ihrer Phase cluster-sharding-shutdown-region, vor cluster-leave. Ein Node, den seine eigene Downing-Entscheidung entfernt hat, oder einer, der seinen Join aufgegeben hat, geht stattdessen sofort und stoppt sein Sharding neben dem Abgang: Die Peers, die ihn entfernt haben, warten auf keine Übergabe.

Sobald leave() aufgelöst ist, sind die Namen der Regionen und Koordinatoren wieder frei, sodass ein erneuter Beitritt auf demselben ActorSystem dieselben Typen über das sharding des neuen Clusters startet. Die Fassade des verlassenen Clusters verweigert jeden Start: Darüber gestartete Aktoren wären an einen Cluster gebunden, den es nicht mehr gibt.

Eine Nachricht, die unterwegs zum gehenden Node ist, während die Übergabe läuft, wird nicht zum neuen Zuhause mitgenommen — sie geht verloren, wie bei jeder Region, die stoppt. Die Übergabe bewegt Shards, keine Nachrichten im Flug.

Sharded Entities unterliegen denselben Neustart-Semantiken wie jeder andere Actor — wenn eine Entity zu einem neuen Node wandert, startet die neue Instanz mit weißer Weste.

Für State, der überleben soll:

  • PersistentActor — die Entity persistiert Events in einem Journal; auf einem frischen Node spielt sie das Journal beim Start ab. Siehe PersistentActor.
  • DurableStateActor — einfacher: persistiere den aktuellen State-Snapshot; restore beim Neustart. Siehe DurableState.
  • DistributedData — für State, der von jedem Node lesbar sein soll (nicht nur vom aktuellen Host der Entity), nutze ein CRDT im DD-Replicator stattdessen.

Ohne eine dieser Lösungen gibt dir Sharding Platzierung und Routing, aber keine Durability.

Der Coordinator hält wo jeder Shard lebt im Speicher, und ein neuer Leader beginnt mit einer leeren Karte, die er aus den Registrierungen der Regions wieder aufbaut. actor-ts.sharding.persist-coordinator-state = on (oder withPersistCoordinatorState()) hält diese Karte stattdessen im Journal der Persistence-Extension, sodass ein neuer Leader — oft ein gerade neu gestarteter Node, weil der Leader die niedrigste Adresse ist — mit der Karte beginnt, die der vorige zuletzt geschrieben hat (#1188):

actor-ts.sharding {
persist-coordinator-state = on
coordinator-state-load-timeout = 10s
}

Das Journal muss eine Datenbank für den ganzen Cluster sein — der nächste Leader liest, was der vorige geschrieben hat —, deshalb wird ein node-lokales Journal auf einem Node, der entfernte Peers erwartet, beim Start des Typs abgelehnt. Gehalten wird nur die jüngste Karte: Jedes Speichern kompaktiert die vorige, und ein Speichern von einem Coordinator, dessen Sicht auf den Stream veraltet ist, schlägt fehl, statt zu überschreiben.

Die Platzierung wartet nach einem Leader-Wechsel trotzdem auf die eigenen Ansprüche der Regions: Die Karte kann der letzten Zuteilung hinterherhinken, und erst die Registrierung einer Region belegt, was sie wirklich betreibt. Was die Karte beiträgt, sind die Regions selbst — ein neuer Leader bittet jede, die sie nennt, sich zu registrieren — und die Homes von Shards, die noch niemand beansprucht hat. Ein neuer Leader wartet höchstens coordinator-state-load-timeout auf das Laden der Karte und platziert danach ohne sie.

Drei gute Anwendungen:

  1. Per-User-/Per-Tenant-State, der zu viel für einen Node ist, aber nicht von überall gleichzeitig lesbar sein muss.
  2. Per-Entity-Workflows — Sagas, Order-Processing, lange laufende Koordinatoren — die von Per-Key-Serialisierung profitieren.
  3. Hotspots, die Keys folgen — eine Streaming-Pipeline, in der die Events jedes Users in Reihenfolge auf einem einzelnen Actor verarbeitet werden sollen.

Die API-Referenzen ClusterSharding und ShardRegion decken die vollständige Oberfläche ab, inklusive des Per-Node-Region-Actors.