Transporte
Os eventos trafegam como mensagens CloudEvents 1.0 em modo de conteúdo binário. O modo binário coloca os atributos de contexto do CloudEvents nos cabeçalhos do transporte, cada um com o prefixoce-, e o corpo do evento no valor da mensagem como JSON. Um consumidor lê o roteamento e a identidade a partir dos cabeçalhos sem desserializar o payload.
A maioria dos produtores — Midaz, components/tracer do Midaz, Lender, Matcher, Consignado — publica sobre Kafka. Dois publicam o mesmo envelope sobre RabbitMQ: o Reporter roteia cada evento para um exchange configurado usando a chave do evento como routing key, e o Fetcher faz o mesmo para seus eventos terminais de job. As convenções de tipo e versionamento do CloudEvents são compartilhadas nos dois transportes; a página de cada produtor continua sendo a autoridade para ids, esquemas, destinos e política de entrega exatos. O repositório independente LerianStudio/tracer-pre-dev atualmente não possui streaming externo e não é este produtor.
O envelope
Todo registro carrega estes cabeçalhos CloudEvents.Tipo do evento
O contrato v3 usa o formato qualificado pela fontestudio.lerian.<source>.<resource>.<event>. O mesmo valor <source> aparece em ce-source; ce-resourcetype e ce-eventtype carregam a chave de dispatch em cabeçalhos separados. Produtores ainda fixados na lib-streaming v2 usam o formato sem fonte studio.lerian.<resource>.<event>; consulte a página ou o manifesto específico do produtor antes de rotear.
Nomes de tópicos
Produtores Kafka no contrato v3 de stream por aplicação — incluindo Midaz,components/tracer do Midaz, Matcher, Lender e Consignado — enviam seus fatos de negócio JSON públicos para:
lerian.streaming.<ce-source>.commands; os dead letters do produtor usam lerian.streaming.<ce-source>.dlq. Não existe um tópico .commands.dlq separado. O tipo de recurso, o tipo de evento e a versão do esquema permanecem nos cabeçalhos CloudEvents, portanto uma mudança de major não renomeia o tópico.
Exemplos:
- Fatos JSON públicos do ledger, CRM e Fees do Midaz:
lerian.streaming.ledger - Fatos do
components/tracerdo Midaz:lerian.streaming.tracer - Fatos do Matcher:
lerian.streaming.matcher - Fatos e comandos do Lender:
lerian.streaming.lenderelerian.streaming.lender.commands - Fatos do gateway de Consignado:
lerian.streaming.consignado-gw
RABBITMQ_JOB_EVENTS_EXCHANGE com job.completed ou job.failed. Seus valores de ce-type também são qualificados pela fonte.
Fonte
ce-source identifica o serviço produtor e faz parte do contrato wire. Os exemplos atuais de produtos v3 usam ledger, tracer (components/tracer do Midaz), matcher, lender, consignado-gw, fetcher ou reporter; todos, exceto o Matcher, fixam ou validam esse valor exato do roster, enquanto o Matcher deriva sua identidade wire do valor configurado. Produtores Kafka v3 incorporam a fonte ao tópico da aplicação, e todos os produtores v3 a incorporam ao ce-type. Portanto, alterá-la muda o roteamento e a identidade para os consumidores; trate isso como uma mudança incompatível.
Subject e tenant
ce-subject carrega o id do agregado a que o evento se refere — a conta, a transação ou a credencial que o fato descreve. ce-tenantid carrega o tenant proprietário. O comportamento em single-tenant depende do produtor: o Midaz sempre envia o literal default no escopo single-tenant ou sem tenant, enquanto outros produtores documentam seu próprio comportamento. Siga o contrato específico do produtor.
Versionamento de esquema
Cada evento declara sua própria versão de esquema do payload emce-schemaversion, independente dos demais eventos da mesma fonte. O padrão é 1.0.0. Um incremento menor é aditivo e retrocompatível; um incremento maior é uma mudança incompatível. Nos streams de aplicação Kafka v3, a versão do esquema nunca muda o nome do tópico. Os exchanges e as routing keys explícitas do RabbitMQ também não mudam com um incremento de esquema. Um consumidor que lê os payloads como um leitor tolerante, ignorando campos desconhecidos, não é afetado por uma mudança aditiva.
Garantias de entrega
A entrega é at-least-once. Um consumidor confirma sua posição apenas depois de terminar de processar um registro, então uma queda no meio do processamento reprocessa o registro em vez de descartá-lo — o que significa que o mesmo evento pode chegar mais de uma vez. Deduplique pelo par(ce-source, ce-id) (o CloudEvents define a identidade do evento por essa combinação, e ce-id sozinho pode colidir entre fontes) e mantenha os handlers idempotentes.
No lado do produtor, a política de entrega pertence a cada definição de evento, não à plataforma. Uma política respaldada por outbox garante relay durável e novas tentativas, mas não prova por si só que a gravação do estado de negócio e a inserção no outbox compartilhem uma transação de banco de dados. O Lender e o Consignado fazem essa gravação atômica para os eventos dos seus catálogos. O Fetcher persiste o estado terminal com um marcador pendente e depois insere o evento no outbox durável do Mongo em uma operação separada; um processo de reparo reemite o ce-id estável até que o marcador seja removido. O Reporter também emite após o commit do estado, e suas políticas críticas usam então um outbox durável do Mongo em uma operação separada. Uma queda ou uma inserção malsucedida no outbox nessa janela pós-commit perde o evento do Reporter: nenhuma reconciliação o recupera, e apenas um log de erro e uma métrica registram a perda. O Matcher e o Reporter também publicam sinais operacionais diretamente com fallback para o outbox. Consulte a página de eventos do produto para conhecer tanto a política quanto o limite transacional e, quando o produto expuser um manifesto de streaming, leia-o na inicialização.
Catálogos por produto
Os trilhos do Brasil (STA, CCS, SLC, SPB, SPI, SILOC, SISBAJUD, transferência bancária e os serviços de Pix) também publicam eventos neste mesmo contrato; consulte a área de documentação de cada trilho para o seu catálogo.