Transporte
Os eventos trafegam como mensagens CloudEvents 1.0 em modo binário de conteúdo. O modo binário coloca os atributos de contexto do CloudEvents em headers de transporte, cada um prefixado comce-, e o corpo do evento no valor da mensagem como JSON. Um consumidor lê o roteamento e a identidade a partir dos headers sem desserializar o payload.
A maioria dos produtores publica via Kafka: Midaz, Tracer (no Midaz), Lender, Matcher e Consignado. O Reporter publica o mesmo envelope via RabbitMQ. Ele roteia cada evento para um exchange configurado, usando a chave do evento como chave de roteamento. Os dois transportes compartilham as convenções de tipo e versionamento do CloudEvents. A página de cada produtor continua sendo a referência definitiva para ids, schemas, destinos e política de entrega exatos. O produtor Kafka do Tracer é o componente dentro do Midaz.
O envelope
Todo registro carrega estes headers do CloudEvents.Tipo de evento
O contrato v3 usa a forma qualificada por sourcestudio.lerian.<source>.<resource>.<event>. O mesmo valor de <source> aparece em ce-source. ce-resourcetype e ce-eventtype carregam a chave de despacho como headers separados. Produtores ainda fixados na lib-streaming v2 usam a forma sem source studio.lerian.<resource>.<event>. Verifique a página específica do produtor ou o manifesto antes de rotear.
Nomenclatura de tópicos
Produtores Kafka no contrato v3 de application stream (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 schema permanecem nos headers do CloudEvents, então mudanças major de schema não renomeiam 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 do Consignado:
lerian.streaming.consignado-gw
ce-type continuam qualificados por source.
Fonte
ce-source identifica o serviço produtor e faz parte do contrato de wire. Os exemplos atuais de produtos v3 usam ledger, tracer (components/tracer do Midaz), matcher, lender, consignado-gw ou reporter. Todos, exceto o Matcher, fixam ou validam esse valor exato do roster. O Matcher deriva sua identidade de wire a partir do valor configurado. Produtores Kafka v3 embutem a fonte no tópico de aplicação, e todos os produtores v3 a embutem em ce-type. Alterá-la, portanto, muda o roteamento e a identidade do consumidor. Trate isso como uma mudança que quebra compatibilidade.
Assunto e tenant
ce-subject carrega o ID do agregado a que o evento se refere (a conta, a transação ou a credencial a que o fato diz respeito). ce-tenantid carrega o tenant proprietário. Quando um evento não tem tenant, o comportamento é específico de cada produtor: o Midaz envia o literal default, enquanto outros produtores documentam seu próprio comportamento. Siga o contrato específico do produtor.
Versionamento de schema
Cada evento declara sua própria versão de schema do payload emce-schemaversion, independente dos demais eventos da mesma fonte. O padrão é 1.0.0. Um incremento minor é aditivo e retrocompatível. Um incremento major introduz uma mudança que quebra compatibilidade.
No application stream Kafka v3, a versão do schema nunca muda o nome do tópico. Um incremento de schema também deixa inalterados os exchanges e as chaves de roteamento explícitos do RabbitMQ. Uma mudança aditiva não afeta um consumidor que lê os payloads como um leitor tolerante e ignora campos desconhecidos.
Garantias de entrega
A entrega é pelo menos uma vez. Um consumidor confirma sua posição apenas depois de terminar de processar um registro. Uma falha durante o processamento reproduz o registro em vez de descartá-lo, então 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 o ce-id sozinho pode colidir entre fontes) e mantenha os handlers idempotentes.
Do lado do produtor, a política de entrega pertence a cada definição de evento, não à plataforma. Uma política apoiada em outbox garante relay e nova tentativa duráveis. Por si só, ela não prova que a escrita de estado de negócio e a inserção no outbox compartilham uma única transação de banco de dados.
O Lender e o Consignado fazem essa escrita atômica para seus eventos de catálogo. O Reporter emite depois do commit de estado, e suas políticas críticas então usam um outbox Mongo durável em uma operação separada. Uma falha ou uma inserção de outbox malsucedida nessa janela pós-commit perde o evento do Reporter. Nenhuma conciliaçã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 de outbox. Verifique a própria página de eventos do produto tanto para sua política quanto para seu limite transacional. Onde o produto expõe um manifesto de streaming, leia o manifesto na inicialização.
Catálogos por produto
Outros trilhos do Brasil também publicam eventos neste contrato. Use a página de eventos de um trilho ou o manifesto em runtime apenas quando o trilho expõe explicitamente seu catálogo.