¿Cómo implementas un graceful shutdown?

Question

Accepted Answer

**Graceful shutdown** significa detener un servidor limpiamente cuando recibe una señal de terminación: terminando las solicitudes en curso, cerrando conexiones (BD, etc.) y liberando recursos, en lugar de matarlo abruptamente y descartar el trabajo activo. Es esencial para despliegues sin tiempo de inactividad y para la fiabilidad.

## Por qué un apagado abrupto es un problema

```text
Sin graceful shutdown, cuando el proceso se mata (despliegue, scale-down, crash):
  ✗ Las solicitudes en curso se descartan → los usuarios reciben errores
  ✗ Transacciones de BD quedan incompletas
  ✗ Conexiones no cerradas limpiamente → fugas/bloqueos
```

Durante los despliegues y el autoescalado, los procesos se detienen constantemente; hacerlo limpiamente es lo que vuelve los despliegues fluidos.

## Implementándolo

```js
import http from "http";
const server = http.createServer(app);
server.listen(3000);

async function shutdown(signal) {
  console.log(`${signal} received — shutting down gracefully`);

// 1. Deja de aceptar conexiones NUEVAS; termina las existentes
  server.close(async () => {
    // 2. Este callback se ejecuta una vez que todas las solicitudes activas han terminado
    await db.end();            // cierra el pool de la base de datos
    await redis.quit();        // cierra otras conexiones
    console.log("clean shutdown complete");
    process.exit(0);           // sale con éxito
  });

// 3. Red de seguridad: fuerza la salida si la limpieza tarda demasiado
  setTimeout(() => {
    console.error("forced shutdown — cleanup timed out");
    process.exit(1);
  }, 10_000).unref();
}

// Escucha las señales de terminación
process.on("SIGTERM", () => shutdown("SIGTERM")); // enviada por orquestadores (k8s, Docker)
process.on("SIGINT", () => shutdown("SIGINT"));   // Ctrl+C en desarrollo
```

La secuencia: captura la señal → `server.close()` (detén nuevas conexiones, drena las existentes) → cierra BD/Redis/otros recursos → sal. Un **timeout de respaldo** fuerza la salida si algo se cuelga, de modo que una conexión atascada no pueda bloquear el apagado para siempre.

## Las señales

```text
SIGTERM → la señal estándar de "por favor termina" de los orquestadores en despliegue/scale-down
SIGINT  → Ctrl+C (desarrollo)
SIGKILL → no se puede capturar (force kill) — el graceful shutdown no ayuda aquí
```

## En entornos contenedorizados

```text
Kubernetes/Docker envían SIGTERM, esperan un período de gracia (p. ej. 30s), LUEGO SIGKILL.
Tu aplicación debe terminar dentro de esa ventana → mantén el timeout de apagado más corto.
Los readiness probes deberían marcar el pod como no listo para que el load balancer deje de enviar tráfico.
```

## Por qué es importante

El graceful shutdown es lo que habilita los **despliegues sin tiempo de inactividad** y la operación fiable en entornos modernos (especialmente contenedorizados/orquestados), donde los procesos se detienen y reinician de forma rutinaria.

Sin él, cada despliegue o scale-down descarta solicitudes activas y arriesga inconsistencia de datos.

Implementar la secuencia captura-señal → dejar-de-aceptar → drenar → cerrar-recursos → salir (con una red de seguridad por timeout) es un sello de los servicios Node listos para producción y una preocupación operativa importante que a menudo se pasa por alto.