Como coordenar um cron entre vários nós NestJS?

Question

IT Interview Practice · Accepted Answer

Primeiro defina o significado de “somente um nó executa o cronjob”. **Evitar execução simultânea e evitar um efeito de negócio repetido são requisitos diferentes.** Um agendador compartilhado coordena a execução; a operação deve continuar segura após falhas e retries.

Considere um faturamento diário em três nós NestJS. Queremos executar o trabalho sem gerar outra fatura quando um worker reiniciar.

## 1. Entenda por que todos os nós iniciam a tarefa

Cada instância registra seu próprio callback de cron. No horário programado, cada uma pode iniciar independentemente:

```text
00:00 -> Node A -> invoice task
      -> Node B -> invoice task
      -> Node C -> invoice task
```

Uma flag local isRunning só existe em um processo. O waitForCompletion do NestJS impede callbacks sobrepostos nessa instância, mas não coordena outros nós. A mesma flag nos três nós ainda deixa três decisões separadas. [Agendamento no NestJS](https://docs.nestjs.com/techniques/task-scheduling).

Precisamos, portanto, de um lugar compartilhado para decidir qual trabalho existe e quem pode processá-lo.

## 2. Escolha o modelo de coordenação

| Situação | Opção a avaliar | Responsabilidade restante |
| --- | --- | --- |
| A plataforma já oferece tarefas agendadas | Agendar fora das instâncias web | Configurar sobreposição, recuperação e execuções perdidas. |
| A equipe já opera BullMQ | Job Scheduler compartilhado e fila dedicada | Configurar concorrência compartilhada e retries seguros. |
| A tarefa precisa continuar nos nós da aplicação | Lock ou lease compartilhado | Tratar propriedade, expiração e workers antigos corretamente. |

Se Redis e BullMQ já existem, um agendador compartilhado com ID estável é uma opção prática para as faturas. Separe o agendamento dos workers para que adicionar nós web não crie agendas independentes.

Em uma versão compatível do BullMQ, configure a concorrência global da fila dedicada como um. Isso limita jobs ativos entre todos os workers; concorrência local de um ainda permite que vários workers executem jobs diferentes. [Concorrência global](https://docs.bullmq.io/guide/queues/global-concurrency).

Decida o que fazer se o trabalho de ontem ainda estiver rodando: esperar, pular ou combinar ocorrências. Defina o fuso e se datas de negócio perdidas devem ser recuperadas após uma interrupção.

## 3. Proteja a fatura, não apenas o job

Suponha que um worker crie a fatura e falhe antes de registrar a conclusão. A recuperação pode repetir o job mesmo com a fatura já existente.

```text
[Create invoice] -> [Crash before completion]
                              |
                            [Retry]
                              |
                  [Same business key: reuse result]
```

Use uma chave de negócio estável, como cliente e período de cobrança. Em operações locais no banco, uma restrição única e uma transação podem ligar a criação da fatura ao registro da execução concluída. O retry encontra o resultado existente em vez de gerar outra fatura.

Para provedores externos, use a chave de idempotência quando disponível e reconcilie resultados incertos. Um ID de job ou registro retido na fila não garante permanentemente que uma ação de negócio nunca se repetirá. [Jobs idempotentes](https://docs.bullmq.io/patterns/idempotent-jobs).

## 4. Conheça as garantias e os limites de um lock

Um lock compartilhado deve ser adquirido atomicamente. Use token de propriedade, expiração e renovação; libere somente se o token ainda corresponder. Caso contrário, um worker antigo pode liberar o lock do novo.

A expiração cria outro cenário: um worker pausado retorna após sua lease vencer enquanto outro já executa. Escritas críticas podem precisar de fencing tokens, números crescentes de propriedade que o destino verifica para rejeitar workers antigos. Um timeout longo não elimina o risco.

Se a coordenação estiver indisponível, decida se a tarefa deve esperar em vez de executar sem propriedade. Para trabalho com consequências importantes, esperar costuma ser mais seguro.

## 5. Verifique os cenários de falha

Teste múltiplos nós, falha após criar a fatura, pausa maior que a lease, perda de conexão com Redis e implantação gradual. Registre data de negócio, worker, tentativa e resultado para distinguir tentativas repetidas de efeitos repetidos.

**Lembre-se:** coordenar agendamento → limitar execução compartilhada → tornar a ação segura para retry → testar recuperação. “Um job ativo” sozinho não comprova exatamente um efeito de negócio.

Situação	Opção a avaliar	Responsabilidade restante
A plataforma já oferece tarefas agendadas	Agendar fora das instâncias web	Configurar sobreposição, recuperação e execuções perdidas.
A equipe já opera BullMQ	Job Scheduler compartilhado e fila dedicada	Configurar concorrência compartilhada e retries seguros.
A tarefa precisa continuar nos nós da aplicação	Lock ou lease compartilhado	Tratar propriedade, expiração e workers antigos corretamente.

1. Entenda por que todos os nós iniciam a tarefa

2. Escolha o modelo de coordenação

3. Proteja a fatura, não apenas o job

4. Conheça as garantias e os limites de um lock

5. Verifique os cenários de falha

Perguntas relacionadas