Explicador · Engenharia
O que é uma chave de idempotência: e por que a vossa app precisa de uma
Toda a app que funciona offline acaba por responder à mesma pergunta: o que acontece quando o utilizador toca em «enviar» duas vezes, ou a rede morre a meio de um pedido e o cliente repete? A resposta é um pequeno mecanismo chamado chave de idempotência, eis como funciona e como aparece no nosso próprio código.
O problema numa frase
As redes não são fiáveis, por isso os clientes têm de repetir. Repetições significam que a mesma ação lógica chega mais de uma vez. Sem proteção, «mais de uma vez» torna-se dois registos de horas, duas faturas, duas marcações.
Reparem no que o problema não é: não é «o utilizador fez duplo clique». Os utilizadores fazem duplo clique, mas o caso comum é muito menos visível, uma app móvel num estaleiro perde cobertura, enfileira o registo de entrada, o servidor aplica-o, a resposta morre a caminho e a app (corretamente) envia-a outra vez. O duplicado é o sistema a funcionar como previsto.
O mecanismo
Uma chave de idempotência é um identificador único que o cliente gera por ação lógica, não por pedido HTTP. O cliente anexa a mesma chave ao pedido original e a cada repetição dessa ação. O servidor regista as chaves que já viu. Quando uma chave chega duas vezes, devolve o primeiro resultado em vez de executar a mutação duas vezes.
Três propriedades fazem-na funcionar:
- A chave pertence ao cliente. Se fosse o servidor a emiti-la, uma repetição antes de a receber não poderia ser identificada. A chave é cunhada no dispositivo, nas nossas apps móveis, um UUID criado no momento em que o utilizador regista, não quando a chamada de rede é disparada.
- O registo é um claim, não um resultado. O servidor escreve primeiro o claim («esta chave agora é minha, resultado pendente») e só depois altera. Uma repetição concorrente encontra o claim e espera pelo desfecho original ou reprodu-lo, nunca consegue enfiar uma segunda mutação por baixo.
- O claim liga o payload. Guardamos um hash da ação e das suas entradas normalizadas junto da chave. A mesma chave com um payload diferente → um conflito 409, não uma sobreposição silenciosa. Uma repetição só deve significar «a mesma coisa outra vez».
Onde aparece nas nossas apps
A fila móvel de registos do ArbeitszeitCheck carrega um clientRequestIdcodeclient_event_id em cada replay. O TourCheck amarra o mesmo contrato a code nas confirmações de pontos de controlo, onde um replay compara o claim completo, nota, foto, carimbo temporal, com a linha guardada. A expiração vale tanto quanto a deduplicação: as nossas linhas de claim vivem sete dias, tempo suficiente para cobrir um fim de semana prolongado sem cobertura, curto o bastante para a tabela continuar uma fila e não um log.
A versão curta para a vossa app
Se a vossa API altera estado e o vosso cliente pode repetir, e qualquer cliente pode repetir, precisam exatamente de três coisas: uma chave gerada no cliente por ação, uma linha de claim à primeira escrita e um hash do payload para que «a mesma chave» também signifique «a mesma intenção». É o padrão completo. Tudo o resto, janelas de replay, tarefas de limpeza, códigos de estado de conflito, é canalização à volta desses três compromissos.