Skip to content

Self-improving AI Employees for everyone

refactor(whatsapp): move 3 option loaders into nodes/whatsapp/_option_loaders.py (Wave 11.I, M.1)

trohitg03a69d1bb8b7
diff --git a/server/nodes/whatsapp/__init__.py b/server/nodes/whatsapp/__init__.py
index ad70a42c..604dc547 100644
--- a/server/nodes/whatsapp/__init__.py
+++ b/server/nodes/whatsapp/__init__.py
@@ -21,10 +21,14 @@ Two self-registrations happen on package import:
from services._supervisor import register_supervisor
from services.event_waiter import register_filter_builder
from services.status_broadcaster import register_service_refresh
-from services.ws_handler_registry import register_ws_handlers
+from services.ws_handler_registry import (
+ register_option_loader,
+ register_ws_handlers,
+)
from ._filters import build_filter as build_whatsapp_filter
from ._handlers import WS_HANDLERS
+from ._option_loaders import load_channels, load_group_members, load_groups
from ._refresh import refresh_whatsapp_status
from ._runtime import WhatsAppRuntime, get_whatsapp_runtime
@@ -47,6 +51,13 @@ register_service_refresh(refresh_whatsapp_status)
# carries no plugin-specific code.
register_filter_builder("whatsappReceive", build_whatsapp_filter)
+# loadOptionsMethod loaders (Wave 11.I, milestone M.1) -- moved out
+# of services/node_option_loaders/ so the central LOAD_OPTIONS_REGISTRY
+# carries no plugin-specific code.
+register_option_loader("whatsappGroups", load_groups)
+register_option_loader("whatsappChannels", load_channels)
+register_option_loader("whatsappGroupMembers", load_group_members)
+
__all__ = [
"WhatsAppRuntime",
"get_whatsapp_runtime",
diff --git a/server/nodes/whatsapp/_option_loaders.py b/server/nodes/whatsapp/_option_loaders.py
new file mode 100644
index 00000000..1889bc72
--- /dev/null
+++ b/server/nodes/whatsapp/_option_loaders.py
@@ -0,0 +1,69 @@
+"""WhatsApp ``loadOptionsMethod`` loaders.
+
+Wave 11.I, milestone M.1. Each function is registered with
+``services.ws_handler_registry.register_option_loader`` from
+``__init__.py`` so the central dispatcher in
+``services/node_option_loaders/__init__.py`` picks them up without a
+plugin-specific import.
+
+Adapter shape: turn the existing WS-handler responses
+(``handle_whatsapp_groups`` / ``handle_whatsapp_newsletters`` /
+``handle_whatsapp_group_info``) into the unified ``[{value, label}]``
+list the frontend ``useLoadOptionsQuery`` consumes. The legacy WS
+message types stay live for back-compat.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+from ._service import (
+ handle_whatsapp_group_info,
+ handle_whatsapp_groups,
+ handle_whatsapp_newsletters,
+)
+
+
+async def load_groups(params: Dict[str, Any]) -> List[Dict[str, Any]]:
+ """List WhatsApp groups for the ``recipient_type='group'`` selector."""
+ response = await handle_whatsapp_groups()
+ groups = response.get("groups", []) if isinstance(response, dict) else []
+ return [
+ {
+ "value": g.get("group_jid") or g.get("id") or "",
+ "label": g.get("name") or g.get("subject") or g.get("group_jid", ""),
+ }
+ for g in groups
+ ]
+
+
+async def load_channels(params: Dict[str, Any]) -> List[Dict[str, Any]]:
+ """List subscribed newsletter channels for the ``channel_jid`` selector."""
+ response = await handle_whatsapp_newsletters()
+ channels = response.get("newsletters", []) if isinstance(response, dict) else []
+ return [
+ {
+ "value": c.get("channel_jid") or c.get("id") or "",
+ "label": c.get("name") or c.get("channel_jid", ""),
+ }
+ for c in channels
+ ]
+
+
+async def load_group_members(params: Dict[str, Any]) -> List[Dict[str, Any]]:
+ """List members of a specific WhatsApp group for the ``senderNumber``
+ selector. Depends on ``params['group_id']``."""
+ group_id = params.get("group_id") or ""
+ if not group_id:
+ return []
+ response = await handle_whatsapp_group_info(group_id)
+ participants = (
+ response.get("participants", []) if isinstance(response, dict) else []
+ )
+ return [
+ {
+ "value": p.get("phone") or p.get("jid") or "",
+ "label": p.get("name") or p.get("phone") or p.get("jid", ""),
+ }
+ for p in participants
+ ]
diff --git a/server/services/node_option_loaders/__init__.py b/server/services/node_option_loaders/__init__.py
index 64a9eee5..453debfa 100644
--- a/server/services/node_option_loaders/__init__.py
+++ b/server/services/node_option_loaders/__init__.py
@@ -1,26 +1,23 @@
-"""Generic loadOptionsMethod dispatch registry.
-
-Wave 6 Phase 4. Generalises the WhatsApp-only dynamic-options pattern
-to a registry mirroring services/node_executor._build_handler_registry().
-
-The editor calls a single endpoint:
-
- POST /api/nodes/options/{method}
-
-with body ``{"node_type": "...", "params": {...}}`` and the dispatcher
-looks up the registered async loader, invokes it, and returns the
-resulting ``[{"value": ..., "label": ...}]`` list. WS mirror at
-``load_options`` matches the Wave 3 handler convention.
-
-Registering a new dynamic-option loader: define an async function in
-its own module under this package, import it here, and add the entry
-to ``LOAD_OPTIONS_REGISTRY``. No frontend change needed - the
-``loadOptionsMethod`` string in the Pydantic ``Field(json_schema_extra=)``
-is what wires it through.
+"""Generic loadOptionsMethod dispatch.
+
+Wave 6 Phase 4 introduced this as a central registry. Wave 11.I,
+milestone M relocates the per-plugin loaders into their plugin folders
+(``nodes/<plugin>/_option_loaders.py``) and routes lookups through
+``services.ws_handler_registry.register_option_loader`` -- the same
+``IdempotentRegistry``-backed sibling of ``register_ws_handlers`` /
+``register_router``.
+
+While milestone M is in flight we keep a small legacy dict for plugins
+that haven't migrated yet; the dispatcher consults the plugin registry
+first and falls back to the legacy table. After M.3 the legacy table is
+empty and this module retires alongside the rest of
+``services/node_option_loaders/``.
"""
from typing import Any, Awaitable, Callable, Optional
+from services.ws_handler_registry import get_option_loader
+
from .android_loaders import load_android_service_actions
from .google_loaders import (
load_gmail_labels,
@@ -28,42 +25,40 @@ from .google_loaders import (
load_google_drive_folders,
load_google_tasklists,
)
-from .whatsapp_loaders import (
- load_whatsapp_channels,
- load_whatsapp_group_members,
- load_whatsapp_groups,
-)
# Async loader signature: (params: dict) -> list of {value, label, ...}
LoadOptionsFn = Callable[[dict[str, Any]], Awaitable[list[dict[str, Any]]]]
-LOAD_OPTIONS_REGISTRY: dict[str, LoadOptionsFn] = {
- # WhatsApp - groups, channels, group members.
- "whatsappGroups": load_whatsapp_groups,
- "whatsappChannels": load_whatsapp_channels,
- "whatsappGroupMembers": load_whatsapp_group_members,
- # Google Workspace - Gmail labels, Calendar list, Drive folders, Tasks lists.
+# Legacy table for not-yet-migrated plugins. Shrinks one entry per M.x
+# commit; deleted entirely at the end of M.3.
+LEGACY_LOAD_OPTIONS_REGISTRY: dict[str, LoadOptionsFn] = {
"gmailLabels": load_gmail_labels,
"googleCalendarList": load_google_calendar_list,
"googleDriveFolders": load_google_drive_folders,
"googleTasklists": load_google_tasklists,
- # Android - service actions enum loaded from the connected bridge.
"getAndroidServiceActions": load_android_service_actions,
}
+# Backwards-compat alias for the previous public name. Tests and
+# ``list_load_options_methods`` still read it; updates land per M.x.
+LOAD_OPTIONS_REGISTRY = LEGACY_LOAD_OPTIONS_REGISTRY
+
+
async def dispatch_load_options(
method: str, params: Optional[dict[str, Any]] = 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)."""
+ Plugin-registry lookup wins; legacy table is the fallback. Returns
+ an empty list when the method isn't registered (matches n8n's
+ tolerant fallback -- the dropdown stays empty rather than erroring
+ out).
+ """
- loader = LOAD_OPTIONS_REGISTRY.get(method)
+ loader = get_option_loader(method) or LEGACY_LOAD_OPTIONS_REGISTRY.get(method)
if loader is None:
return []
return await loader(params or {})
@@ -74,4 +69,8 @@ def list_load_options_methods() -> list[str]:
prefetches this once on boot so it knows which ``loadOptionsMethod``
values are wired."""
- return sorted(LOAD_OPTIONS_REGISTRY.keys())
+ from services.ws_handler_registry import list_registered_option_methods
+
+ plugin_methods = set(list_registered_option_methods())
+ legacy_methods = set(LEGACY_LOAD_OPTIONS_REGISTRY.keys())
+ return sorted(plugin_methods | legacy_methods)
diff --git a/server/services/node_option_loaders/whatsapp_loaders.py b/server/services/node_option_loaders/whatsapp_loaders.py
deleted file mode 100644
index 7c58bb6f..00000000
--- a/server/services/node_option_loaders/whatsapp_loaders.py
+++ /dev/null
@@ -1,69 +0,0 @@
-"""WhatsApp loadOptions adapters.
-
-Wave 6 Phase 4. Thin wrappers around the existing WhatsApp WS handlers
-that normalise the response into the unified ``[{value, label}]`` shape
-the frontend ``useLoadOptionsQuery`` consumes.
-
-Today the editor talks to ``handle_whatsapp_groups`` /
-``handle_whatsapp_newsletters`` / ``handle_whatsapp_group_info``
-directly via dedicated WS message types. These adapters expose the
-same data through the unified ``load_options`` dispatcher so the
-``loadOptionsMethod`` schema field wires straight through with no
-per-method WS handler. The legacy WS handlers stay live for back-compat.
-"""
-
-from typing import Any
-
-
-async def load_whatsapp_groups(params: dict[str, Any]) -> list[dict[str, Any]]:
- """List WhatsApp groups for the recipient_type='group' selector."""
-
- from nodes.whatsapp._service import handle_whatsapp_groups as _wa_groups
-
- response = await _wa_groups()
- groups = response.get("groups", []) if isinstance(response, dict) else []
- return [
- {
- "value": g.get("group_jid") or g.get("id") or "",
- "label": g.get("name") or g.get("subject") or g.get("group_jid", ""),
- }
- for g in groups
- ]
-
-
-async def load_whatsapp_channels(params: dict[str, Any]) -> list[dict[str, Any]]:
- """List subscribed newsletter channels for the channel_jid selector."""
-
- from nodes.whatsapp._service import handle_whatsapp_newsletters as _wa_newsletters
-
- response = await _wa_newsletters()
- channels = response.get("newsletters", []) if isinstance(response, dict) else []
- return [
- {
- "value": c.get("channel_jid") or c.get("id") or "",
- "label": c.get("name") or c.get("channel_jid", ""),
- }
- for c in channels
- ]
-
-
-async def load_whatsapp_group_members(params: dict[str, Any]) -> list[dict[str, Any]]:
- """List members of a specific WhatsApp group for the senderNumber
- selector. Depends on ``params['group_id']``."""
-
- from nodes.whatsapp._service import handle_whatsapp_group_info as _wa_group_info
-
- group_id = params.get("group_id") or ""
- if not group_id:
- return []
- response = await _wa_group_info(group_id)
- participants = (
- response.get("participants", []) if isinstance(response, dict) else []
- )
- return [
- {
- "value": p.get("phone") or p.get("jid") or "",
- "label": p.get("name") or p.get("phone") or p.get("jid", ""),
- }
- for p in participants
- ]
diff --git a/server/services/ws_handler_registry.py b/server/services/ws_handler_registry.py
index 484003d4..21c17ffb 100644
--- a/server/services/ws_handler_registry.py
+++ b/server/services/ws_handler_registry.py
@@ -1,6 +1,6 @@
"""Plugin self-registration registries.
-Two sibling concerns share this file because they're the same pattern
+Three 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):
@@ -14,9 +14,15 @@ Two sibling concerns share this file because they're the same pattern
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
+ ``services.node_option_loaders.dispatch_load_options`` and the
+ matching WS handler in ``routers/websocket.py``.
+
No hardcoded plugin names anywhere in the central router or main.py.
-Adding a new plugin's WS / HTTP surface is one registration call inside
-that plugin's package.
+Adding a new plugin's WS / HTTP / option-loader surface is one
+registration call inside that plugin's package.
"""
from __future__ import annotations
@@ -31,9 +37,13 @@ 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_REGISTRY: IdempotentRegistry[str, WSHandler] = IdempotentRegistry("ws_handler")
_ROUTER_REGISTRY: IdempotentRegistry[str, APIRouter] = IdempotentRegistry("router")
+_OPTION_LOADER_REGISTRY: IdempotentRegistry[str, LoadOptionsFn] = IdempotentRegistry(
+ "option_loader"
+)
# ---- WebSocket handlers --------------------------------------------------
@@ -85,3 +95,28 @@ def get_routers() -> List[APIRouter]:
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())
diff --git a/server/tests/test_node_spec.py b/server/tests/test_node_spec.py
index 0221e766..6a906437 100644
--- a/server/tests/test_node_spec.py
+++ b/server/tests/test_node_spec.py
@@ -386,14 +386,16 @@ class TestPhase4LoadOptions:
"""Wave 6 Phase 4: unified loadOptionsMethod dispatch registry."""
def test_registry_has_whatsapp_methods(self):
- from services.node_option_loaders import LOAD_OPTIONS_REGISTRY
+ from services.node_option_loaders import list_load_options_methods
+ methods = list_load_options_methods()
for method in ["whatsappGroups", "whatsappChannels", "whatsappGroupMembers"]:
- assert method in LOAD_OPTIONS_REGISTRY
+ assert method in methods
def test_registry_has_google_methods(self):
- from services.node_option_loaders import LOAD_OPTIONS_REGISTRY
+ from services.node_option_loaders import list_load_options_methods
+ methods = list_load_options_methods()
for method in ["gmailLabels", "googleCalendarList", "googleDriveFolders", "googleTasklists"]:
- assert method in LOAD_OPTIONS_REGISTRY
+ assert method in methods
def test_list_methods_sorted(self):
from services.node_option_loaders import list_load_options_methods
@@ -744,17 +746,19 @@ class TestNodeSpecContractInvariants:
def test_load_options_methods_are_registered(self):
"""Every Pydantic Field(loadOptionsMethod=X) must point at a
- method registered in LOAD_OPTIONS_REGISTRY. Catches typos and
+ registered loader -- either in the legacy table or in a
+ plugin's ``register_option_loader`` call. Catches typos and
forgotten loader registrations."""
from services.node_input_schemas import get_node_input_schema, NODE_INPUT_MODELS
- from services.node_option_loaders import LOAD_OPTIONS_REGISTRY
+ from services.node_option_loaders import list_load_options_methods
+ methods = set(list_load_options_methods())
for t in NODE_INPUT_MODELS:
schema = get_node_input_schema(t)
for prop_name, prop in schema.get("properties", {}).items():
method = prop.get("loadOptionsMethod")
if method is None:
continue
- assert method in LOAD_OPTIONS_REGISTRY, (
+ assert method in methods, (
f"{t}.{prop_name} references unknown loadOptionsMethod {method!r}"
)