ADR-0014: Lifecycle teardown — onClose callback + Node signal/drain contract
- Status: Accepted
- Date: 2026-06-15
- Deciders: @VicenzoMF
Context
A long-lived Kata process holds resources that must be released in an orderly way when the orchestrator asks it to stop: a database pool to drain, a queue consumer to stop, buffered logs or metrics to flush. Today none of that is handled. There is no SIGTERM trap, and singletons have no teardown hook — so docs/cookbook/database.md punts explicitly:
Lifecycle is outside the request. Closing the pool on shutdown belongs in the server bootstrap (
main.ts) via process signals — Kata has no per-request teardown hook for singletons.
docs/cookbook/migrating-from-nestjs.md carries the same gap as a migration note: NestJS's OnApplicationShutdown has no Kata equivalent, and the table sends the reader to "shutdown via process signals in main.ts". An app that ignores SIGTERM is killed mid-flight: in-flight requests are dropped and the pool never closes, so the next deploy or pod-rotation truncates live work.
This is the always-the-same plumbing epic #95 describes — trap the signal, stop accepting connections, run user teardown, force-exit on a timeout. Getting it right (correct drain order, an escape hatch when a connection hangs, no listener leaks) is fiddly and identical across every app, which is exactly the kind of thing a framework should own. This ADR decides the contract; it ships no code. The helper itself is #97 and the worked example/doc updates are #98.
The forces in play:
- Who owns teardown order? Resource shutdown is the inverse of construction order and is domain-specific (flush metrics, then drain the queue, then close the pool). The framework does not know that order; the app does.
- Where does the framework stop and
main.tsbegin? ADR-0004 made singletons eager —makeDb(env)runs whencontext.tsis imported. Construction has a natural order (module evaluation, dependencies passed as arguments); teardown does not, and it must also wait for in-flight requests first. - Runtime neutrality. ADR-0001 chose Hono for first-class edge/Workers/Deno support and deliberately rejected a plugin lifecycle model. Signal handling is a Node concept (
process.on('SIGTERM')); Workers have no long-lived process to signal. Whatever we add must not dragnode:processinto the runtime-neutral core. - Scope. v0.3 targets the
@hono/node-serveradapter only (epic #95); edge/Bun/Deno lifecycle belongs to the v0.4 cross-runtime milestone.
Decision
We will keep teardown a single onClose callback wired by the app in main.ts, and have Kata own only the always-identical Node plumbing through a helper:
import { serve } from '@hono/node-server'
import { gracefulShutdown } from '@katajs-framework/core/node'
const server = serve({ fetch: app.fetch, port })
gracefulShutdown(server, {
onClose: async () => {
// App-owned teardown, in the app's chosen order. Resources are reached
// through the registry (ADR-0004) or closed-over references.
await k.registry.db.__value.close()
},
signals: ['SIGTERM', 'SIGINT'], // default
timeoutMs: 10_000, // default
})type GracefulShutdownOptions = {
onClose: () => void | Promise<void>
signals?: readonly NodeJS.Signals[] // default ['SIGTERM', 'SIGINT']
timeoutMs?: number // default 10_000
}
function gracefulShutdown(server: ServerType, options: GracefulShutdownOptions): voidServerType is the handle @hono/node-server's serve() returns (a node:http/http2 Server). The helper takes the server, not the Kata app — the app is the request handler; the server is the thing that owns the listening socket and in-flight connections.
Teardown model: callback, not an auto-dispose registry
Kata does not own a teardown registry. We rejected attaching an optional dispose() to singleton slots (singleton(value, { dispose })) that the framework auto-runs on shutdown. Rationale:
- Teardown order is the inverse of construction order, and only the app knows it. A registry would have to invent an ordering policy (reverse-registration? reverse-dependency?) and would get it wrong for any non-trivial graph. A single
onCloselets the app sequence teardown explicitly — the same principle ADR-0004 chose for middleware ("the order in theuse:array is the contract": explicit ordering over implicit resolution). - Lifecycle is a property of a few resources, not of the slot mechanism. Most singletons — a logger, a config object, a table of pure functions — have nothing to close. Putting
disposeonsingleton()spreads a teardown concern across every registration when only one or two slots ever need it, and invites adisposeon things that should not have one. - It keeps the framework-vs-BYO line where epic #95 drew it. Kata owns the plumbing that is genuinely hard and identical everywhere (trap once, stop accepting, await drain, force-exit). What to close, and in what order, is domain knowledge that stays in
main.ts. An auto-dispose registry drags that knowledge into the framework. - Partial-failure policy stays in app code. If closing one resource throws, the app decides whether to continue, abort, or log — with an ordinary
try/catchinsideonClose. Kata does not have to standardise a teardown-error policy for everyone. - It is the smaller, non-breaking surface, and forecloses nothing. A future
singleton(value, { dispose })could be implemented purely as a built-inonClosethat walks the registry in reverse — additive on top of this contract, exactly as ADR-0011 widenedoutputwithout breaking the single-schema form. Choosing the callback now keeps that door open (see Follow-ups).
Signals and the framework / main.ts boundary
- Signals trapped:
SIGTERM(the orchestrator's graceful-stop signal —docker stop, Kubernetes pod termination, systemd) andSIGINT(Ctrl-C in a dev terminal, so local shutdown drains too). Default['SIGTERM', 'SIGINT'], overridable viasignals.SIGKILL/SIGSTOPare uncatchable by definition andSIGHUP(reload semantics vary by deployment) is intentionally left to the app. - The framework provides the helper;
main.tscalls it. Kata does not install signal handlers as a side effect ofcreateApp. Building an app must not have the global side effect of registeringprocess.onlisteners — that is surprising, leaks duplicate listeners across multiple apps and across test runs, couples the runtime-neutral core tonode:process, and is wrong for serverless or embedded callers that never own the process. Opting in frommain.ts(the one place ADR's layout already lets talk toprocess) is the boundary.
Drain semantics
On the first trapped signal, gracefulShutdown runs, in order:
- Guard against re-entry. A second
SIGTERM/SIGINTwhile already shutting down is ignored — the helper is idempotent and double-signal safe (#97). - Arm the force-exit timer.
setTimeout(() => process.exit(1), timeoutMs),.unref()'d so the timer itself never keeps the event loop alive. - Stop accepting new connections.
server.close()— Node stops the listener and closes idle keep-alive sockets; in-flight requests run to completion. - Await the in-flight drain — the
server.close(callback)completion, which fires once every open connection has finished. - Run
await onClose()— after the drain, so no in-flight handler loses its pool or transaction mid-query. (Closing resources concurrently with the drain would break requests still using them; sequential drain →onCloseis the safe default.) - Exit
0. Clean shutdown completed within the budget.
If steps 4–5 exceed timeoutMs, the timer fires first and the process force-exits with a non-zero code (in-flight work was abandoned — a distinct, visible outcome for the orchestrator, not a clean stop). timeoutMs defaults to 10 s and must be set below the orchestrator's grace period (Kubernetes' terminationGracePeriodSeconds defaults to 30 s, after which it sends an uncatchable SIGKILL): the in-process timer is the soft deadline that still lets us exit cleanly; the orchestrator's is the hard one we want to beat.
The shutdown routine must be invokable directly in a unit test (no real signal required) so #97 can cover the signal → onClose → timeout path deterministically.
Adapter scope
Node (@hono/node-server) only, shipped as a new kata/node subpath export. Keeping the Node-only helper (and its node:process / ServerType dependencies) out of the package root preserves the root entry's runtime neutrality (ADR-0001): an edge/Workers build importing kata never pulls in node:process. Edge, Bun, and Deno have different lifecycle models (Workers have no process signal; Bun and Deno expose signals but differ on server-close semantics) and are deferred to the v0.4 cross-runtime milestone.
Alternatives considered
Alternative A — auto-run dispose registry (singleton(v, { dispose }))
Attach an optional dispose() to singleton slots and have the framework iterate them on shutdown. Rejected for the five reasons in Teardown model above — chiefly that teardown ordering is domain knowledge the framework cannot infer, and that lifecycle is a property of a few resources, not of every slot. It remains a viable future additive layer built on top of onClose (Follow-ups) if real usage shows the open/close co-location DX is worth it; choosing the callback now does not foreclose it.
Alternative B — auto-install signal handlers inside createApp
Have createApp register process.on('SIGTERM', …) itself, so shutdown "just works". Rejected: constructing an app should be free of global process side effects. It leaks duplicate listeners when a test (or a process) builds more than one app, couples the runtime-neutral core to node:process (breaking the ADR-0001 edge story), and assumes the caller owns the process — false for serverless, embedded, or test hosts. The signal trap is opt-in from main.ts.
Alternative C — createApp returns a dispose() method
Make createApp return { fetch, dispose } and have the app expose teardown. Rejected: createApp returns the RPC-typed Hono app (KataApp, ADR-0011 / epic #11); bolting a dispose onto that value muddies the type that the RPC client infers from, and it still solves neither signal trapping nor draining. The object you must close() to stop accepting connections is the server, not the app — gracefulShutdown(server, …) takes the right handle.
Alternative D — a full lifecycle / plugin system (onStart/onClose/onError)
Adopt a Fastify-style lifecycle with ordered hooks. Rejected: ADR-0001 explicitly declined a plugin lifecycle model, and v0.3 needs only teardown. A hook framework is far more surface than the problem warrants and can be revisited if a concrete need beyond teardown appears.
Consequences
Positive
- The error-prone, always-identical plumbing (signal trap, connection drain, force-exit timer, idempotency) is owned and tested once by the framework (#97), not re-derived — usually subtly wrong — in every app's
main.ts. - The teardown contract is tiny and explicit;
onCloseordering belongs to the app, matching ADR-0004's explicit-ordering ethos. - The package root stays runtime-neutral (ADR-0001): Node-only lifecycle lives behind
kata/node, so edge/Workers builds never importnode:process. - Non-breaking and additive — a dispose-registry (Alternative A) can be layered on later without changing this contract.
- Closes the standing punt in
docs/cookbook/database.mdand theOnApplicationShutdowngap indocs/cookbook/migrating-from-nestjs.md: pool-closing on shutdown finally has a blessed, copy-pasteable pattern (#98).
Negative / costs
- No framework guarantee that every resource is closed. A resource the app forgets to close in
onCloseleaks on shutdown — the cost of not owning a registry. Mitigated by the cookbook recipe and the worked example (#98), and bygracefulShutdownreducing the wiring to a few lines. - Open and close live in two places — the
singleton(makeX(env))factory incontext.tsand the matching close inmain.ts'sonClose— rather than co-located. Accepted in exchange for explicit teardown ordering. - Node-only for v0.3. Edge/Bun/Deno users get no helper yet (explicit v0.4 scope).
- A new
kata/nodesubpath export to maintain inpackages/kata/package.json.
Follow-ups
- #97 — implement
gracefulShutdown(server, { onClose, signals?, timeoutMs? })for the Node adapter: registers handlers, stops accepting, awaits the drain thenonClose, force-exits aftertimeoutMs; idempotent (double-signal safe); noany; a unit test simulating the signal →onClose→ timeout path. - #97 — add the
kata/nodesubpath export (Node-only entry) to the package. - #98 — ship an example
main.tsclosing a stub DB pool onSIGTERM, and updatedocs/cookbook/database.md's lifecycle gotcha and thedocs/cookbook/migrating-from-nestjs.mdOnApplicationShutdownrow to point at the pattern. - v0.4 cross-runtime milestone — edge/Bun/Deno lifecycle adapters (ties into ADR-0001's multi-runtime stance).
- Possible additive
singleton(value, { dispose })(Alternative A) layered ononClose, if usage shows the co-location DX earns its keep.
Companion rules
This ADR decides a runtime contract and a packaging boundary; like ADR-0011 it introduces no new mandatory mechanical rule for v0.3. There is no multi-file source invariant to grep for — gracefulShutdown is opt-in library code, not a shape every module must follow.
Rule IDs worth drafting later, once the helper ships (#97), are speculative and listed here rather than enforced now:
kata/raw-signal-handler(future) — flag a hand-rolledprocess.on('SIGTERM' | 'SIGINT', …)in app code and nudge it towardgracefulShutdown, which gets drain ordering and the force-exit timer right.