Dead-Letter Queue (DLQ)

Fila que recebe a mensagem que não pode ser processada — corrompida, recusada ou com as retentativas esgotadas — em vez de deixá-la em loop na fila principal ou descartá-la sem rastro. Lá ela é inspecionada, gera alerta e, corrigida a causa, é reprocessada.

passos: 6
arquivos: 9
teste: 1
tecnologias: 5

Infraestrutura realTypeScriptBunElysiaRabbitMQDocker

Cenário Relações Comparar

Baixar cartão

Cenário

Um banco digital liquida pagamentos PIX e TED num PSP. Mensagem corrompida, pagamento acima do limite do PSP e banco do pagador fora do ar não podem travar a fila nem sumir: cada um vai à DLQ com o motivo, a origem e o trace id, a equipe é alertada, e quando o banco volta os pagamentos estacionados são reenviados com o mesmo id.

Como funciona

6 passos

Mensagem venenosa sai do fluxo principal.

Esconde cada passo: lembre antes de tocar para revelar.

Vocabulário compartilhado

ack+12

nack+6

x-death+3

/metrics+3

x-dead-letter-exchange+1

Dead-Letter Queue

01
payment-settle é declarada com x-dead-letter-exchange e TTL; a DLQ é ligada na DLX antes de qualquer rejeição
02
Poison pill (JSON inválido ou fora do schema) e recusa 4xx do PSP → nack com requeue=false na hora, sem retry
03
Falha transitória (5xx, timeout, conexão recusada) → cópia confirmada na fila de atraso, que devolve à principal ao expirar; x-death[].count conta as tentativas
04
Estourado o limite (PAYMENT_RETRY_MAX) → nack sem requeue → DLX → DLQ
05
O inspetor lê x-death, x-origin-service e x-trace-id, registra o log de erro, incrementa o alerta, estaciona a mensagem e faz ack; /metrics expõe o total e a profundidade
06
Corrigida a causa, replay_dlq.ts republica os estacionados na fila principal sem x-death, com o mesmo messageId, e remove cada um só depois do confirm

apps/messaging-streaming/dead-letter-queue

9 arquivos

src/

topology_payment.tsExchange, fila principal com DLX e TTL, fila de atraso, DLQ, estacionamento, contagem por x-death e publicação confirmada
config_payment.tsVariáveis de ambiente validadas no boot
api_psp.tsPSP em Elysia: liquida, recusa acima do limite (422) ou responde 503 para banco fora do ar
worker_payment.tsClassifica a falha: poison e 4xx para a DLQ, transitória para a fila de atraso até o limite
worker_dlq.tsInspetor da DLQ: diagnóstico, alerta, estacionamento, ack e métricas
replay_dlq.tsReprocessamento controlado, com --dry-run
worker_payment.test.tstesteIntegração com RabbitMQ real: poison sem retry, limite exato, recuperação na última tentativa, TTL, estacionamento e replay
demo.tsdemoSobe PSP, worker e inspetor e percorre os quatro destinos de um pagamento