Inbox Pattern

O lado receptor grava toda mensagem recebida numa tabela inbox antes de processar, com a chave do remetente como única. A entrega duplicada é absorvida na porta, e um processador separado aplica cada mensagem uma vez só, na mesma transação que a marca como concluída. É o par do Outbox: a entrega é at-least-once, o efeito é exactly-once.

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

Infraestrutura realTypeScriptBunElysiaPostgreSQLDocker

Cenário Relações Comparar

Baixar cartão

Cenário

Banco digital recebe do PSP as notificações de PIX creditados nas contas. O PSP reenvia quando não recebe confirmação a tempo, então o mesmo PIX pode chegar várias vezes. O crédito na conta precisa acontecer uma vez só, e um PIX para conta inexistente não pode travar os outros.

Planta

Sequência

9/9

9 passos — reproduza para seguir o fluxo

chamada
resposta ou assíncrono
falha
passo
toque num participante para focar
Outras plantas de sequência

Como funciona

5 passos

Deduplica mensagens na entrada.

Esconde cada passo: lembre antes de tocar para revelar.

Vocabulário compartilhado

FOR UPDATE SKIP LOCKED+2

01
A API grava a notificação em inbox_messages com end_to_end_id único e responde 202 na hora — reentrega vira duplicate: true, sem segunda mensagem
02
O processador pega uma mensagem pending por vez com FOR UPDATE SKIP LOCKED: vários processadores dividem a fila sem pegar a mesma
03
Crédito na conta, registro em pix_credits e status = 'done' commitam juntos; queda no meio desfaz os três
04
Falha no crédito volta ao savepoint, registra last_error e agenda nova tentativa com backoff exponencial
05
Ao atingir INBOX_ATTEMPTS_MAX a mensagem vira failed e sai do caminho das outras

Trade-offs

O que se ganha, o que se paga

3 vantagenscada ganho tem um preço3 custos

Vantagens

Reentrega absorvida na porta
Crédito e conclusão atômicos
Vários processadores sem coordenação

Custos

Crédito acontece depois, não na resposta
Polling adiciona latência de segundos
Tabela cresce: exige limpeza de done

apps/data-patterns/inbox-pattern

6 arquivos

sql/

01_schema.sqlschemaaccounts, inbox_messages com chave única do remetente, pix_credits

src/

api_inbox.tsRecebe a notificação e grava na inbox
processor_inbox.tsProcessa com SKIP LOCKED, savepoint, backoff e failed
demo.tsdemoEntregas, reentrega, conta inexistente e processamento
processor_inbox.test.tstesteDedup, reprocessamento, falha isolada e concorrência contra PostgreSQL real

src/config_inbox.ts / src/