swl-ses 3.3.2

package/habilidades/event-driven/SKILL.md

@@ -0,0 +1,580 @@
+---
+name: event-driven
+description: Arquitectura event-driven. Message brokers RabbitMQ y Kafka, event sourcing, CQRS, pub/sub, event schemas, idempotency, dead letter queues, retry strategies, eventual consistency. Con ejemplos Python.
+---
+
+# Arquitectura Orientada a Eventos
+
+Los sistemas event-driven desacoplan productores de consumidores, permitiendo escalar
+componentes independientemente y resilir ante fallos. Este skill cubre desde pub/sub
+básico hasta event sourcing avanzado.
+
+---
+
+## 1. Cuándo Usar Event-Driven
+
+```
+USAR cuando:
+- Múltiples consumidores necesitan reaccionar al mismo evento
+- El productor no necesita respuesta inmediata del consumidor
+- Necesitas escalar productores y consumidores independientemente
+- Quieres desacoplar servicios que hoy están fuertemente acoplados
+- Necesitas auditoría completa de cambios (event log = audit log)
+
+NO USAR cuando:
+- Necesitas respuesta síncrona inmediata para el usuario
+- El flujo es simple y lineal (no hay múltiples consumidores)
+- El equipo no tiene experiencia operando brokers de mensajes
+- La consistencia eventual no es aceptable para el dominio
+```
+
+---
+
+## 2. RabbitMQ — Pub/Sub con Python
+
+```python
+# pip install aio-pika
+import aio_pika
+import asyncio
+import json
+from dataclasses import dataclass, asdict
+from datetime import datetime, timezone
+from typing import Any, Callable, Awaitable
+import uuid
+
+@dataclass
+class Evento:
+    tipo: str
+    payload: dict
+    id: str = ""
+    timestamp: str = ""
+    correlation_id: str = ""
+    version: str = "1.0"
+
+    def __post_init__(self):
+        if not self.id:
+            self.id = str(uuid.uuid4())
+        if not self.timestamp:
+            self.timestamp = datetime.now(timezone.utc).isoformat()
+
+class BrokerEventos:
+    """Wrapper sobre aio_pika para publicar y consumir eventos."""
+
+    def __init__(self, url: str):
+        self._url = url
+        self._conexion: aio_pika.RobustConnection | None = None
+        self._canal: aio_pika.abc.AbstractChannel | None = None
+
+    async def conectar(self) -> None:
+        self._conexion = await aio_pika.connect_robust(
+            self._url,
+            heartbeat=60,
+            reconnect_interval=5.0,
+        )
+        self._canal = await self._conexion.channel()
+        await self._canal.set_qos(prefetch_count=10)  # Procesar 10 mensajes a la vez
+
+    async def publicar(
+        self,
+        evento: Evento,
+        exchange: str = "eventos.rrhh",
+        routing_key: str | None = None,
+    ) -> None:
+        """Publicar evento al exchange con routing key = tipo del evento."""
+        assert self._canal, "Llamar connect() primero"
+
+        exchange_obj = await self._canal.declare_exchange(
+            exchange,
+            aio_pika.ExchangeType.TOPIC,
+            durable=True,
+        )
+
+        await exchange_obj.publish(
+            aio_pika.Message(
+                body=json.dumps(asdict(evento), ensure_ascii=False).encode(),
+                content_type="application/json",
+                delivery_mode=aio_pika.DeliveryMode.PERSISTENT,  # Sobrevive restart
+                message_id=evento.id,
+                timestamp=datetime.now(timezone.utc),
+                headers={
+                    "x-correlation-id": evento.correlation_id,
+                    "x-event-version": evento.version,
+                },
+            ),
+            routing_key=routing_key or evento.tipo,  # "empleado.creado"
+        )
+
+    async def suscribir(
+        self,
+        cola: str,
+        exchange: str,
+        routing_keys: list[str],
+        handler: Callable[[Evento], Awaitable[None]],
+    ) -> None:
+        """Suscribir a eventos con manejo automático de DLQ."""
+        assert self._canal
+
+        # Dead Letter Queue — eventos que fallan tras N reintentos
+        dlq_nombre = f"{cola}.dlq"
+        await self._canal.declare_queue(
+            dlq_nombre,
+            durable=True,
+        )
+
+        # Cola principal con referencia a DLQ
+        queue = await self._canal.declare_queue(
+            cola,
+            durable=True,
+            arguments={
+                "x-dead-letter-exchange": "",
+                "x-dead-letter-routing-key": dlq_nombre,
+                "x-message-ttl": 86400000,  # 24h en ms
+            },
+        )
+
+        exchange_obj = await self._canal.declare_exchange(
+            exchange, aio_pika.ExchangeType.TOPIC, durable=True
+        )
+
+        for routing_key in routing_keys:
+            await queue.bind(exchange_obj, routing_key=routing_key)
+
+        async def procesar_mensaje(mensaje: aio_pika.IncomingMessage) -> None:
+            async with mensaje.process(requeue=False):  # requeue=False → DLQ al fallar
+                try:
+                    datos = json.loads(mensaje.body)
+                    evento = Evento(**datos)
+                    await handler(evento)
+                except Exception as e:
+                    logger.error("Error procesando evento %s: %s", mensaje.message_id, e)
+                    raise  # Enviar a DLQ
+
+        await queue.consume(procesar_mensaje)
+```
+
+---
+
+## 3. Kafka — Streaming de Alta Escala
+
+```python
+# pip install aiokafka
+from aiokafka import AIOKafkaProducer, AIOKafkaConsumer
+from aiokafka.errors import KafkaConnectionError
+import asyncio
+import json
+
+class ProductorKafka:
+    """Productor Kafka idempotente con reintentos."""
+
+    def __init__(self, bootstrap_servers: str):
+        self._producer = AIOKafkaProducer(
+            bootstrap_servers=bootstrap_servers,
+            enable_idempotence=True,        # Garantiza exactamente-una-vez
+            max_batch_size=65536,           # 64KB por batch
+            compression_type="gzip",
+            value_serializer=lambda v: json.dumps(v, ensure_ascii=False).encode(),
+            key_serializer=lambda k: k.encode() if k else None,
+        )
+
+    async def __aenter__(self) -> "ProductorKafka":
+        await self._producer.start()
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self._producer.stop()
+
+    async def enviar(
+        self,
+        topico: str,
+        evento: dict,
+        clave: str | None = None,   # Misma clave → mismo partition → orden garantizado
+    ) -> None:
+        await self._producer.send_and_wait(
+            topico,
+            value=evento,
+            key=clave,
+            headers=[
+                ("content-type", b"application/json"),
+                ("event-id", evento.get("id", "").encode()),
+            ],
+        )
+
+class ConsumidorKafka:
+    """Consumidor Kafka con manejo de errores y commit manual."""
+
+    def __init__(self, bootstrap_servers: str, group_id: str, topicos: list[str]):
+        self._consumer = AIOKafkaConsumer(
+            *topicos,
+            bootstrap_servers=bootstrap_servers,
+            group_id=group_id,
+            auto_offset_reset="earliest",
+            enable_auto_commit=False,       # Commit manual después de procesar
+            max_poll_records=100,
+            session_timeout_ms=30000,
+        )
+
+    async def consumir(
+        self,
+        handler: Callable[[dict], Awaitable[None]],
+    ) -> None:
+        await self._consumer.start()
+        try:
+            async for mensaje in self._consumer:
+                try:
+                    datos = json.loads(mensaje.value)
+                    await handler(datos)
+                    await self._consumer.commit()  # Commit SOLO si procesó exitosamente
+                except Exception as e:
+                    logger.error(
+                        "Error en topico=%s partition=%s offset=%s: %s",
+                        mensaje.topic, mensaje.partition, mensaje.offset, e,
+                    )
+                    # Dependiendo de la política: commit igualmente (skip) o no (retry)
+        finally:
+            await self._consumer.stop()
+```
+
+---
+
+## 4. Schemas de Eventos — Contrato entre servicios
+
+```python
+# SIEMPRE definir un schema explícito para cada tipo de evento
+# Los schemas son el contrato entre productor y consumidores
+
+from pydantic import BaseModel, field_validator
+from datetime import datetime
+from typing import Literal
+import uuid
+
+class EventoBase(BaseModel):
+    """Base para todos los eventos del sistema."""
+    id: str = ""
+    timestamp: datetime = None
+    version: str = "1.0"
+    correlation_id: str = ""
+    origen: str                     # Nombre del servicio que genera el evento
+
+    def model_post_init(self, *args):
+        if not self.id:
+            self.id = str(uuid.uuid4())
+        if not self.timestamp:
+            self.timestamp = datetime.now(timezone.utc)
+
+# Evento de dominio: empleado.creado
+class EmpleadoCreadoPayload(BaseModel):
+    empleado_id: str
+    numero_empleado: str
+    nombre_completo: str
+    email_corporativo: str
+    departamento_id: str
+    puesto: str
+    fecha_ingreso: str              # ISO 8601
+
+class EventoEmpleadoCreado(EventoBase):
+    tipo: Literal["empleado.creado"] = "empleado.creado"
+    payload: EmpleadoCreadoPayload
+
+# Versioning de schemas — NUNCA romper compatibilidad hacia atrás
+class EmpleadoCreadoPayloadV2(EmpleadoCreadoPayload):
+    """v2 agrega campos opcionales — compatible con consumidores de v1."""
+    nss: str | None = None          # Nuevo campo opcional
+    curp: str | None = None
+
+class EventoEmpleadoCreadoV2(EventoBase):
+    tipo: Literal["empleado.creado"] = "empleado.creado"
+    version: str = "2.0"
+    payload: EmpleadoCreadoPayloadV2
+```
+
+---
+
+## 5. Idempotency — Procesar exactamente una vez
+
+```python
+import hashlib
+from datetime import datetime, timezone
+
+class RegistroIdempotencia:
+    """Previene procesamiento duplicado de eventos."""
+
+    def __init__(self, redis_client):
+        self._redis = redis_client
+        self._ttl = 86400  # 24 horas
+
+    async def ya_procesado(self, evento_id: str, consumer_id: str) -> bool:
+        clave = f"idempotencia:{consumer_id}:{evento_id}"
+        return bool(await self._redis.exists(clave))
+
+    async def marcar_procesado(self, evento_id: str, consumer_id: str) -> None:
+        clave = f"idempotencia:{consumer_id}:{evento_id}"
+        await self._redis.setex(clave, self._ttl, "1")
+
+# Uso en handler de eventos
+class HandlerNuevaAlta:
+    def __init__(self, repo, idempotencia: RegistroIdempotencia):
+        self._repo = repo
+        self._idempotencia = idempotencia
+
+    async def manejar(self, evento: EventoEmpleadoCreado) -> None:
+        consumer_id = "handler.nueva_alta.configurar_nomina"
+
+        # Verificar idempotencia ANTES de procesar
+        if await self._idempotencia.ya_procesado(evento.id, consumer_id):
+            logger.info("Evento %s ya procesado, ignorando", evento.id)
+            return
+
+        # Procesar el evento
+        await self._repo.configurar_nomina(evento.payload)
+
+        # Marcar como procesado DESPUÉS del procesamiento exitoso
+        await self._idempotencia.marcar_procesado(evento.id, consumer_id)
+```
+
+---
+
+## 6. Retry Strategies — Reintentos con Backoff
+
+```python
+import asyncio
+from datetime import datetime, timezone, timedelta
+
+class PoliticaReintento:
+    """Backoff exponencial con jitter para evitar thundering herd."""
+
+    def __init__(
+        self,
+        max_intentos: int = 5,
+        delay_inicial: float = 1.0,
+        delay_maximo: float = 60.0,
+        multiplicador: float = 2.0,
+    ):
+        self.max_intentos = max_intentos
+        self.delay_inicial = delay_inicial
+        self.delay_maximo = delay_maximo
+        self.multiplicador = multiplicador
+
+    def delay_para_intento(self, intento: int) -> float:
+        """Calcula delay con jitter para evitar reintentos sincronizados."""
+        import random
+        delay = min(
+            self.delay_inicial * (self.multiplicador ** (intento - 1)),
+            self.delay_maximo,
+        )
+        # Jitter: ±25% del delay calculado
+        jitter = delay * 0.25 * (2 * random.random() - 1)
+        return delay + jitter
+
+# Dead Letter Queue — reintentos agotados
+class ProcesadorDLQ:
+    """Procesa mensajes en la Dead Letter Queue para análisis y reintento manual."""
+
+    async def analizar_dlq(self, cola_dlq: str) -> list[dict]:
+        """Obtiene mensajes fallidos para investigación."""
+        mensajes = []
+        async for mensaje in self._consumer.consumir_dlq(cola_dlq):
+            mensajes.append({
+                "id": mensaje.message_id,
+                "timestamp_original": mensaje.headers.get("x-first-death-time"),
+                "motivo_fallo": mensaje.headers.get("x-death")[0]["reason"],
+                "intentos": mensaje.headers.get("x-death")[0]["count"],
+                "cuerpo": json.loads(mensaje.body),
+            })
+        return mensajes
+
+    async def reintentar_mensaje(self, mensaje_id: str) -> None:
+        """Reintento manual después de investigación."""
+        mensaje = await self._obtener_de_dlq(mensaje_id)
+        await self._publicar_a_cola_original(mensaje)
+```
+
+---
+
+## 7. CQRS — Command Query Responsibility Segregation
+
+```python
+# Separar modelos de lectura y escritura
+# Escritura (Commands) → actualiza BD principal → emite evento
+# Lectura (Queries) → consulta vista desnormalizada optimizada para lectura
+
+# COMMAND SIDE
+class ComandoCrearEmpleado(BaseModel):
+    nombre: str
+    apellido_paterno: str
+    apellido_materno: str
+    email: str
+    departamento_id: str
+
+class HandlerComandoCrearEmpleado:
+    async def manejar(
+        self,
+        comando: ComandoCrearEmpleado,
+        db: AsyncSession,
+        broker: BrokerEventos,
+    ) -> str:
+        # Crear en BD normalizada (source of truth)
+        empleado = Empleado(**comando.model_dump())
+        db.add(empleado)
+        await db.flush()
+
+        # Emitir evento ANTES del commit (transactional outbox pattern)
+        evento = EventoEmpleadoCreado(
+            origen="servicio-empleados",
+            payload=EmpleadoCreadoPayload(
+                empleado_id=str(empleado.id),
+                nombre_completo=f"{comando.nombre} {comando.apellido_paterno}",
+                email_corporativo=comando.email,
+                departamento_id=comando.departamento_id,
+                numero_empleado=empleado.numero_empleado,
+                puesto=empleado.puesto,
+                fecha_ingreso=empleado.fecha_ingreso.isoformat(),
+            ),
+        )
+        await broker.publicar(evento)
+        await db.commit()
+        return str(empleado.id)
+
+# QUERY SIDE — Vista desnormalizada actualizada por eventos
+class VistaEmpleado(Base):
+    """Tabla de lectura: desnormalizada para queries de UI."""
+    __tablename__ = "vista_empleados"
+    id = Column(UUID, primary_key=True)
+    nombre_completo = Column(String)
+    email = Column(String)
+    departamento_nombre = Column(String)    # Desnormalizado — no requiere JOIN
+    puesto = Column(String)
+    activo = Column(Boolean, default=True)
+    ultima_actualizacion = Column(DateTime)
+
+class ActualizadorVistaEmpleados:
+    """Consumidor de eventos que mantiene la vista actualizada."""
+
+    async def en_empleado_creado(self, evento: EventoEmpleadoCreado) -> None:
+        departamento = await self._repo.obtener_departamento(
+            evento.payload.departamento_id
+        )
+        vista = VistaEmpleado(
+            id=uuid.UUID(evento.payload.empleado_id),
+            nombre_completo=evento.payload.nombre_completo,
+            email=evento.payload.email_corporativo,
+            departamento_nombre=departamento.nombre,
+            puesto=evento.payload.puesto,
+            ultima_actualizacion=evento.timestamp,
+        )
+        await self._db.merge(vista)
+        await self._db.commit()
+```
+
+---
+
+## 8. Transactional Outbox Pattern
+
+```python
+# Problema: publicar evento Y hacer commit en BD de forma atómica
+# Solución: escribir evento a tabla "outbox" en misma transacción,
+#           un worker asíncrono publica al broker
+
+class EventoOutbox(Base):
+    """Tabla de outbox para publicación garantizada de eventos."""
+    __tablename__ = "eventos_outbox"
+    id = Column(UUID, primary_key=True, default=uuid.uuid4)
+    tipo = Column(String(100), nullable=False)
+    payload = Column(JSONB, nullable=False)
+    exchange = Column(String(100), nullable=False)
+    routing_key = Column(String(100), nullable=False)
+    creado_en = Column(DateTime(timezone=True), server_default=func.now())
+    publicado_en = Column(DateTime(timezone=True), nullable=True)
+    intentos = Column(Integer, default=0)
+
+async def crear_empleado_con_outbox(
+    comando: ComandoCrearEmpleado,
+    db: AsyncSession,
+) -> str:
+    """Crea empleado y registra evento en outbox — todo en una transacción."""
+    empleado = Empleado(**comando.model_dump())
+    db.add(empleado)
+    await db.flush()
+
+    # Mismo commit = garantía de consistencia
+    evento_outbox = EventoOutbox(
+        tipo="empleado.creado",
+        payload={...},
+        exchange="eventos.rrhh",
+        routing_key="empleado.creado",
+    )
+    db.add(evento_outbox)
+    await db.commit()   # Atómico: empleado + evento en outbox
+
+    return str(empleado.id)
+
+# Worker que publica desde outbox al broker
+async def worker_outbox(db: AsyncSession, broker: BrokerEventos) -> None:
+    """Ejecuta cada 5 segundos, publica eventos pendientes."""
+    while True:
+        eventos = await db.execute(
+            select(EventoOutbox)
+            .where(EventoOutbox.publicado_en.is_(None))
+            .where(EventoOutbox.intentos < 5)
+            .order_by(EventoOutbox.creado_en)
+            .limit(100)
+            .with_for_update(skip_locked=True)  # Para múltiples workers
+        )
+        for evento in eventos.scalars():
+            try:
+                await broker.publicar_raw(
+                    tipo=evento.tipo,
+                    payload=evento.payload,
+                    exchange=evento.exchange,
+                    routing_key=evento.routing_key,
+                )
+                evento.publicado_en = datetime.now(timezone.utc)
+            except Exception as e:
+                evento.intentos += 1
+                logger.error("Error publicando evento %s: %s", evento.id, e)
+        await db.commit()
+        await asyncio.sleep(5)
+```
+
+---
+
+## 9. Eventual Consistency — Manejo en UI
+
+```python
+# El frontend debe manejar que los datos pueden no estar actualizados inmediatamente
+
+# Backend: responder con estado "aceptado" (202 Accepted)
+@router.post("/empleados", status_code=202)
+async def crear_empleado(comando: ComandoCrearEmpleado, ...):
+    empleado_id = await handler.manejar(comando, db, broker)
+    return {
+        "empleado_id": empleado_id,
+        "estado": "procesando",
+        "mensaje": "El empleado está siendo procesado. Estará disponible en segundos.",
+        "consultar_en": f"/empleados/{empleado_id}/estado",
+    }
+
+# Polling endpoint para que el frontend verifique
+@router.get("/empleados/{id}/estado")
+async def estado_empleado(id: UUID, db: AsyncSession = Depends(get_db)):
+    vista = await db.get(VistaEmpleado, id)
+    if vista is None:
+        return {"estado": "procesando"}
+    return {"estado": "completado", "datos": vista}
+```
+
+---
+
+## 10. Checklist de Sistema Event-Driven
+
+- [ ] Schemas de eventos definidos con Pydantic (tipado fuerte)
+- [ ] Versioning en schemas (campo `version: "1.0"`)
+- [ ] Idempotency implementada en todos los handlers
+- [ ] Dead Letter Queue configurada para cada cola
+- [ ] Retry con backoff exponencial y jitter
+- [ ] Correlation ID propagado en todos los eventos
+- [ ] Transactional Outbox para garantía de publicación
+- [ ] Monitoring de DLQ (alertas cuando hay mensajes ahí)
+- [ ] Tests de integración con broker real (no mocks)
+- [ ] Documentación de todos los tipos de eventos (event catalog)
+- [ ] Schemas backward-compatible (cambios aditivos únicamente)
+- [ ] Consumer group names descriptivos y estables