Claim Check

Em vez de colocar um payload grande dentro da mensagem, armazena-o em um storage externo e transmite pelo broker só uma referência (o “comprovante” / claim check) — bucket, chave e tamanho — necessária para buscá-lo de volta depois.

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

Infraestrutura realTypeScriptBunRabbitMQMinIODocker

Cenário Relações Comparar

Baixar cartão

Cenário

Um lote de liquidação bancária (arquivo de remessa estilo CNAB, com milhares de registros de pagamento) precisa ser processado de forma assíncrona. Colocar o arquivo inteiro dentro da mensagem do RabbitMQ estouraria o limite prático de tamanho de mensagem e degradaria o throughput do broker. O producer sobe o arquivo completo para o storage (MinIO, compatível com S3) e publica no broker apenas um "claim check" — um JSON pequeno com bucket, key, sizeBytes e recordCount. O consumer recebe essa referência minúscula e só então baixa o arquivo real do storage para processar.

Planta

Sequência

4/4

4 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

6 passos

Payload no storage, ticket na fila.

Esconde cada passo: lembre antes de tocar para revelar.

Vocabulário compartilhado

key+1

Change Data Capture (CDC)

01
O producer grava o arquivo de remessa no storage (MinIO, compatível com S3, pelo S3Client nativo do Bun) e só depois publica o claim check — nunca uma referência para arquivo que ainda não existe
02
O claim check leva bucket, key, sizeBytes (bytes do payload codificado), checksumSha256, contentType e recordCount: poucas centenas de bytes, qualquer que seja o arquivo
03
O worker decide primeiro pelos metadados — tipo não suportado ou tamanho acima do limite vai para a DLQ sem tocar no storage
04
Baixa o arquivo e confere tamanho e checksum; arquivo ausente ou adulterado é falha permanente, vai para a DLQ
05
Storage inacessível é falha transitória, separada da fila: o claim check espera na fila de atraso e volta, até o limite
06
O bucket tem regra de lifecycle (7 dias em batches/): a mensagem sai da fila ao ser consumida, o arquivo expira sozinho — inclusive o órfão de um publish que falhou

apps/data-patterns/claim-check

9 arquivos

src/

claim_settlement.tsClaim check, arquivo de remessa e checksum
storage_settlement.tsStorage S3 nativo do Bun; ausente e adulterado separados de indisponível
producer_settlement.tsUpload antes do publish
worker_settlement.tsDecisão pelos metadados, download verificado, liquidação, retry e DLQ
topology_settlement.tsFila do claim check, fila de atraso e DLQ
config_settlement.tsVariáveis de ambiente validadas no boot
worker_settlement.test.tstesteIntegração com MinIO e RabbitMQ reais: tamanho no broker, liquidação, recusa por metadado, arquivo ausente ou adulterado, storage fora do ar e lifecycle
demo.tsdemoDois lotes grandes e um claim check forjado

docker-compose.ymlinfraMinIO com bucket e lifecycle (9000) e RabbitMQ 3 (5672)

Executar · com Docker

$ docker compose up -d --wait# sobe RabbitMQ · MinIO
$ cp .env.example .env# variáveis de ambiente
$ bun install# dependências
$ bun run demo# roda o cenário
$ bun run test# integração contra o serviço real
$

Requisitos: BunDocker
Sobe junto: RabbitMQMinIO

Relações

Onde ele se encaixa

Mapa

Claim Check

Combina com3

Por que se relacionam

Combina com

Teste rápido

Qual destes combina com Claim Check?

Próximo projeto · Dados & PersistênciaMessaging Bridge

Contatos

Claim Check