Habilidad de Worker de Cola

Worker de BullMQ con reintentos y lista de verificación de DLQ - una Habilidad de Agente para el procesamiento asíncrono de trabajos en Node.js 24 con Redis.

Qué Hace Esta Habilidad

Produce un plan de arranque de worker: definición de cola, entrada del proceso de worker, esquema de carga útil, política de reintentos/DLQ, hooks de observabilidad y división del despliegue de la API HTTP.

Cuándo Usarlo

• Añadir trabajos de correo electrónico, webhook o exportación a una API existente
• Mover el trabajo síncrono fuera de la ruta de solicitud (alivio de 502/tiempo de espera)
• Estandarizar el comportamiento de reintentos en todos los servicios
• Crear un nuevo desplegable solo para workers en el monorepo

Entradas

Salidas

• src/queues/<name>.queue.ts - Productor de cola
• src/workers/<name>.worker.ts - Consumidor de worker
• src/schemas/<name>.job.ts - Esquema de carga útil Zod
• Script package.json: "worker:<name>": "node dist/workers/<name>.worker.js"
• Cola DLQ o pasos de inspección de trabajos fallidos
• Comandos de verificación

Barreras de Protección

1. Los workers se ejecutan en un proceso separado - nunca new Worker() dentro de server.ts HTTP.
2. maxRetriesPerRequest: null en las conexiones ioredis utilizadas por los workers de BullMQ.
3. Valida la carga útil con Zod - parse lanza una excepción → reintento de BullMQ; registra los "poison pills".
4. No removeOnComplete: true ilimitado - mantén los últimos N para depuración.
5. Reintenta efectos secundarios tipo POST solo con claves de idempotencia almacenadas en Postgres.
6. SIGTERM: await worker.close() antes de salir para trabajos en curso.
7. Registra jobId, attemptsMade, no la carga útil completa de PII.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

# Verificación después de la salida de la habilidad
export REDIS_URL=redis://localhost:6379
npm run build
npm run worker:email &
WORKER_PID=$!
 
node -e "
  import { emailQueue } from './dist/queues/email.queue.js';
  const job = await emailQueue.add('send', { to: 'test@example.com', templateId: 'welcome' });
  console.log('enqueued', job.id);
"
 
sleep 5
redis-cli LLEN bull:email:failed   # espera 0 si tiene éxito
kill -TERM $WORKER_PID

// src/schemas/email.job.ts
import { z } from "zod";
 
export const emailJobSchema = z.object({
  to: z.string().email(),
  templateId: z.string(),
  vars: z.record(z.string()).default({}),
});
 
export type EmailJob = z.infer<typeof emailJobSchema>;

// src/workers/email.worker.ts
import { Worker } from "bullmq";
import { createRedis } from "../redis.js";
import { emailJobSchema } from "../schemas/email.job.js";
import { sendEmail } from "../services/email.js";
 
const worker = new Worker(
  "email",
  async (job) => {
    const payload = emailJobSchema.parse(job.data);
    await sendEmail(payload);
  },
  {
    connection: createRedis(),
    concurrency: 5,
  }
);
 
async function shutdown() {
  await worker.close();
  process.exit(0);
}
process.on("SIGTERM", shutdown);
process.on("SIGINT", shutdown);

Lista de Verificación de DLQ

• attempts configurados por tipo de trabajo (3-5 es típico)
• backoff: { type: "exponential", delay: 2000 }
• Trabajos fallidos después de intentos máximos copiados a la cola email-dlq O retenidos en el conjunto failed
• Runbook: cómo reproducir manualmente un trabajo de DLQ
• Alerta sobre el umbral de recuento failed en Redis/Bull Board
• Panel de control: profundidad de la cola, tasa de procesamiento, recuento de trabajos estancados

Ejemplos de Prompts

Usa la Habilidad de Worker de Cola:
- Cola: webhooks-outbound
- Carga útil: { url, secret, eventType, body }
- Concurrencia: 20
- Idempotencia: eventId único en Postgres
- Servicio: notifications-api (Fastify 5)

Preguntas Frecuentes

Relacionado

• bullmq / ioredis - guía de emparejamiento
• BullMQ - patrones de profundidad de cola
• zod - validación de carga útil
• Conceptos básicos de las habilidades del agente - reglas de invocación

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.