Identidade e parâmetros
A chave composta do laboratório é cliente mais operação; a quantidade fica guardada como parte da intenção. Repetir a mesma chave com cinco unidades recupera o efeito anterior, mas enviar sete produz 409 e conserva o estado existente. Mudar a ordem textual dos campos JSON não altera os valores interpretados e continua a recuperar o mesmo effectId.
Estes comportamentos pertencem ao contrato pedagógico apresentado, não são garantias automáticas de qualquer API HTTP. Num serviço real, decide quais parâmetros definem intenção equivalente e quais alterações exigem operação própria. Liga o âmbito do cliente a identidade autenticada e autoriza também as consultas. Receber client no JSON, como neste guião, não fornece essa segurança.
Confirmar o efeito e a memória da intenção
O endpoint abre uma ligação SQLite por pedido e executa uma transação curta. O efeito e a resposta recuperável são gravados na mesma unidade; só depois ocorre a suspensão da resposta HTTP. A escolha impede, dentro desta base, tratar as duas gravações como passos independentes.
Não estende a transação ao consumidor nem a serviços externos. Se uma evolução introduzir uma ordem externa antes de gravar ledger, aparece outra fronteira de falha: o fornecedor pode aplicar a ordem sem o registo local existir. Será necessário rever identidade, consulta, estado durável e recuperação desse fluxo.
Um BEGIN IMMEDIATE local não transforma chamadas HTTP em participantes de uma transação distribuída.
Reinício e retenção
O guião fecha os dois listeners, aguarda o seu fim e abre outros no mesmo processo, mantendo a base SQLite. A repetição encontra o registo e devolve a mesma resposta. Essa observação demonstra continuidade através de um reinício limpo dos listeners, sem provar recuperação de crash, reinício do processo ou perda de energia.
Depois, o guião remove deliberadamente uma linha de ledger e mantém o efeito correspondente. A repetição tardia já não é reconhecida e cria outro efeito. Não existe TTL automático implementado; a eliminação controlada permite discutir o contrato temporal.
Retenção, validade dos pedidos e tratamento de chegadas tardias têm de ser coerentes com o período em que os consumidores ainda podem repetir.
Recuperação não elimina carga
A repetição protegida continua a abrir ligações, executar handlers e consultar a base. Evitar duplicação de efeito não torna tentativas ilimitadas gratuitas. Define um responsável pela política de repetição e verifica os limites de cada camada para não multiplicar chamadas inadvertidamente.
O timeout de leitura de 0.25 segundos usado pelo gateway é um controlo local do exercício, não uma recomendação de configuração nem uma deadline global garantida. Não foram executados benchmark, análise estatística de latência ou backoff com jitter.
Se a operação termina depois de várias tentativas, conserva indicadores de falha e demora que o cliente sentiu. Reporta separadamente tentativas, conclusão de operações, latência e efeitos duplicados para orientar a melhoria.
Mudanças ao contrato
Uma equipa fictícia quer aceitar retries durante vinte e quatro horas e limpar registos depois de uma hora. O problema não é escolher um número maior por hábito; é resolver o intervalo em que o cliente ainda considera válida uma intenção que o servidor já esqueceu.
Pode ser necessário reter mais tempo, limitar validade ou rejeitar chegadas tardias de forma explícita, com mudança compatível e impacto aceite. Se já houve duplicação, a alteração da política evita novas ocorrências mas não reconcilia os efeitos anteriores.
Aplica a mesma disciplina a mudanças de parâmetros, âmbito de cliente e migração para mensagens. Um broker tem as suas próprias confirmações e regras de redelivery; o laboratório HTTP não valida esse produto.
Oficina de handover e resumo
Distribui os papéis de fornecedor, desenvolvimento e RUN. Apresenta uma resposta perdida, um conflito de quantidade e um pedido tardio depois da remoção do registo. O grupo deve escrever como consulta estado, quando repete, quando para e quem autoriza uma operação diferente.
Acrescenta um painel com muitos 504 e um único efeito por operação: a equipa deve conservar o problema de experiência e carga apesar da recuperação funcional. A oficina humana continua por executar. O laboratório automatizado passou treze grupos duas vezes, fechou quatro listeners ao longo do ciclo e removeu a pasta temporária.
Resume o contrato através de âmbito, intenção, confirmação local, retenção, observabilidade e recuperação, preservando as limitações de segurança e distribuição.
Ficheiros do exercício
Extrai o ZIP para uma pasta nova e abre README.pt.md. Inclui o programa e os ficheiros deste exercício, preservando os caminhos content/labs e os registos históricos. Python 3.13, sqlite3 e permissão para servidores HTTP temporários em 127.0.0.1. As bases, sockets e threads são próprios; não há ligações externas.
Descarregar laboratório micro-timeouts
SHA-256 (ZIP)
e80e9efaa543d644fc0c4b5b7aa243c1fe816b274474565037adebcccc04c75c
python3 content/labs/micro-timeouts/run.py --output /tmp/dr-micro-timeouts-second.json
# same-key-different-intent-rejected: 409, original units remain 5
# equivalent-json-order-reuses-result: same effectId
# clean-listener-restart-retains-record: same response, same SQLite database
# removed-record-allows-late-duplicate: effects=2, units=10
# Record deletion is controlled; no automatic TTL is implemented.
# Listener restart is not OS-process restart, crash or power-loss testing.A mesma chave com outra quantidade é rejeitada; uma repetição depois de remover o registo cria outro efeito apesar de a intenção ser antiga.
Armadilhas comuns
Retenção escolhida só por armazenamento, rótulo de cliente como autenticação, transação local como garantia distribuída e idempotência como ausência de carga.
Tópicos relacionados: Transações locais · Resiliência e carga · Diagnóstico operacional
O contrato de idempotência precisa de uma identidade com âmbito, intenção estável e memória suficiente para o período admitido de repetição.
Referências
- Making retries safe with idempotent APIs · Amazon Builders Library article inspected 2026-10-04; original teaching API is not an AWS implementation
- RFC9110: 504 Gateway Timeout · RFC9110, June 2022, section 15.6.5
- http.client: HTTP protocol client · Python 3.13 rolling docs label 3.13.16; executed CPython3.13.1
- threading: Event and thread lifecycle · Python 3.13 rolling docs label 3.13.16; executed CPython3.13.1
- http.server: HTTP servers · Python 3.13 rolling docs label 3.13.16; executed CPython3.13.1
- Transaction · SQLite transaction documentation; executedSQLite3.51.2