28. Node.js en producción: bucle de eventos, memoria, streams y perfilado

28.1 Qué vas a poder hacer al terminar

28.2 Cómo se ejecuta realmente tu código

La frase «Node.js es de un solo hilo» se repite tanto y se entiende tan poco que conviene desmontarla desde el principio. Un proceso de Node.js tiene varios hilos. Lo que tiene uno solo es el hilo que ejecuta tu JavaScript. Alrededor de él, la biblioteca libuv mantiene un grupo de hilos para operaciones de sistema de ficheros y criptografía, y el sistema operativo se encarga por su cuenta de la entrada y salida de red mediante mecanismos de notificación que no consumen un hilo por conexión.

Esa distinción no es una curiosidad: es la que explica por qué diez mil conexiones simultáneas no son un problema y por qué cinco llamadas a fs.readFileSync sí lo son.

  ┌─────────────────────────────────────────────────────────────┐
  │                     PROCESO DE NODE.JS                      │
  │                                                             │
  │   ┌───────────────────────────────────────────────────┐     │
  │   │  HILO PRINCIPAL                                   │     │
  │   │  ┌─────────────┐      ┌────────────────────────┐  │     │
  │   │  │ V8          │      │  libuv                 │  │     │
  │   │  │ (ejecuta tu │◄────►│  (bucle de eventos)    │  │     │
  │   │  │  JavaScript)│      │                        │  │     │
  │   │  └─────────────┘      └───────────┬────────────┘  │     │
  │   └───────────────────────────────────┼───────────────┘     │
  │                                       │                     │
  │        ┌──────────────────────────────┼──────────────┐      │
  │        ▼                              ▼              ▼      │
  │  ┌───────────┐              ┌──────────────┐  ┌───────────┐ │
  │  │ Thread    │              │ epoll/kqueue │  │ Worker    │ │
  │  │ pool      │              │ /IOCP        │  │ threads   │ │
  │  │ (4 por    │              │              │  │ (los que  │ │
  │  │  defecto) │              │ La RED no    │  │  crees tú)│ │
  │  │           │              │ consume      │  │           │ │
  │  │ fs, dns,  │              │ hilos: el SO │  │ Cada uno  │ │
  │  │ zlib,     │              │ avisa cuando │  │ con su    │ │
  │  │ crypto    │              │ hay datos    │  │ propio V8 │ │
  │  └───────────┘              └──────────────┘  └───────────┘ │
  └─────────────────────────────────────────────────────────────┘

28.2.1 Las fases del bucle de eventos

El bucle de eventos no es una cola única: es un ciclo de seis fases, cada una con su propia cola de callbacks. Conocer el orden explica comportamientos que de otro modo parecen caprichosos.

   ┌─────────────────────────────────────────────┐
   │                                             │
   │   ┌──────────────────────────┐              │
   └──►│         timers           │  callbacks de setTimeout
       │                          │  y setInterval vencidos
       └────────────┬─────────────┘
                    ▼
       ┌──────────────────────────┐
       │   pending callbacks      │  algunos errores de TCP
       └────────────┬─────────────┘  aplazados del ciclo anterior
                    ▼
       ┌──────────────────────────┐
       │   idle, prepare          │  uso interno de libuv
       └────────────┬─────────────┘
                    ▼
       ┌──────────────────────────┐      ┌─────────────────┐
       │         poll             │◄────►│ Conexiones      │
       │  Aquí se pasa la mayor   │      │ entrantes,      │
       │  parte del tiempo.       │      │ datos leídos,   │
       │  Si no hay nada más que  │      │ ficheros        │
       │  hacer, BLOQUEA aquí     │      │ terminados      │
       │  esperando E/S.          │      └─────────────────┘
       └────────────┬─────────────┘
                    ▼
       ┌──────────────────────────┐
       │        check             │  callbacks de setImmediate
       └────────────┬─────────────┘
                    ▼
       ┌──────────────────────────┐
       │    close callbacks       │  socket.on('close'), etc.
       └────────────┬─────────────┘
                    │
                    └───── vuelta al principio ─────►

   ENTRE CADA FASE, y también entre cada callback individual, se vacían
   POR COMPLETO estas dos colas, en este orden:

       1. process.nextTick()   ← máxima prioridad
       2. microtareas          ← promesas: .then, await, queueMicrotask

console.log('1. síncrono');

setTimeout(() => console.log('6. timers'), 0);
setImmediate(() => console.log('7. check'));

Promise.resolve().then(() => console.log('4. microtarea'));
process.nextTick(() => console.log('3. nextTick'));

queueMicrotask(() => console.log('5. microtarea 2'));

console.log('2. síncrono');

// Salida:
// 1. síncrono
// 2. síncrono
// 3. nextTick        ← toda la cola de nextTick, antes que las promesas
// 4. microtarea      ← luego las microtareas, en orden de encolado
// 5. microtarea 2
// 6. timers          ← ya en la siguiente iteración del bucle
// 7. check

let n = 0;
function procesar() {
  if (n++ < 1e9) process.nextTick(procesar);
}
procesar();

setTimeout(() => {
  console.log('esto NO se imprime nunca');
}, 100);

// El bucle jamás sale de vaciar la cola de
// nextTick. El servidor deja de responder.

let n = 0;
function procesar() {
  if (n++ < 1e9) setImmediate(procesar);
}
procesar();

setTimeout(() => {
  console.log('esto SÍ se imprime');
}, 100);

// setImmediate encola en la fase check, así
// que el bucle completa la vuelta y atiende
// temporizadores y E/S entre iteraciones.

28.2.2 El grupo de hilos y su tamaño

Cuatro tipos de operación no se pueden resolver con notificaciones del sistema operativo y por eso libuv las delega en un grupo de hilos: el sistema de ficheros, la resolución de nombres con dns.lookup, la compresión con zlib y algunas operaciones criptográficas como pbkdf2, scrypt y la generación de claves. Ese grupo tiene cuatro hilos por defecto, y ese número es una de las causas de degradación más silenciosas que existen.

const crypto = require('node:crypto');
const inicio = Date.now();

// Cinco operaciones criptográficas costosas lanzadas a la vez.
for (let i = 0; i < 5; i++) {
  crypto.pbkdf2('clave', 'sal', 200_000, 64, 'sha512', () => {
    console.log(`${i}: ${Date.now() - inicio} ms`);
  });
}

// Salida típica en una máquina de 4 núcleos:
//   0: 410 ms
//   1: 415 ms
//   2: 418 ms
//   3: 420 ms
//   4: 830 ms   ← ¡el doble! Esperó a que se liberara un hilo.
//
// Con UV_THREADPOOL_SIZE=8 las cinco terminan a la vez.
// Con 100 peticiones simultáneas de login usando bcrypt, este efecto
// convierte una latencia de 400 ms en una de 10 segundos.

28.3 Bloquear el bucle: el pecado capital

Cualquier código JavaScript síncrono que tarde en ejecutarse impide que el bucle avance. Durante ese tiempo el proceso no acepta conexiones, no lee sockets, no dispara temporizadores y no responde a la comprobación de salud. Con una sola instancia, cien milisegundos de bloqueo por petición y cien peticiones por segundo, el servidor está permanentemente saturado aunque la CPU parezca ir al treinta por ciento en las gráficas.

28.3.1 Medir el retardo del bucle

La métrica clave no es la CPU ni la memoria: es cuánto se retrasa el bucle de eventos respecto a lo que debería tardar. Si programas algo para dentro de veinte milisegundos y se ejecuta a los ciento ochenta, tienes ciento sesenta milisegundos de retardo y todas tus peticiones lo están sufriendo. Node.js incluye un histograma preciso para medirlo.

import { Injectable, OnModuleInit, OnModuleDestroy, Logger } from '@nestjs/common';
import { monitorEventLoopDelay, performance } from 'node:perf_hooks';

@Injectable()
export class BucleService implements OnModuleInit, OnModuleDestroy {
  private readonly log = new Logger(BucleService.name);
  // resolution: cada cuántos ms se toma una muestra. 20 ms es un
  // buen compromiso entre precisión y coste.
  private readonly histograma = monitorEventLoopDelay({ resolution: 20 });
  private temporizador?: NodeJS.Timeout;

  onModuleInit() {
    this.histograma.enable();

    this.temporizador = setInterval(() => {
      const h = this.histograma;
      const metricas = {
        // El histograma trabaja en nanosegundos.
        p50: +(h.percentile(50) / 1e6).toFixed(1),
        p99: +(h.percentile(99) / 1e6).toFixed(1),
        max: +(h.max / 1e6).toFixed(1),
      };

      // El p99 es la señal útil. La media esconde justo lo que
      // buscas: un bloqueo de 2 s cada minuto no mueve la media.
      if (metricas.p99 > 100) {
        this.log.warn(`Retardo del bucle alto: ${JSON.stringify(metricas)}`);
      }
      this.publicarEnPrometheus(metricas);
      h.reset();
    }, 10_000);

    // unref() evita que este intervalo mantenga vivo el proceso
    // cuando todo lo demás ha terminado y queremos apagar.
    this.temporizador.unref();
  }

  onModuleDestroy() {
    clearInterval(this.temporizador);
    this.histograma.disable();
  }

  private publicarEnPrometheus(m: Record<string, number>) { /* ... */ }
}

28.4 Cuando hace falta paralelismo de verdad

Ante una tarea que consume CPU hay cinco respuestas posibles, ordenadas de menor a mayor coste. La disciplina profesional consiste en no saltar a la quinta sin haber descartado las cuatro anteriores.

28.4.1 Hilos de trabajo con un grupo reutilizable

import { parentPort, workerData } from 'node:worker_threads';

// Este fichero se ejecuta en un HILO APARTE, con su propia instancia
// de V8, su propio montón y su propio bucle de eventos. No comparte
// variables con el hilo principal ni tiene acceso a los servicios de
// Nest: hay que pasarle todo lo que necesite.
function calcular(filas: FilaTarea[]) {
  // Cálculo pesado: agregaciones, percentiles, tendencias...
  return filas.reduce(/* ... */);
}

parentPort!.on('message', (mensaje: { id: string; filas: FilaTarea[] }) => {
  try {
    parentPort!.postMessage({ id: mensaje.id, resultado: calcular(mensaje.filas) });
  } catch (e) {
    parentPort!.postMessage({ id: mensaje.id, error: (e as Error).message });
  }
});

import { Injectable, OnModuleInit, OnModuleDestroy } from '@nestjs/common';
import { Worker } from 'node:worker_threads';
import { cpus } from 'node:os';
import { randomUUID } from 'node:crypto';
import { join } from 'node:path';

interface Pendiente {
  resolver: (v: unknown) => void;
  rechazar: (e: Error) => void;
  reloj: NodeJS.Timeout;
}

@Injectable()
export class GrupoHilosService implements OnModuleInit, OnModuleDestroy {
  private hilos: Worker[] = [];
  private libres: Worker[] = [];
  private readonly espera: Array<(w: Worker) => void> = [];
  private readonly pendientes = new Map<string, Pendiente>();

  onModuleInit() {
    // Regla de dimensionado: núcleos menos uno, dejando el principal
    // para atender la red. Nunca más hilos que núcleos: competirían
    // por la misma CPU y el cambio de contexto empeoraría todo.
    const n = Math.max(1, cpus().length - 1);

    for (let i = 0; i < n; i++) {
      const w = new Worker(join(__dirname, 'informe.worker.js'));

      w.on('message', (m: { id: string; resultado?: unknown; error?: string }) => {
        const p = this.pendientes.get(m.id);
        if (!p) return;
        clearTimeout(p.reloj);
        this.pendientes.delete(m.id);
        m.error ? p.rechazar(new Error(m.error)) : p.resolver(m.resultado);
        this.devolver(w);
      });

      // Un hilo puede morir por un error no capturado o por quedarse
      // sin memoria. Hay que reponerlo o el grupo se vacía en silencio
      // y las peticiones se quedan esperando para siempre.
      w.on('error', () => this.reponer(w));
      w.on('exit', (codigo) => { if (codigo !== 0) this.reponer(w); });

      this.hilos.push(w);
      this.libres.push(w);
    }
  }

  async ejecutar<T>(filas: unknown[], msTope = 30_000): Promise<T> {
    const hilo = await this.tomarLibre();
    const id = randomUUID();

    return new Promise<T>((resolver, rechazar) => {
      // Un tope de tiempo es imprescindible: si el hilo entra en un
      // bucle infinito, sin él la promesa nunca se resolvería y la
      // petición HTTP quedaría colgada indefinidamente.
      const reloj = setTimeout(() => {
        this.pendientes.delete(id);
        void hilo.terminate();   // matar y reponer
        this.reponer(hilo);
        rechazar(new Error('El cálculo superó el tiempo máximo'));
      }, msTope);

      this.pendientes.set(id, { resolver: resolver as any, rechazar, reloj });
      hilo.postMessage({ id, filas });
    });
  }

  private tomarLibre(): Promise<Worker> {
    const libre = this.libres.pop();
    if (libre) return Promise.resolve(libre);
    // No hay hilos libres: la petición espera en cola en lugar de
    // crear un hilo nuevo. Crear hilos bajo demanda con carga alta
    // es la forma más rápida de quedarse sin memoria.
    return new Promise((r) => this.espera.push(r));
  }

  private devolver(w: Worker) {
    const siguiente = this.espera.shift();
    siguiente ? siguiente(w) : this.libres.push(w);
  }

  private reponer(muerto: Worker) { /* crea uno nuevo y sustituye */ }

  async onModuleDestroy() {
    await Promise.all(this.hilos.map((w) => w.terminate()));
  }
}

28.4.2 Clúster, y por qué probablemente no lo necesitas

El módulo cluster arranca varios procesos idénticos que comparten el puerto de escucha, repartiendo las conexiones entre ellos. Multiplica el aprovechamiento de una máquina con varios núcleos, pero en una arquitectura moderna esa función suele estar cubierta un nivel más arriba.

28.5 Streams: no acumules lo que puedes fluir

Un stream es una abstracción sobre datos que llegan a trozos. En lugar de esperar a tener el fichero entero en memoria para procesarlo, lo vas consumiendo conforme llega. En un servidor de producción esto no es una optimización cosmética: es la diferencia entre exportar un informe de cien mil tareas con 50 MB de RAM o tumbar el proceso con un Out of memory.

  SIN STREAM (malo)                    CON STREAM (bueno)

  [BD] ──► buffer enorme ──► [HTTP]    [BD] ──► trozo ──► [HTTP]
            ▲                                    │
            │ todo en RAM                        ▼
            │ a la vez                    el siguiente trozo
                                          (contrapresión si
                                           el cliente es lento)

@Get('export.csv')
async exportar() {
  // find() carga TODAS las filas en memoria.
  const tareas = await this.em.find(Tarea, {});
  const csv = tareas.map((t) =>
    `${t.id},${escape(t.titulo)},${t.estado}`
  ).join('\n');
  return csv; // String enorme en el montón
}
// Con 500.000 tareas esto es un OOM garantizado
// en un contenedor de 512 MB.

@Get('export.csv')
async exportar(@Res({ passthrough: false }) res: Response) {
  res.setHeader('Content-Type', 'text/csv; charset=utf-8');
  res.setHeader(
    'Content-Disposition',
    'attachment; filename="tareas.csv"',
  );
  res.write('id,titulo,estado\n');

  // Cursor del lado del servidor: una fila cada vez.
  for await (const t of this.em.createQueryBuilder(Tarea)
    .select(['id', 'titulo', 'estado'])
    .orderBy({ id: 'ASC' })
    .getResultStream()) {
    const linea = `${t.id},${csvEscape(t.titulo)},${t.estado}\n`;
    // write() puede devolver false: el búfer de salida está lleno.
    // Hay que esperar a 'drain' o saturarás la memoria igual.
    if (!res.write(linea)) {
      await once(res, 'drain');
    }
  }
  res.end();
}

28.5.1 pipeline y composición

import { createReadStream, createWriteStream } from 'node:fs';
import { pipeline } from 'node:stream/promises';
import { createGzip } from 'node:zlib';

async function comprimirAdjunto(origen: string, destino: string) {
  // pipeline propaga errores, destruye los streams si uno falla
  // y espera a que todo termine. pipe() clásico NO hace nada de eso.
  await pipeline(
    createReadStream(origen),
    createGzip({ level: 6 }),
    createWriteStream(destino),
  );
}

28.6 Memoria: el montón de V8 y las fugas

V8 divide la memoria del proceso en varias regiones. La que más te importa es el montón (heap), donde viven los objetos de JavaScript. El recolector de basura libera lo que ya no es alcanzable; lo que permanece referenciado desde algún sitio «vivo» (una variable global, una caché, un closure, un listener) no se libera nunca. Eso es una fuga.

  ┌─────────────────────────────────────────────┐
  │  PROCESO NODE                               │
  │  ┌──────────────┐  ┌─────────────────────┐  │
  │  │ Stack        │  │ Montón (heap)       │  │
  │  │ (marcos de   │  │  Nueva generación   │  │
  │  │  llamada)    │  │  (objetos jóvenes,  │  │
  │  └──────────────┘  │   GC frecuente)     │  │
  │                    │  Vieja generación   │  │
  │  ┌──────────────┐  │  (sobreviven más,   │  │
  │  │ C++ / Buffers│  │   GC más caro)      │  │
  │  │ fuera del    │  └─────────────────────┘  │
  │  │ heap de JS   │                           │
  │  │ (ojo: también│  Límite típico: --max-old-│
  │  │  cuentan)    │  space-size (por defecto  │
  │  └──────────────┘  ~2–4 GB según máquina)   │
  └─────────────────────────────────────────────┘

# RSS = memoria residente del proceso (lo que ve el SO)
node -e "setInterval(() => console.log(process.memoryUsage()), 2000)"

# heapUsed / heapTotal: montón de V8
# external: Buffers y objetos C++
# arrayBuffers: ArrayBuffer / SharedArrayBuffer

28.6.1 Fugas típicas en NestJS / TaskFlow

const cache = new Map<string, Tarea>();

@Injectable()
export class CacheTareas {
  get(id: string) { return cache.get(id); }
  set(id: string, t: Tarea) { cache.set(id, t); }
  // Sin evicción: en un mes el Map tiene
  // todas las tareas que existieron.
}

import { LRUCache } from 'lru-cache';

@Injectable()
export class CacheTareas {
  private readonly cache = new LRUCache<string, TareaDto>({
    max: 5_000,
    ttl: 60_000, // 1 minuto
  });

  get(id: string) { return this.cache.get(id); }
  set(id: string, t: TareaDto) { this.cache.set(id, t); }
}

28.6.2 Diagnosticar con instantáneas del montón

import { Controller, Post, UseGuards } from '@nestjs/common';
import { writeHeapSnapshot } from 'node:v8';
import { AdminGuard } from '../seguridad/admin.guard';

@Controller('interno/debug')
@UseGuards(AdminGuard)
export class HeapController {
  @Post('heap-snapshot')
  snapshot() {
    // Genera un .heapsnapshot que abres en Chrome DevTools
    // → Memory → Load. Compara dos capturas: "antes" y "después"
    // de reproducir la fuga. Busca objetos que CRECEN y retienen.
    const ruta = writeHeapSnapshot();
    return { ruta };
  }
}

28.7 Perfilado de CPU y gráficos de llamas

Cuando el retardo del bucle es alto y la CPU está alta, necesitas saber qué función consume el tiempo. Adivinar («seguro que es la base de datos») falla la mitad de las veces: a menudo es serialización JSON, una regex, un mapper o bcrypt mal dimensionado.

# Opción 1: inspector (Chrome DevTools → Performance)
node --inspect=0.0.0.0:9229 dist/main.js
# Abre chrome://inspect → Profile → Start

# Opción 2: perfil de CPU a fichero (0 = infinito hasta SIGINT)
node --cpu-prof --cpu-prof-dir=./perfiles dist/main.js
# Genera un .cpuprofile; ábrelo en DevTools o en speedscope.app

# Opción 3: clinic.js (muy didáctico)
npx clinic flame -- node dist/main.js

/*
  Eje X = tiempo (o muestras). Eje Y = pila de llamadas.
  Las barras ANCHAS arriba del todo son el coste agregado.
  Baja hasta la barra ancha más profunda que sea TU código:
  ahí está el sospechoso.

  Ejemplo TaskFlow:
  http_parser → Nest → TareasService.listar
    → JSON.stringify   ← barra ancha: payload enorme
    → em.find          ← si es ancha: consulta o N+1
*/

28.8 El pool de conexiones a la base de datos

Cada petición que usa MikroORM necesita una conexión (o la reutiliza del pool). Si tienes 4 réplicas de Nest con pool.max = 20 cada una, puedes estar abriendo 80 conexiones contra PostgreSQL. Si el servidor está configurado con max_connections = 100, te quedan 20 para migraciones, admin y picos: un mal cálculo aquí produce errores remaining connection slots are reserved que parecen «aleatorios».

export default defineConfig({
  // ...
  pool: {
    // Fórmula práctica:
    // max_total ≈ (max_connections_postgres * 0.7) / num_replicas
    // Deja margen para migraciones, métricas y humanos.
    min: 2,
    max: 10,
    // Cuánto esperar un hueco libre antes de fallar la petición
    acquireTimeoutMillis: 5_000,
  },
});

async detalle(id: string) {
  const t = await this.em.findOneOrFail(Tarea, id);
  // Cada acceso lazy dispara otra query (N+1)
  const autor = await t.autor.load();
  const proyecto = await t.proyecto.load();
  return { t, autor, proyecto };
}

async detalle(id: string) {
  return this.em.findOneOrFail(Tarea, id, {
    populate: ['autor', 'proyecto', 'etiquetas'],
  });
}

28.9 Configurar el proceso para producción

28.9.1 Memoria, warnings y visibilidad

# Ajusta el montón al tamaño del contenedor (ejemplo: límite 512Mi)
# Deja ~100–150 MB para código nativo, stacks y buffers.
NODE_OPTIONS="--max-old-space-size=350 --enable-source-maps"

# En desarrollo útil; en producción suele sobrar el ruido:
# --trace-warnings

node dist/main.js

28.9.2 Apagado ordenado

Kubernetes envía SIGTERM antes de matar el contenedor. Si no cierras el servidor HTTP, el pool de BD y las colas, cortarás peticiones a mitad y dejarás transacciones abiertas.

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  app.enableShutdownHooks(); // escucha SIGTERM/SIGINT

  // Tras SIGTERM: deja de aceptar conexiones nuevas,
  // espera a que terminen las in-flight (con tope),
  // cierra MikroORM, Redis, etc.
  const server = await app.listen(process.env.PORT ?? 3000);

  const cierre = async (senal: string) => {
    console.log(`Señal ${senal}: cerrando…`);
    // tope: si una petición no termina, igual hay que morir
    const tope = setTimeout(() => process.exit(1), 25_000);
    await app.close(); // dispara OnModuleDestroy
    clearTimeout(tope);
    process.exit(0);
  };

  process.on('SIGTERM', () => void cierre('SIGTERM'));
  process.on('SIGINT', () => void cierre('SIGINT'));
}

@Injectable()
export class OrmShutdown implements OnModuleDestroy {
  constructor(private readonly orm: MikroORM) {}

  async onModuleDestroy() {
    await this.orm.close(true); // espera a conexiones del pool
  }
}

28.9.3 Comprobaciones de salud (liveness vs readiness)

// Liveness que consulta la BD
@Get('healthz')
async live() {
  await this.em.getConnection().execute('select 1');
  return { ok: true };
}
// Si Postgres va lento, Kubernetes reinicia
// TODOS los pods → peor cascada.

@Get('live')
live() { return { ok: true }; }

@Get('ready')
async ready() {
  await this.em.getConnection().execute('select 1');
  // opcional: retardo del bucle < umbral
  return { ok: true };
}

28.9.4 Tiempos de espera y cabeceras keep-alive

const server = app.getHttpServer();

// Tiempo máximo para recibir cabeceras (protección básica)
server.headersTimeout = 10_000;
// Tiempo máximo de inactividad en keep-alive
server.keepAliveTimeout = 5_000;
// Importante si hay balanceador: keepAliveTimeout del Node
// debe ser MAYOR que el idle timeout del LB, o el LB reutiliza
// conexiones que Node ya cerró → 502 esporádicos.

28.9.5 Procesos hijos frente a hilos

Antes de los worker threads, la forma habitual de sacar trabajo pesado del hilo principal era child_process: un proceso de sistema operativo aparte. Sigue siendo la herramienta correcta cuando necesitas ejecutar un binario nativo (conversión de imágenes, CLI de PDF, un script en otro lenguaje) o aislar un fallo que podría tumbar V8 entero. Un hilo de trabajo comparte el proceso y es más ligero para JavaScript CPU-bound; un hijo aísla mejor y habla por stdin/stdout o IPC.

import { Injectable } from '@nestjs/common';
import { execFile } from 'node:child_process';
import { promisify } from 'node:util';

const execFileAsync = promisify(execFile);

@Injectable()
export class MiniaturaService {
  /**
   * NUNCA uses exec() con strings interpoladas: inyección de shell.
   * execFile evita el shell y pasa argumentos como array.
   */
  async generar(ruta: string, destino: string) {
    await execFileAsync('convert', [
      ruta, '-resize', '200x200>', destino,
    ], { timeout: 15_000, maxBuffer: 2 * 1024 * 1024 });
  }
}

exec(`convert ${nombre} out.png`);
// nombre = "a.png; rm -rf /" → shell injection

execFile('convert', [nombre, 'out.png']);
// Valida además que la ruta está bajo un
// directorio permitido (path traversal).

28.9.6 Observabilidad mínima del runtime

Sin métricas del proceso solo ves síntomas (502, reinicios). Con unas pocas series temporales triageas la mayoría de incidentes de Node en TaskFlow: retardo del bucle p99, heap usado y RSS, conexiones activas y en espera del pool, más latencia p99 por ruta y tasa de 5xx. OpenTelemetry cubre trazas distribuidas (Angular → Nest → Postgres); el lag y el pool siguen siendo métricas locales imprescindibles.

import client from 'prom-client';

const register = new client.Registry();
client.collectDefaultMetrics({ register });
// Expón GET /metrics solo en red interna o con autenticación.

En incidentes, el orden de lectura recomendado es: ¿subió el lag? → perfil de CPU. ¿Lag bajo y p99 alto? → dependencia o pool. ¿Heap en rampa? → instantáneas. ¿Reinicios sin OOM? → probes mal diseñados o salida por excepción no capturada. Ese árbol evita el «reinicia y reza» que borra evidencia. Documenta umbrales en el runbook: por ejemplo lag p99 > 100 ms durante cinco minutos pagina al equipo; heapUsed por encima del 80 % del max-old-space investiga antes del OOM; waiting en el pool sostenido revisa consultas y tamaño del pool.

28.10 Errores no capturados y promesas rechazadas

Un throw fuera de un try/catch en el hilo principal, o una promesa rechazada sin .catch, puede tumbar el proceso o dejarlo en un estado indefinido según la versión de Node y los flags.

process.on('uncaughtException', (err) => {
  console.error('uncaughtException', err);
  // Lo correcto en la mayoría de servicios: registrar, métrica, y
  // salir. Seguir vivo tras un estado desconocido es peor.
  process.exit(1);
});

process.on('unhandledRejection', (reason) => {
  console.error('unhandledRejection', reason);
  process.exit(1);
});

async asignar(tareaId: string, usuarioId: string) {
  try {
    return await this.em.transactional(async (em) => {
      const tarea = await em.findOneOrFail(Tarea, tareaId);
      tarea.asignadoA = em.getReference(Usuario, usuarioId);
      await em.flush();
      return tarea;
    });
  } catch (e) {
    this.log.error(`asignar falló`, { tareaId, usuarioId, e });
    throw e; // que el filtro global traduzca a HTTP
  }
}

28.11 Pruebas de carga: qué mirar

Una prueba de carga no sirve para presumir de «X peticiones por segundo». Sirve para encontrar el punto en el que el p99 se dispara, el pool se agota o el bucle se retrasa. Enlaza con el capítulo 13 (k6) y con la descarga de carga de la sección 28.3.

import http from 'k6/http';
import { check, sleep } from 'k6';

export const options = {
  stages: [
    { duration: '1m', target: 20 },
    { duration: '3m', target: 80 },
    { duration: '1m', target: 0 },
  ],
  thresholds: {
    http_req_failed: ['rate<0.01'],
    http_req_duration: ['p(99)<500'],
  },
};

export default function () {
  const res = http.get('http://localhost:3000/api/tareas?limit=50', {
    headers: { Authorization: `Bearer ${__ENV.TOKEN}` },
  });
  check(res, { '200': (r) => r.status === 200 });
  sleep(0.3);
}

28.12 Checklist de despliegue Node/Nest

Un detalle que suele olvidarse en checklists es la paridad de entorno: si producción tiene 2 CPU y 512 MB y staging tiene 8 CPU y 4 GB, tus pruebas de carga mentirán. Reproduce límites de CPU y memoria del contenedor también en staging. Otro detalle: el tamaño del bundle y el coste de arranque frío. Un proceso Nest que tarda 40 s en importar módulos hará fallar el startupProbe aunque el código sea correcto; mide time until listen y recorta imports pesados al arranque (carga diferida de rutas admin, por ejemplo).

Respecto a la seguridad del runtime, además del capítulo 12: desactiva stack traces detallados hacia el cliente en producción, limita la superficie de /metrics y de cualquier endpoint de heap snapshot, y no ejecutes el contenedor como root. Node no te obliga a nada de eso; el orquestador y la imagen sí.

28.13 Errores comunes y cómo solucionarlos

28.14 Buenas y malas prácticas

28.15 Preguntas frecuentes

28.16 Ejercicios

import { Injectable, NestMiddleware } from '@nestjs/common';
import { Request, Response, NextFunction } from 'express';
import { monitorEventLoopDelay } from 'node:perf_hooks';

const h = monitorEventLoopDelay({ resolution: 20 });
h.enable();

@Injectable()
export class TooBusyMiddleware implements NestMiddleware {
  use(_req: Request, res: Response, next: NextFunction) {
    const p99ms = h.percentile(99) / 1e6;
    h.reset();
    if (p99ms > 200) {
      res.setHeader('Retry-After', '2');
      res.status(503).json({
        title: 'Servidor saturado',
        detail: 'Reintenta en unos segundos',
        status: 503,
      });
      return;
    }
    next();
  }
}

import { once } from 'node:events';

async function escribirLinea(res: NodeJS.WritableStream, linea: string) {
  if (!res.write(linea)) {
    await once(res, 'drain');
  }
}

28.17 Resumen del capítulo

28.18 Recursos adicionales

Antes de dar por cerrado un incidente de rendimiento en TaskFlow, deja por escrito tres frases: qué métrica se movió, qué evidencia (flamegraph, snapshot, EXPLAIN, log de pool) lo confirma, y qué cambio concreto lo mitiga. Sin esas tres frases, el siguiente turno volverá a empezar de cero. Esa disciplina, más que cualquier flag de V8, es lo que separa un equipo que opera Node en serio de uno que solo lo despliega. Guarda esas notas junto a la alerta: el conocimiento operativo también es código. Y revisa el postmortem a la semana: si la misma clase de fallo se repite, el arreglo fue incompleto y hay que seguir investigando con datos nuevos.