Skip to content
English

CoordinatedShutdown

Defined in: src/CoordinatedShutdown.ts:164

Lifecycle coordinator that runs registered tasks in well-known phases. Ordinary application code calls addTask(phase, name, task); the runtime guarantees task order across phases and bounded parallelism within a phase. Task failures are logged and do NOT by default abort the rest of the pipeline.

new CoordinatedShutdown(system): CoordinatedShutdown

Defined in: src/CoordinatedShutdown.ts:240

ActorSystem

CoordinatedShutdown

readonly autoRegisterTasks: boolean

Defined in: src/CoordinatedShutdown.ts:224

Whether framework components register their own teardown — see addFrameworkTask.


defaultPhaseTimeoutMs: number = DEFAULT_PHASE_TIMEOUT_MS

Defined in: src/CoordinatedShutdown.ts:199

Default per-phase timeout in ms. Can be changed globally or per-phase via setPhaseTimeout, or from actor-ts.coordinated-shutdown. default-phase-timeout. 5 seconds is a reasonable balance between letting slow tasks finish and not blocking shutdown indefinitely.

Assigning it later only affects phases registered after the fact — the 12 canonical phases copy it when they are seeded below, which is why the config read has to happen first.


readonly runByProcessSignals: boolean

Defined in: src/CoordinatedShutdown.ts:238

Whether the framework’s two defaulting signal call sites — ActorSystem.runUntilTerminated() and the cluster bootstrap — arm SIGTERM/SIGINT on the caller’s behalf.

Deliberately not consulted by installProcessHooks, which keeps meaning “do it”. The key ships as a leaf, so reference.conf always supplies a value and a gate inside the installer would let HOCON beat a caller who named the signals explicitly — the exact inversion of explicit options > HOCON > defaults. Reading it where the default is chosen keeps that order intact.

get isComplete(): boolean

Defined in: src/CoordinatedShutdown.ts:385

True once run() has completed (successful or not).

boolean


get isRunning(): boolean

Defined in: src/CoordinatedShutdown.ts:383

True once run() has been kicked off.

boolean

addFrameworkTask(phase, name, task): boolean

Defined in: src/CoordinatedShutdown.ts:324

Register a task the framework owns — an HTTP unbind, a broker teardown, the cluster leave, the DevTools detach — and report whether it was taken.

Identical to addTask except that it is a no-op when actor-ts.coordinated-shutdown.auto-register-tasks is false. That flag is the opt-out for an embedder who wants the pipeline’s phases but not its opinions about when its own resources go: a host process that hands the same HTTP server to two subsystems, a test harness that binds and unbinds inside one system, or anyone who would rather order the teardown by hand. It is deliberately one switch rather than one per subsystem — the reason to reach for it is never “unbind the HTTP server but leave the brokers to me”, it is “I own the lifecycle”.

The boolean return exists so a caller can skip the matching removeTask bookkeeping instead of guessing.

string

string

ShutdownTask

boolean


addPhase(def): void

Defined in: src/CoordinatedShutdown.ts:349

Add a custom phase. dependsOn tells the coordinator where in the order it sits.

PhaseDefinition

void


addTask(phase, name, task): void

Defined in: src/CoordinatedShutdown.ts:294

Register a task to run during the given phase. Task names must be unique within a phase.

string

string

ShutdownTask

void


installProcessHooks(signals?): void

Defined in: src/CoordinatedShutdown.ts:472

Install SIGTERM / SIGINT handlers that call run(ProcessTerminateReason). Calling twice is harmless. Uninstall via removeProcessHooks.

Delivery goes through the src/runtime/signals/ backend rather than process.on directly, because Deno’s process shim carries no signal events — the old call site registered nothing at all there and reported success (#549). A signal the runtime cannot deliver is skipped rather than registered: on Deno that would throw, and on Windows there is no SIGTERM to catch under any runtime.

readonly ProcessSignal[] = ...

void


phaseDefinition(phase): PhaseDefinition | undefined

Defined in: src/CoordinatedShutdown.ts:371

The resolved definition of a phase, or undefined if there is none.

Read-only on purpose — the map is the pipeline’s own state, and the copy handed back is the same frozen-by-convention record addPhase took. It exists because the graph stopped being something only code builds: once actor-ts.coordinated-shutdown.phases can retime a phase or add one, the operator who wrote that block needs a way to ask what the merge actually produced, and “run a shutdown and watch” is not one.

string

PhaseDefinition | undefined


removeProcessHooks(): void

Defined in: src/CoordinatedShutdown.ts:546

Detach the handlers this instance installed.

Not optional housekeeping on Deno: a signal listener there holds the event loop open with no unref to soften it, so a program that installs one and never removes it stops exiting by itself.

void


removeTask(phase, name): boolean

Defined in: src/CoordinatedShutdown.ts:339

Unregister a task, returning whether one was there.

A task registered for a resource that has since been released must be able to go with it. Without this, a component that registers on acquire — the HTTP layer’s http-unbind-<host>:<port>, say — could never re-acquire the same resource in one process: the second registration collides with a task whose binding no longer exists.

string

string

boolean


run(reason?): Promise<void>

Defined in: src/CoordinatedShutdown.ts:414

Run the pipeline. Safe to call from multiple sites — subsequent calls return the same in-flight promise.

A reason that reports a failure — ClusterJoinUnsuccessfulReason, a node that could not join — makes the run one for a failure, which exit-process never exits 0 after; passed to a run already under way, it marks that run so too, as _runForFailure does.

A startup the system is still running is abandoned as the run begins, before its first phase — the same abandonment terminate() makes (#1473).

Reason = UnknownReason.instance

Promise<void>


setPhaseTimeout(phase, timeoutMs): void

Defined in: src/CoordinatedShutdown.ts:376

Override the timeout for a phase. Uses defaultPhaseTimeoutMs by default.

string

number

void