Roteiro de um agendador de jobs: leases, retentativas, chaves de idempotência e uma tabela de fila

Objetivo

Executar jobs em segundo plano e agendamentos recorrentes com execução at-least-once (pelo menos uma vez), retentativas limitadas e sem efeitos colaterais duplicados, usando uma tabela de banco de dados antes de adotar um broker.

Pré-requisitos

Um banco de dados relacional compartilhado por todos os workers, handlers que possam ser tornados idempotentes e um único relógio: os timestamps vêm do banco de dados, não dos hosts dos workers.

Passos

1. Restrições: um job é executado pelo menos uma vez e pode ser executado de novo após uma falha; um agendamento dispara uma vez por slot, mesmo com várias instâncias do scheduler; um job com defeito não pode bloquear os demais.
2. Componentes: uma tabela job como fila; workers que reivindicam, executam e finalizam jobs; um scheduler que transforma agendamentos em jobs; um reaper para leases expirados; uma lista de dead-letter.
3. Modelo de dados: job(id, type, payload, idempotency_key unique, status: ready|running|done|failed|dead, run_at, attempts, max_attempts, locked_by, locked_until, last_error, created_at); schedule(id, job_type, cron, next_run_at, last_slot); um índice em (status, run_at). Para jobs agendados, a chave de idempotência é schedule_id + slot, de modo que uma segunda instância do scheduler que enfileire o mesmo slot não produz nenhum efeito.
4. Reivindicação: SELECT ... WHERE status = 'ready' AND run_at <= now() ORDER BY run_at LIMIT 1 FOR UPDATE SKIP LOCKED; em seguida, definir running, locked_by e locked_until = now() + lease e fazer commit. A documentação do PostgreSQL afirma que, com SKIP LOCKED, as linhas que não podem ser bloqueadas imediatamente são ignoradas, e que isso pode ser usado para evitar contenção de locks quando vários consumidores acessam uma tabela com comportamento de fila. Handlers de longa duração estendem o lease com um heartbeat.
5. Retentativas: em caso de falha, definir run_at = now() + backoff(attempts) com jitter e devolver a linha para ready, até que max_attempts a mova para dead; erros de infraestrutura (banco de dados inacessível) não contam como tentativas. O handler verifica o próprio efeito antes de agir (uma linha já gravada, um id de mensagem já registrado), pois o scheduler não consegue garantir uma execução única.
6. Modos de falha: um worker morre segurando um lease (o reaper redefine a linha após locked_until e o handler é executado novamente); picos no início de cada hora (um deslocamento por agendamento distribui os run_at); um poison job (max_attempts, dead-letter, alerta); crescimento ilimitado da tabela (arquivar as linhas done periodicamente); um worker com relógio defasado (usar apenas a hora do banco de dados).
7. Medir: idade do job ready mais antigo, jobs em execução por tipo, distribuição de tentativas, expirações de lease por hora, quantidade de dead-letter, slots de agendamento perdidos.
8. Não no início: um message broker, prioridades e equidade por tenant, grafos de workflow, reivindicações exactly-once.

Resultado esperado

Uma falha em qualquer ponto atrasa o trabalho em vez de perdê-lo ou duplicá-lo, e o histórico de cada job fica em uma única linha que explica seu estado.

Limites e base de verificação

Projeto proposto, sem medições. Uma tabela de fila serve para volumes moderados; a migração para um broker é uma decisão posterior, orientada pela idade medida da fila e pelas esperas de lock.