Ciclo de vida e graceful shutdown
Uma app Kata não tem ciclo de vida de plugins, não tem hooks onStart/onError, e não tem container de IoC para desmontar. Singletons são eager: uma factory como singleton(makeDb(env)) roda quando context.ts é importado, e o valor vive pelo processo inteiro. Resta uma única coisa sob sua responsabilidade — parar o processo de forma limpa quando o orquestrador pedir. Isso é o gracefulShutdown de @katajs-framework/core/node.
createApp não toca no processo. Ele não instala nenhum signal handler, não abre nenhum socket e não sabe nada sobre Node. Construir uma app é uma operação sem efeitos colaterais. Servi-la, e desligá-la, é tarefa do main.ts.
Servindo a app
Kata não traz um servidor HTTP. A app é um request handler — app.fetch — e você o entrega a um adaptador de runtime. No Node esse adaptador é @hono/node-server, um peer que você instala por conta própria; o serve() dele é dono do socket de escuta.
// src/main.ts
import { serve } from '@hono/node-server'
import { createApp, k } from './context'
import * as users from './modules/users/users.route'
const app = createApp({ modules: [users] })
const port = Number(process.env['PORT'] ?? 3000)
serve({ fetch: app.fetch, port }, (info) => {
k.resolve('logger').info(`listening on http://localhost:${info.port}`)
})createApp retorna uma app Hono paramétrica; app.fetch é o handler Request → Response dela. Veja a referência de create-app para a config que ele aceita.
Por que graceful shutdown
serve() retorna um Server do Node que é dono do socket de escuta e de toda conexão em andamento. Quando o orquestrador para seu container — um docker stop, uma rotação de pod do Kubernetes, um restart do systemd — ele envia SIGTERM. Se você ignorar, o handler padrão do Node termina o processo no meio do voo: requisições em andamento são descartadas e qualquer pool que você abriu nunca fecha. O próximo deploy trunca trabalho ao vivo.
A sequência correta é sempre a mesma: capturar o sinal uma vez, parar de aceitar novas conexões, deixar as requisições em andamento terminarem, rodar seu teardown, e forçar a saída se uma conexão travar. Acertar a ordem do dreno e a válvula de escape é trabalhoso e idêntico em toda app, então Kata cuida disso (ADR-0014).
gracefulShutdown
gracefulShutdown vive no subpath @katajs-framework/core/node — o único ponto de entrada que toca em node:process — para que importar o core neutro em relação ao runtime (@katajs-framework/core) de um build edge ou Workers nunca puxe o Node junto.
import { gracefulShutdown } from '@katajs-framework/core/node'
import type { ServerType, GracefulShutdownOptions } from '@katajs-framework/core/node'
function gracefulShutdown(server: ServerType, options: GracefulShutdownOptions): void
type GracefulShutdownOptions = {
onClose: () => void | Promise<void>
signals?: readonly NodeJS.Signals[] // default ['SIGTERM', 'SIGINT']
timeoutMs?: number // default 10_000
}Ele recebe o server, não a app. A app é o request handler; o server é o que é dono do socket e precisa de close() para drenar. ServerType é o handle que o serve() retorna — um Server node:http/http2 — re-derivado de @types/node para que @katajs-framework/core/node precise apenas de @types/node e nunca empacote o adaptador.
// src/main.ts
import { serve } from '@hono/node-server'
import { gracefulShutdown } from '@katajs-framework/core/node'
import { createApp, k } from './context'
import * as users from './modules/users/users.route'
const app = createApp({ modules: [users] })
const port = Number(process.env['PORT'] ?? 3000)
const server = serve({ fetch: app.fetch, port }, (info) => {
k.resolve('logger').info(`listening on http://localhost:${info.port}`)
})
gracefulShutdown(server, {
onClose: async () => {
// Teardown sob responsabilidade da app, na ordem que a app escolher. Recursos
// são alcançados pelo registry ou por referências capturadas em closure.
await k.resolve('db').close()
},
// signals: ['SIGTERM', 'SIGINT'], // default
// timeoutMs: 10_000, // default
})O que ele faz em um sinal
No primeiro sinal capturado, gracefulShutdown roda, nesta ordem:
- Protege contra reentrância. Um segundo
SIGTERM/SIGINTdurante o desligamento é ignorado — a rotina é idempotente e segura para sinal duplicado. - Arma um timer de force-exit.
setTimeout(() => process.exit(1), timeoutMs), com.unref()para que o timer nunca mantenha o event loop vivo por conta própria. - Para de aceitar novas conexões.
server.close()— o Node fecha o listener e os sockets keep-alive ociosos; as requisições em andamento rodam até o fim. - Aguarda o dreno das em andamento — a conclusão do
server.close(callback), que dispara assim que toda conexão aberta termina. - Roda
await onClose()— estritamente depois do dreno, para que nenhum handler ao vivo perca seu pool ou transação no meio de uma query. - Sai com
0ao concluir limpo dentro do orçamento.
Se os passos 4–5 excederem timeoutMs, o timer dispara primeiro e o processo força a saída com código diferente de zero — trabalho em andamento foi abandonado, um desfecho distinto e visível para o orquestrador, não uma parada limpa. Se o dreno ou o onClose lançar, o processo também sai com código diferente de zero.
O listener do sinal permanece registrado durante todo o desligamento, então um segundo sinal é capturado e engolido pelo guard de reentrância em vez de atingir o handler de término padrão do Node.
onClose: seu teardown, sua ordem
Kata não é dono de nenhum registry de dispose. Não há hook dispose no singleton() e nada percorre o registry por você. onClose é o único lugar onde você sequencia o teardown, e a ordem é sua — teardown é o inverso da construção e específico do domínio, algo que só a app conhece:
gracefulShutdown(server, {
onClose: async () => {
await metrics.flush() // primeiro dá flush nas métricas bufferizadas
await queue.stop() // depois para o consumer da fila
await k.resolve('db').close() // por último, fecha o pool
},
})A política de falha parcial também é sua: envolva um passo em try/catch dentro do onClose se quiser continuar após um recurso que falha ao fechar. Qualquer coisa que o onClose esquecer de fechar simplesmente vaza no desligamento — o custo de não ser dono de um registry.
Defina timeoutMs abaixo do período de graça do orquestrador
timeoutMs (default 10 s) é um deadline soft que ainda permite uma saída limpa. O do orquestrador é o hard. O terminationGracePeriodSeconds do Kubernetes tem default de 30 s, após o qual ele envia um SIGKILL incapturável. Mantenha timeoutMs dentro dessa janela para vencer o SIGKILL e desligar nos seus próprios termos.
Sinais
O default é ['SIGTERM', 'SIGINT']:
SIGTERM— o sinal de parada graciosa do orquestrador (docker stop, término de pod do Kubernetes, systemd).SIGINT— Ctrl-C em um terminal de dev, para que o desligamento local também drene.
Launchers podem engolir o SIGTERM
npx tsx src/main.ts roda a app como filha do processo npx: o SIGTERM que você envia atinge o npx, que sai sem repassá-lo, então a app nunca vê o sinal e nada drena. Script runners de gerenciadores de pacote (pnpm dev, npm run dev) podem se interpor da mesma forma. Quando sinais importam, lance o processo diretamente — node --import tsx src/main.ts em dev, ou o build final (node dist/main.js).
SIGKILL e SIGSTOP são incapturáveis por definição. SIGHUP (a semântica de reload varia conforme o deployment) é deixado para você de propósito. Sobrescreva o conjunto com signals se precisar de uma captura diferente.
Habilite a partir do main.ts
createApp não instala nenhum signal handler. Registrar listeners de process.on como efeito colateral de construir uma app vazaria listeners duplicados entre múltiplas apps e execuções de teste, acoplaria o core neutro em relação ao runtime ao node:process, e estaria errado para hosts serverless ou embarcados que nunca são donos do processo. main.ts — o único lugar onde o layout deixa você falar com o process — chama gracefulShutdown explicitamente.
Testando o graceful shutdown
A sequência de dreno só se revela em um processo real: faça o spawn do entrypoint como processo filho, espere até ele responder, envie SIGTERM e verifique o comportamento documentado acima. Faça o spawn de node --import tsx diretamente — não de npx tsx, conforme o aviso acima — para que o sinal chegue à app.
Esta é uma suíte em nível de processo, não o teste de um único módulo, então ela fica na raiz de src/, ao lado de main.ts, em vez de dentro de src/modules/: src/ é a única árvore que o "include": ["src"] do tsconfig.json gerado checa por tipos, e essa config é um arquivo protegido que um agente não pode alargar. Veja Suítes de teste entre módulos e em nível de processo para a regra completa.
// src/main.shutdown.test.ts
import { spawn } from 'node:child_process'
import { once } from 'node:events'
import { setTimeout as sleep } from 'node:timers/promises'
import { expect, it } from 'vitest'
it('drena o trabalho em andamento e sai com 0 no SIGTERM', async () => {
const child = spawn('node', ['--import', 'tsx', 'src/main.ts'], {
env: { ...process.env, PORT: '3123' },
})
while ((await fetch('http://localhost:3123/users').catch(() => null)) === null) {
await sleep(50) // espera a prontidão
}
const inflight = fetch('http://localhost:3123/users') // em andamento quando o sinal chega
await sleep(50)
child.kill('SIGTERM')
expect((await inflight).status).toBe(200) // passos 3–4: a em andamento termina
await expect(fetch('http://localhost:3123/users')).rejects.toThrow() // passo 3: novas conexões recusadas
const [code] = await once(child, 'exit')
expect(code).toBe(0) // passo 6: saída limpa
})Para tornar o dreno observável, aponte a requisição em andamento para sua rota mais lenta — um handler que termina antes de o sinal chegar não prova nada.
Como ele se relaciona com @hono/node-server
@hono/node-server é o adaptador Node: o serve() dele faz o bind do socket e roda app.fetch para cada requisição. Kata não adiciona nada a isso — não envolve nem re-exporta o serve(). gracefulShutdown opera sobre o handle Server que o serve() retorna, chamando o close(callback) padrão dele. Os dois se compõem: o serve() abre o socket, o gracefulShutdown o drena e o fecha.
Outros runtimes
@katajs-framework/core/node é exclusivo de Node e é o único adaptador de ciclo de vida da v0.3. Edge e Workers não têm processo de longa duração para sinalizar; Bun e Deno expõem sinais mas divergem na semântica de fechamento de server. Ciclo de vida cross-runtime fica adiado para o milestone v0.4. Nesses runtimes você serve a app da mesma forma — entrega app.fetch ao adaptador próprio do runtime — mas não usa gracefulShutdown.
Veja também
- Referência de create-app — a app que você serve e sua config.
- Context & DI — singletons eager e o registry que você alcança no
onClose. - Cookbook de banco de dados — fechando um pool de conexões no desligamento, de ponta a ponta.
- ADR-0014 — por que o teardown é um callback, não um registry de auto-dispose.