Skill de Worker de Fila

Worker BullMQ com retentativas e checklist de DLQ - uma Skill de Agente para processamento assíncrono de jobs no Node.js 24 com Redis.

O Que Esta Skill Faz

Produz um plano de bootstrap do worker: definição da fila, entrada do processo do worker, schema do payload, política de retentativa/DLQ, hooks de observabilidade e divisão do deploy a partir da API HTTP.

Quando Invocar

• Adicionar jobs de e-mail, webhook ou exportação a uma API existente
• Mover trabalho síncrono para fora do caminho da requisição (alívio de 502/timeout)
• Padronizar comportamento de retentativa entre serviços
• Criar um deployável apenas para worker no monorepo

Entradas

Saídas

• src/queues/<name>.queue.ts - Produtor da fila
• src/workers/<name>.worker.ts - Consumidor do worker
• src/schemas/<name>.job.ts - Schema do payload Zod
• Script package.json: "worker:<name>": "node dist/workers/<name>.worker.js"
• Etapas de inspeção da fila DLQ ou jobs falhados
• Comandos de verificação

Guardrails

1. Workers rodam em processo separado - nunca new Worker() dentro de server.ts HTTP.
2. maxRetriesPerRequest: null em conexões ioredis usadas por workers BullMQ.
3. Validar payload com Zod - parse lança exceção → retentativa BullMQ; logar "poison pills".
4. Sem removeOnComplete: true ilimitado - manter os últimos N para depuração.
5. Retentar efeitos colaterais POST-like apenas com chaves de idempotência armazenadas no Postgres.
6. SIGTERM: await worker.close() antes de sair para jobs em andamento.
7. Logar jobId, attemptsMade, não PII completo do payload.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

# Verificação após a saída da skill
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   # esperar 0 em sucesso
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);

Checklist DLQ

• attempts definido por tipo de job (3-5 típico)
• backoff: { type: "exponential", delay: 2000 }
• Jobs falhados após tentativas máximas copiados para a fila email-dlq OU retidos no conjunto failed
• Runbook: como reproduzir job DLQ manualmente
• Alerta no limite de contagem failed no Redis/Bull Board
• Dashboard: profundidade da fila, taxa de processamento, contagem de stalled

Exemplos de Prompts

Use a Skill de Worker de Fila:
- Fila: webhooks-outbound
- Payload: { url, secret, eventType, body }
- Concorrência: 20
- Idempotência: eventId único no Postgres
- Serviço: notifications-api (Fastify 5)

Relacionados

Relacionado

• bullmq / ioredis - guia de pareamento
• BullMQ - padrões de profundidade de fila
• zod - validação de payload
• Noções Básicas de Skills de Agente - regras de invocação

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (LTS Ativo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.