Três momentos da operação
Separa receção do pedido, confirmação do efeito e receção da resposta pelo consumidor. O laboratório usa dois listeners HTTP simultâneos no mesmo processo Python: um gateway pedagógico e uma dependência. A dependência grava o efeito em SQLite e só depois suspende a resposta num Event.
O gateway espera pela resposta através de http.client e devolve 504 quando esse limite local expira. O guião observa que committed já está ativo e done ainda não. Assim, o resultado não é uma narrativa inventada sobre o que poderia acontecer: há tráfego loopback real e um efeito local consultável.
A fronteira permanece limitada a este processo, estas threads e esta base temporária.
O que o erro não decide
A semântica de 504 descreve um gateway que não recebeu uma resposta atempada da dependência necessária. Não estabelece que a operação tenha sido cancelada ou revertida. No primeiro caminho do laboratório, o cliente recebe outcome-unknown enquanto já existe um efeito de cinco unidades.
Fechar a ligação de saída do gateway não apaga essa linha. Em sistemas reais, o timeout pode ocorrer noutro ponto e produzir outro estado; por isso, não generalizes a observação para afirmar que todo o 504 contém um efeito aplicado. Mantém a incerteza explícita até consultar o contrato e a evidência relevante.
Um código de transporte é uma observação útil, mas insuficiente para decidir sozinho o estado de negócio.
A repetição que duplica
O endpoint /unsafe insere um efeito por chamada, mesmo quando cliente e operação se repetem. Depois do primeiro timeout, o guião repete os mesmos parâmetros enquanto a resposta original ainda está suspensa. A segunda chamada devolve 200 e a base contém dois efeitos, totalizando dez unidades.
O sucesso final não significa que só a última chamada tenha alterado estado. Este exemplo permite discutir um erro comum de runbook: repetir sempre que o painel mostra falha. Antes de transformar essa instrução em automação, define quais resultados são repetíveis, com que identidade, durante quanto tempo e até que limite.
O laboratório não implementa um ciclo automático de retries, backoff ou jitter.
Recuperar a mesma intenção
No caminho /dedupe, a transação insere o efeito e guarda a sua resposta num registo identificado por cliente e operação. A primeira resposta também pode expirar no gateway. Uma consulta local recupera state=applied e o effectId; uma repetição equivalente devolve esse mesmo identificador sem acrescentar efeito.
Isso acontece antes de libertar a resposta original suspensa. O guião demonstra recuperação de uma intenção local, não entrega única universal. Uma nova chave com os mesmos parâmetros representa outra intenção neste contrato e cria outro efeito.
Não derives identidade apenas da quantidade pedida: duas operações legítimas podem ser iguais nos parâmetros. Os rótulos de cliente do laboratório são fictícios e não autenticados.
Decidir durante uma janela de batch
Num caso fictício de APS, a reserva antecede o passo seguinte de um batch. O operador vê 504 e propõe outra chave para desbloquear a janela. O gestor pede primeiro a identidade original e o estado da dependência.
Se a consulta correlacionada confirmar o efeito, recupera o resultado segundo o contrato; se continuar desconhecido, mantém a operação em reconciliação e escala. Uma consulta sem resultado noutro produto pode ter atrasos ou garantias diferentes das desta base local.
Não atribuas uma certeza que o contrato não oferece. Conserva tentativas anteriores e evita apagar efeitos para fazer a base coincidir com o painel. Os papéis e unidades são exemplos fictícios, sem representar procedimentos bancários reais.
Oficina e síntese
Prepara três cartões para desenvolvimento, QA e RUN: timeout antes de haver informação suficiente, timeout com efeito confirmado e repetição que já duplicou o efeito. Pede que distingam o que sabem, o que falta e quem decide o próximo passo.
Acrescenta a restrição de que não podem mudar a identidade só para obter um resultado verde. Cada grupo deve produzir uma nota com estado, evidência, impacto e recuperação proposta. Esta oficina humana foi preparada, mas não executada.
No ensaio automatizado, os sockets são próprios e os efeitos são linhas numa base temporária. Resume a distinção entre tentativa, operação, efeito e resposta, ligando-a às aulas anteriores de outbox, inbox e reconciliaçã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-first.json
# Choose a new output path. Requires owned loopback listeners.
# Actual path: client -> teaching gateway -> dependency -> local SQLite.
# timeout-after-unsafe-commit: 504; effects=1, units=5
# unsafe-retry-duplicates-effect: 200; effects=2, units=10
# Response is held AFTER commit by an Event, not by delaying the transaction.
# A timeout ends the gateway wait; it does not undo the committed effect.Um gateway fictício devolve 504 depois de a dependência gravar cinco unidades. Repetir sem deduplicação cria outro efeito e aumenta o total para dez.
Armadilhas comuns
504 como rollback, nova chave por tentativa, fecho da ligação como cancelamento e timeout local como deadline global garantida.
Tópicos relacionados: Transações locais · Resiliência e carga · Diagnóstico operacional
A falta de resposta pode coexistir com um efeito confirmado. A recuperação depende de identidade, estado e contrato, além do código HTTP observado.
Referências
- RFC9110: 504 Gateway Timeout · RFC9110, June 2022, section 15.6.5
- Making retries safe with idempotent APIs · Amazon Builders Library article inspected 2026-10-04; original teaching API is not an AWS implementation
- 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