chatops-sdk 1.0.0__py3-none-any.whl

chatops_sdk/__init__.py

@@ -0,0 +1,91 @@
+"""chatops-sdk: convierte cualquier app Python en un bot controlable desde el Control Center."""
+
+from .agent import BOT_TOKEN_ENV, HUB_URL_ENV, BotAgent, BotConfigurationError, backoff_delay
+from .decorators import (
+    CommandArgumentsError,
+    CommandContext,
+    CommandDefinitionError,
+    CommandRegistry,
+    CommandResult,
+    RegisteredCommand,
+    build_command,
+    execute_command,
+    normalize_blocks,
+)
+from .models import (
+    ActionButton,
+    ActionsBlock,
+    AnyEnvelope,
+    AnyUIBlock,
+    BotDeletedEnvelope,
+    BotMessageEnvelope,
+    BotPresenceChangedEnvelope,
+    BotPresencePayload,
+    BotRegisterEnvelope,
+    BotRegisterPayload,
+    CodeLogBlock,
+    CommandArgSchema,
+    CommandInvokeEnvelope,
+    CommandInvokePayload,
+    CommandManifest,
+    CommandSchema,
+    HeaderBlock,
+    MarkdownBlock,
+    MessageAckEnvelope,
+    MetricItem,
+    MetricsBlock,
+    ProgressBlock,
+    TableBlock,
+    UIBlockBase,
+    parse_block,
+    parse_envelope,
+)
+from .ui import BlockList, UIBlock
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "BOT_TOKEN_ENV",
+    "HUB_URL_ENV",
+    "ActionButton",
+    "ActionsBlock",
+    "AnyEnvelope",
+    "AnyUIBlock",
+    "BlockList",
+    "BotAgent",
+    "BotConfigurationError",
+    "BotDeletedEnvelope",
+    "BotMessageEnvelope",
+    "BotPresenceChangedEnvelope",
+    "BotPresencePayload",
+    "BotRegisterEnvelope",
+    "BotRegisterPayload",
+    "CodeLogBlock",
+    "CommandArgSchema",
+    "CommandArgumentsError",
+    "CommandContext",
+    "CommandDefinitionError",
+    "CommandInvokeEnvelope",
+    "CommandInvokePayload",
+    "CommandManifest",
+    "CommandRegistry",
+    "CommandResult",
+    "CommandSchema",
+    "HeaderBlock",
+    "MarkdownBlock",
+    "MessageAckEnvelope",
+    "MetricItem",
+    "MetricsBlock",
+    "ProgressBlock",
+    "RegisteredCommand",
+    "TableBlock",
+    "UIBlock",
+    "UIBlockBase",
+    "__version__",
+    "backoff_delay",
+    "build_command",
+    "execute_command",
+    "normalize_blocks",
+    "parse_block",
+    "parse_envelope",
+]

chatops_sdk/agent.py

@@ -0,0 +1,461 @@
+"""``BotAgent``: conexión WebSocket saliente al Relay Hub con reconexión automática.
+
+Ejemplo mínimo con FastAPI::
+
+    from fastapi import FastAPI
+    from chatops_sdk import BotAgent, UIBlock
+
+    bot = BotAgent(name="Mi-Bot")
+
+    @bot.command(name="ping", description="Comprueba que el bot responde")
+    async def ping():
+        return UIBlock.header("🏓 pong")
+
+    app = FastAPI(lifespan=bot.lifespan)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+from collections import deque
+from collections.abc import AsyncIterator, Callable, Sequence
+from contextlib import asynccontextmanager
+from typing import Any, Literal
+
+from pydantic import ValidationError
+from websockets.asyncio.client import ClientConnection, connect
+from websockets.exceptions import ConnectionClosed, InvalidStatus
+
+from .decorators import CommandRegistry, RegisteredCommand, execute_command, normalize_blocks
+from .models import (
+    ACCESS_DENIED_CLOSE_CODES,
+    WS_CLOSE_BOT_DELETED,
+    WS_CLOSE_BOT_DISABLED,
+    WS_CLOSE_TOKEN_INVALID,
+    BotMessageEnvelope,
+    BotRegisterEnvelope,
+    BotRegisterPayload,
+    CommandInvokeEnvelope,
+    CommandSchema,
+    UIBlockBase,
+)
+from .ui import BlockList, UIBlock
+
+HUB_URL_ENV = "CHATOPS_HUB_URL"
+BOT_TOKEN_ENV = "CHATOPS_BOT_TOKEN"
+
+RECONNECT_INITIAL_DELAY = 1.0
+RECONNECT_MAX_DELAY = 30.0
+#: Backoff extendido cuando el Hub deniega el acceso (token inválido/rotado o bot
+#: deshabilitado): reintentar cada segundo no arregla nada y solo genera ruido.
+ACCESS_DENIED_INITIAL_DELAY = 30.0
+ACCESS_DENIED_MAX_DELAY = 300.0
+#: Margen tras enviar BOT_REGISTER para detectar un cierre inmediato del Hub.
+REGISTER_GRACE_SECONDS = 0.15
+
+_ACCESS_DENIED_REASONS = {
+    WS_CLOSE_TOKEN_INVALID: "el token es inválido o ha sido rotado",
+    WS_CLOSE_BOT_DISABLED: "el bot está deshabilitado (pausado) en el Hub",
+    WS_CLOSE_BOT_DELETED: "el bot ha sido eliminado del Hub",
+}
+
+
+class BotConfigurationError(RuntimeError):
+    """Falta la URL del Hub o el token del bot."""
+
+
+def backoff_delay(
+    attempt: int,
+    initial: float = RECONNECT_INITIAL_DELAY,
+    maximum: float = RECONNECT_MAX_DELAY,
+) -> float:
+    """Exponential backoff: 1s, 2s, 4s, ... con tope en ``maximum`` (30s)."""
+    if attempt < 0:
+        attempt = 0
+    # El exponente se acota para no desbordar con muchos reintentos.
+    return float(min(maximum, initial * (2 ** min(attempt, 32))))
+
+
+class BotAgent:
+    """Agente que registra el bot en el Hub, atiende comandos y emite alertas."""
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        version: str = "1.0.0",
+        environment: str = "production",
+        project: str = "",
+        hub_url: str | None = None,
+        token: str | None = None,
+        reconnect_initial_delay: float = RECONNECT_INITIAL_DELAY,
+        reconnect_max_delay: float = RECONNECT_MAX_DELAY,
+        access_denied_initial_delay: float = ACCESS_DENIED_INITIAL_DELAY,
+        access_denied_max_delay: float = ACCESS_DENIED_MAX_DELAY,
+        register_grace: float = REGISTER_GRACE_SECONDS,
+        open_timeout: float = 10.0,
+        outbox_size: int = 200,
+        logger: logging.Logger | None = None,
+    ) -> None:
+        self.name = name
+        self.version = version
+        self.environment = environment
+        self.project = project
+        self._hub_url = hub_url
+        self._token = token
+        self.reconnect_initial_delay = reconnect_initial_delay
+        self.reconnect_max_delay = reconnect_max_delay
+        self.access_denied_initial_delay = access_denied_initial_delay
+        self.access_denied_max_delay = access_denied_max_delay
+        self.register_grace = register_grace
+        self.open_timeout = open_timeout
+        self.log = logger or logging.getLogger(f"chatops_sdk.{name}")
+
+        self.registry = CommandRegistry()
+        self._ws: ClientConnection | None = None
+        self._task: asyncio.Task[None] | None = None
+        self._command_tasks: set[asyncio.Task[None]] = set()
+        self._stopped = asyncio.Event()
+        self._connected = asyncio.Event()
+        self._send_lock = asyncio.Lock()
+        # Mensajes finales y alertas emitidos sin conexión: se envían al reconectar.
+        self._outbox: deque[BotMessageEnvelope] = deque(maxlen=outbox_size)
+        self.connection_attempts = 0
+        #: Veces seguidas que el Hub ha denegado el acceso (se reinicia al conectar).
+        self.access_denied_count = 0
+        #: Código de cierre WebSocket de la última conexión, si lo hubo.
+        self.last_close_code: int | None = None
+
+    # ------------------------------------------------------------------ #
+    # Configuración
+    # ------------------------------------------------------------------ #
+
+    @property
+    def hub_url(self) -> str | None:
+        """URL del endpoint ``/ws/bot``; por defecto ``CHATOPS_HUB_URL``."""
+        return self._hub_url or os.environ.get(HUB_URL_ENV) or None
+
+    @property
+    def token(self) -> str | None:
+        """Token ``bot_<id>:<secret>``; por defecto ``CHATOPS_BOT_TOKEN``."""
+        return self._token or os.environ.get(BOT_TOKEN_ENV) or None
+
+    @property
+    def bot_id(self) -> str | None:
+        """``bot_id`` derivado del token (la parte anterior a ``:``)."""
+        token = self.token
+        if not token or ":" not in token:
+            return None
+        return token.split(":", 1)[0]
+
+    @property
+    def is_connected(self) -> bool:
+        return self._connected.is_set()
+
+    @property
+    def is_running(self) -> bool:
+        return self._task is not None and not self._task.done()
+
+    # ------------------------------------------------------------------ #
+    # Registro de comandos
+    # ------------------------------------------------------------------ #
+
+    def command(
+        self,
+        name: str | Callable[..., Any] | None = None,
+        description: str | None = None,
+    ) -> Any:
+        """Decorador ``@bot.command(name="...", description="...")``."""
+        return self.registry.command(name, description)
+
+    def add_command(
+        self,
+        func: Callable[..., Any],
+        name: str | None = None,
+        description: str | None = None,
+    ) -> RegisteredCommand:
+        """Registro imperativo equivalente al decorador."""
+        return self.registry.register(func, name=name, description=description)
+
+    @property
+    def manifest(self) -> list[CommandSchema]:
+        return self.registry.manifest()
+
+    def build_register_envelope(self) -> BotRegisterEnvelope:
+        return BotRegisterEnvelope(
+            payload=BotRegisterPayload(
+                bot_name=self.name,
+                version=self.version,
+                environment=self.environment,
+                project=self.project,
+                commands=self.manifest,
+            )
+        )
+
+    # ------------------------------------------------------------------ #
+    # Ciclo de vida
+    # ------------------------------------------------------------------ #
+
+    async def start_background(self) -> asyncio.Task[None]:
+        """Lanza el bucle de conexión como ``asyncio.Task`` y vuelve de inmediato."""
+        if self.is_running:
+            assert self._task is not None
+            return self._task
+        if not self.hub_url:
+            raise BotConfigurationError(
+                f"Falta la URL del Hub: pásala como hub_url o define {HUB_URL_ENV}"
+            )
+        if not self.token:
+            raise BotConfigurationError(
+                f"Falta el token del bot: pásalo como token o define {BOT_TOKEN_ENV}"
+            )
+        self._stopped.clear()
+        self._task = asyncio.create_task(self.run_forever(), name=f"chatops-bot-{self.name}")
+        return self._task
+
+    async def stop(self) -> None:
+        """Detiene el bucle, cierra el socket y cancela comandos en curso."""
+        self._stopped.set()
+        ws = self._ws
+        if ws is not None:
+            try:
+                await ws.close()
+            except Exception:  # noqa: BLE001 - el cierre es best-effort
+                self.log.debug("Error cerrando el WebSocket", exc_info=True)
+
+        pending = [task for task in self._command_tasks if not task.done()]
+        for task in pending:
+            task.cancel()
+        if pending:
+            await asyncio.gather(*pending, return_exceptions=True)
+
+        task, self._task = self._task, None
+        if task is not None:
+            if not task.done():
+                task.cancel()
+            await asyncio.gather(task, return_exceptions=True)
+        self._connected.clear()
+
+    @asynccontextmanager
+    async def lifespan(self, app: Any = None) -> AsyncIterator[None]:
+        """Lifespan listo para FastAPI: ``FastAPI(lifespan=bot.lifespan)``."""
+        await self.start_background()
+        try:
+            yield
+        finally:
+            await self.stop()
+
+    async def wait_until_connected(self, timeout: float | None = None) -> bool:
+        """Espera a que el bot esté registrado en el Hub. ``False`` si vence el timeout."""
+        try:
+            await asyncio.wait_for(self._connected.wait(), timeout)
+        except asyncio.TimeoutError:
+            return False
+        return True
+
+    async def run_forever(self) -> None:
+        """Bucle ``while not stopped``: conecta, registra, escucha y reconecta con backoff.
+
+        Las caídas normales se reintentan con backoff exponencial (1s, 2s, 4s… máx. 30s).
+        Si el Hub deniega el acceso (cierre ``4001`` token inválido/rotado, ``4003`` bot
+        deshabilitado, o rechazo HTTP 401/403 del handshake) se registra un log CRITICAL
+        y se aplica un backoff extendido: el bot volverá solo cuando lo rehabiliten.
+        """
+        attempt = 0
+        while not self._stopped.is_set():
+            hub_url, token = self.hub_url, self.token
+            if not hub_url or not token:
+                raise BotConfigurationError("El bot no tiene hub_url o token configurados")
+            self.connection_attempts += 1
+            close_code: int | None = None
+            denied = False
+            try:
+                async with connect(
+                    hub_url,
+                    additional_headers={"Authorization": f"Bearer {token}"},
+                    open_timeout=self.open_timeout,
+                ) as ws:
+                    await ws.send(self.build_register_envelope().model_dump_json())
+                    if await self._closed_right_after_register(ws):
+                        close_code = ws.close_code
+                    else:
+                        self._ws = ws
+                        self._connected.set()
+                        attempt = 0
+                        self.access_denied_count = 0
+                        self.log.info("Bot '%s' registrado en el Hub %s", self.name, hub_url)
+                        await self._flush_outbox()
+                        async for raw in ws:
+                            self._on_frame(raw)
+                        close_code = ws.close_code
+            except asyncio.CancelledError:
+                raise
+            except InvalidStatus as exc:
+                status = exc.response.status_code
+                denied = status in (401, 403)
+                if not denied:
+                    self.log.error("El Hub rechazó la conexión (HTTP %s)", status)
+            except ConnectionClosed as exc:
+                close_code = exc.rcvd.code if exc.rcvd is not None else None
+                if close_code not in ACCESS_DENIED_CLOSE_CODES:
+                    self.log.warning("Conexión con el Hub cerrada: %s", exc)
+            except (OSError, asyncio.TimeoutError) as exc:
+                self.log.warning("No se pudo conectar al Hub %s: %s", hub_url, exc)
+            except Exception:  # noqa: BLE001 - el bucle debe sobrevivir a cualquier fallo
+                self.log.exception("Error inesperado en la conexión con el Hub")
+            finally:
+                self._ws = None
+                self._connected.clear()
+
+            self.last_close_code = close_code
+            if self._stopped.is_set():
+                break
+
+            if denied or close_code in ACCESS_DENIED_CLOSE_CODES:
+                reason = _ACCESS_DENIED_REASONS.get(
+                    close_code or 0, "el Hub rechazó las credenciales"
+                )
+                delay = backoff_delay(
+                    self.access_denied_count,
+                    self.access_denied_initial_delay,
+                    self.access_denied_max_delay,
+                )
+                self.access_denied_count += 1
+                self.log.critical(
+                    "CRITICAL: Bot token invalid or bot disabled in Hub (%s; código %s). "
+                    "Revisa %s o el estado del bot en el Control Center. Reintento en %.0fs",
+                    reason,
+                    close_code if close_code is not None else "HTTP 401/403",
+                    BOT_TOKEN_ENV,
+                    delay,
+                )
+            else:
+                delay = backoff_delay(
+                    attempt, self.reconnect_initial_delay, self.reconnect_max_delay
+                )
+                attempt += 1
+                self.log.info("Reintentando conexión en %.1fs", delay)
+            try:
+                await asyncio.wait_for(self._stopped.wait(), timeout=delay)
+            except asyncio.TimeoutError:
+                pass
+
+    async def _closed_right_after_register(self, ws: ClientConnection) -> bool:
+        """``True`` si el Hub cierra el socket nada más abrirlo.
+
+        El Hub deniega el acceso aceptando el WebSocket y cerrándolo con un código
+        (4001/4003). Como el protocolo no tiene acuse de BOT_REGISTER, se espera un
+        instante antes de dar el bot por conectado.
+        """
+        if self.register_grace <= 0:
+            return False
+        try:
+            await asyncio.wait_for(ws.wait_closed(), timeout=self.register_grace)
+        except asyncio.TimeoutError:
+            return False
+        return True
+
+    # ------------------------------------------------------------------ #
+    # Envío
+    # ------------------------------------------------------------------ #
+
+    async def send_bot_message(self, message: BotMessageEnvelope) -> bool:
+        """Envía un ``BOT_MESSAGE``. Devuelve ``True`` si salió por el socket.
+
+        Sin conexión, los mensajes finales (``COMPLETED``/``ERROR``) y las alertas
+        se encolan y se entregan al reconectar; el progreso intermedio se descarta.
+        """
+        if message.source_bot_id is None:
+            message.source_bot_id = self.bot_id
+        ws = self._ws
+        if ws is not None:
+            try:
+                async with self._send_lock:
+                    await ws.send(message.model_dump_json())
+                return True
+            except ConnectionClosed:
+                self.log.debug("Socket cerrado al enviar %s", message.message_id)
+        if message.is_final:
+            self._outbox.append(message)
+        return False
+
+    async def _flush_outbox(self) -> None:
+        while self._outbox and self._ws is not None:
+            message = self._outbox.popleft()
+            try:
+                async with self._send_lock:
+                    await self._ws.send(message.model_dump_json())
+            except ConnectionClosed:
+                self._outbox.appendleft(message)
+                raise
+
+    async def send_alert(
+        self,
+        severity: Literal["info", "warning", "critical"],
+        title: str,
+        message: str,
+        blocks: Sequence[UIBlockBase] | BlockList | None = None,
+    ) -> BotMessageEnvelope:
+        """Envía una alerta proactiva: ``BOT_MESSAGE`` sin ``correlation_id``."""
+        envelope = BotMessageEnvelope(
+            correlation_id=None,
+            source_bot_id=self.bot_id,
+            status="COMPLETED",
+            severity=severity,
+            blocks=[
+                UIBlock.header(title),
+                UIBlock.markdown(message),
+                *normalize_blocks(blocks),
+            ],
+        )
+        await self.send_bot_message(envelope)
+        return envelope
+
+    # ------------------------------------------------------------------ #
+    # Recepción y ejecución de comandos
+    # ------------------------------------------------------------------ #
+
+    def _on_frame(self, raw: str | bytes) -> None:
+        try:
+            data = json.loads(raw)
+        except (TypeError, ValueError):
+            self.log.warning("Trama no JSON recibida del Hub; se ignora")
+            return
+        if not isinstance(data, dict):
+            self.log.warning("Trama inesperada recibida del Hub; se ignora")
+            return
+        frame_type = data.get("type")
+        if frame_type != "COMMAND_INVOKE":
+            self.log.debug("Trama '%s' ignorada por el bot", frame_type)
+            return
+        try:
+            envelope = CommandInvokeEnvelope.model_validate(data)
+        except ValidationError as exc:
+            self.log.warning("COMMAND_INVOKE inválido: %s", exc)
+            return
+        # Cada comando corre en su propia tarea para no bloquear la recepción.
+        task = asyncio.create_task(
+            self._process_invoke(envelope), name=f"chatops-cmd-{envelope.payload.command}"
+        )
+        self._command_tasks.add(task)
+        task.add_done_callback(self._command_tasks.discard)
+
+    async def _process_invoke(self, envelope: CommandInvokeEnvelope) -> None:
+        message = await self.handle_invoke(envelope)
+        await self.send_bot_message(message)
+
+    async def handle_invoke(self, envelope: CommandInvokeEnvelope) -> BotMessageEnvelope:
+        """Valida argumentos, ejecuta el comando y devuelve el ``BOT_MESSAGE`` final."""
+        return await execute_command(self.registry, envelope, self, bot_id=self.bot_id)
+
+
+__all__ = [
+    "BOT_TOKEN_ENV",
+    "HUB_URL_ENV",
+    "BotAgent",
+    "BotConfigurationError",
+    "backoff_delay",
+]