Norma para la construcción de sistemas basados en eventos

Ámbito de aplicación de la norma

Esta norma es de aplicación en desarrollos que impliquen la adopción de un enfoque basado en el procesamiento y la reacción a eventos .

Las directrices que contiene la norma son independientes de la pila tecnológica que se adopte para la arquitectura de eventos. Los objetivos y características de la arquitectura no están vinculados a la tecnología de implementación.

Por tanto, al implementar un sistema basado en eventos con una tecnología específica, hay que considerar:

• Las directrices y estándares referidos en esta página.
• Otras normas particulares para la implementación de dicha tecnología.

Diseño

DIR_01 Propósito del evento

OBLIGATORIO Se definirá claramente el propósito de cada evento con nombres descriptivos y significativos. Cada evento debe tener un propósito específico y claro. Esto facilita su comprensión en los consumidores y asegura que se utilicen de manera adecuada.

Ejemplo: UsuarioCreado, TicketActualizado.

DIR_02 Relevancia del evento

OBLIGATORIO Los eventos representarán cambios significativos en el estado del sistema que serán notificados a otros sistemas o componentes, evitando eventos triviales o redundantes. 

• Queda prohibido el uso de eventos para el envío de ficheros físicos a través de la red ya que este uso no está alineado con el uso de eventos para notificar cambios ni está contemplado por parte de la tecnología de los broker de mensajería. 
• Se permitirá aprovechar la notificación del cambio de estado para transportar otra información relevante siempre que esta información no sea pesada. Ejemplo: no se permite el envío de ficheros físicos pero sí el envío de la url a un fichero almacenado en un sistema de almacenamiento externo.

Ejemplo: ReservaCancelada es significativo, mientras que un mensaje CiudadConsultada puede ser menos relevante para el control de operaciones.

DIR_03 Definición de los mensajes

OBLIGATORIO La definición de la estructura de los mensajes se hará usando usando Avro o JSON.

Se definirá una estructura de datos coherente para cada mensaje. La definición de los mensajes facilita la interoperabilidad entre los diferentes componentes del sistema y garantiza un procesamiento uniforme. 

Ejemplo (AVRO):
{
  "type": "record",
  "name": "Reserva",
  "namespace": "es.juntadeandalucia.eventos.vuelos",
  "fields": [
    {
      "name": "idReserva",
      "type": ["null", "string"]
    },
    {
      "name": "nombreViajero",
      "type": ["null", "string"]
    },
    {
      "name": "fechaReserva",
      "type": [
"null",
{
"type": "int",
"logicalType": "date"
}
]
    }
  ]
}

DIR_04 Definición de los eventos

RECOMENDADO Para poder compartir la definición de los eventos entre diferentes sistemas de información, se recomienda definir los eventos usando AsyncAPi. Aunque la definición de los contratos AsyncApi no esté aún soportado por muchas aplicaciones y frameworks de desarrollo, es una forma estandarizada y sencilla de definir un evento y compartirlo cuando el evento vaya a ser consumido por uno o varios sistemas externos y que no dependen del sistema que lo generó.

DIR_05 Nivel de detalle de los mensajes

RECOMENDADO Se recomienda que los mensajes sean del menor tamaño posible para que su envío y procesamiento sea lo más eficiente posible. En cualquier caso, está prohibido que un mensaje supere el megabyte que es el tamaño máximo recomendado por la tecnología.

DIR_06 Consistencia en los nombres de los campos

OBLIGATORIO Se mantendrá consistencia en los nombres de los campos para evitar confusiones y errores de interpretación.

Ejemplo: Si un mensaje tiene un campo llamado idPedido, todos los eventos relacionados con pedidos deben seguir la misma convención de nombres.

DIR_07 Claridad en nombres de los topics

OBLIGATORIO Los nombres de los topics serán claros y descriptivos.

Los nombres de los topics reflejarán el propósito y el contenido de los eventos que contienen, facilitando su comprensión e identificación. Para ello se agregará información contextual con prefijos y sufijos significativos.

Ejemplo: orden-creada, pago-realizado, usuario-actualizado.

DIR_08 Estructura de los topics

RECOMENDADO Los topics se agruparán y categorizarán en una estructura jerárquica.

Se utilizará una convención de nomenclatura que refleje una estructura de tipo "dominio.subdominio.nombre-evento" para organizar los topics de manera coherente y facilitar su gestión.

Ejemplo: ventas.orden-creada, ventas.pago-realizado, log.error, log.acceso.

DIR_09  Reglas básicas para la nomenclatura de los topics

RECOMENDADO Se seguirán convenciones consistentes para la nomenclatura de los topics.

Se seguirán las reglas de nomenclatura de los topics en toda la arquitectura para una organización clara y una fácil gestión:

• Utilizar siempre minúsculas
• Separador de palabras con guiones o guiones bajos
• No usar caracteres especiales

DIR_10 Nombres de los topics

RECOMENDADO Los nombres de los topic serán cortos, concisos e independientes y no guardarán relación con los sistemas que conectan, los productores, los consumidores o cualquier componente que utilizan el topic .

DIR_11 Nomenclatura de productores y consumidores

OBLIGATORIO Se seguirán las convenciones de nomenclatura de productores y consumidores.

Los clientes de productores y consumidores seguirán una convención de nombres descriptiva y coherente, que refleje su función y contexto dentro del sistema. Esto garantiza consistencia y facilita la identificación y comprensión del propósito de cada clase cliente.

Ejemplo: una clase cliente responsable de enviar eventos de registro de actividad podría llamarse RegistroActividadProducer y por tanto otra que consuma dicho evento se llamaría RegistroActividadConsumer.

DIR_12 Documentación de productores y consumidores

RECOMENDADO Se documentará de forma detallada la implementación de productores y consumidores, incluyendo configuraciones, dependencias, versiones, etc.

Se documentarán los parámetros de configuración utilizados, las dependencias de bibliotecas externas y ejemplos de uso para los desarrolladores.

DIR_13 Documentación de la entrega

RECOMENDADO Se documentará de manera detallada la garantía de entrega en sistemas de eventos, especificando si se utiliza el modelo at-most-once, at-least-once o exactly-once y cómo se maneja la transaccionalidad de los eventos.

Esta documentación incluirá las configuraciones técnicas necesarias para garantizar la entrega, como la configuración de offsets, reintentos y confirmaciones de mensajes.

La documentación también debe abordar el impacto en la consistencia de los datos y cómo se manejan las transacciones en caso de fallo, garantizando la integridad del sistema. 

Construcción

DIR_14 Distribución de carga

OBLIGATORIO Se configurará el manejo de las particiones de los topics para distribuir la carga y garantizar un rendimiento adecuado.

Cuando sea necesario garantizar la entrega de los mensajes en orden, los productores especificarán la clave de partición adecuada para asegurar que los mensajes con la misma clave se envíen a la misma partición

DIR_15 Validación de los mensajes en productores y consumidores

OBLIGATORIO Se validará que los mensajes cumplan con la estructura y los requisitos de contenido esperados.

Las validaciones de mensajes deben incluir:

• Validación del formato y la estructura del mensaje
• Validación de los campos del mensaje
• Validación de los campos que sean dependientes de otro campo del mensaje o externo
• Validación del tamaño de los campos del mensaje
• Sanitización de los mensajes para evitar ataques de inyección de código y otros tipos de vulnerabilidades

Se recomienda que la validación de los mensajes esté apoyada en la definición de los mismos (ver norma asociada). También se podrá hacer una validación manual mediante código.

Seguridad

DIR_16 Protección de productores y consumidores

OBLIGATORIO Se establecerán políticas de seguridad y autorización para proteger los productores y consumidores de eventos, garantizando que solo los usuarios autorizados puedan acceder a ellos.

Se implementará autenticación basada en certificados SSL/TLS para garantizar la seguridad de las conexiones entre productores, consumidores y brokers.

DIR_17 Autorización sobre topics

OBLIGATORIO Se deben definir políticas de autorización sobre los topics.

Es necesario establecer políticas claras que definan quién tiene acceso y qué operaciones se pueden realizar en cada topic. De esta manera se garantiza que haya una comprensión clara de quién tiene autorización para realizar qué acciones en los topics, lo que ayuda a mantener la seguridad y la integridad de los datos. 

DIR_18 Mínimo privilegio y segregación de tareas

OBLIGATORIO Se seguirá el principio de mínimo privilegio y la segregación de tareas: 

Esto asegura que los usuarios tengan acceso solo a los recursos necesarios para realizar sus funciones, reduciendo así el riesgo de compromiso de datos y funciones críticas. Implementar un sistema de control de acceso efectivo es crucial para la seguridad de cualquier aplicación. 

DIR_19 Nivel de detalle de los permisos

OBLIGATORIO Se proporcionarán permisos con granularidad que permita definir quién puede realizar operaciones específicas en cada topic.

Esto promueve la especificidad en la definición de permisos, lo que permite un control más preciso sobre quién puede hacer qué en los topics.

DIR_20 Listas de control

OBLIGATORIO Se configurarán listas de control de acceso (ACL) para regular las autorizaciones en los topics.

La definición de ACL asegura que se utilicen mecanismos adecuados para controlar el acceso a los topics, lo que proporciona una capa adicional de seguridad. 

DIR_21 Control de acceso basado en roles

RECOMENDADO Si se utiliza RBAC (role based access control) se asignarán roles y responsabilidades específicos en función de las operaciones que necesiten realizarse en los topics.

Esta directriz facilita la gestión de autorizaciones al asignar roles específicos en función de sus responsabilidades en el sistema.

DIR_22 Registro de eventos críticos

RECOMENDADO Se implementará un sistema de LOG para procesos y operaciones específicas, enfocado en registrar eventos críticos relacionados con las operaciones de lectura, escritura y eliminación fuera del sistema.

Este sistema de LOG mejoraría significativamente la visibilidad y la trazabilidad de dichos eventos críticos.

Es importante que este sistema de auditoría para eventos críticos utilice un canal específico, que podría persistir los eventos en una base de datos o en otro sistema que permita una mayor rastreabilidad y facilidad de auditoría.

DIR_23 Revisión de las autorizaciones

RECOMENDADO Se revisará periódicamente las autorizaciones en los topics para garantizar su adecuación y cumplimiento.

De esta manera, se promueve la revisión regular de las políticas de autorización para asegurar que sigan siendo efectivas y estén alineadas con los requisitos de seguridad y cumplimiento. 

Ejemplo: Revisar trimestralmente las ACL y los roles asignados en los topics de Kafka para asegurarse de que reflejen correctamente la estructura y las necesidades del sistema.

Observabilidad y gestión de errores

DIR_24 Traza de mensajes

RECOMENDADO Cuando un mensaje no sea válido, se registrará en las trazas de logs.

En el proceso de validación de formato, estructura y contenido de un mensaje, se recomienda registrar el error en los logs del sistema

DIR_25 Seguimiento de la entrega

OBLIGATORIO Se implementarán políticas para la retransmisión de mensajes en caso de fallos temporales en la entrega.

Se implementarán estrategias de reintento con un límite máximo de intentos para manejar errores temporales, como problemas de red o indisponibilidad del servidor.

DIR_26 Gestión de errores en productores y consumidores

OBLIGATORIO Se implementarán lógicas de gestión de errores en los productores y consumidores.

Se registrarán errores y eventos importantes en los logs con suficiente detalle, incluyendo información como la marca de tiempo, el tipo de error y el contexto relevante.

DIR_27 Errores de validación

OBLIGATORIO Los productores y consumidores manejarán adecuadamente los errores de validación:

Se implementarán mecanismos para manejar errores de validación de datos de manera adecuada, registrando información detallada sobre los errores y tomando acciones correctivas según corresponda. Para errores de validación el mensaje deberá ser enviado directamente a la DLQ para su posterior análisis y resolución.

Ejemplo: Registrar información sobre los errores de validación en un registro de auditoría y enviar alertas para su corrección.

DIR_28 Seguimiento de errores

RECOMENDADO Se implementará un sistema de registro de errores y excepciones para registrar los problemas de validación encontrados durante la producción y consumo de eventos:

De esta manera, se facilita la identificación y resolución de problemas al proporcionar información detallada sobre los errores de validación que se producen en el sistema. 

Ejemplo: Registrar los errores de validación junto con detalles como el tipo de error, el evento afectado y la fecha y hora en que ocurrió.

DIR_29 Política de aceptación de errores de validación

OBLIGATORIO Se establecerá una política que defina los niveles de aceptación para los errores de validación, especificando cómo deben manejarse y cuándo deben ser notificados:

Se definirá cómo deben tratarse los errores de validación y cuándo deben considerarse críticos, lo que facilita la toma de decisiones y la resolución de problemas. 

Ejemplo: Definir que los errores de validación menores puedan ser registrados para su análisis posterior, mientras que los errores críticos deben desencadenar una notificación inmediata mediante un sistema de alertas como Prometheus y Grafana.

DIR_30 Manejo de los errores e información

OBLIGATORIO Se implementarán mecanismos que manejen las situaciones inesperadas de manera segura y efectiva, sin revelar información confidencial sobre la aplicación o su infraestructura subyacente:

Los errores se manejarán de manera controlada y los usuarios recibirán mensajes de error claros y concisos, sin ofrecer información que pueda comprometer la seguridad del sistema.

Ejemplo: Cuando se emite un error de autenticación si se indica que el “usuario no existe”, se estaría proporcionando a un usuario malintencionado que pruebe con otro usuario hasta que el error que se muestre sea diferente, por ejemplo “contraseña incorrecta”. Esto hace que el usuario mal intencionado pueda deducir que ha encontrado un usuario válido del que pueda inferir mediante fuera bruta una posible contraseña.

DIR_31 Número de reintentos

OBLIGATORIO Se establecerá el número máximo de intentos para el procesamiento de eventos fallidos antes de ser enrutados a la Dead Letter Queue.

Se definirán también los intervalos de tiempo entre cada reintento utilizando estrategias como el reintento exponencial.

Ejemplo: Se configura una política de retries automático con un máximo de 3 intentos y un intervalo de tiempo inicial de 5 segundos, que se incrementa exponencialmente en cada reintento.

DIR_32 Colas de mensajes

OBLIGATORIO Se definirán una o varias colas de mensajes (DLQs) dedicadas a almacenar eventos que no pudieron ser procesados después de varios intentos de reenvío.

Se establecerán políticas para el enrutamiento de estos eventos a las DLQs, incluyendo la clasificación basada en el tipo de error o la causa del error.

DIR_33 Seguimiento y gestión de eventos almacenados en las colas de mensajes

RECOMENDADO Se establecerán procedimientos y herramientas para seguir y gestionar los eventos almacenados en las colas de mensajes (DLQs).

Se pueden incluir alertas automáticas para notificar sobre la acumulación de eventos, mecanismos para la visualización y búsqueda de eventos en las DLQs, y la implementación de procesos de corrección para resolver los problemas subyacentes que causaron la falla en el procesamiento.

DIR_34 Errores no reintentables

RECOMENDADO Todos los eventos que generen errores no reintentables serán enviados automáticamente a una Dead Letter Queue (DLQ) para su posterior análisis y resolución, independientemente del tipo de error ocurrido:

Se implementará un mecanismo que capture todos los eventos que, tras fallar en su procesamiento, no puedan ser reintentados de manera automática. Estos eventos deben ser redirigidos a la DLQ, donde serán almacenados con suficiente información contextual para facilitar su diagnóstico. La DLQ será monitoreada regularmente, y los eventos en ella deben ser procesados por un equipo designado, con el fin de identificar la causa del fallo, corregirla y, si es posible, reprocesar los eventos para asegurar su correcta ejecución.

Pruebas

DIR_35 Pruebas unitarias

OBLIGATORIO Se realizarán pruebas unitarias para cubrir el mínimo porcentaje exigido de código, validando todos los componentes elementales y sus distintas rutas lógicas.

Las pruebas unitarias son la primera línea de defensa en la detección de errores, por lo que es importante que cubran la mayor parte de la lógica de forma aislada del resto.

DIR_36 Pruebas de integración de componentes

OBLIGATORIO Se realizarán pruebas para comprobar que todos los componentes de la arquitectura de eventos se integran de manera correcta.

DIR_37 Pruebas de rendimiento

OBLIGATORIO Se realizarán pruebas de rendimiento (carga, picos y estrés) en entornos no productivos para validar que la solución de eventos implementada es capaz de responder a las necesidades para las que ha sido creada.

Normas relacionadas

La construcción de un evento implica el cumplimiento de esta norma y las normas transversales que se apliquen:

• Norma para el alineamiento con la pila tecnológica de la ADA
• Norma para el desarrollo seguro
• Norma para la observabilidad

Estándares

El siguiente listado muestra los estándares que se aplican a la arquitectura de microservicios. Puede consultarse la descripción de cada estándar en la siguiente página

Definición de servicios y eventos

• Avro
• JSON Schema
• Async API

Comunicaciones

• GraphQL

Seguridad

• SSOWEB(SAML 2.0)
• HTTPS/SSL
• OAuth2