Skip to content

Self-improving AI Employees for everyone

refactor(plugin-extraction): IdempotentRegistry generic base

trohitg0605e2cdae39
diff --git a/server/services/event_waiter.py b/server/services/event_waiter.py
index bb2d9bb8..58c846ce 100644
--- a/server/services/event_waiter.py
+++ b/server/services/event_waiter.py
@@ -515,6 +515,14 @@ FILTER_BUILDERS: Dict[str, Callable[[Dict], Callable[[Dict], bool]]] = {
'emailReceive': build_email_filter,
}
+from services.plugin.registry import IdempotentRegistry as _IdempotentRegistry # noqa: E402
+
+# Backed by the module-level FILTER_BUILDERS dict so existing readers
+# (e.g. build_filter, _ensure_populated, tests) keep working.
+_FILTER_REGISTRY: _IdempotentRegistry[str, Callable[[Dict], Callable[[Dict], bool]]] = (
+ _IdempotentRegistry("filter_builder", items=FILTER_BUILDERS)
+)
+
def register_filter_builder(
node_type: str,
@@ -526,13 +534,7 @@ def register_filter_builder(
Used by plugin packages to keep all per-node-type knowledge inside
the plugin folder instead of hardcoding it here.
"""
- existing = FILTER_BUILDERS.get(node_type)
- if existing is not None and existing is not builder:
- raise ValueError(
- f"Filter builder for '{node_type}' is already registered by "
- f"{existing.__module__}.{existing.__qualname__}"
- )
- FILTER_BUILDERS[node_type] = builder
+ _FILTER_REGISTRY.register(node_type, builder)
def build_filter(node_type: str, params: Dict) -> Callable[[Dict], bool]:
@@ -568,6 +570,9 @@ import inspect as _inspect
_TriggerPrecheck = Callable[[Dict[str, Any]], Any]
_TRIGGER_PRECHECKS: Dict[str, _TriggerPrecheck] = {}
+_TRIGGER_PRECHECK_REGISTRY: _IdempotentRegistry[str, _TriggerPrecheck] = (
+ _IdempotentRegistry("trigger_precheck", items=_TRIGGER_PRECHECKS)
+)
def register_trigger_precheck(node_type: str, fn: _TriggerPrecheck) -> None:
@@ -576,13 +581,7 @@ def register_trigger_precheck(node_type: str, fn: _TriggerPrecheck) -> None:
Idempotent on re-import. The callback may be sync or async; ``run_trigger_precheck``
awaits the coroutine when needed.
"""
- existing = _TRIGGER_PRECHECKS.get(node_type)
- if existing is not None and existing is not fn:
- raise ValueError(
- f"Trigger precheck for '{node_type}' is already registered by "
- f"{existing.__module__}.{existing.__qualname__}"
- )
- _TRIGGER_PRECHECKS[node_type] = fn
+ _TRIGGER_PRECHECK_REGISTRY.register(node_type, fn)
async def run_trigger_precheck(node_type: str, parameters: Dict) -> Any:
diff --git a/server/services/node_output_schemas.py b/server/services/node_output_schemas.py
index b8d1b1a3..65b5cc90 100644
--- a/server/services/node_output_schemas.py
+++ b/server/services/node_output_schemas.py
@@ -866,6 +866,26 @@ def list_node_types_with_schema() -> list[str]:
return sorted(NODE_OUTPUT_SCHEMAS.keys())
+from services.plugin.registry import IdempotentRegistry as _IdempotentRegistry # noqa: E402
+
+
+def _bust_schema_cache(node_type: str, _model_class: type[BaseModel]) -> None:
+ """on_register hook: drop the cached JSON schema for the re-registered type."""
+ _schema_cache.pop(node_type, None)
+
+
+# Backed by the module-level NODE_OUTPUT_SCHEMAS dict so existing
+# readers (e.g. get_output_schema, list_node_types_with_schema, tests)
+# keep working.
+_OUTPUT_SCHEMA_REGISTRY: _IdempotentRegistry[str, type[BaseModel]] = (
+ _IdempotentRegistry(
+ "output_schema",
+ items=NODE_OUTPUT_SCHEMAS,
+ on_register=_bust_schema_cache,
+ )
+)
+
+
def register_output_schema(node_type: str, model_class: type[BaseModel]) -> None:
"""Publish an output schema for a node type from a plugin package.
@@ -877,13 +897,4 @@ def register_output_schema(node_type: str, model_class: type[BaseModel]) -> None
See e.g. ``nodes/telegram/__init__.py``.
"""
- existing = NODE_OUTPUT_SCHEMAS.get(node_type)
- if existing is not None and existing is not model_class:
- raise ValueError(
- f"Output schema for '{node_type}' is already registered as "
- f"{existing.__module__}.{existing.__qualname__}; refusing to "
- f"overwrite with {model_class.__module__}.{model_class.__qualname__}"
- )
- NODE_OUTPUT_SCHEMAS[node_type] = model_class
- # Bust the JSON-schema cache so the next call re-serialises.
- _schema_cache.pop(node_type, None)
+ _OUTPUT_SCHEMA_REGISTRY.register(node_type, model_class)
diff --git a/server/services/plugin/registry.py b/server/services/plugin/registry.py
new file mode 100644
index 00000000..6c6d2cab
--- /dev/null
+++ b/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
diff --git a/server/services/status_broadcaster.py b/server/services/status_broadcaster.py
index 3d09d998..b8704c2e 100644
--- a/server/services/status_broadcaster.py
+++ b/server/services/status_broadcaster.py
@@ -1269,6 +1269,15 @@ _ServiceRefreshCallback = _typing.Callable[
]
_SERVICE_REFRESH_CALLBACKS: _typing.List[_ServiceRefreshCallback] = []
+from services.plugin.registry import IdempotentList as _IdempotentList # noqa: E402
+
+# Backed by the module-level _SERVICE_REFRESH_CALLBACKS list so the
+# existing iterator at line 153 (``for callback in list(_SERVICE_REFRESH_CALLBACKS)``)
+# keeps working unchanged.
+_SERVICE_REFRESH_FANOUT: _IdempotentList[_ServiceRefreshCallback] = _IdempotentList(
+ "service_refresh", items=_SERVICE_REFRESH_CALLBACKS
+)
+
def register_service_refresh(callback: _ServiceRefreshCallback) -> None:
"""Register a per-service refresh callback.
@@ -1277,8 +1286,7 @@ def register_service_refresh(callback: _ServiceRefreshCallback) -> None:
callback runs once per ``_refresh_all_services()`` cycle (i.e. on
every WebSocket client connect).
"""
- if callback not in _SERVICE_REFRESH_CALLBACKS:
- _SERVICE_REFRESH_CALLBACKS.append(callback)
+ _SERVICE_REFRESH_FANOUT.register(callback)
# Global singleton instance
diff --git a/server/services/ws_handler_registry.py b/server/services/ws_handler_registry.py
index 48d882fb..484003d4 100644
--- a/server/services/ws_handler_registry.py
+++ b/server/services/ws_handler_registry.py
@@ -26,12 +26,14 @@ from typing import Any, Awaitable, Callable, Dict, List
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]]]
-_WS_REGISTRY: Dict[str, WSHandler] = {}
-_ROUTER_REGISTRY: Dict[str, APIRouter] = {}
+_WS_REGISTRY: IdempotentRegistry[str, WSHandler] = IdempotentRegistry("ws_handler")
+_ROUTER_REGISTRY: IdempotentRegistry[str, APIRouter] = IdempotentRegistry("router")
# ---- WebSocket handlers --------------------------------------------------
@@ -44,14 +46,7 @@ def register_ws_handlers(handlers: Dict[str, WSHandler]) -> None:
``ValueError`` to surface plugin namespace collisions early.
"""
for msg_type, handler in handlers.items():
- existing = _WS_REGISTRY.get(msg_type)
- if existing is not None and existing is not handler:
- raise ValueError(
- f"WS handler for message_type '{msg_type}' is already registered "
- f"by {existing.__module__}.{existing.__qualname__}; refusing to "
- f"overwrite with {handler.__module__}.{handler.__qualname__}"
- )
- _WS_REGISTRY[msg_type] = handler
+ _WS_REGISTRY.register(msg_type, handler)
def get_ws_handlers() -> Dict[str, WSHandler]:
@@ -60,7 +55,7 @@ def get_ws_handlers() -> Dict[str, WSHandler]:
Returns a fresh dict so callers can mutate without affecting the
registry (e.g. ``MESSAGE_HANDLERS = {**core, **get_ws_handlers()}``).
"""
- return dict(_WS_REGISTRY)
+ return dict(_WS_REGISTRY.items())
def list_registered_types() -> list[str]:
@@ -79,18 +74,12 @@ def register_router(router: APIRouter, *, name: str) -> None:
existing name raises ``ValueError`` so plugin-name collisions fail
at import time, not request time.
"""
- existing = _ROUTER_REGISTRY.get(name)
- if existing is not None and existing is not router:
- raise ValueError(
- f"Router for '{name}' is already registered; two plugin folders "
- f"cannot claim the same name."
- )
- _ROUTER_REGISTRY[name] = router
+ _ROUTER_REGISTRY.register(name, router)
def get_routers() -> List[APIRouter]:
"""Snapshot of registered routers in registration order."""
- return list(_ROUTER_REGISTRY.values())
+ return _ROUTER_REGISTRY.values()
def list_registered_routers() -> List[str]: