Node.js uygulamasında graceful shutdown nasıl yapılır? SIGTERM geldiğinde neler olmalı?

Graceful shutdown, process kapatılırken yeni istek kabul etmeyi durdurup devam eden istekleri tamamlamak ve kaynakları (DB, kuyruk bağlantıları) düzgün kapatmaktır. Kubernetes, Docker ve PM2 process'i durdururken önce SIGTERM gönderir; belirli süre (Kubernetes'te varsayılan terminationGracePeriodSeconds: 30) sonra hâlâ kapanmamışsa SIGKILL ile öldürür.

import http from "node:http";

const server = http.createServer(app);
server.listen(3000);

let shuttingDown = false;

async function shutdown(signal) {
  if (shuttingDown) return;
  shuttingDown = true;
  console.log(`${signal} alındı, kapanıyor...`);

  // 1) Readiness'i düşür: yeni trafik gelmesin
  // (health endpoint shuttingDown ise 503 döner)

  // 2) Yeni bağlantıları kabul etmeyi bırak, mevcutları bitir
  server.close(async () => {
    // 3) Kaynakları kapat
    await db.end();
    await queueConsumer.close();
    process.exit(0);
  });
  server.closeIdleConnections(); // Node 18.2+: boştaki keep-alive bağlantıları kapat

  // 4) Güvenlik ağı: süre aşılırsa zorla çık
  setTimeout(() => process.exit(1), 25_000).unref();
}

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

Dikkat edilecekler

• PID 1 sorunu: Docker'da CMD npm start kullanırsanız sinyal npm'e gider ve Node'a iletilmeyebilir. CMD ["node", "server.js"] (exec form) kullanın veya tini / docker run --init ile çalıştırın.
• Kubernetes yarışı: pod silinirken endpoint listesinden çıkarılması birkaç saniye sürebilir; bu sürede gelen istekler kaybolmasın diye kısa bir bekleme (preStop hook ile sleep 5) eklemek yaygındır.
• Keep-alive bağlantıları server.close()'un bitmesini geciktirir; closeIdleConnections() veya yanıtlara Connection: close başlığı ekleyin.
• Kuyruk consumer'ları: yeni mesaj almayı durdurun, işlenmekte olanları ack'leyin; yarım kalanlar zaten yeniden teslim edilir, bu yüzden handler'lar idempotent olmalıdır.