Transporte
Los eventos viajan como mensajes CloudEvents 1.0 en modo de contenido binario sobre Kafka. El modo binario coloca los atributos de contexto de CloudEvents en las cabeceras del registro de Kafka, cada una con el prefijoce-, y el cuerpo del evento en el valor del registro como JSON. Un consumidor lee el enrutamiento y la identidad desde las cabeceras sin deserializar el payload.
El sobre
Cada registro lleva estas cabeceras de CloudEvents.| Cabecera | Presencia | Contiene |
|---|---|---|
ce-specversion | Siempre | Versión de la especificación CloudEvents — 1.0. |
ce-id | Siempre | Id único del evento (UUIDv7). Deduplica por este valor. |
ce-source | Siempre | El servicio productor. |
ce-type | Siempre | Tipo de evento — studio.lerian.<resource>.<event>. |
ce-time | Siempre | Marca de tiempo de emisión (RFC 3339). |
ce-resourcetype | Siempre | El recurso — por ejemplo account. |
ce-eventtype | Siempre | El evento — por ejemplo created. |
ce-schemaversion | Siempre | Versión del esquema del payload. |
ce-subject | Cuando aplica | El id del agregado al que se refiere el evento. |
ce-tenantid | Cuando aplica | El tenant propietario; se omite en el ámbito single-tenant. |
ce-datacontenttype | Cuando aplica | Tipo de medio del cuerpo — application/json. |
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
Cada evento llega a un tópico de Kafka nombrado por el recurso y el evento que transporta, bajo un prefijo de plataforma compartido:lerian.streaming.account.created; la creación de un titular en el CRM a lerian.streaming.holder.created. El prefijo es idéntico en todos los productores Lerian, así que un consumidor se suscribe por recurso y evento sin necesidad de saber qué servicio emitió el registro. El nombre del tópico no lleva sufijo de versión — la versión del esquema del payload viaja en la cabecera ce-schemaversion (consulta Versionado de esquema), así que un cambio de esquema nunca renombra un tópico.
Fuente
ce-source identifica el servicio productor y se configura en el despliegue mediante la variable de entorno STREAMING_CLOUDEVENTS_SOURCE; no está fijada en el producto. Registra dónde se originó un registro, para auditoría y enrutamiento del lado del consumidor. El nombre del tópico no deriva de ella — los tópicos usan el prefijo compartido lerian.streaming. sin importar la fuente — así que un despliegue puede asignar cualquier valor de fuente estable y descriptivo.
| Productor | Fuente predeterminada |
|---|---|
| Ledger de Midaz | lerian.midaz.ledger |
| CRM de Midaz | lerian.midaz.crm |
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 durabilidad proviene de un outbox transaccional. Un producto escribe el evento en su outbox dentro de la misma transacción de base de datos que el cambio de estado que lo generó, de modo que el evento y el hecho que reporta se confirman o se revierten juntos. Luego un relay publica en Kafka las filas confirmadas del outbox y reintenta durante las caídas del broker, así que ningún hecho de negocio confirmado se pierde antes de llegar al stream.