Desligamento Gracioso

Visão Geral

Uma habilidade para implementar o desligamento gracioso em servidores, workers e processos de longa duração. Garante que requisições em andamento sejam concluídas, trabalhos em segundo plano terminem ou sejam salvos, conexões de banco de dados sejam fechadas corretamente e o processo saia com um código de status apropriado. Essencial para implantações sem interrupção em orquestradores de contêineres (Kubernetes, ECS, Docker Compose) e gerenciadores de processos bare-metal (systemd, PM2).

Quando Usar Esta Habilidade

• Use ao construir um servidor HTTP que não deve descartar conexões ativas durante implantações.
• Use ao escrever um worker em segundo plano que processa trabalhos de uma fila.
• Use ao implantar no Kubernetes, Docker ou qualquer ambiente que envie SIGTERM antes de encerrar.
• Use quando o usuário disser "desligamento gracioso", "drenar conexões", "lidar com SIGTERM", "sem interrupção" ou "não matar requisições ativas".
• Use ao implementar endpoints de verificação de saúde (/healthz, /readyz) para orquestradores.

Como Funciona

Passo 1: Registrar manipuladores de sinal cedo

Capture SIGTERM (desligamento do orquestrador) e SIGINT (Ctrl+C) no início do processo. Defina uma flag para que a aplicação saiba que está desligando.

let isShuttingDown = false;

function onShutdownSignal(signal: string): void {
  if (isShuttingDown) return; // prevent double-shutdown
  isShuttingDown = true;
  console.log(`Received ${signal}, starting graceful shutdown...`);
  shutdown();
}

process.on("SIGTERM", () => onShutdownSignal("SIGTERM"));
process.on("SIGINT", () => onShutdownSignal("SIGINT"));

Passo 2: Parar de aceitar novo trabalho

Imediatamente pare o servidor de aceitar novas conexões. Para servidores HTTP, chame server.close(). Para workers de fila, pare de consultar novos trabalhos.

async function shutdown(): Promise<void> {
  // 1. Stop accepting new connections
  server.close(() => {
    console.log("Server closed — no new connections accepted");
  });

  // 2. Mark health check as not-ready so load balancers stop routing
  //    (readiness probe returns 503 from this point)
}

Passo 3: Drenar trabalho em andamento com um prazo

Espere que requisições ativas e tarefas em segundo plano terminem, mas imponha um prazo rígido para que o processo nunca fique pendurado indefinidamente.

const DRAIN_TIMEOUT_MS = 25_000; // must be less than orchestrator's terminationGracePeriodSeconds

async function drainAndExit(): Promise<void> {
  const deadline = setTimeout(() => {
    console.error("Drain timeout reached — forcing exit");
    process.exit(1);
  }, DRAIN_TIMEOUT_MS);
  deadline.unref(); // don't keep the event loop alive just for the timer

  try {
    // Wait for active connections to finish
    await waitForActiveConnections();

    // Flush buffered data (logs, metrics, queues)
    await flushBuffers();

    // Close external resource handles
    await closeResources();

    console.log("Graceful shutdown complete");
    process.exit(0);
  } catch (err) {
    console.error("Error during shutdown:", err);
    process.exit(1);
  }
}

Passo 4: Implementar sondas de prontidão e vivacidade

Orquestradores usam estas para decidir se devem rotear tráfego e se devem reiniciar o contêiner. A vivacidade prova que o processo está ativo; a prontidão controla se o tráfego é roteado. Enquanto o listener ainda estiver disponível durante uma drenagem, mantenha a vivacidade saudável e retorne 503 apenas da prontidão. Após o fechamento do listener, novas sondas não conseguem se conectar, portanto, não prometa que a vivacidade HTTP permanecerá alcançável durante toda a janela de terminação.

import { createServer, IncomingMessage, ServerResponse } from "node:http";

function handleHealthCheck(req: IncomingMessage, res: ServerResponse): void {
  if (req.url === "/healthz") {
    // Keep liveness distinct from readiness while the listener is available.
    // Drain-rejection middleware must not turn this endpoint into a 503.
    res.writeHead(200).end("ok");
    return;
  }

  if (req.url === "/readyz") {
    // Readiness: 503 during shutdown so the load balancer stops routing.
    if (isShuttingDown) {
      res.writeHead(503).end("shutting down");
    } else {
      res.writeHead(200).end("ready");
    }
    return;
  }
}

Passo 5: Rastrear conexões ativas

Mantenha uma contagem de requisições em andamento para saber quando a drenagem estiver completa. Use um guarda "once" cobrindo os eventos finish e close para que desconexões de clientes (requisições abortadas) decrementem corretamente o contador.

let activeConnections = 0;
let drainResolve: (() => void) | null = null;


…