Zum Inhalt springen
Deutsch

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.

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 ist

Drei Dinge passieren, wenn SIGTERM ankommt:

  1. Die Runtime ruft coordinatedShutdown.run(new ProcessTerminateReason('SIGTERM')).
  2. Die Phasen laufen in kanonischer Reihenfolge. Innerhalb jeder Phase laufen alle registrierten Tasks parallel; die Phase wartet auf alle (oder auf ihre Timeouts).
  3. Die Pipeline endet mit dem eingebauten actor-system-terminate-Task, der system.terminate() für dich aufruft.

Ein Teil dessen, was dazwischen passiert, ist bereits verdrahtet; der Rest ist das, was du hinzugefügt hast.

In Ausführungsreihenfolge gelistet. Verdrahtet markiert die Phasen, die das Framework selbst füllt — alles andere ist leer, bis du etwas registrierst.

#Phasen-NameVerdrahtetTypische Tasks
1before-service-unbind—Letzte Ankündigungen, bevor der Server keine Verbindungen mehr akzeptiert.
2service-unbindsystem.http(...).bind(...), DevToolsHTTP-Server / gRPC-Server / WebSocket-Listener stoppen, neue Verbindungen anzunehmen.
3service-requests-done—Auf das Ende laufender Requests warten; den Rest abbrechen.
4service-stopBroker-Actors (MQTT, Kafka, NATS, AMQP, …)Client-Verbindungen schließen, Sockets freigeben.
5before-cluster-shutdown—Optionale Pre-Cluster-Leave-Hooks.
6cluster-sharding-shutdown-regionCluster.join(...)Der Sharding-Region sagen, Entitäten zu übergeben.
7cluster-leaveCluster.join(...)Ein Cluster.leave() ausgeben — Leaving-Status gossipen.
8cluster-exiting—Warten, bis der Cluster den Leave bestätigt.
9cluster-exiting-done—Cluster-Übergang als abgeschlossen bestätigen.
10cluster-shutdown—Cluster-Transports abbauen.
11before-actor-system-terminate—Letzte Chance für App-Level-Cleanup (Journals flushen, Broker schließen).
12actor-system-terminateder eingebaute TerminatorDer eingebaute system.terminate()-Task.

Du musst nicht jede Phase verwenden. Leere Phasen sind No-Ops; nur Phasen mit registrierten Tasks tun etwas.

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, ...); // ✓ typisiert
coordinatedShutdown.addTask('service-unbind', ...); // ✗ Stringly-typed, kein Auto-Complete

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.

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 }

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:

KlasseWann
ProcessTerminateReason(signal)SIGTERM/SIGINT, aus runUntilTerminated() oder installProcessHooks().
ActorSystemTerminateReasonWas 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.
ClusterLeavingReasonWas shutdown() von Cluster.bootstrap übergibt — ein Mitglied, das absichtlich geht.
ClusterDowningReasonWas 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.
ClusterJoinUnsuccessfulReasonWas 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.
UnknownReasonDer 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.).

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.

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, den terminate({ 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 = false legt fest, dass die Pipeline das System nie herunterfährt. In beiden Fällen wird der Halt als ERROR geloggt. Ein run(), 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 = on endet stattdessen der Prozess am Halt, gleich welcher Auslöser den Lauf gestartet hat — ein Signal, terminate(), dein eigenes run() oder der Cluster —, und zwar mit einem Status, der sich nicht wie ein sauberer Stopp liest: exit-code, wo dieser nicht 0 ist, 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 von actor-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, ein terminate(), das während dieser Flushes eintrifft, startet also nichts.

Überschreibe pro Phase:

coordinatedShutdown.setPhaseTimeout(Phases.ServiceRequestsDone, 30_000); // 30s Drain-Budget

Oder 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
}
}

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:

BudgetKeyDefault
Die gesamte Phase actor-system-terminateactor-ts.coordinated-shutdown.phases.actor-system-terminate.timeout, ersatzweise …default-phase-timeout5 s
Der Drain darinactor-ts.system.shutdown-drain-timeout2 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.

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 hat

Beides 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 = false

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

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 0

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

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.

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 = on

Ist 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-quorum downte einen Cluster, der noch kleiner als quorum-size war (Issue #933), und keep-oldest downte 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=always oder dieselbe Policy eines anderen Supervisors.
  • Ein exit-code ungleich null, mit exit-process = on. Dieser Status gehört nicht dem Downing allein: Jeder Lauf, den exit-process beendet, endet mit ihm, gleich aus welchem Grund — der Lauf eines Signals und der eines system.terminate(), das die Pipeline ausführt, genauso wie dieser —, und die Läufe für einen Fehlschlag enden mit ihm statt mit 1. 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 hat system.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 in terminate() statt in einer Phase und deckt damit auch ein Programm ab, das terminate() 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.

  • Actor-System — das terminate(), das am Ende der Pipeline läuft.
  • Cluster-Überblick — Cluster.join() registriert die Tasks cluster-sharding-shutdown-region und cluster-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.