Coordinated Shutdown
system.terminate() stoppt das Actor-System, aber eine
Produktions-App hat normalerweise vor dem Stopp noch Arbeit:
laufende HTTP-Requests drainen, dem Cluster sagen, dass du gehst,
ein Journal flushen, Broker-Verbindungen schließen. Und diese
Schritte haben eine Reihenfolge — übergib die Shards der
Sharding-Region bevor du den Cluster verlässt; stoppe den
HTTP-Server bevor die Actors, die Requests behandeln.
Coordinated Shutdown ist das DSL dafür. Du registrierst Tasks
gegen benannte Phasen; das Framework führt sie in
Abhängigkeitsreihenfolge aus, eine Phase nach der nächsten, jede mit
einem Timeout-Cap. Ein Aufruf von run() aus einem beliebigen
Trigger (SIGTERM, K8s-PreStop-Hook, ein Admin-Endpoint) führt die
ganze Pipeline einmal aus.
Das minimale Beispiel
Abschnitt betitelt „Das minimale Beispiel“import { ActorSystem, CoordinatedShutdownId, Phases, type Reason,} from 'actor-ts';
const system = ActorSystem.create('my-app');const coordinatedShutdown = system.extension(CoordinatedShutdownId);
coordinatedShutdown.addTask(Phases.ServiceUnbind, 'close-http', async (reason) => { await httpServer.close();});
coordinatedShutdown.addTask(Phases.ServiceRequestsDone, 'drain-in-flight', async () => { await waitForInFlightRequests(/* bis zu 10s */);});
await system.runUntilTerminated(); // SIGTERM/SIGINT → die Pipeline → löst auf, wenn sie fertig istDrei Dinge passieren, wenn SIGTERM ankommt:
- Die Runtime ruft
coordinatedShutdown.run(new ProcessTerminateReason('SIGTERM')). - Die Phasen laufen in kanonischer Reihenfolge. Innerhalb jeder Phase laufen alle registrierten Tasks parallel; die Phase wartet auf alle (oder auf ihre Timeouts).
- Die Pipeline endet mit dem eingebauten
actor-system-terminate-Task, dersystem.terminate()für dich aufruft.
Ein Teil dessen, was dazwischen passiert, ist bereits verdrahtet; der Rest ist das, was du hinzugefügt hast.
Die 12 kanonischen Phasen
Abschnitt betitelt „Die 12 kanonischen Phasen“In Ausführungsreihenfolge gelistet. Verdrahtet markiert die Phasen, die das Framework selbst füllt — alles andere ist leer, bis du etwas registrierst.
| # | Phasen-Name | Verdrahtet | Typische Tasks |
|---|---|---|---|
| 1 | before-service-unbind | — | Letzte Ankündigungen, bevor der Server keine Verbindungen mehr akzeptiert. |
| 2 | service-unbind | system.http(...).bind(...), DevTools | HTTP-Server / gRPC-Server / WebSocket-Listener stoppen, neue Verbindungen anzunehmen. |
| 3 | service-requests-done | — | Auf das Ende laufender Requests warten; den Rest abbrechen. |
| 4 | service-stop | Broker-Actors (MQTT, Kafka, NATS, AMQP, …) | Client-Verbindungen schließen, Sockets freigeben. |
| 5 | before-cluster-shutdown | — | Optionale Pre-Cluster-Leave-Hooks. |
| 6 | cluster-sharding-shutdown-region | Cluster.join(...) | Der Sharding-Region sagen, Entitäten zu übergeben. |
| 7 | cluster-leave | Cluster.join(...) | Ein Cluster.leave() ausgeben — Leaving-Status gossipen. |
| 8 | cluster-exiting | — | Warten, bis der Cluster den Leave bestätigt. |
| 9 | cluster-exiting-done | — | Cluster-Übergang als abgeschlossen bestätigen. |
| 10 | cluster-shutdown | — | Cluster-Transports abbauen. |
| 11 | before-actor-system-terminate | — | Letzte Chance für App-Level-Cleanup (Journals flushen, Broker schließen). |
| 12 | actor-system-terminate | der eingebaute Terminator | Der eingebaute system.terminate()-Task. |
Du musst nicht jede Phase verwenden. Leere Phasen sind No-Ops; nur Phasen mit registrierten Tasks tun etwas.
Die verdrahteten Tasks abwählen
Abschnitt betitelt „Die verdrahteten Tasks abwählen“Setze actor-ts.coordinated-shutdown.auto-register-tasks = false, und
das Framework registriert keinen davon. Die Phasen bleiben, der
eingebaute Terminator bleibt, und jede Ressource oben liegt in deiner
Hand — gedacht für einen Einbettenden, dem der Lebenszyklus dessen
gehört, was er dem System übergeben hat. Es ist ein einzelner
Schalter statt einer pro Subsystem, denn der Grund, danach zu greifen,
lautet immer „mir gehört der Lebenszyklus” und nie „binde den
HTTP-Server ab, aber überlass mir die Broker”.
Die Phases-Konstante exportiert die kanonischen Namen — bevorzuge
sie gegenüber String-Literalen für Autocomplete:
import { Phases } from 'actor-ts';
coordinatedShutdown.addTask(Phases.ServiceUnbind, ...); // ✓ typisiertcoordinatedShutdown.addTask('service-unbind', ...); // ✗ Stringly-typed, kein Auto-CompleteEigene Phasen hinzufügen
Abschnitt betitelt „Eigene Phasen hinzufügen“Für app-spezifische Arbeit, die nicht in eine kanonische Phase passt, deklariere deine eigene:
coordinatedShutdown.addPhase({ name: 'flush-metrics', timeoutMs: 3_000, dependsOn: [Phases.BeforeActorSystemTerminate], recover: true,});
coordinatedShutdown.addTask('flush-metrics', 'push-prometheus', async () => { await metricsRegistry.flush();});Das dependsOn-Feld macht die Ordnung DAG-förmig statt linear —
deine Phase läuft nach before-actor-system-terminate.
Sie landet damit aber nicht automatisch vor
actor-system-terminate. Beide werden in derselben Runde der
topologischen Sortierung fertig — actor-system-terminate hat dieselbe
einzelne Abhängigkeit —, und dann entscheidet der alphabetische
Tie-Breaker der Sortierung: flush-metrics oben läuft also nachdem
das System terminiert ist. Erst die Gegenkante platziert die Phase,
und die gibt es als depends-on aus der Konfiguration (unten), das
den bestehenden Kanten einer kanonischen Phase hinzugefügt wird. Aus
dem Code heraus: benenne eine Phase, deren Nachfolger nicht die ist,
der du vorangehen musst.
Weil addPhase verlangt, dass jeder dependsOn-Eintrag eine
bereits registrierte Phase benennt, lässt sich ein Zyklus gar
nicht erst bilden. Die Reihenfolge selbst wird durch einen
topologischen Sort berechnet, wenn run() ausgeführt wird —
dieser Sort würde Error: cycle in phase dependencies werfen,
falls je ein Zyklus entstünde.
Aus der Konfiguration
Abschnitt betitelt „Aus der Konfiguration“Derselbe Graph lässt sich in HOCON ausdrücken, unter
actor-ts.coordinated-shutdown.phases — ein Kind pro Phasenname,
jedes mit timeout, recover und depends-on:
actor-ts.coordinated-shutdown.phases { flush-metrics { timeout = 3s recover = true depends-on = ["before-actor-system-terminate"] } actor-system-terminate { depends-on = ["flush-metrics"] }}Ein Name, der eine der zwölf kanonischen Phasen benennt,
verschmilzt mit ihr; jeder andere deklariert eine neue, und
dort ist depends-on Pflicht — eine Phase ohne Kanten landet im
ersten fertigen Batch und liefe vor before-service-unbind.
Beachte, was das zweite Kind bringt. depends-on an einer
kanonischen Phase wird der bestehenden Kante hinzugefügt, nie
ersetzt; flush-metrics dort zu nennen ist also das, was deine
Phase tatsächlich vor actor-system-terminate setzt statt
lediglich hinter before-actor-system-terminate — sonst würden
beide in derselben Runde fertig und der alphabetische Tie-Breaker
des Sorts entschiede. Dieselbe additive Regel verhindert, dass
eine Config-Datei cluster-leave vor service-unbind umhängt:
der Sort fängt Zyklen ab, nicht eine Pipeline, die still in der
falschen Reihenfolge läuft.
Die Reihenfolge in der Datei ist egal — zwei Phasen dürfen einander
benennen und werden abhängigkeitsweise registriert. Ein nicht
auflösbarer Name, ein Zyklus, ein unbekanntes Setting unter einer
Phase oder eine deklarierte Phase ohne depends-on ist ein
ConfigError beim Bau der Extension, nicht beim Shutdown.
Was die Verschmelzung ergeben hat, verrät phaseDefinition:
coordinatedShutdown.phaseDefinition('flush-metrics');// { name: 'flush-metrics', timeoutMs: 3000, dependsOn: [...], recover: true }Task-Semantik
Abschnitt betitelt „Task-Semantik“Jeder Task ist eine Funktion von Reason zu void | Promise<void>:
type ShutdownTask = (reason: Reason) => Promise<void> | void;Der reason lässt einen Task auf den Grund des
Shutdown-Triggers branchen:
coordinatedShutdown.addTask(Phases.BeforeClusterShutdown, 'deregister', async (reason) => { if (reason instanceof ClusterDowningReason) { // Wir wurden gedownt — die Registry hat uns bereits abgeschrieben. return; } await serviceRegistry.deregister(cluster.selfAddress.toString());});Eingebaute Reason-Klassen:
| Klasse | Wann |
|---|---|
ProcessTerminateReason(signal) | SIGTERM/SIGINT, aus runUntilTerminated() oder installProcessHooks(). |
ActorSystemTerminateReason | Was system.terminate() übergibt, wenn es die Pipeline ausführt — verlangt mit runCoordinatedShutdown: true oder per Default mit actor-ts.coordinated-shutdown.run-by-actor-system-terminate an. Ein gewöhnlicher Shutdown, den dein Programm beschließt, ist dieser Aufruf statt eines run(), dem du diesen Grund übergibst: Der Aufruf fährt das System auch dann herunter, wenn der Lauf es nicht tut. |
ClusterLeavingReason | Was shutdown() von Cluster.bootstrap übergibt — ein Mitglied, das absichtlich geht. |
ClusterDowningReason | Was ein Knoten übergibt, wenn ihn seine eigene Downing-Entscheidung entfernt und actor-ts.cluster.run-coordinated-shutdown-when-down an ist — siehe wenn der Cluster diesen Knoten downt. |
ClusterJoinUnsuccessfulReason | Was ein Knoten übergibt, wenn er seinen Join aufgibt — actor-ts.cluster.shutdown-after-unsuccessful-join ist abgelaufen, ohne dass ihn etwas befördern kann —, und was Cluster.bootstrap übergibt, wenn sein Readiness-Warten scheitert oder wenn es nach dem Aufbau seines Systems den Start verweigert; siehe wenn kein Seed je antwortet. Ein Lauf damit endet nie mit 0. |
StartupFailedReason(phase, task, cause) | Was das System übergibt, wenn ein Task des Starts fehlgeschlagen ist oder das Budget seiner Phase überschritten hat — sie nennt Phase und Task und trägt die Ursache. |
UnknownReason | Der Default, wenn run() ohne Argument aufgerufen wird. |
Auch ein fehlgeschlagener Start führt diese Pipeline aus: das System
startet sie mit einem StartupFailedReason und fährt danach herunter,
was auch immer die Pipeline getan hat — ein Task hier kann also einen
Knoten, der nie fertig hochgefahren ist, von einem unterscheiden, der
gestoppt wird. Den Prozess beendet er auch nicht mit einem Status, der
sich wie ein sauberer Stopp liest: Mit exit-process = on endet er mit
exit-code, wenn dieser nicht 0 ist, und mit 1, wenn er es ist —
nach derselben Regel wie ein Lauf, der anhält.
Beim Default exit-process = off scheitert stattdessen
runUntilTerminated() mit dem Fehler des Starts, und ein main, das
darauf wartet, endet von selbst mit einem Status ungleich null.
Ein Knoten, der nicht beitreten konnte, führt sie ebenfalls aus, und sein
Grund sagt es. ClusterJoinUnsuccessfulReason kommt, wenn der Join
aufgibt, wenn das Readiness-Warten von Cluster.bootstrap scheitert — das
früher ClusterLeavingReason übergab; ein Task, der einen gescheiterten
Start an diesem Grund erkannte, sieht jetzt diesen — und wenn der Bootstrap
nach dem Aufbau seines Systems nicht weitermacht, sofern
run-by-actor-system-terminate diesen Abbau zu einem Lauf macht. Keiner
davon beendet den Prozess von selbst: Der eingebaute Terminator beendet das
Actor-System, und der Prozess endet nur mit
actor-ts.coordinated-shutdown.exit-process = on, und dann nach der Regel
oben: Ein Knoten, der nicht beitreten konnte, hat ebenfalls nicht sauber
gestoppt, und ein Fehlschlag endet nie mit 0. Der Bootstrap nennt den
Grund auf ERROR, bevor der Lauf beginnt, weil der Exit kommt, bevor sein
Fehler dein main erreichen könnte.
Du kannst Reason für app-spezifische Trigger subklassen
(AdminEndpointReason, HotReloadReason, etc.).
Parallelität innerhalb einer Phase
Abschnitt betitelt „Parallelität innerhalb einer Phase“Alle Tasks in einer Phase laufen gleichzeitig — sie werden
zusammen gestartet, und die Phase wartet auf den letzten (oder
seinen Timeout). Wenn du innerhalb einer Phase
Ordnungs-Anforderungen hast (Task B muss auf Task A warten), packe
sie in unterschiedliche Phasen mit einem dependsOn.
Timeouts
Abschnitt betitelt „Timeouts“Jede Phase hat ein timeoutMs (Default 5 s); jeder Task wird in
einen Timeout-Race gewickelt. Ein Task, der nicht rechtzeitig
fertig wird, wird geloggt und entweder:
-
Wiederhergestellt (die Phase fährt fort,
recover: true— der Default). Die nächste Phase startet. -
Hält die Pipeline an (
recover: false). Nachfolgende Phasen werden nicht ausgeführt; der Shutdown stoppt mitten im Flug. Ein Lauf, denterminate({ runCoordinatedShutdown: true })gestartet hat, endet trotzdem im Teardown, denn dieser Aufruf hat ein terminiertes System verlangt; ebenso ein Lauf, den ein Signal, die eigene Downing-Entscheidung dieses Knotens oder ein Join, der nicht zustande kam, gestartet hat — auf diese Läufe wartet niemand, also beantwortet der Lauf seinen Halt selbst —, es sei denn,terminate-actor-system = falselegt fest, dass die Pipeline das System nie herunterfährt. In beiden Fällen wird der Halt als ERROR geloggt. Einrun(), das du selbst mit einem anderen Grund aufrufst, scheitert mit dem Fehler des Tasks und lässt das System so, wie der Halt es vorgefunden hat.Mit
exit-process = onendet stattdessen der Prozess am Halt, gleich welcher Auslöser den Lauf gestartet hat — ein Signal,terminate(), dein eigenesrun()oder der Cluster —, und zwar mit einem Status, der sich nicht wie ein sauberer Stopp liest:exit-code, wo dieser nicht0ist,1, wo er es ist. Nach dem Exit läuft nichts mehr, er tritt also an die Stelle dieser Teardowns — nicht aber an die Stelle dessen, was sie auf dem Weg nach unten flushen: Die Schreibvorgänge der Dead-Letter-Queue und danach die Log-Sinks werden vor dem Exit geflusht, jeweils innerhalb vonactor-ts.logger.close-timeout, sodass die ERROR-Zeile mit dem Namen der Phase, unmittelbar davor geloggt, auch einen bündelnden Sink erreicht. Ein abgeschlossener Lauf, der das System stehen ließ (terminate-actor-system = false), wird vor seinem Exit genauso geflusht; einen, dessen Terminator das System heruntergefahren hat, hat dieser Teardown bereits geflusht. Der Lauf ist bis zu seinem Exit im Gange, einterminate(), das während dieser Flushes eintrifft, startet also nichts.
Überschreibe pro Phase:
coordinatedShutdown.setPhaseTimeout(Phases.ServiceRequestsDone, 30_000); // 30s Drain-BudgetOder definiere deine eigene mit gewünschtem timeoutMs / recover:
coordinatedShutdown.addPhase({ name: 'aggressive-cleanup', timeoutMs: 1_000, // strikter Cap dependsOn: [Phases.BeforeActorSystemTerminate], recover: false, // Fehler → Halt});Beides geht auch aus der Konfiguration, pro Phase und ohne Rebuild —
derselbe phases-Block wie oben, und er retimet nur die Phase, die er
benennt:
actor-ts.coordinated-shutdown { default-phase-timeout = 5s # every phase that says nothing phases { service-requests-done { timeout = 30s } # …except this one service-stop { recover = false } # a failure here halts the run }}Das Drain-Budget steckt in der letzten Phase
Abschnitt betitelt „Das Drain-Budget steckt in der letzten Phase“actor-system-terminate ist ein Task, der den Teardown des Systems
awaited — das, was ein einfaches system.terminate() ausführt —, und
der Teardown beginnt damit, die Actors unter /user zu leeren — siehe
Terminieren. Damit sind
zwei Budgets ineinander verschachtelt, und das innere muss das kleinere
sein:
| Budget | Key | Default |
|---|---|---|
Die gesamte Phase actor-system-terminate | actor-ts.coordinated-shutdown.phases.actor-system-terminate.timeout, ersatzweise …default-phase-timeout | 5 s |
| Der Drain darin | actor-ts.system.shutdown-drain-timeout | 2 s |
Setzt du das Drain-Budget über das Phasen-Timeout, wird die Phase abgebrochen, während der Drain noch läuft — bevor auch nur einem Actor gesagt wurde, dass er stoppen soll. Erhöhe beide zusammen oder zuerst das Phasen-Timeout.
Greife zum Per-Phasen-Key, wenn nur der Terminate-Schritt mehr Luft
braucht. default-phase-timeout anzuheben gibt dasselbe größere Budget
elf weiteren Phasen — und jede davon ist eine Phase, in der ein
hängender Task den Shutdown nun entsprechend länger festhalten kann.
SIGTERM / SIGINT-Hooks
Abschnitt betitelt „SIGTERM / SIGINT-Hooks“Fast jeder Service will dasselbe — Handler installieren, warten, herunterfahren, beenden — also ist genau diese Form ein einziger Aufruf:
await system.runUntilTerminated();// Oder, um zusätzlich auf etwas anderes zu hören:await system.runUntilTerminated(['SIGTERM', 'SIGINT', 'SIGUSR2']);Er installiert die Handler, löst auf, sobald das System unten und
die Pipeline fertig ist, und hängt die Handler auf dem Weg hinaus
wieder ab. Dieser letzte Schritt ist keine Kosmetik: unter Deno hält
ein Signal-Listener die Event-Loop offen und hat kein unref — ein
Programm, das aus irgendeinem anderen Grund herunterfährt (ein
terminate() von innen, ein Admin-Endpoint), würde sich also nie
beenden.
Ein Signal, das die Plattform nicht zustellen kann, wird übersprungen statt registriert. Windows hat unter keiner Runtime ein SIGTERM, und Deno wirft bei einem Signal, das es nicht zustellen kann, statt es zu ignorieren — danach zu fragen ist also nie ein Startfehler.
Der Prozess bleibt am Leben, solange das Promise offen ist — und das
ist eine Zusage, die der Aufruf selbst macht, nicht eine, die er von den
installierten Handlern erbt. Ein Signal-Handler ist für sich genommen
kein Grund für eine Runtime, weiterzulaufen: Node unreft seine
Signal-Handles, ein Service ohne irgendetwas anderes in der Event-Loop —
kein gebundener Port, kein offener Socket, kein referenzierter Timer —
würde sie also in dem Moment leerlaufen lassen, in dem er zu warten
beginnt, und sich beenden, bevor das SIGTERM eintreffen kann, für das
er sich gerade selbst gerüstet hat. Deshalb hält der Aufruf die Loop
selbst offen und lässt in demselben Schritt los, in dem er die Handler
abhängt. Ein Node ohne offene Ressourcen braucht kein eigenes
setInterval, um oben zu bleiben.
Die beiden Hälften bleiben einzeln verfügbar, wenn du das System in einen Host einbettest, dem die Prozess-Lebenszeit gehört:
coordinatedShutdown.installProcessHooks(); // → run(new ProcessTerminateReason(signal))coordinatedShutdown.removeProcessHooks(); // hängt exakt das ab, was es installiert hatBeides zweimal aufzurufen ist harmlos. removeProcessHooks() fasst
nie einen Listener an, den es nicht selbst installiert hat — ein
zweites ActorSystem im selben Prozess, oder das eigene
SIGTERM-Handling der Anwendung, bleibt unberührt.
Der Default kommt aus der Konfiguration: ein Host, dem die Signale gehören, kann die Handler bei jedem Node abschalten, ohne den Code anzufassen:
actor-ts.coordinated-shutdown.run-by-process-signals = falseDas schaltet um, was runUntilTerminated() und der Cluster-Bootstrap
tun, wenn der Aufrufer keine Signale genannt hat. Wer sie nennt —
runUntilTerminated(['SIGTERM']), shutdownOnSignals in den
Bootstrap-Optionen oder installProcessHooks() selbst —, installiert
trotzdem, denn explizite Optionen schlagen die Konfiguration. Mit dem
Key auf false hält runUntilTerminated() seine beiden anderen
Zusagen weiterhin ein: es wartet, und es hält die Event-Loop offen.
K8s-PreStop-Integration
Abschnitt betitelt „K8s-PreStop-Integration“In Kubernetes ist die Pod-Shutdown-Sequenz:
1. K8s sendet SIGTERM und beendet die Grace-Period-Uhr des Pods.2. K8s ruft auch den PreStop-Hook (falls konfiguriert), läuft parallel.3. Nach max(Graceful-Shutdown, Grace-Period) sendet K8s SIGKILL.Das Standard-Rezept:
// Bei SIGTERM Coordinated Shutdown laufen lassen:await system.runUntilTerminated();
// PreStop-Hook-Script (in deinem Container-Image):// #!/bin/sh// sleep 10 # gib Upstream-LBs Zeit, diesen Pod zu drainen// exit 0Das sleep in PreStop gibt dem Load Balancer Zeit, diesen Pod aus
der Rotation zu nehmen, bevor das Actor-System anfängt
herunterzufahren — laufende HTTP-Requests sehen also nicht “ich
draine, geh weg.”
Siehe Operations — Kubernetes für das vollständige Deployment-Manifest.
Multi-Trigger-Sicherheit
Abschnitt betitelt „Multi-Trigger-Sicherheit“coordinatedShutdown.run() ist idempotent — es mehrmals aufzurufen, gibt
dasselbe laufende Promise zurück. Unabhängige Trigger, die alle
run aufrufen, lassen die Pipeline nicht erneut laufen. Der erste
Aufruf startet sie; folgende Aufrufe warten auf dieselbe
Vollendung.
Das ist wichtig, weil du in Produktion oft mehrere Shutdown-Pfade hast:
// SIGTERM-Pfad:await system.runUntilTerminated();
// Admin-Endpoint-Pfad:app.post('/shutdown', async (req, res) => { await coordinatedShutdown.run(new AdminEndpointReason()); res.send('ok');});
// Cluster-Downing-Pfad: run-coordinated-shutdown-when-down = on — siehe unten.Jeder davon führt am Ende dieselbe Shutdown-Sequenz aus, einmal.
Wenn der Cluster diesen Knoten downt
Abschnitt betitelt „Wenn der Cluster diesen Knoten downt“Ein Knoten, den seine eigene Downing-Entscheidung entfernt — das Urteil
einer Strategie, das diesen Knoten
einschließt, oder down-all-when-unstable —, verlässt den Cluster immer. Ob
er auch herunterfährt, entscheidet run-coordinated-shutdown-when-down:
const clusterOptions = ClusterOptions.create() .withDowning(new KeepMajority()) .withRunCoordinatedShutdownWhenDown(true);actor-ts.cluster.run-coordinated-shutdown-when-down = onIst er an, verlässt der Knoten zuerst den Cluster und führt danach diese
Pipeline mit ClusterDowningReason aus, auch wenn das Verlassen fehlschlägt:
seine Services werden entbunden, und der eingebaute Terminator beendet das
Actor-System und mit ihm jede Entity und jeden Singleton, die der Knoten
hielt. terminate-actor-system und exit-process entscheiden, worin der
Lauf endet, wie bei einem Signal — ein Lauf, den eine Phase
anhält, endet trotzdem im Teardown, weil ein gedownter Knoten
seine Actors nicht neben der Seite weiterlaufen lassen darf, die gewonnen hat
—, und auto-register-tasks = off unterdrückt ihn nicht: Dieser Schalter hält
die eigenen Tasks des Frameworks zurück und entscheidet nichts darüber, wann
die Pipeline läuft. Der Knoten meldet das auf warn, bevor der Lauf beginnt.
Eine Entscheidung, die nur Peers downt, ändert an diesem Knoten nichts: Der
Schalter beantwortet seine eigene Entfernung, nicht ein Downing, das er
entscheidet.
Ausgeliefert wird an:
- An beendet ein falsches Selbst-Downing den Knoten. Die beiden
bekannten —
static-quorumdownte einen Cluster, der noch kleiner alsquorum-sizewar (Issue #933), undkeep-oldestdownte jeden Überlebenden, sobald der Knoten mit der niedrigsten Adresse abstürzte (Issue #932) — sind behoben, und erst damit wurde der Default umgestellt. - Aus verlässt der Knoten den Cluster und lässt seine Actors weiterlaufen — die Entities und Singletons, die er hielt, jede HTTP-Bindung — neben der Seite, die gewonnen hat. Das ist ein zweiter Schreiber, genau das, was eine Downing-Entscheidung verhindern soll.
Nur das eigene Urteil dieses Knotens erreicht den Schalter. Die Behauptung
eines Peers über den eigenen Eintrag dieses Knotens wird abgelehnt, die
Gewinnerseite kann ihn also nicht direkt downen. Das muss sie auch nicht:
Ein Peer, der diesen Knoten entfernt hat, beantwortet seine Heartbeats mit
einer Ablehnung, der Knoten parkt jeden solchen Peer als unreachable, und
sobald ihn jeder Peer abgelehnt hat, wird seine eigene Strategie sofort
gefragt — ein Knoten, der über das Downing-Fenster hinaus pausiert war, tritt
binnen einer Heartbeat-Runde nach dem Aufwachen ab
(Issue #940). Ein
Selbst-Downing endet in removed und meldet SelfRemoved für diesen Knoten,
ob an oder aus — eine Anwendung, die zu eigenen Bedingungen abtreten will,
kann es abonnieren.
Ein Knoten, den der Schalter herunterfährt, beendet seinen Prozess so, wie
ein sauberer Stopp es tut. Mit exit-process = on endet der Lauf mit
exit-code, der als 0 ausgeliefert wird: Ein Downing ist keiner der
Fehlschläge, die nie mit 0 enden — ein fehlgeschlagener Start, ein Knoten,
der nicht beitreten konnte, ein Lauf, den eine Phase anhält, der auch hier
mit 1 endet. Beim Default exit-process = off endet der Prozess so, wie
dein main endet, sobald runUntilTerminated() auflöst: mit 0, bei der
Produktions-Main unten. Ein Supervisor, der einen Prozess nur nach einem
Fehlschlag neu startet — systemds Restart=on-failure, wie die
systemd-Unit es
setzt —, holt den Knoten also nicht zurück. Zwei Wege tun es:
- Neustart unabhängig vom Status:
Restart=alwaysoder dieselbe Policy eines anderen Supervisors. - Ein
exit-codeungleich null, mitexit-process = on. Dieser Status gehört nicht dem Downing allein: Jeder Lauf, denexit-processbeendet, endet mit ihm, gleich aus welchem Grund — der Lauf eines Signals und der einessystem.terminate(), das die Pipeline ausführt, genauso wie dieser —, und die Läufe für einen Fehlschlag enden mit ihm statt mit1. Ein Supervisor liest dann jeden Stopp als Fehlschlag, und der Status unterscheidet einen gescheiterten Start, einen gescheiterten Join oder einen angehaltenen Lauf nicht mehr von einem geordneten Stopp.
Was nach coordinatedShutdown.run()-Abschluss läuft
Abschnitt betitelt „Was nach coordinatedShutdown.run()-Abschluss läuft“Bis das Promise resolved:
- Jeder Task in jeder Phase ist entweder erfolgreich oder zeitabgelaufen.
- Der eingebaute
actor-system-terminate-Task hatsystem.terminate()aufgerufen, was jeden Actor gestoppt und den Dispatcher und Scheduler geschlossen hat. - Die Log-Sinks sind geflusht und geschlossen, begrenzt durch
actor-ts.logger.close-timeout(Standard 3 s) — die letzten Records eines bündelnden Sinks liegen also auf der Platte oder auf dem Draht, bevor der Prozess geht. Dieser Flush sitzt interminate()statt in einer Phase und deckt damit auch ein Programm ab, dasterminate()direkt aufruft; siehe Multi-Sink-Logging. - Der Prozess ist frei zu beenden (
process.exit(0)). Nichts mehr zu tun.
Eine vollständige Produktions-Main:
async function main() { const system = ActorSystem.create('my-app');
await system.http(8080).bind(routes); // registriert sein eigenes Unbind // Registriere, was dem Framework nicht gehört...
await system.runUntilTerminated();}
main().catch((err) => { console.error(err); process.exit(1);});Wenn SIGTERM ankommt, läuft die Pipeline, das System terminiert,
runUntilTerminated() löst auf, seine Handler gehen ab, und der
Prozess beendet sich, weil nichts mehr die Loop am Leben hält.
Häufige Fallstricke
Abschnitt betitelt „Häufige Fallstricke“Wie es weitergeht
Abschnitt betitelt „Wie es weitergeht“- Actor-System —
das
terminate(), das am Ende der Pipeline läuft. - Cluster-Überblick —
Cluster.join()registriert die Taskscluster-sharding-shutdown-regionundcluster-leave; die übrigen Cluster-Phasen füllst du selbst. - Kubernetes-Deployment — das vollständige PreStop + SIGTERM + Grace-Period-Rezept.
- Persistenz — Migration — Rolling Shutdown für Journal-Migrationen.
Die CoordinatedShutdown-API-Referenz
deckt addTask, addPhase, run und den vollständigen
Phasen-Konstanten-Set ab.
