Um lease pode expirar enquanto o worker que o recebeu está pausado. Quando outro worker assume a tarefa, o processo antigo ainda pode acordar e tentar gravar o resultado que calculou antes da troca. Se o recurso aceitar essa escrita apenas porque o worker conferiu o lease alguns instantes antes, a proteção tem uma janela aberta.
O fencing token fecha essa janela no lugar certo: a fronteira que aceita a mutação. Cada aquisição recebe uma geração crescente. O worker leva essa geração junto da escrita, e o banco ou proxy rejeita qualquer token menor do que o maior token já aceito. O guia sobre retomar um agente depois de um crash trata da recuperação mais ampla; aqui, o foco é impedir que um dono antigo grave depois da retomada.
Este artigo usa uma fixture pequena em Node.js para reproduzir a ordem dos eventos. Ela prova a regra do recurso em memória. Não é um lock distribuído, não mede latência e não prova o comportamento de um broker ou banco específico.
Resposta curta
- O lease decide quem deveria trabalhar agora, mas não consegue parar um processo que já está executando.
- A autoridade de posse deve emitir um token crescente a cada nova aquisição.
- O recurso protegido precisa comparar o token e a mutação de forma atômica.
- Uma rejeição por token antigo não deve virar retry automático com o mesmo token.
Por que conferir o lease antes de gravar não basta?
Imagine que o worker A recebe o lease de job-7 e começa a calcular. Ele sofre uma pausa longa, perde a renovação e o lease expira. O worker B assume a mesma tarefa e grava um resultado novo. A então volta à execução e verifica uma variável local que ainda diz que é o dono. Entre essa verificação e a escrita, nada impede que o resultado antigo substitua o novo.
O problema não depende apenas de garbage collection. Um processo pode ser suspenso, perder CPU, ficar sem rede ou enviar uma requisição que chega atrasada. A análise de Martin Kleppmann sobre locks distribuídos explica por que uma checagem de expiração antes do write não fecha a corrida e por que o serviço que recebe a escrita precisa rejeitar tokens antigos.
A sequência que importa é esta:
| Momento | Worker | Token | Resultado |
|---|---|---|---|
| A tarefa começa | A | 1 |
Pode trabalhar enquanto sua posse é válida |
| A pausa ultrapassa o lease | A | 1 |
O processo pode continuar sem saber que perdeu a posse |
| A tarefa é recuperada | B | 2 |
B vira o dono mais novo |
| B grava | B | 2 |
O recurso aceita a mutação |
| A acorda e grava | A | 1 |
O recurso rejeita a mutação antiga |
O último passo é a diferença entre "o worker deve parar" e "o recurso não aceita uma escrita velha". O primeiro é uma política de liveness. O segundo é a guarda de safety que continua valendo quando o processo falha em obedecer.
Separe lease, heartbeat e fencing token
Esses mecanismos aparecem juntos, mas fazem trabalhos diferentes:
| Mecanismo | Pergunta que responde | Limite |
|---|---|---|
| Lease | Quem pode tentar trabalhar durante este intervalo? | Um processo pausado pode não perceber que perdeu a posse. |
| Heartbeat | O worker ainda consegue provar que está vivo? | Uma renovação falha não desfaz uma escrita já enviada. |
| Fencing token | Esta geração de posse ainda pode alterar o recurso? | Só protege a fronteira que compara o token. |
Um exemplo oficial da Microsoft sobre lock distribuído no Azure Cosmos DB combina aquisição atômica, renovação com ETag, TTL para liberar um lock abandonado e um token crescente que um sistema downstream pode usar para rejeitar um dono antigo. A combinação é útil porque o TTL ajuda a recuperar a tarefa, enquanto o token protege a escrita posterior.
Não trate o heartbeat como autorização permanente. Ele ajuda o worker a descobrir cedo que perdeu a posse e a interromper chamadas que aceitam cancelamento. Ainda assim, o recurso precisa verificar a geração recebida na mutação que não pode ser sobrescrita por um worker antigo.
O recurso precisa aplicar a regra do token
O token não serve se ele aparece apenas no log ou no contexto do worker. O destino da escrita precisa guardar a maior geração aceita e comparar o valor recebido na mesma operação que muda o estado.
Uma atualização SQL ilustrativa pode ter esta forma:
UPDATE job_results
SET result = $1,
accepted_fence = $2,
updated_at = now()
WHERE job_id = $3
AND accepted_fence < $2;
Se a atualização afetar zero linhas, o executor deve tratar o caso como stale_fencing_token, não como um erro transitório que merece repetir a mesma escrita. A coluna precisa começar com um valor definido, e todo caminho que altera aquele resultado precisa usar a mesma condição. Um script administrativo que ignora a comparação pode reabrir a falha.
Quando o token é criado em uma sequência PostgreSQL, nextval entrega valores distintos de forma atômica entre sessões concorrentes, segundo a documentação de funções de sequência. A sequência não é gapless, e isso não é um problema para fencing: o que importa é não voltar para uma geração menor.
Para um serviço externo que não entende o token, coloque a verificação em um proxy ou em um armazenamento que registre a maior geração antes de chamar o serviço. Se a chamada externa já aconteceu, fencing não desfaz o efeito. Você ainda precisa de idempotência, consulta de estado ou reconciliação.
Fixture Node.js: o worker antigo é rejeitado
A fixture abaixo representa duas aquisições da mesma tarefa. A segunda aquisição simboliza a recuperação do lease. O store aceita o token mais novo e recusa o token antigo, mesmo que o worker A ainda esteja executando código.
import assert from "node:assert/strict";
class FencingAuthority {
#next = 0;
acquire(resource) {
this.#next += 1;
return { resource, fence: this.#next };
}
}
class FencedStore {
#highestFence = new Map();
#values = new Map();
write(resource, value, fence) {
const highest = this.#highestFence.get(resource) ?? 0;
if (fence < highest) {
throw new Error("stale_fencing_token");
}
this.#highestFence.set(resource, fence);
this.#values.set(resource, value);
}
read(resource) {
return this.#values.get(resource);
}
}
const authority = new FencingAuthority();
const store = new FencedStore();
const workerA = authority.acquire("job-7");
const workerB = authority.acquire("job-7");
store.write(workerB.resource, "result-from-B", workerB.fence);
assert.throws(
() => store.write(workerA.resource, "late-result-from-A", workerA.fence),
/stale_fencing_token/,
);
assert.equal(store.read("job-7"), "result-from-B");
console.log("stale worker write rejected");
Salve como fencing-token-fixture.mjs e execute com Node.js:
node fencing-token-fixture.mjs
O teste verifica a invariável local: depois que o recurso aceitou o token 2, uma escrita com token 1 não substitui o valor. Ele não verifica a atomicidade de um banco, a emissão do token por um coordenador real, a renovação do lease ou qualquer efeito fora desse store. Essas fronteiras precisam de testes de integração separados.
Onde uma fila PostgreSQL entra nessa arquitetura?
Se as tarefas já vivem no PostgreSQL, uma transação pode selecionar uma tarefa disponível, registrar a posse e devolver a geração ao worker. A documentação de SELECT do PostgreSQL descreve SKIP LOCKED como uma opção que pode reduzir contenção em tabelas usadas como filas, mas alerta que ela produz uma visão inconsistente e não serve para consultas gerais.
Isso resolve a disputa para retirar uma tarefa da fila. Não resolve sozinho um worker que calcula por muito tempo e volta depois de perder a posse. O resultado final ainda precisa carregar a geração e usar uma atualização condicional. Se dois processos podem disputar o mesmo run, o artigo sobre execução durável com filas e workflows ajuda a separar fila, checkpoint e workflow.
Também ordene a seleção de forma explícita quando a política exigir prioridade ou fairness. SKIP LOCKED não transforma a tabela em um scheduler justo, e um lock de linha não é uma permissão para a aplicação ignorar a versão da tarefa.
Como reagir a stale_fencing_token?
Uma rejeição do recurso é informação sobre posse, não um convite para repetir a mesma operação. O executor pode seguir este caminho:
- Pare a etapa atual e não repita a escrita com o token antigo.
- Registre
runId,jobId, token apresentado, token aceito e a fronteira que rejeitou a mutação. - Se havia uma chamada externa antes da rejeição, consulte o efeito por uma chave estável ou marque o resultado como desconhecido.
- Deixe o worker novo reler o estado e decidir se continua, reconcilia ou encerra a tarefa.
- Emita um sinal operacional que diferencie perda de posse de erro da dependência.
O teste de um worker de fila depois de perder o ack cobre outra janela: o efeito foi aplicado, mas a confirmação de entrega falhou. Aqui, a janela é a posse do trabalho. Os dois casos precisam observar o efeito real, não apenas a quantidade de chamadas.
Erros que deixam o fencing decorativo
Verificar e gravar em operações separadas
Um if (token === currentToken) seguido de outro comando ainda permite que a posse mude entre as duas operações. A comparação e a mutação precisam compartilhar a transação ou a operação condicional que o recurso realmente garante.
Guardar o token apenas na memória
Se o processo que protege o recurso reinicia e esquece a maior geração aceita, um worker antigo pode parecer válido outra vez. Persista o high-water mark ou use um mecanismo cuja ordem sobreviva ao restart.
Reiniciar a sequência de tokens
Token é uma geração, não um contador de tentativas que pode voltar a zero depois de uma limpeza. Se a ordem for reiniciada, trate isso como uma mudança de protocolo e preserve uma barreira que impeça tokens antigos de voltar a ser aceitos.
Confundir cancelamento com fencing
Um AbortSignal pode interromper uma operação que coopera com ele. Não cancela uma requisição que já chegou ao servidor e não impede uma resposta atrasada de tentar chegar ao destino. O fencing continua necessário na fronteira que aceita o estado.
Prometer exactly-once para vários sistemas
Fencing pode impedir uma geração antiga de atualizar um recurso protegido. Ele não torna transações entre banco, broker e API externa atômicas. Para essas fronteiras, combine idempotência, outbox, compensação ou reconciliação conforme o efeito que precisa proteger.
Checklist antes de liberar o worker
- [ ] Cada aquisição recebe uma geração nova que não volta para trás.
- [ ] O token acompanha a mutação até o recurso que pode aceitar ou rejeitar a escrita.
- [ ] A comparação do token e a mudança de estado são atômicas na fronteira protegida.
- [ ] O caminho de token antigo termina sem retry automático com a mesma geração.
- [ ] Heartbeat e cancelamento ajudam na liveness, mas não são a única defesa de safety.
- [ ] O sistema registra perda de posse e permite investigar a geração vencedora.
- [ ] Efeitos externos têm chave idempotente, consulta de estado ou um caminho explícito de reconciliação.
- [ ] A fixture força uma pausa ou uma troca de posse e confirma a rejeição do write antigo.
Método e limites
Samuel Fajreldines é o autor responsável por este texto. A pesquisa combinou a análise de locks distribuídos de Martin Kleppmann, o exemplo atual de lock distribuído da Microsoft e a documentação do PostgreSQL sobre locks de linha, SKIP LOCKED e sequências. Discussões públicas foram usadas apenas para reconhecer termos e falhas que praticantes descrevem. A fixture foi escrita para este artigo e executada localmente com Node.js v25.5.0. Ela usa estado em memória, portanto não mede recuperação distribuída, não testa um broker e não prova exatamente uma execução em produção.
Usei assistência de IA para organizar as fontes, revisar a redação e produzir as localizações. Ela não executou um worker de produção nem forneceu experiência operacional. Quando preciso manter continuidade entre sessões longas de Codex e Claude Code, uso o RemoteCode, uma ferramenta minha; isso não substitui journal, lease, fencing ou reconciliação.
Conclusão
Lease e heartbeat ajudam a recuperar uma tarefa e a tirar um worker parado do caminho. Eles não garantem que o processo antigo parou. A proteção decisiva fica no recurso: aceite a mutação junto com um token de posse e rejeite qualquer geração menor do que a última aceita.
Esse desenho não promete exactly-once para todo o sistema. Ele fecha uma pergunta mais específica e útil: um worker que perdeu a posse ainda pode sobrescrever o estado protegido? Se a resposta for "sim", o lease está funcionando como convenção. Se a resposta for "não", a fronteira de escrita está aplicando o fencing.
Fontes consultadas
- Martin Kleppmann, "How to do distributed locking", consultado em 21/11/2026.
- Microsoft Learn, "Azure Cosmos DB design pattern: Global Distributed Lock", consultado em 21/11/2026.
- PostgreSQL, "SELECT", consultado em 21/11/2026.
- PostgreSQL, "Sequence Manipulation Functions", consultado em 21/11/2026.