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, Tracer, 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. El sobre, el tipado, el versionado y la semántica de entrega de abajo se aplican de forma idéntica en ambos transportes.
El sobre
Cada registro lleva estas cabeceras de CloudEvents.Tipo de evento
La cabecerace-type nombra el evento como studio.lerian.<resource>.<event>. La creación de una cuenta en el ledger es studio.lerian.account.created. Los dos segmentos también aparecen por separado en ce-resourcetype y ce-eventtype, de modo que un consumidor filtra por el tipo completo o por sus partes.
Nombres de tópicos
Los nombres de los tópicos de Kafka no se comparten entre productores — no hay un único prefijo común a toda la plataforma. Cada productor es dueño de su propio namespace de tópicos, y un nombre sigue uno de dos patrones según cómo el productor enruta sus eventos. Las páginas por producto listan el tópico exacto de cada evento; las reglas de abajo te permiten predecir la forma y saber de qué productor provino un registro.Tópicos explícitos (Midaz)
Midaz enruta cada evento a un destino explícito del que es dueño:- El núcleo del ledger publica bajo
lerian.streaming.ledger_<resource>.<event>. - Las capacidades CRM y Fees — emitidas por el mismo servicio consolidado del ledger, compartiendo su
ce-source— conservan sus propios segmentos:lerian.streaming.crm_<resource>.<event>ylerian.streaming.fee_<resource>.<event>. - Tracer publica bajo
lerian.streaming.tracer_<resource>.<event>.
[a-z0-9_]: balance.config-changed llega a lerian.streaming.ledger_balance.config_changed, mientras que su ce-type conserva el guion (studio.lerian.balance.config-changed). La cola del tópico es el único lugar donde aparece la forma con guion bajo — la identidad del evento que llevan ce-type, ce-resourcetype y ce-eventtype no cambia.
Tópicos derivados de la fuente (Lender, Matcher, Consignado, comandos entre productos)
Otros productores derivan el tópico de su fuente de CloudEvents:lender.<resource>.<event>, Matcher bajo matcher.<resource>.<event> y Consignado bajo consignado-gw.<resource>.<event>. Un comando que un producto envía a otro conserva el namespace del productor, no el del consumidor — un comando que Consignado consume desde Lender llega a lender.<resource>.<event>. El segmento de la fuente se pasa a minúsculas y cualquier carácter fuera de [a-z0-9._-] se pliega a un guion antes de usarse, así que elige un valor de fuente que siga siendo único tras esa normalización.
Un tópico derivado no lleva sufijo de versión para un esquema 1.x; un incremento mayor de esquema (2.0.0 y superiores) añade .v<major> al tópico — por ejemplo ...event.v2 — de modo que un cambio incompatible de payload traslada a los consumidores a un tópico nuevo en lugar de reinterpretar el antiguo. Los tópicos explícitos de Midaz son literales fijos y nunca llevan sufijo de versión — un cambio incompatible de esquema en un tópico explícito se señala únicamente mediante ce-schemaversion, no mediante el nombre del tópico.
Fuente
ce-source identifica el servicio productor. Se configura en el despliegue mediante la variable de entorno STREAMING_CLOUDEVENTS_SOURCE. El ledger (incluidos CRM y Fees), Consignado, Matcher, Reporter y Fetcher la requieren: con el streaming habilitado, no arrancan si está sin definir, en lugar de emitir bajo una fuente adivinada. Lender va más allá y exige el valor exacto lender. Tracer, en cambio, trae un valor por defecto en el código (lerian.midaz.tracer) y trata la variable como una sobrescritura. Asígnale un valor estable y descriptivo por despliegue.
ce-source registra dónde se originó un registro, para auditoría y enrutamiento del lado del consumidor. Para los productores que derivan sus tópicos de ella (consulta Nombres de tópicos), la fuente también determina el namespace del tópico, así que su valor es parte del contrato del formato de cable, no solo metadatos. Midaz enruta a tópicos explícitos en su lugar, así que su fuente aparece en ce-source para atribución pero no da forma al nombre del tópico.
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 en despliegues multi-tenant; se omite en los eventos de negocio single-tenant, así que un consumidor trata la ausencia de id de tenant como un ámbito single-tenant válido y no como un error.
Versionado de esquema
Cada evento declara su propia versión de esquema de 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. La versión vive en la cabecera, nunca en el nombre del tópico, así que 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 porce-id 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. Un producto que declara un evento respaldado por outbox lo escribe en su outbox dentro de la misma transacción de base de datos que el cambio de estado que lo generó. El evento y el hecho que reporta se confirman o se revierten juntos. Luego un relay publica las filas confirmadas del outbox en el transporte del productor (Kafka o RabbitMQ) y reintenta durante las caídas del broker. Lender, Consignado y Fetcher declaran así cada evento de sus catálogos; Matcher y Reporter dividen los suyos — los hechos de grado de auditoría están respaldados por outbox, y las señales operativas publican directo con fallback al outbox. Consulta la página de eventos del propio producto para la política que lleva su catálogo, y donde el producto expone un manifiesto de streaming, lee el manifiesto 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.