machinaos 0.0.76 → 0.0.78

package/server/services/plugin/registry.py

@@ -0,0 +1,145 @@
+"""Idempotent plugin registries.
+
+Single generic base for all the ``register_*`` plumbing that plugin
+``__init__.py`` files call into. Replaces five hand-rolled
+implementations with the same shape.
+
+Two flavours:
+
+- :class:`IdempotentRegistry` -- key->value mapping with collision
+  detection. Used for WS handlers, FastAPI routers, filter builders,
+  trigger prechecks, output schemas. Re-registering the same value for
+  a key is a no-op (re-import safe); a different value raises
+  ``ValueError`` so plugin namespace clashes fail at import time.
+
+- :class:`IdempotentList` -- fanout list with identity dedup. Used for
+  per-cycle callbacks like ``register_service_refresh`` where every
+  registered callable runs once per cycle. Re-registering the same
+  callable is a no-op; different callables coexist (fanout semantics).
+
+Each module that exposes a ``register_*`` public API constructs one of
+these and provides a thin wrapper. Module-level dicts that other code
+reads directly (e.g. ``FILTER_BUILDERS``, ``NODE_OUTPUT_SCHEMAS``) can
+be passed in as the backing store via the ``items`` kwarg, so existing
+readers keep working.
+"""
+
+from __future__ import annotations
+
+from types import MappingProxyType
+from typing import (
+    Callable,
+    Dict,
+    Generic,
+    Iterator,
+    List,
+    Mapping,
+    Optional,
+    TypeVar,
+)
+
+K = TypeVar("K")
+V = TypeVar("V")
+
+
+def _qual(value: object) -> str:
+    """Best-effort qualified name for callable / class -- used in error messages."""
+    module = getattr(value, "__module__", None)
+    qualname = getattr(value, "__qualname__", None)
+    if module and qualname:
+        return f"{module}.{qualname}"
+    return repr(value)
+
+
+class IdempotentRegistry(Generic[K, V]):
+    """Key->value registry with idempotent register + collision raise.
+
+    Args:
+        name: Human-readable label used in error messages
+            (``f"{name}: '{key}' already registered..."``).
+        items: Optional pre-existing dict to use as the backing store.
+            Lets a module expose its registry-backed dict as a
+            module-level constant for readers that grew up reading the
+            dict directly.
+        on_register: Optional callback fired after a successful
+            register. Used e.g. by ``register_output_schema`` to bust a
+            JSON-schema cache.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        items: Optional[Dict[K, V]] = None,
+        on_register: Optional[Callable[[K, V], None]] = None,
+    ) -> None:
+        self._name = name
+        self._items: Dict[K, V] = items if items is not None else {}
+        self._on_register = on_register
+
+    def register(self, key: K, value: V) -> None:
+        """Add ``key -> value``. Idempotent on identity; raises on conflict."""
+        existing = self._items.get(key)
+        if existing is not None and existing is not value:
+            raise ValueError(
+                f"{self._name}: {key!r} is already registered by "
+                f"{_qual(existing)}; refusing to overwrite with {_qual(value)}"
+            )
+        self._items[key] = value
+        if self._on_register is not None:
+            self._on_register(key, value)
+
+    def get(self, key: K) -> Optional[V]:
+        return self._items.get(key)
+
+    def items(self) -> Mapping[K, V]:
+        """Read-only view. Use ``dict(reg.items())`` for a mutable copy."""
+        return MappingProxyType(self._items)
+
+    def keys(self) -> List[K]:
+        return list(self._items.keys())
+
+    def values(self) -> List[V]:
+        return list(self._items.values())
+
+    def __contains__(self, key: object) -> bool:
+        return key in self._items
+
+    def __len__(self) -> int:
+        return len(self._items)
+
+    def __iter__(self) -> Iterator[K]:
+        return iter(self._items)
+
+
+class IdempotentList(Generic[V]):
+    """Fanout list with identity dedup.
+
+    Args:
+        name: Human-readable label (used in repr / future logging).
+        items: Optional pre-existing list to use as the backing store.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        items: Optional[List[V]] = None,
+    ) -> None:
+        self._name = name
+        self._items: List[V] = items if items is not None else []
+
+    def register(self, value: V) -> None:
+        """Append if not already present (identity dedup)."""
+        if value in self._items:
+            return
+        self._items.append(value)
+
+    def __iter__(self) -> Iterator[V]:
+        return iter(self._items)
+
+    def __len__(self) -> int:
+        return len(self._items)
+
+    def __contains__(self, value: object) -> bool:
+        return value in self._items

package/server/services/plugin/singleton.py

@@ -0,0 +1,65 @@
+"""Service-singleton mixin for plugin-owned long-lived services.
+
+Replaces the per-plugin ``_instance`` + ``get_instance()`` boilerplate
+that each ``nodes/<plugin>/_service.py`` currently re-implements.
+Pre-T inventory (Wave 11.I plan):
+
+- ``nodes/telegram/_service.py:TelegramService`` -- ``_instance`` + sync
+  ``get_instance`` + async ``reset_instance`` (custom — disconnects).
+- ``nodes/email/_service.py:EmailService`` -- ``_instance`` + sync
+  ``get_instance``, no reset.
+- ``nodes/browser/_service.py`` -- module-level ``_instance`` global,
+  no class-level state (different shape, kept bespoke).
+- ``nodes/whatsapp/_service.py`` -- supervisor-aware singleton via
+  ``BaseProcessSupervisor``, kept bespoke (different lifecycle).
+
+Subclasses get :meth:`instance` for free. They override
+:meth:`reset_instance` only if there's a side effect on reset
+(Telegram disconnects the bot poll loop; that stays per-plugin).
+"""
+
+from __future__ import annotations
+
+from typing import ClassVar, Optional, TypeVar
+
+T = TypeVar("T", bound="ServiceSingleton")
+
+
+class ServiceSingleton:
+    """Mixin: per-class lazy singleton.
+
+    Each subclass that opts in gets its own ``_instance`` slot lazily
+    populated on first :meth:`instance` call. The Python attribute
+    rules guarantee per-class isolation (read climbs MRO, write goes
+    to the immediate class), so ``A.instance()`` and ``B.instance()``
+    return distinct singletons even though both inherit the same
+    declaration here.
+
+    Usage::
+
+        class TelegramService(ServiceSingleton):
+            ...
+
+        # module-level helper consumed by handler files:
+        def get_telegram_service() -> TelegramService:
+            return TelegramService.instance()
+
+    Subclasses may also override :meth:`reset_instance` to add side
+    effects (e.g. tear down a bot polling loop) before clearing.
+    """
+
+    _instance: ClassVar[Optional["ServiceSingleton"]] = None
+
+    @classmethod
+    def instance(cls: type[T]) -> T:
+        """Return the per-class singleton, constructing it on first call."""
+        if cls.__dict__.get("_instance") is None:
+            cls._instance = cls()
+        return cls._instance  # type: ignore[return-value]
+
+    @classmethod
+    def reset_instance(cls) -> None:
+        """Drop the cached singleton. Override for async / cleanup
+        flows; the default is a sync no-side-effect clear."""
+        if cls.__dict__.get("_instance") is not None:
+            cls._instance = None

package/server/services/plugin/ws.py

@@ -0,0 +1,81 @@
+"""WebSocket handler helpers (Wave 11.I, milestone T-residual).
+
+Single helper today: :func:`ws_response`, an opt-in decorator that
+collapses the duplicated ``try / except / return {success: False,
+error: str(e)}`` block at the bottom of every plugin WS handler.
+
+Audited 79 instances of this exact pattern across ``nodes/<plugin>/``
+in the pre-T-residual codebase. The decorator is **opt-in** because
+not every handler returns the ``{success: bool}`` envelope -- OAuth
+lifecycle handlers built by
+:mod:`services.events.oauth_lifecycle` return ``{connected: bool}``,
+auto-wrapping would clobber that. Plugin authors decorate per-handler.
+
+Honors the :class:`services.plugin.base.NodeUserError` contract: when
+a handler raises ``NodeUserError`` (user-correctable failure -- bad
+input, unknown enum value, missing required field), the wrapper logs
+at WARN without a traceback. Genuinely unexpected exceptions log at
+ERROR with full traceback via ``logger.exception``.
+"""
+
+from __future__ import annotations
+
+from functools import wraps
+from typing import Any, Awaitable, Callable, Dict
+
+from fastapi import WebSocket
+
+from core.logging import get_logger
+from services.plugin.base import NodeUserError
+
+logger = get_logger(__name__)
+
+WSHandlerFn = Callable[[Dict[str, Any], WebSocket], Awaitable[Dict[str, Any]]]
+
+
+def ws_response(handler: WSHandlerFn) -> WSHandlerFn:
+    """Wrap a WS handler to convert exceptions into a ``{success: False,
+    error: ...}`` envelope.
+
+    Successful return values pass through untouched -- the wrapper
+    only intervenes on exceptions. Extra fields the handler adds to
+    the success envelope (``connected``, ``message``, ``result``, ...)
+    are preserved.
+
+    Two log levels:
+
+    * :class:`NodeUserError` -> WARN, no traceback. Reason: these are
+      expected and user-correctable; a stack trace just clutters the
+      operator log without adding signal.
+    * Anything else -> ERROR via ``logger.exception`` (full traceback).
+      Reason: it's a server bug, the trace is the diagnostic.
+
+    Usage::
+
+        from services.plugin.ws import ws_response
+
+        @ws_response
+        async def handle_thing(data, websocket):
+            ...
+            return {"success": True, "result": ...}
+    """
+
+    handler_name = getattr(handler, "__name__", repr(handler))
+
+    @wraps(handler)
+    async def wrapper(
+        data: Dict[str, Any], websocket: WebSocket,
+    ) -> Dict[str, Any]:
+        try:
+            return await handler(data, websocket)
+        except NodeUserError as exc:
+            logger.warning(f"[{handler_name}] {type(exc).__name__}: {exc}")
+            return {"success": False, "error": str(exc)}
+        except Exception as exc:  # noqa: BLE001 -- surface as envelope
+            logger.exception(f"[{handler_name}] unexpected error")
+            return {"success": False, "error": str(exc)}
+
+    return wrapper
+
+
+__all__ = ["ws_response"]

package/server/services/process_service.py

@@ -16,7 +16,7 @@ import shutil
 from dataclasses import dataclass, field
 from datetime import datetime
 from pathlib import Path
-from typing import Any, Dict, List, Optional
+from typing import Any, Awaitable, Callable, Dict, List, Optional
 
 from core.logging import get_logger
 from services._supervisor.util import kill_tree
@@ -26,6 +26,10 @@ logger = get_logger(__name__)
 MAX_PROCESSES = 10  # Default limit, configurable via Settings panel
 
 
+# (stream_name, line) -> awaitable. Invoked once per decoded stdout/stderr line.
+LineHandler = Callable[[str, str], Awaitable[None]]
+
+
 @dataclass
 class ManagedProcess:
     name: str
@@ -43,6 +47,11 @@ class ManagedProcess:
     exit_code: Optional[int] = None
     stdout_lines: int = 0
     stderr_lines: int = 0
+    # Optional per-line callback: framework-level subscribers (e.g. the
+    # generalised event source `DaemonEventSource`) install this to ingest
+    # the daemon's stdout/stderr without re-tailing the log files we already
+    # write for the Terminal tab.
+    line_handler: Optional[LineHandler] = None
 
 
 class ProcessService:
@@ -70,8 +79,17 @@ class ProcessService:
         command: str,
         workflow_id: str = "default",
         working_directory: str = "",
+        *,
+        line_handler: Optional[LineHandler] = None,
     ) -> Dict[str, Any]:
-        """Start a long-running process."""
+        """Start a long-running process.
+
+        ``line_handler``: optional ``async (stream_name, line) -> None``
+        callback invoked for every decoded stdout/stderr line, AFTER the
+        line has been written to the log file and broadcast to the
+        Terminal tab. Used by ``DaemonEventSource`` to parse subprocess
+        output into typed events without re-tailing the log files.
+        """
         if not command:
             return {"success": False, "error": "command is required"}
 
@@ -170,6 +188,7 @@ class ProcessService:
             working_directory=cwd,
             process=proc,
             log_dir=log_dir,
+            line_handler=line_handler,
         )
 
         managed.stdout_task = asyncio.create_task(
@@ -392,6 +411,16 @@ class ProcessService:
                             "message": text,
                             "source": source,
                         })
+
+                    # Optional framework-level subscriber.
+                    if managed.line_handler is not None:
+                        try:
+                            await managed.line_handler(stream_name, text)
+                        except Exception as cb_err:
+                            logger.debug(
+                                "[Process] line_handler %s/%s raised: %s",
+                                managed.name, stream_name, cb_err,
+                            )
         except asyncio.CancelledError:
             pass
         except Exception as e: