Transporte
Los eventos viajan como mensajes CloudEvents 1.0 en modo de contenido binario. El modo binario coloca los atributos de contexto de CloudEvents en las cabeceras del transporte, cada una con el prefijoce-, y el cuerpo del evento en el valor del mensaje como JSON. Un consumidor lee el enrutamiento y la identidad desde las cabeceras sin deserializar el payload.
La mayoría de los productores — Midaz, components/tracer de Midaz, Lender, Matcher, Consignado — publica sobre Kafka. Dos publican el mismo sobre por RabbitMQ: Reporter enruta cada evento a un exchange configurado usando la clave del evento como routing key, y Fetcher hace lo mismo con sus eventos terminales de job. Las convenciones de tipo y versionado de CloudEvents se comparten en ambos transportes; la página de cada productor sigue siendo la autoridad para ids, esquemas, destinos y política de entrega exactos. El repositorio independiente LerianStudio/tracer-pre-dev no tiene actualmente streaming externo y no es este productor.
El sobre
Cada registro lleva estas cabeceras de CloudEvents.Tipo de evento
El contrato v3 usa la forma calificada por la fuentestudio.lerian.<source>.<resource>.<event>. El mismo valor <source> aparece en ce-source; ce-resourcetype y ce-eventtype llevan la clave de dispatch en headers separados. Los productores que siguen fijados en lib-streaming v2 usan la forma sin fuente studio.lerian.<resource>.<event>; consulta la página o el manifest del productor antes de enrutar.
Nombres de tópicos
Los productores Kafka con el contrato v3 de stream por aplicación — incluidos Midaz,components/tracer de Midaz, Matcher, Lender y Consignado — envían sus hechos de negocio JSON públicos a:
lerian.streaming.<ce-source>.commands; los dead letters del productor usan lerian.streaming.<ce-source>.dlq. No existe un tópico .commands.dlq separado. El tipo de recurso, el tipo de evento y la versión de esquema permanecen en los headers de CloudEvents, por lo que un cambio de major no renombra el tópico.
Ejemplos:
- Hechos JSON públicos del ledger, CRM y Fees de Midaz:
lerian.streaming.ledger - Hechos de
components/tracerde Midaz:lerian.streaming.tracer - Hechos de Matcher:
lerian.streaming.matcher - Hechos y comandos de Lender:
lerian.streaming.lenderylerian.streaming.lender.commands - Hechos del gateway de Consignado:
lerian.streaming.consignado-gw
RABBITMQ_JOB_EVENTS_EXCHANGE con job.completed o job.failed. Sus valores de ce-type también están calificados por la fuente.
Fuente
ce-source identifica el servicio productor y forma parte del contrato wire. Los ejemplos actuales de productos v3 usan ledger, tracer (components/tracer de Midaz), matcher, lender, consignado-gw, fetcher o reporter; todos salvo Matcher fijan o validan ese valor exacto del roster, mientras Matcher deriva su identidad wire del valor configurado. Los productores Kafka v3 incorporan la fuente al tópico de aplicación y todos los productores v3 la incorporan a ce-type. Por ello, cambiarla modifica el enrutamiento y la identidad para los consumidores; trátalo como un cambio incompatible.
Subject y tenant
ce-subject lleva el id del agregado al que se refiere el evento — la cuenta, la transacción o la credencial que el hecho describe. ce-tenantid lleva el tenant propietario. Su comportamiento en single-tenant depende del productor: Midaz siempre envía el literal default en el ámbito single-tenant o sin tenant, mientras que otros productores documentan su propio comportamiento. Sigue el contrato específico del productor.
Versionado de esquema
Cada evento declara su propia versión de esquema del payload ence-schemaversion, independiente de los demás eventos de la misma fuente. El valor predeterminado es 1.0.0. Un incremento menor es aditivo y retrocompatible; un incremento mayor es un cambio incompatible. En los streams de aplicación Kafka v3, la versión de esquema nunca cambia el nombre del tópico. Los exchanges y routing keys explícitos de RabbitMQ tampoco cambian con un incremento de esquema. Un consumidor que lee los payloads como un lector tolerante, ignorando los campos desconocidos, no se ve afectado por un cambio aditivo.
Garantías de entrega
La entrega es at-least-once. Un consumidor confirma su posición solo después de terminar de procesar un registro, así que una caída a mitad del procesamiento reprocesa el registro en lugar de descartarlo, lo que significa que el mismo evento puede llegar más de una vez. Deduplica por el par(ce-source, ce-id) (CloudEvents define la identidad del evento por esa combinación, y ce-id por sí solo puede colisionar entre fuentes) y mantén los handlers idempotentes.
En el lado del productor, la política de entrega pertenece a cada definición de evento, no a la plataforma. Una política respaldada por outbox garantiza relay duradero y reintentos, pero no demuestra por sí sola que la escritura del estado de negocio y la inserción en el outbox compartan una transacción de base de datos. Lender y Consignado realizan esa escritura atómica para los eventos de sus catálogos. Fetcher persiste el estado terminal con un marcador pendiente y después inserta el evento en su outbox duradero de Mongo mediante una operación separada; un proceso de reparación vuelve a emitir el ce-id estable hasta que se elimina el marcador. Reporter también emite después del commit del estado y sus políticas críticas usan después un outbox duradero de Mongo en una operación separada. Una caída o una inserción fallida en el outbox en esa ventana posterior al commit pierde el evento de Reporter: ninguna reconciliación lo recupera, y solo un registro de error y una métrica dejan constancia de la pérdida. Matcher y Reporter también publican señales operativas directamente con fallback al outbox. Consulta la página de eventos del producto para conocer tanto la política como el límite transaccional y, cuando el producto exponga un manifiesto de streaming, léelo al arrancar.
Catálogos por producto
Los rieles de Brasil (STA, CCS, SLC, SPB, SPI, SILOC, SISBAJUD, transferencia bancaria y los servicios de Pix) también publican eventos con este mismo contrato; consulta el área de documentación de cada riel para su catálogo.