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 los headers de transporte, cada uno con el prefijoce-, y el cuerpo del evento como JSON en el valor del mensaje. Un consumidor lee el enrutamiento y la identidad desde los headers sin deserializar el payload.
La mayoría de los productores publican sobre Kafka: Midaz, Tracer (en Midaz), Lender, Matcher y Consignado. Reporter publica el mismo envelope sobre RabbitMQ. Enruta cada evento a un exchange configurado, con la clave del evento como routing key. Ambos transportes comparten las convenciones de tipo y versionado de CloudEvents. La página de cada productor sigue siendo la fuente autorizada para los ids, esquemas, destinos y política de entrega exactos. El productor Kafka de Tracer es el componente dentro de Midaz.
El envelope
Cada registro incluye estos headers de CloudEvents.Tipo de evento
El contrato v3 usa la forma calificada por fuentestudio.lerian.<source>.<resource>.<event>. El mismo valor de <source> aparece en ce-source. ce-resourcetype y ce-eventtype transportan la clave de despacho como headers separados. Los productores que todavía están fijados a lib-streaming v2 usan la forma sin fuente studio.lerian.<resource>.<event>. Verifica la página específica del productor o el manifest antes de enrutar.
Nomenclatura de temas
Los productores de Kafka en el contrato de application-stream v3 (incluidos Midaz, Midazcomponents/tracer, 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 tema .commands.dlq separado. El tipo de recurso, el tipo de evento y la versión del esquema permanecen en los headers de CloudEvents, de modo que los cambios de versión mayor del esquema no renombran el tema.
Ejemplos:
- Hechos JSON públicos de Midaz ledger, CRM y Fees:
lerian.streaming.ledger - Hechos de Midaz
components/tracer: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
ce-type siguen calificados por fuente.
Fuente
ce-source identifica el servicio productor y forma parte del contrato de wire. Los ejemplos actuales de productos v3 usan ledger, tracer (Midaz components/tracer), matcher, lender, consignado-gw o reporter. Todos, excepto Matcher, fijan o validan ese valor exacto de la lista. Matcher deriva su identidad de wire a partir del valor configurado. Los productores Kafka v3 incrustan la fuente en el tema de la aplicación, y todos los productores v3 la incrustan en ce-type. Cambiarla, por lo tanto, cambia el enrutamiento y la identidad del consumidor. Trátalo como un cambio disruptivo.
Asunto y tenant
ce-subject transporta el id del agregado al que se refiere el evento (la cuenta, transacción o credencial que concierne el hecho). ce-tenantid transporta el tenant propietario. Su comportamiento de un solo tenant es específico de cada productor: Midaz siempre envía el literal default en el ámbito de un solo tenant o sin tenant, mientras que otros productores documentan su propio comportamiento. Sigue el contrato específico de cada productor.
Versionado de esquema
Cada evento declara su propia versión de esquema del payload ence-schemaversion, independiente de otros eventos de la misma fuente. El valor predeterminado es 1.0.0. Un incremento menor es aditivo y compatible con versiones anteriores. Un incremento mayor introduce un cambio disruptivo.
En los application streams de Kafka v3, la versión del esquema nunca cambia el nombre del tema. Un incremento de esquema tampoco modifica los exchanges y routing keys explícitos de RabbitMQ. Un cambio aditivo no afecta a un consumidor que lee los payloads como tolerant reader e ignora los campos desconocidos.
Garantías de entrega
La entrega es al menos una vez. Un consumidor confirma su posición solo después de terminar de procesar un registro. Un crash a mitad del procesamiento reproduce el registro en lugar de descartarlo, de modo que el mismo evento puede llegar más de una vez. Deduplica según el par(ce-source, ce-id) (CloudEvents define la identidad del evento mediante esa combinación, y ce-id por sí solo puede colisionar entre fuentes) y mantén los handlers idempotentes.
Del lado del productor, la política de entrega pertenece a la definición de cada evento, no a la plataforma. Una política respaldada por outbox garantiza el relay y el reintento duraderos. Por sí sola, no demuestra que la escritura del estado de negocio y la inserción en el outbox compartan una misma transacción de base de datos.
Lender y Consignado hacen esa escritura atómica para sus eventos de catálogo. Reporter emite después del commit del estado, y sus políticas críticas luego usan un outbox duradero en Mongo en una operación separada. Un crash o una inserción fallida en el outbox durante esa ventana posterior al commit pierde el evento de Reporter. Ninguna conciliación lo recupera, y solo un log de error y una métrica registran la pérdida.
Matcher y Reporter también publican señales operativas directamente, con fallback a outbox. Consulta la página de eventos propia del producto tanto para su política como para su límite de transacción. Cuando el producto expone un manifest de streaming, lee el manifest al arrancar.
Catálogos por producto
Otros rieles de Brasil también publican eventos en este contrato. Usa la página de eventos de un riel o su manifest en tiempo de ejecución solo cuando el riel expone explícitamente su catálogo.