Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
"""Plugin self-registration registries.
Five sibling concerns share this file because they're the same pattern
(idempotent dict + collision check) for the same audience (plugin
``__init__.py`` modules wiring themselves into the framework):
1. **WebSocket handlers** — ``register_ws_handlers({type: handler})``
for side-channel commands like ``telegram_connect``,
``whatsapp_status``. Read by ``routers/websocket.py`` at dispatch
time and merged into ``MESSAGE_HANDLERS``.
2. **HTTP routers** — ``register_router(APIRouter, name="<plugin>")``
for plugin-owned routes (OAuth callbacks, webhook receivers,
direct-API endpoints). Read by ``server.main`` after plugin discovery
and ``app.include_router(...)``'d.
3. **Option loaders** — ``register_option_loader(method_name, fn)`` for
dynamic-options dropdowns wired through the
``loadOptionsMethod`` Pydantic field metadata. Read by
:func:`dispatch_load_options` (here in this module) and the matching
WS handler in ``routers/websocket.py``. A loader whose options belong
to a user reads the caller from :func:`current_load_options_principal`,
never from ``params`` (the client writes those).
4. **OAuth callback paths** — ``register_oauth_callback_path(provider,
path)`` so :func:`services.oauth_utils.get_redirect_uri` can derive
the full redirect URI at runtime without a cross-folder import.
5. **Public ingress paths** — ``register_public_ingress_path(path,
name="<plugin>")`` for a plugin route that a provider calls without a
session cookie and that authenticates each request itself (Discord's
signed interactions). Read by ``middleware.auth.AuthMiddleware``.
No hardcoded plugin names anywhere in the central router or main.py.
Adding a new plugin's WS / HTTP / option-loader / oauth-callback /
public-ingress surface is one registration call inside that plugin's
package.
"""
from __future__ import annotations
import functools
import logging
from contextvars import ContextVar
from typing import Any, Awaitable, Callable, Dict, List, Optional
from fastapi import APIRouter, WebSocket
from services.plugin.registry import IdempotentRegistry
logger = logging.getLogger(__name__)
WSHandler = Callable[[Dict[str, Any], WebSocket], Awaitable[Dict[str, Any]]]
LoadOptionsFn = Callable[[Dict[str, Any]], Awaitable[List[Dict[str, Any]]]]
# ---- WS-handler decorator ------------------------------------------------
def ws_handler(*required_fields: str):
"""Decorator for WebSocket handlers.
Validates required fields are non-empty and wraps exceptions into a
``{"success": False, "error": str(e)}`` envelope. Default-injects
``{"success": True}`` when the handler body omits it.
Moved from ``routers/websocket.py`` (Wave 13) so domain modules
under ``services/`` can decorate their own handlers without a
circular import on the router.
"""
def decorator(func: WSHandler) -> WSHandler:
@functools.wraps(func)
async def wrapper(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
for field in required_fields:
if not data.get(field):
return {"success": False, "error": f"{field} required"}
try:
result = await func(data, websocket)
if "success" not in result:
result = {"success": True, **result}
return result
except Exception as e:
logger.error(f"Handler error: {e}", exc_info=True)
return {"success": False, "error": str(e)}
return wrapper
return decorator
_WS_REGISTRY: IdempotentRegistry[str, WSHandler] = IdempotentRegistry("ws_handler")
_ROUTER_REGISTRY: IdempotentRegistry[str, APIRouter] = IdempotentRegistry("router")
_OPTION_LOADER_REGISTRY: IdempotentRegistry[str, LoadOptionsFn] = IdempotentRegistry("option_loader")
_OAUTH_CALLBACK_PATHS: IdempotentRegistry[str, str] = IdempotentRegistry("oauth_callback_path")
_PUBLIC_INGRESS_PATHS: IdempotentRegistry[str, str] = IdempotentRegistry("public_ingress_path")
# ---- WebSocket handlers --------------------------------------------------
def register_ws_handlers(handlers: Dict[str, WSHandler]) -> None:
"""Publish a batch of ``message_type -> handler`` mappings.
Idempotent on re-import (same callable for the same key is a no-op).
Registering a different callable for an existing key raises
``ValueError`` to surface plugin namespace collisions early.
"""
for msg_type, handler in handlers.items():
_WS_REGISTRY.register(msg_type, handler)
def get_ws_handlers() -> Dict[str, WSHandler]:
"""Snapshot of all plugin-registered WS handlers.
Returns a fresh dict so callers can mutate without affecting the
registry (e.g. ``MESSAGE_HANDLERS = {**core, **get_ws_handlers()}``).
"""
return dict(_WS_REGISTRY.items())
def list_registered_types() -> list[str]:
"""For diagnostics / startup logging."""
return sorted(_WS_REGISTRY.keys())
# ---- HTTP routers --------------------------------------------------------
def register_router(router: APIRouter, *, name: str) -> None:
"""Publish a plugin-owned ``APIRouter`` for inclusion at app startup.
``name`` is the plugin folder name — used for diagnostics and
collision detection. Same idempotency contract as the WS side: the
same router for the same name is a no-op; a different router for an
existing name raises ``ValueError`` so plugin-name collisions fail
at import time, not request time.
"""
_ROUTER_REGISTRY.register(name, router)
def get_routers() -> List[APIRouter]:
"""Snapshot of registered routers in registration order."""
return _ROUTER_REGISTRY.values()
def list_registered_routers() -> List[str]:
"""For diagnostics / startup logging."""
return sorted(_ROUTER_REGISTRY.keys())
# ---- Option loaders ------------------------------------------------------
def register_option_loader(method_name: str, fn: LoadOptionsFn) -> None:
"""Publish a ``loadOptionsMethod`` async loader.
``method_name`` is the string declared on Pydantic ``Field`` metadata
via ``json_schema_extra={"loadOptionsMethod": "..."}`` (e.g.
``gmailLabels``, ``whatsappGroups``). Same idempotency contract as
the WS / router registries: the same callable for the same method
is a no-op; a different callable raises ``ValueError`` so plugin
namespace clashes fail at import time.
"""
_OPTION_LOADER_REGISTRY.register(method_name, fn)
def get_option_loader(method_name: str) -> LoadOptionsFn | None:
"""Look up a registered loader. ``None`` when the method is unknown."""
return _OPTION_LOADER_REGISTRY.get(method_name)
def list_registered_option_methods() -> List[str]:
"""For diagnostics / startup logging."""
return sorted(_OPTION_LOADER_REGISTRY.keys())
_LOAD_OPTIONS_PRINCIPAL: ContextVar[Optional[str]] = ContextVar("load_options_principal", default=None)
def current_load_options_principal() -> Optional[str]:
"""The authenticated caller of the load-options request being served.
``None`` outside a request or when the caller is unknown. Set by
:func:`dispatch_load_options` from the socket or HTTP identity, so a
loader that lists one user's things (browser profiles) never has to
trust a ``user_id`` inside ``params``.
"""
return _LOAD_OPTIONS_PRINCIPAL.get()
async def dispatch_load_options(
method: str, params: Dict[str, Any] | None = None, *, principal: Optional[str] = None
) -> List[Dict[str, Any]]:
"""Look up and invoke a registered loader.
Returns an empty list when the method isn't registered (matches
n8n's tolerant fallback -- the dropdown stays empty rather than
erroring out). ``principal`` is the authenticated caller, exposed to
the loader through :func:`current_load_options_principal`.
"""
loader = _OPTION_LOADER_REGISTRY.get(method)
if loader is None:
return []
token = _LOAD_OPTIONS_PRINCIPAL.set(principal)
try:
return await loader(params or {})
finally:
_LOAD_OPTIONS_PRINCIPAL.reset(token)
def list_load_options_methods() -> List[str]:
"""Stable alphabetised list of registered method names. The editor
prefetches this once on boot so it knows which ``loadOptionsMethod``
values are wired."""
return list_registered_option_methods()
# ---- OAuth callback paths -----------------------------------------------
def register_oauth_callback_path(provider: str, path: str) -> None:
"""Publish a plugin's OAuth callback path (``/api/<provider>/callback``).
Same idempotency contract as the other registries: the same path
for the same provider is a no-op; a different path for an existing
provider raises ``ValueError``. ``services.oauth_utils.get_redirect_uri``
looks up via this registry so the OAuth callback URL is plugin-
registered, not cross-imported from ``nodes/<plugin>/_oauth.py``.
"""
_OAUTH_CALLBACK_PATHS.register(provider, path)
def get_oauth_callback_path(provider: str) -> str:
"""Look up the registered callback path or fall back to a default
(`/api/<provider>/callback`). The fallback matches the convention
every existing plugin uses."""
registered = _OAUTH_CALLBACK_PATHS.get(provider)
if registered is not None:
return registered
return f"/api/{provider}/callback"
def list_registered_oauth_providers() -> List[str]:
"""For diagnostics / startup logging."""
return sorted(_OAUTH_CALLBACK_PATHS.keys())
# ---- Public ingress paths -----------------------------------------------
def register_public_ingress_path(path: str, *, name: str) -> None:
"""Publish a route a provider calls without a session cookie.
The route itself must authenticate every request (a signature over
the raw body, failing closed), because the auth middleware lets the
path and everything below it through. Same idempotency contract as
the other registries, keyed by ``name``.
"""
_PUBLIC_INGRESS_PATHS.register(name, path.rstrip("/"))
def is_public_ingress_path(path: str) -> bool:
"""Whether ``path`` is a registered public ingress path or below one."""
return any(path == public or path.startswith(public + "/") for public in _PUBLIC_INGRESS_PATHS.values())