Saltar al contenido principal
Un evento se mueve por Streaming Hub en tres etapas. El hub lo ingiere desde el stream interno, lo compara con tus suscripciones y lo despacha a cada destino que coincide. Esta página recorre cada etapa y las garantías de entrega que salen de ella.

​
Ingesta de eventos desde el stream

Streaming Hub consume el stream de la plataforma como mensajes CloudEvents 1.0 en modo de contenido binario. Los atributos de contexto de CloudEvents viajan en los headers del registro de Kafka (cada uno con el prefijo ce-). El cuerpo del evento es el valor del registro. El hub lee el enrutamiento y la identidad desde los headers. El hub se suscribe solo a los temas de hechos de aplicación v3:
ce-source es un solo segmento en minúsculas y sin puntos. Usa letras, dígitos, guiones bajos o guiones. El tema no lleva sufijo de recurso, de evento ni de major de esquema. El hub despacha por los headers de CloudEvents. El conjunto de seguimiento excluye los temas de comandos (.commands) y los temas de dead-letter (.dlq). Un segundo consumidor lee los temas .dlq que escriben los productores. Ese consumidor sirve solo para observabilidad. La gramática del conjunto de seguimiento excluye un .dlq final, así que un registro de dead-letter nunca se convierte en una entrega a una de tus suscripciones. GET /admin/dlq lee esos registros. Consulta Observaciones de dead-letter. Cada registro que el hub acepta debe llevar este conjunto de contexto: Para cada registro el hub devuelve uno de tres veredictos: El tenant admitido en la ingesta viene solo del atributo ce-tenantid validado que extrajo el parser. La ingesta no tiene un control de descarte por listado de tenants. Los eventos guardados coinciden solo con suscripciones que tengan el mismo id de tenant.
Tres cadenas relacionadas se parecen, pero son distintas. Nunca las confundas:
  • ce-type es el tipo de CloudEvents calificado por fuente: studio.lerian.<source>.<resource>.<event> (por ejemplo, studio.lerian.lender.loan_application.approved).
  • Tema de Kafka es un tema de hechos v3 por aplicación: lerian.streaming.<source> (por ejemplo, lerian.streaming.lender). El recurso, el evento y el major de esquema no aparecen en el tema.
  • X-Lerian-Event-Type es la clave simple <resource>.<event> en un webhook entregado (loan_application.approved). Omite el productor a propósito. Usa una fijación de origin en la suscripción cuando la misma clave puede venir de más de una aplicación.
Consulta el resumen de event streaming para el contrato de transmisión completo.

​
Deduplicación de consumo único

El stream interno es de al menos una vez, así que el mismo registro puede llegar más de una vez. Al entrar al inbox de eventos el hub deduplica por ce-id. Un id duplicado no escribe nada y cuenta como un descarte por deduplicación. El hub persiste los registros por partición de Kafka en una sola transacción. Confirma la posición del stream de una partición solo después de que la escritura de esa partición se confirma. Por eso una falla en una partición nunca pierde ni confirma dos veces los eventos de otra.

​
Coincidencia de suscripciones

La coincidencia admite una suscripción solo cuando está enabled y en verification_state = active. Estas son dos condiciones independientes, y la coincidencia requiere ambas. Consulta el modelo de suscripción. Un evento que ninguna suscripción quiere produce cero entregas. Ese es un resultado correcto, no un error.

​
Despacho a tus destinos

Por cada coincidencia, el hub crea un trabajo de entrega y lo pasa a un grupo de workers (ocho workers de forma predeterminada). El destino de una suscripción usa como máximo la mitad de los workers a la vez, así que un destino lento deja el resto a tus otras suscripciones. Los workers reclaman trabajos vencidos de forma atómica con un lease corto y se alternan entre tenants, así que la acumulación de un solo tenant no deja sin recursos a los demás. Cada worker carga el payload guardado, descifra en memoria el secreto de firma o la credencial del destino, y hace exactamente un intento de entrega al sink. La entrega es al menos una vez: el hub puede entregar el mismo evento más de una vez (mediante reintentos o reentregas después de que un worker se reinicia). Consulta Consumo de eventos para el lado del consumidor de este contrato.

​
Reintentos y back-off

Cuando un intento falla, el hub programa el siguiente sobre una curva de back-off fija con jitter completo:
Un trabajo recibe como máximo ocho intentos. Un intento que empieza 24 horas o más después de que el hub recibió el evento es el último del trabajo.

​
Envío a dead-letter

El hub manda a dead-letter un evento que agota sus reintentos. Deja de intentarlo y registra el resultado final. El hub recupera un trabajo que, en cambio, sigue haciendo caer a un worker a mitad de intento y nunca registra un resultado. El límite de recuperación es cinco de forma predeterminada. Luego el hub lo manda a dead-letter como envenenado, así que un solo trabajo tóxico nunca puede ocupar un worker para siempre.

​
Circuit breaker

Cada par (tenant, destination) tiene un circuit breaker. Cuando un destino falla repetidamente, su circuit breaker se abre. Los siguientes trabajos para ese destino esperan sin intento, pero el último intento de un trabajo todavía puede ejecutarse. Un solo endpoint roto no quema capacidad de workers ni golpea un destino que ya está sufriendo. El circuit breaker se recupera por sí solo una vez que el destino vuelve a tener éxito.

​
Desactivación automática de un destino roto

El hub desactiva automáticamente un destino que sigue roto durante mucho tiempo. La desactivación automática se dispara solo cuando el tramo de fallas abierto cumple las dos condiciones:
  • sostenido: dura al menos la ventana de fallas (120 horas de forma predeterminada), y
  • extendido: al menos 12 horas separan la primera falla de la última del tramo.
Ambos controles deben cumplirse, y una sola entrega exitosa borra el tramo, así que un problema breve nunca acumula hacia el veredicto. Cuando la desactivación automática se dispara, cambia la bandera enabled de la suscripción a false. Nunca toca verification_state. La entrega se detiene (la coincidencia requiere enabled), y el hub registra por qué. Recuperas una suscripción desactivada automáticamente con POST /v1/subscriptions/:id/verify, que vuelve a sondear el destino y, si tiene éxito, la vuelve a habilitar en su lugar. Consulta recuperar una suscripción desactivada automáticamente.

​
Garantías de ordenamiento

Los productores particionan el stream por tenant, así que los eventos de un tenant normalmente viajan en una sola partición. El hub los guarda en ese orden y le da a cada uno una secuencia de llegada (seq). Un consumidor con pull lee los eventos en el orden de seq. La entrega push no conserva ese orden. Los workers entregan en paralelo, y un reintento envía un evento fallido después de los eventos que lo siguieron. El hub atribuye y deduplica por los headers de CloudEvents, no por la clave del registro de Kafka. Un productor que reparte (con salt) un tenant caliente entre varias particiones mantiene la atribución correcta, pero seq refleja entonces el orden en que los eventos llegaron al hub, no el orden en que se produjeron.

​
Próximos pasos

Gestión de suscripciones

El modelo de suscripción, los flujos de incorporación y la rotación de secretos.

Consumo de eventos

Verifica firmas, deduplica y lee eventos con pull.