Skip to content

Self-improving AI Employees for everyone

feat(plugin): @ws_response decorator + lazy DI helpers + reference adopters (Wave 11.I, T-residual)

trohitgdac74c5b7107
diff --git a/server/nodes/android/_handlers.py b/server/nodes/android/_handlers.py
index 338b3c57..f657bfbe 100644
--- a/server/nodes/android/_handlers.py
+++ b/server/nodes/android/_handlers.py
@@ -23,6 +23,7 @@ from typing import Any, Dict
from starlette.websockets import WebSocket
from core.logging import get_logger
+from services.plugin.ws import ws_response
from services.status_broadcaster import get_status_broadcaster
logger = get_logger(__name__)
@@ -61,6 +62,7 @@ async def handle_execute_android_action(data: Dict[str, Any], websocket: WebSock
return result
+@ws_response
async def handle_android_relay_connect(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
"""Connect to the Android relay server.
@@ -79,44 +81,37 @@ async def handle_android_relay_connect(data: Dict[str, Any], websocket: WebSocke
logger.info(f"[WebSocket] Android relay connect: {url}")
- try:
- client, error = await get_relay_client(url, api_key)
- if client:
- logger.info(
- f"[WebSocket] Android relay connect success, qr_data present: "
- f"{bool(client.qr_data)}, session_token: {client.session_token}"
- )
- return {
- "success": True,
- "connected": True,
- "session_token": client.session_token,
- "qr_data": client.qr_data,
- "message": "Connected to relay server",
- }
+ client, error = await get_relay_client(url, api_key)
+ if client:
+ logger.info(
+ f"[WebSocket] Android relay connect success, qr_data present: "
+ f"{bool(client.qr_data)}, session_token: {client.session_token}"
+ )
return {
- "success": False,
- "connected": False,
- "error": error or "Failed to connect to relay server",
+ "success": True,
+ "connected": True,
+ "session_token": client.session_token,
+ "qr_data": client.qr_data,
+ "message": "Connected to relay server",
}
- except Exception as e:
- logger.error(f"[WebSocket] Android relay connect error: {e}")
- return {"success": False, "error": str(e)}
+ return {
+ "success": False,
+ "connected": False,
+ "error": error or "Failed to connect to relay server",
+ }
+@ws_response
async def handle_android_relay_disconnect(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
"""Disconnect from the Android relay server."""
from ._relay import close_relay_client
logger.info("[WebSocket] Android relay disconnect requested")
-
- try:
- await close_relay_client()
- return {"success": True, "connected": False, "message": "Disconnected from relay server"}
- except Exception as e:
- logger.error(f"[WebSocket] Android relay disconnect error: {e}")
- return {"success": False, "error": str(e)}
+ await close_relay_client()
+ return {"success": True, "connected": False, "message": "Disconnected from relay server"}
+@ws_response
async def handle_android_relay_reconnect(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
"""Reconnect to the relay with a fresh session token + QR code."""
from ._relay import close_relay_client, get_relay_client
@@ -131,27 +126,23 @@ async def handle_android_relay_reconnect(data: Dict[str, Any], websocket: WebSoc
logger.info("[WebSocket] Android relay reconnect: forcing new session")
- try:
- await close_relay_client()
- await asyncio.sleep(0.5) # ensure clean disconnect
-
- client, error = await get_relay_client(url, api_key)
- if client:
- return {
- "success": True,
- "connected": True,
- "session_token": client.session_token,
- "qr_data": client.qr_data,
- "message": "Reconnected with new session token",
- }
+ await close_relay_client()
+ await asyncio.sleep(0.5) # ensure clean disconnect
+
+ client, error = await get_relay_client(url, api_key)
+ if client:
return {
- "success": False,
- "connected": False,
- "error": error or "Failed to reconnect to relay server",
+ "success": True,
+ "connected": True,
+ "session_token": client.session_token,
+ "qr_data": client.qr_data,
+ "message": "Reconnected with new session token",
}
- except Exception as e:
- logger.error(f"[WebSocket] Android relay reconnect error: {e}")
- return {"success": False, "error": str(e)}
+ return {
+ "success": False,
+ "connected": False,
+ "error": error or "Failed to reconnect to relay server",
+ }
WS_HANDLERS = {
diff --git a/server/nodes/telegram/_handlers.py b/server/nodes/telegram/_handlers.py
index 66622253..a0155edd 100644
--- a/server/nodes/telegram/_handlers.py
+++ b/server/nodes/telegram/_handlers.py
@@ -19,6 +19,8 @@ from typing import Any, Awaitable, Callable, Dict
from fastapi import WebSocket
+from services.plugin.ws import ws_response
+
from ._credentials import TelegramCredential
from ._service import get_telegram_service
@@ -112,8 +114,15 @@ async def handle_telegram_status(data: Dict[str, Any], websocket: WebSocket) ->
return {"success": True, "status": status}
+@ws_response
async def handle_telegram_send(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
- """Direct send via WebSocket (not via workflow node)."""
+ """Direct send via WebSocket (not via workflow node).
+
+ ``@ws_response`` collapses the catch-all ``try / except Exception``
+ block at the bottom of the function -- exceptions become
+ ``{success: False, error: str(e)}`` automatically. Early-return
+ validation stays since those are deterministic input checks.
+ """
service = get_telegram_service()
if not service.connected:
return {"success": False, "error": "Telegram bot not connected"}
@@ -125,15 +134,11 @@ async def handle_telegram_send(data: Dict[str, Any], websocket: WebSocket) -> Di
if dispatch is None:
return {"success": False, "error": f"Unsupported message type: {message_type}"}
- try:
- coro_or_none, err = dispatch(service, data, data.get("parse_mode"))
- if err:
- return {"success": False, "error": err}
- result = await coro_or_none
- return {"success": True, "result": result}
- except Exception as e:
- logger.error(f"[Telegram] Send error: {e}")
- return {"success": False, "error": str(e)}
+ coro_or_none, err = dispatch(service, data, data.get("parse_mode"))
+ if err:
+ return {"success": False, "error": err}
+ result = await coro_or_none
+ return {"success": True, "result": result}
async def handle_telegram_reconnect(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
@@ -155,26 +160,22 @@ async def handle_telegram_reconnect(data: Dict[str, Any], websocket: WebSocket)
return await get_telegram_service().connect(secrets["api_key"])
+@ws_response
async def handle_telegram_get_me(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
service = get_telegram_service()
if not service.connected:
return {"success": False, "error": "Telegram bot not connected"}
- try:
- return {"success": True, "result": await service.get_me()}
- except Exception as e:
- return {"success": False, "error": str(e)}
+ return {"success": True, "result": await service.get_me()}
+@ws_response
async def handle_telegram_get_chat(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
service = get_telegram_service()
if not service.connected:
return {"success": False, "error": "Telegram bot not connected"}
if not data.get("chat_id"):
return {"success": False, "error": "chat_id required"}
- try:
- return {"success": True, "result": await service.get_chat(data["chat_id"])}
- except Exception as e:
- return {"success": False, "error": str(e)}
+ return {"success": True, "result": await service.get_chat(data["chat_id"])}
# ---------------------------------------------------------------------------
diff --git a/server/services/plugin/deps.py b/server/services/plugin/deps.py
new file mode 100644
index 00000000..01565195
--- /dev/null
+++ b/server/services/plugin/deps.py
@@ -0,0 +1,68 @@
+"""Lazy dependency-injection helpers (Wave 11.I, milestone T-residual).
+
+Plugin packages need lazy imports of singletons from
+:mod:`core.container` to avoid the
+``nodes/<plugin>/__init__ -> core.container -> nodes.android._dispatcher
+-> nodes.android.__init__ -> _router`` import cycle that bites at
+package load time. Pre-T-residual the codebase had 53 inline
+``from core.container import container`` statements scattered across
+plugin handlers + services. These helpers consolidate the pattern
+into one place.
+
+**Important: NOT memoised.** Both helpers re-resolve the singleton on
+every call. Test fixtures swap the auth-service / database instances
+mid-test via the dependency-injection container's ``override``
+mechanism; a memoised cache would lock in the originally-resolved
+instance and the override would be silently ignored. The lookup is
+a dict access -- caching adds nothing measurable.
+
+Usage::
+
+ from services.plugin.deps import get_auth_service
+
+ async def handle_thing(data, websocket):
+ auth_service = get_auth_service()
+ client_id = await auth_service.get_api_key("twitter_client_id")
+ ...
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+ from core.cache import CacheService
+ from core.database import Database
+ from services.auth import AuthService
+
+
+def get_auth_service() -> "AuthService":
+ """Resolve the singleton :class:`services.auth.AuthService`.
+
+ Lazy import + call-time lookup. Test monkeypatching depends on
+ the container override being read at call time, not at module
+ import time -- do NOT memoise.
+ """
+ from core.container import container
+
+ return container.auth_service()
+
+
+def get_database() -> "Database":
+ """Resolve the singleton :class:`core.database.Database`.
+
+ Same NOT-memoised contract as :func:`get_auth_service`.
+ """
+ from core.container import container
+
+ return container.database()
+
+
+def get_cache() -> "CacheService":
+ """Resolve the singleton :class:`core.cache.CacheService`."""
+ from core.container import container
+
+ return container.cache()
+
+
+__all__ = ["get_auth_service", "get_database", "get_cache"]
diff --git a/server/services/plugin/ws.py b/server/services/plugin/ws.py
new file mode 100644
index 00000000..8658a6dd
--- /dev/null
+++ b/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"]
diff --git a/server/tests/test_plugin_helpers.py b/server/tests/test_plugin_helpers.py
new file mode 100644
index 00000000..6b44dca6
--- /dev/null
+++ b/server/tests/test_plugin_helpers.py
@@ -0,0 +1,116 @@
+"""Unit tests for :mod:`services.plugin.ws` + :mod:`services.plugin.deps`.
+
+Locks the contract for the two T-residual helpers added in Wave 11.I:
+
+* :func:`services.plugin.ws.ws_response` -- exception-to-envelope wrapper
+ with ``NodeUserError`` carve-out.
+* :func:`services.plugin.deps.get_auth_service` /
+ ``get_database`` / ``get_cache`` -- NOT memoised; re-resolve on
+ every call so test container overrides take effect.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from services.plugin.base import NodeUserError
+from services.plugin.deps import get_auth_service, get_cache, get_database
+from services.plugin.ws import ws_response
+
+
+# ----------------------------------------------------------------------------
+# ws_response
+# ----------------------------------------------------------------------------
+
+
+class TestWsResponse:
+ """``@ws_response`` -- opt-in exception-to-envelope decorator."""
+
+ async def test_success_path_passes_through_unchanged(self):
+ @ws_response
+ async def handler(data, websocket):
+ return {"success": True, "result": "ok", "extra": 42}
+
+ out = await handler({}, MagicMock())
+ assert out == {"success": True, "result": "ok", "extra": 42}
+
+ async def test_unexpected_exception_returns_error_envelope(self):
+ @ws_response
+ async def handler(data, websocket):
+ raise RuntimeError("server bug")
+
+ out = await handler({}, MagicMock())
+ assert out == {"success": False, "error": "server bug"}
+
+ async def test_node_user_error_returns_error_envelope(self):
+ @ws_response
+ async def handler(data, websocket):
+ raise NodeUserError("missing required field")
+
+ out = await handler({}, MagicMock())
+ assert out == {"success": False, "error": "missing required field"}
+
+ async def test_decorator_preserves_handler_metadata(self):
+ @ws_response
+ async def documented_handler(data, websocket):
+ """Original docstring."""
+ return {"success": True}
+
+ assert documented_handler.__name__ == "documented_handler"
+ assert documented_handler.__doc__ == "Original docstring."
+
+
+# ----------------------------------------------------------------------------
+# deps -- get_auth_service / get_database / get_cache
+# ----------------------------------------------------------------------------
+
+
+class TestLazyDependencyHelpers:
+ """The lazy DI helpers MUST NOT memoise -- test fixtures rely on
+ call-time container resolution to swap singletons mid-test."""
+
+ def test_get_auth_service_returns_container_singleton(self):
+ fake_auth = MagicMock(name="auth_service_singleton")
+ with patch("core.container.container") as fake_container:
+ fake_container.auth_service.return_value = fake_auth
+ assert get_auth_service() is fake_auth
+
+ def test_get_database_returns_container_singleton(self):
+ fake_db = MagicMock(name="database_singleton")
+ with patch("core.container.container") as fake_container:
+ fake_container.database.return_value = fake_db
+ assert get_database() is fake_db
+
+ def test_get_cache_returns_container_singleton(self):
+ fake_cache = MagicMock(name="cache_singleton")
+ with patch("core.container.container") as fake_container:
+ fake_container.cache.return_value = fake_cache
+ assert get_cache() is fake_cache
+
+ def test_get_auth_service_is_not_memoised(self):
+ """Two consecutive calls must each re-query the container.
+
+ Test monkeypatching swaps the container's auth-service mid-test.
+ A memoised cache would lock in the first instance and the swap
+ would be silently ignored.
+ """
+ first = MagicMock(name="first_auth_service")
+ second = MagicMock(name="second_auth_service")
+ with patch("core.container.container") as fake_container:
+ fake_container.auth_service.side_effect = [first, second]
+ assert get_auth_service() is first
+ assert get_auth_service() is second
+ # Verify the container was queried twice -- not a single cached
+ # lookup (which would mean side_effect's second value is unused).
+ assert fake_container.auth_service.call_count == 2
+
+ def test_get_database_is_not_memoised(self):
+ first = MagicMock(name="first_db")
+ second = MagicMock(name="second_db")
+ with patch("core.container.container") as fake_container:
+ fake_container.database.side_effect = [first, second]
+ assert get_database() is first
+ assert get_database() is second
+ assert fake_container.database.call_count == 2