Zum Inhalt springen
Deutsch

MultiNodeSpec

MultiNodeSpec lässt N Cluster-Nodes innerhalb eines Test-Prozesses laufen. Jeder ist ein echtes ActorSystem; sie kommunizieren via einen In-Process-Transport (kein TCP). Nützlich zum Testen von Cluster-Verhalten — Sharding, Singletons, Gossip- Konvergenz, Failover — ohne Docker.

import { MultiNodeSpec, TestProbe } from 'actor-ts/testkit';
// Jeder Rollenname ist ein Node — und zugleich dessen System-Name.
const spec = new MultiNodeSpec({ roles: ['a', 'b', 'c'] });
await spec.start();
await spec.awaitMembers('a', 3); // warten, bis der Cluster konvergiert
// Das ActorSystem jedes Nodes via systemFor(role) erreichen:
const node2 = spec.systemFor('b');
// Actor auf einem bestimmten Node spawnen und mit einer Probe asserten:
const probe = new TestProbe(spec.systemFor('a'));
const remote = node2.spawnAnonymous(Worker);
remote.tell({ kind: 'do', replyTo: probe });
await probe.expectMessage({ kind: 'done' });
await spec.stop();

Drei primäre Fälle:

  1. Cluster-Verhalten testen — Sharding-Rebalances, Singleton-Failover, Gossip-Konvergenz — diese ohne echtes Netzwerk-Setup verifizieren.
  2. Verteilte Bugs reproduzieren — leichter zu isolieren, wenn der gesamte Cluster in einem Prozess läuft.
  3. CI-freundliche Cluster-Tests — schnell (sub-Sekunde), kein Docker, keine Ports.

Für Tests, die echte Parallelität brauchen (echte OS-Threads — nebenläufige Journal-Schreibvorgänge, Scheduler-Interleaving), nutze ParallelMultiNodeSpec. Für echtes TCP/TLS oder Cross-Host-Latenz nutze einen externen Docker-Compose-Cluster.

type MultiNodeSpecOptionsType = {
roles: ReadonlyArray<string>; // ein Node pro Rolle; müssen eindeutig sein
seedRoles?: ReadonlyArray<string>; // Bootstrap-Seeds — Default [roles[0]]
addresses?: Record<string, { host: string; port: number }>;
failureDetector?: ClusterOptionsType['failureDetector'];
gossipIntervalMs?: number; // Default 100 (vs. 1 s in Produktion)
awaitTimeoutMs?: number; // Default 10_000 — wie lange await*-Helfer warten
logLevel?: LogLevel; // Default: ein leiser NoopLogger
downing?: (role: string) => DowningProvider | undefined;
failureDetectorAutoDown?: boolean; // Default ungesetzt = das ausgelieferte true
stableAfterMs?: number; // Default 100 (vs. 20 s in Produktion)
};
FeldZweck
rolesNode-Liste — jeder Eintrag ist ein Node, und der String ist zugleich dessen System-Name. Müssen eindeutig sein.
seedRolesWelche Rollen als Bootstrap-Seeds dienen. Default ist die erste Rolle.
addressesPer-Rolle Host/Port-Overrides. Automatisch vergeben, wenn ausgelassen.
failureDetectorFailure-Detector-Overrides — Tests ziehen diese meist enger, damit Crashes schnell erkannt werden.
gossipIntervalMsGossip-Runden-Intervall. Default 100 ms.
awaitTimeoutMsDefault-Timeout für die await*-Helfer. Default 10 s.
logLevelLog-Level — standardmäßig leise.
downingPer-Rolle Split-Brain-Resolver-Factory.
failureDetectorAutoDownOb der Failure Detector jedes Nodes einen Peer entfernt, den er für down erklärt. Ungesetzt bleibt es beim ausgelieferten true: Eine abgestürzte Rolle wird bei down-after entfernt, ein Spec, der Crash-Failover ohne downing-Strategie prüft, braucht also nichts weiter. false ist das Opt-out, das ein Spec setzt, um eine abgestürzte Rolle auf unreachable geparkt zu sehen, wo sie Mitglied bleibt. Der downing-Provider einer Rolle entscheidet deren Entfernungen, was immer dieser Schalter sagt.
stableAfterMsWie lange das Bild stillstehen muss, bevor downing gefragt wird. Default 100 ms — die ausgelieferten 20 s sind das Doppelte von awaitTimeoutMs, ein Spec mit dem Produktionswert liefe also ins Timeout, bevor sein Resolver überhaupt gefragt wurde.

Übergib ein einfaches Objekt wie gezeigt, oder baue es fluent mit MultiNodeSpecOptions.create().withRoles(['a', 'b', 'c']).

Jeder Eintrag in roles ist ein eigener Node — der String ist die Identität dieses Nodes und sein ActorSystem-Name, muss also eindeutig sein (der Konstruktor wirft bei Duplikaten oder leerer Liste). Standardmäßig ist die erste Rolle der einzige Bootstrap-Seed; überschreibe das mit seedRoles:

const spec = new MultiNodeSpec({
roles: ['seed', 'worker-1', 'worker-2'],
seedRoles: ['seed'],
});
await spec.start();

Ports werden automatisch auf 127.0.0.1 vergeben; fixiere bestimmte via addresses, wenn ein Test feste Endpunkte braucht:

const spec = new MultiNodeSpec({
roles: ['a', 'b'],
addresses: { a: { host: '127.0.0.1', port: 2551 } },
});

Alle Nodes teilen sich:

  • Einen gemeinsamen In-Process-Nachrichtenbus — sie können miteinander reden.
  • Dasselbe Gossip-Protokoll — Membership konvergiert.
  • Unabhängige Actor-Systeme — separate Dispatcher, Scheduler, Supervisor-Bäume.

Das heißt:

  • Echte Cluster-Semantik — Mitglieder kommen hoch, Gossip konvergiert, Failure-Detector beobachtet, Sharding rebalancet.
  • Keine Serialisierung — Nachrichten zwischen „Nodes” werden per Referenz übergeben (in-process). Kein Fit zum Testen serialisierungs-abhängigen Verhaltens.

Zwei Wege, einen Node herunterzunehmen: crash(role) reißt dessen Transport abrupt weg (Peers erkennen das über den Failure-Detector), und leave(role) führt einen sauberen Cluster-Austritt durch.

// Singleton-Failover verifizieren:
const spec = new MultiNodeSpec({
roles: ['a', 'b', 'c'],
failureDetector: { heartbeatIntervalMs: 50, unreachableAfterMs: 200, downAfterMs: 400 },
// Keine Downing-Strategie: Das ausgelieferte auto-down entfernt den abgestürzten Node bei downAfterMs.
});
await spec.start();
await Promise.all([
spec.awaitMembers('a', 3),
spec.awaitMembers('b', 3),
spec.awaitMembers('c', 3),
]);
// ... den Singleton auf jedem Node starten ...
// Den aktuellen Host ermitteln, dann crashen:
const host = spec.clusterFor('a').leader().toNullable();
await spec.crash('a');
// Warten, bis die Überlebenden ohne 'a' neu konvergieren:
await spec.awaitMembers('b', 2);
// ... asserten, dass der Singleton zu einem Überlebenden umgezogen ist ...
await spec.stop();

crash(role) entfernt den Node abrupt; die Detectors der anderen markieren ihn nach unreachableAfterMs als unreachable und erreichen bei downAfterMs das Urteil down. Was dieses Urteil bewirkt, entscheidet der Spec: Per Default entfernt der Detector den Node, wie oben — failureDetectorAutoDown ungesetzt bleibt beim ausgelieferten true; die downing-Strategie einer Rolle entscheidet stattdessen; und mit failureDetectorAutoDown: false ohne Strategie bleibt der Node Mitglied auf unreachable — kein Shard wird neu vergeben, und kein entfernter Watcher bekommt Terminated. Die await*-Helfer ersetzen fragile setTimeout-Schlafphasen — sie pollen, bis die Bedingung gilt (oder werfen nach awaitTimeoutMs).

restart(role) bringt eine Rolle an derselben Adresse als neuen Prozess zurück — die Form eines Pod-Austauschs. Das alte System wird gecrasht und beendet, ein frisches System mit Cluster tritt an seiner Stelle mit einer neuen Inkarnation bei, und die anderen Mitglieder sehen den alten Lauf enden, bevor der neue beitritt. withNodeSetup läuft auf jedem Node nach seinem Beitritt und erneut auf einem neu gestarteten, sodass die Sharding-Typen, Singletons und Abonnements, die ein Test startet, auch auf dem neuen Node existieren.

const spec = new MultiNodeSpec(MultiNodeSpecOptions.create()
.withRoles(['a', 'b', 'c'])
// Läuft auf jedem Node, sobald er beigetreten ist — und erneut auf einem neu gestarteten.
.withNodeSetup((role, system, cluster) => {
cluster.sharding.start(shardingOptions);
}));
await spec.start();
const oldRun = spec.clusterFor('a').selfAddress.incarnation;
await spec.restart('a'); // gleiche Adresse, neuer Prozess
await spec.awaitMembers('b', 3);
expect(spec.clusterFor('a').selfAddress.incarnation).not.toBe(oldRun);

Die Seeds des neu gestarteten Nodes sind die anderen laufenden Rollen, ein neu gestarteter Seed tritt also wieder dem Cluster bei, den er gegründet hat. Mit restart(role, { seeds: [] }) gründet er stattdessen einen eigenen — die Gabelung, um die es in Issue #1176 geht. Referenzen aus systemFor / clusterFor von vor dem Neustart benennen den alten Node; danach erneut abfragen.

partition und crash beschreiben ein Netz, das perfekt oder durchtrennt ist. Dazwischen liegt jeder Zustand, in dem ein Cluster tatsächlich läuft: ein Fünftel der Gossip-Pushes verloren, Frames, die einander überholen, ein Peer, der langsam statt tot ist. degrade(roleA, roleB, profile) ist diese Mitte, restore(roleA, roleB) nimmt sie zurück.

Eine partition, die downAfterMs überdauert, verhält sich wie in Produktion: Ohne downing-Strategie entfernt jede Seite die andere und läuft allein weiter, und ein späteres heal bringt die beiden nicht wieder zusammen (Issue #930). Ein Spec, der eine Seite gewinnen lassen will, gibt den Rollen über downing eine Strategie.

const spec = new MultiNodeSpec(MultiNodeSpecOptions.create()
.withRoles(['a', 'b', 'c'])
.withScheduler(new ManualScheduler())
.withFaultSeed(20_231));
await spec.start();
// Der Cluster bildet sich auf einem sauberen Netz, danach wird es schlechter.
spec.degrade('a', 'b', {
dropProbability: 0.2, // ein Fünftel der Frames kommt nie an
duplicateProbability: 0.1, // ein Zehntel kommt doppelt an
reorderWindow: 4, // bis zu vier Frames dürfen einander überholen
latencyMs: 50, // auf dem Scheduler der Spec gemessen
});
await spec.advanceUntil(
() => spec.clusterFor('a').getMembers().filter((m) => m.status === 'up').length === 3,
{ budgetMs: 60_000, description: 'die Sicht konvergiert trotz der Verluste' },
);
spec.restore('a', 'b');

Jedes Feld ist optional und steht per Default auf „kein Fehler”, ein Profil nennt also nur, was es ändert. degrade wirkt beidseitig wie partition; für eine einseitige Verschlechterung greifst du zu spec.faultsFor(role).degradeTo(address, profile).

Jede Entscheidung stammt aus einem geseedeten Generator pro Node, gezogen in Sende-Reihenfolge — und unter einem geteilten ManualScheduler ist diese Reihenfolge selbst deterministisch. Ein rot gewordener Lauf reproduziert also exakt, und die Timeout-Meldungen der Spec nennen den Seed dazu:

MultiNodeSpec: timeout after 10000 ms — awaitMembers(a, expected=3) — current: 2
Faults were injected on: a, b. Reproduce with withFaultSeed(20231).

Das ist kein Detail. Ein nicht reproduzierbarer Chaos-Test ist ein Flake-Generator; ein fester Seed macht den Unterschied — der Preis ist, dass die Suite von sich aus keine neuen Netze mehr findet. Variiere den Seed bewusst (eine Schleife über withFaultSeed), wenn die Frage „gilt das für viele Netze” lautet und nicht „gilt das für das Netz, das kaputtging”.

Eine Verzögerung von der Wanduhr würde genau die Timing-Abhängigkeit zurückholen, die ManualScheduler beseitigen soll — sie wird deshalb abgelehnt statt stillschweigend genommen: ein latencyMs ungleich null ohne Scheduler wirft schon bei der Konstruktion. Die anderen drei Fehler brauchen gar keine Uhr.

Ein Fenster von n hält bis zu n Frames zurück und gibt sie als eine permutierte Charge frei; ein Frame verschiebt sich also um weniger als n Positionen. Genau diese Schranke ist der Punkt: ein Shuffle könnte einen Frame ans Ende des Laufs permutieren und einen Test auf etwas warten lassen, das nie kommt. Die letzte unvollständige Charge geben restore, stop und die nächste volle Charge frei — kontinuierliches Gossip erledigt Letzteres von allein.

FaultyTransport ist ein Dekorator: InMemoryTransport, MultiNodeTransport und MessageChannelTransport bekommen dieselben Regler, ohne dass einer von ihnen Fehler-Logik dazubekommt. Außerhalb einer Spec:

const link = new FaultyTransport(new InMemoryTransport(address), { dropProbability: 0.2 });

MultiNodeSpec hat keine Probe-Factory — konstruiere eine TestProbe gegen das System des Nodes, den du beobachten willst:

const probeA = new TestProbe(spec.systemFor('a')); // Probe auf Node 'a'
const probeB = new TestProbe(spec.systemFor('b')); // Probe auf Node 'b'

Jede Probe ist an das Actor-System eines Nodes gebunden. Nützlich beim Testen von Routing — verifizieren, dass eine Nachricht auf dem erwarteten Node landet.

Starte eine Sharding-Region auf jedem Node über dessen Cluster — erreiche jede via clusterFor(role):

const spec = new MultiNodeSpec({ roles: ['a', 'b', 'c'] });
await spec.start();
await spec.awaitMembers('a', 3);
const startShardingOptions = StartShardingOptions.create<Command>()
.withTypeName('entity')
.withEntityActor(Entity)
.withExtractEntityId((message) => message.id);
const regions = spec.allRoles().map((role) =>
spec.clusterFor(role).sharding.start(startShardingOptions)
);
// Entities spawnen; verifizieren, dass sie sich über Nodes verteilen:
for (const id of ['e1', 'e2', 'e3', 'e4', 'e5']) {
regions[0].tell({ id, kind: 'wake-up' });
}
await spec.stop();

Der Koordinator des Frameworks verteilt Shards über die Nodes wie in einem echten Cluster.