Provedores de Fila

O Hedhog processa tarefas em segundo plano — envio de e-mails, geração de relatórios, processamento de arquivos, tarefas agendadas — através do @hed-hog-pro/queue. Apenas o provedor Database está de fato implementado hoje. RabbitMQ e BullMQ existem como configurações e como um valor de enum provider, mas ainda não há um worker RabbitMQ ou BullMQ funcional por trás deles — escolher qualquer um dos dois nas configurações não fará as tarefas avançarem.

Isto não é um erro de configuração da sua parte se não funcionar; é o estado atual da biblioteca. Construa sobre o Database e trate as configurações de RabbitMQ/BullMQ como reservadas para uma versão futura, não como algo a depurar.

Status: ⚠️ Parcial — o provedor Database está totalmente implementado; RabbitMQ e BullMQ são configurações reservadas, ainda sem um provedor por trás.

1. Deixe queue.provider definido como database — é o único que funciona
2. Registre um handler de tarefa via QueueModule.register({ handlers: {...} })
3. Enfileire uma tarefa e confirme que uma linha queue_job aparece, e depois muda de pending para done

1. O código da aplicação enfileira uma tarefa, ex.: QueueService.add('send-email', payload)
2. A tarefa é gravada como uma linha na tabela queue_job com status = 'pending'
3. O QueueWorkerProcessor consulta essa tabela em intervalos, reivindica atomicamente um lote de tarefas via um updateMany com lock otimista (para que múltiplas instâncias da API possam rodar workers sem processar a mesma tarefa em duplicidade) e invoca o handler registrado correspondente
4. Em caso de sucesso, a tarefa é marcada como concluída; em caso de falha, ela é reprocessada até queue.default_max_attempts, depois marcada como falha
5. Tarefas presas em processing além de queue.database.lock_timeout_seconds (ex.: um worker que travou no meio da tarefa) são automaticamente liberadas de volta para reprocessamento — você não precisa desbloqueá-las manualmente

Diferente da maioria das outras receitas, as configurações de fila usam chaves separadas por ponto, não por hífen — não duvide de si mesmo se você ver queue.database.poll_interval_seconds em vez de queue-database-poll-interval-seconds, isso está correto.

Não suba RabbitMQ ou Redis esperando que o Hedhog os utilize — ainda não há nada do outro lado escutando.

Registre os handlers no seu módulo NestJS:

import { QueueModule } from '@hed-hog-pro/queue';

@Module({
  imports: [
    QueueModule.register({
      handlers: {
        'send-email': SendEmailHandler,
        'process-report': ProcessReportHandler,
      },
    }),
  ],
})
export class AppModule {}

Cada handler é uma classe com um método handle(job):

@Injectable()
export class SendEmailHandler implements JobHandler {
  async handle(job: Job<{ to: string; subject: string; body: string }>) {
    await this.mail.send(job.data);
  }
}

Lance um NonRetryableError (do @hed-hog-pro/queue) em vez de um erro comum se uma falha não deve ser reprocessada — por exemplo, uma tarefa que falhou porque os dados de entrada eram permanentemente inválidos, não por causa de uma indisponibilidade transitória.

Como o worker usa uma reivindicação atômica (updateMany com um filtro de status como lock otimista), é seguro rodar múltiplas instâncias da API com queue.worker.enabled = true simultaneamente — elas não processarão a mesma tarefa em duplicidade. A vazão é limitada por queue.database.poll_interval_seconds e queue.database.batch_size; reduza o intervalo de consulta ou aumente o tamanho do lote para volume maior, ao custo de mais carga de consulta frequente no PostgreSQL.

• Enfileire uma tarefa de teste e confirme que uma linha aparece em queue_job com status = 'pending', e depois muda para done dentro de queue.database.poll_interval_seconds
• Force um handler a lançar uma exceção uma vez e confirme que a tarefa é reprocessada em vez de desaparecer, até queue.default_max_attempts