Skip to content

Self-improving AI Employees for everyone

refactor(credentials): shared Credential.validate scaffold + per-provider _probe

trohitg65a6c12a6cb2
diff --git a/server/main.py b/server/main.py
index be51e91f..4f0d63db 100644
--- a/server/main.py
+++ b/server/main.py
@@ -443,19 +443,36 @@ app.add_middleware(
expose_headers=["*"],
)
-# Include routers
+# Include framework-level routers (everything that's NOT plugin-specific
+# stays here). Plugin-owned routers self-register via
+# ``services.ws_handler_registry.register_router`` from their plugin
+# folder's ``__init__.py`` and are mounted via the loop below — main.py
+# never imports a migrated plugin module by name.
app.include_router(auth.router) # Auth routes (login, register, logout, status)
app.include_router(nodejs_compat.router) # Node.js compatibility (includes root endpoints)
app.include_router(workflow.router)
app.include_router(database.router)
+app.include_router(websocket.router)
+app.include_router(credentials.router) # Credentials panel - lazy per-tile icon endpoint (n8n pattern)
+app.include_router(schemas.router) # Per-node output schema endpoint (GET /api/schemas/nodes/{type}.json)
+
+# Routers awaiting migration into their plugin folders. As each plugin
+# moves to the self-contained pattern (nodes/<plugin>/_router.py +
+# register_router from __init__.py), the corresponding line below is
+# removed. Tracked in the plugin-extraction plan.
app.include_router(maps.router)
app.include_router(android.router)
-app.include_router(websocket.router)
app.include_router(webhook.router)
app.include_router(twitter.router) # Twitter/X OAuth routes
app.include_router(google.router) # Google Workspace OAuth routes (Gmail, Calendar, Drive, Sheets, Tasks, Contacts)
-app.include_router(credentials.router) # Credentials panel - lazy per-tile icon endpoint (n8n pattern)
-app.include_router(schemas.router) # Per-node output schema endpoint (GET /api/schemas/nodes/{type}.json)
+
+# Plugin-registered routers — populated by `nodes/<plugin>/__init__.py`
+# at import time via `register_router(...)`. Plugins are imported during
+# the node-discovery walk on app startup; iterating here picks up
+# anything that registered.
+from services.ws_handler_registry import get_routers as _get_plugin_routers
+for _plugin_router in _get_plugin_routers():
+ app.include_router(_plugin_router)
# ---------------------------------------------------------------------------
diff --git a/server/nodes/location/_credentials.py b/server/nodes/location/_credentials.py
index cbe46f44..b1674c20 100644
--- a/server/nodes/location/_credentials.py
+++ b/server/nodes/location/_credentials.py
@@ -8,7 +8,17 @@ gmaps_locations, gmaps_nearby_places). Separate from
from __future__ import annotations
-from services.plugin.credential import ApiKeyCredential
+import httpx
+
+from services.plugin.credential import ApiKeyCredential, ProbeResult
+
+
+# Google's documented sentinel address for connectivity tests on the
+# Geocoding API. Returns ``status=OK`` for any working key with the
+# Geocoding API enabled; ``REQUEST_DENIED`` for a bad key or disabled
+# API. We never store the response — it's just a probe.
+_GEOCODE_SENTINEL = "1600 Amphitheatre Parkway, Mountain View, CA"
+_GEOCODE_URL = "https://maps.googleapis.com/maps/api/geocode/json"
class GoogleMapsCredential(ApiKeyCredential):
@@ -19,3 +29,37 @@ class GoogleMapsCredential(ApiKeyCredential):
key_name = "key"
key_location = "query"
docs_url = "https://developers.google.com/maps/documentation"
+
+ @classmethod
+ async def _probe(cls, api_key: str) -> ProbeResult:
+ """Geocode a sentinel address to verify the key is live.
+
+ Replaces ``handle_validate_maps_key`` in
+ ``routers/websocket.py``; the storage + broadcast wiring is
+ handled by the base :meth:`Credential.validate` so this method
+ only needs to translate the geocode response into a
+ :class:`ProbeResult`. ``REQUEST_DENIED`` → invalid; ``OK`` /
+ ``ZERO_RESULTS`` / ``OVER_QUERY_LIMIT`` → valid (the key
+ authenticated, even if the query didn't return rows).
+ """
+ async with httpx.AsyncClient(timeout=10.0) as client:
+ response = await client.get(
+ _GEOCODE_URL,
+ params={"address": _GEOCODE_SENTINEL, "key": api_key},
+ )
+ payload = response.json()
+ status = payload.get("status")
+
+ if status == "REQUEST_DENIED":
+ return ProbeResult(
+ valid=False,
+ message=payload.get("error_message", "Invalid API key"),
+ )
+ return ProbeResult(
+ valid=True,
+ message=(
+ "Google Maps API key is valid"
+ if status == "OK"
+ else f"API key is valid (status: {status})"
+ ),
+ )
diff --git a/server/nodes/model/_credentials.py b/server/nodes/model/_credentials.py
index 8bc7bc51..059f8a8d 100644
--- a/server/nodes/model/_credentials.py
+++ b/server/nodes/model/_credentials.py
@@ -21,16 +21,44 @@ from __future__ import annotations
from typing import Any, Dict
-from services.plugin.credential import ApiKeyCredential
+from services.plugin.credential import ApiKeyCredential, ProbeResult
class _LLMApiKey(ApiKeyCredential):
- """Shared defaults. Subclasses only set id / display_name / icon."""
+ """Shared defaults. Subclasses only set id / display_name / icon.
+
+ The :meth:`_probe` override calls ``ai_service.fetch_models`` —
+ every cloud LLM provider in this file inherits it, so adding a new
+ OpenAI-compatible provider is purely declarative (id + base_url in
+ JSON; no validator code). The local-server credential override
+ (:class:`_LocalLLM`) supersedes ``validate`` entirely because its
+ side-effect ordering differs (URL stored under ``{id}_proxy``
+ before the probe + per-model context registration after).
+ """
category = "AI"
key_name = "Authorization"
key_location = "bearer"
+ @classmethod
+ async def _probe(cls, api_key: str) -> ProbeResult:
+ """Default LLM probe: fetch the provider's model list.
+
+ Hits ``GET /v1/models`` (or the provider equivalent) via
+ :meth:`AIService.fetch_models`. Returns a populated
+ :class:`ProbeResult` on success; raises ``httpx``/``openai``
+ exceptions for the base ``Credential.validate`` to classify.
+ """
+ from core.container import container
+
+ ai_service = container.ai_service()
+ models = await ai_service.fetch_models(cls.id, api_key)
+ return ProbeResult(
+ valid=True,
+ message="API key validated",
+ models=models,
+ )
+
class OpenAICredential(_LLMApiKey):
id = "openai"
@@ -125,6 +153,23 @@ class _LocalLLM(_LLMApiKey):
api_key = await container.auth_service().get_api_key(cls.id)
return {"api_key": api_key or "ollama"}
+ @classmethod
+ async def validate(cls, data: Dict[str, Any]) -> Dict[str, Any]:
+ """Probe the user's local server via the official SDK.
+
+ Overrides the base ``Credential.validate`` because local-LLM
+ side-effect ordering genuinely differs from the cloud case:
+ the user's URL is persisted under ``{cls.id}_proxy`` BEFORE
+ the probe runs, the placeholder ``api_key="ollama"`` is
+ stored under ``cls.id`` only on success, and per-model context
+ is registered in the model registry. Delegates to the
+ SDK-typed probe in ``_local_validator.py`` which already owns
+ that full flow.
+ """
+ from ._local_validator import validate_local_llm
+
+ return await validate_local_llm(dict(data, provider=cls.id))
+
class OllamaCredential(_LocalLLM):
id = "ollama"
diff --git a/server/nodes/model/_local_validator.py b/server/nodes/model/_local_validator.py
index d36b688d..ca7a6ca9 100644
--- a/server/nodes/model/_local_validator.py
+++ b/server/nodes/model/_local_validator.py
@@ -44,8 +44,6 @@ from typing import Any, Dict, List, Optional, Tuple
import httpx
import lmstudio
import ollama
-from fastapi import WebSocket
-
from core.container import container
from core.logging import get_logger
from services.status_broadcaster import get_status_broadcaster
@@ -239,8 +237,16 @@ async def _fetch_local_models(provider: str, base_url: str) -> List[Dict[str, An
raise ValueError(f"Unsupported local provider: {provider}")
-async def validate_local_llm(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
- """Validator for ollama / lmstudio. Matches the SPECIAL_PROVIDER_VALIDATORS contract."""
+async def validate_local_llm(data: Dict[str, Any]) -> Dict[str, Any]:
+ """Validator for ollama / lmstudio. Returns the standard response envelope.
+
+ Called from :meth:`nodes.model._credentials._LocalLLM.validate` (the
+ ``Credential.validate`` hook ``handle_validate_api_key`` dispatches
+ to). All side effects (URL persistence, status broadcasts, model
+ registry registration) go through the ``StatusBroadcaster`` /
+ ``AuthService`` singletons — no per-request WebSocket reference is
+ needed.
+ """
provider = data["provider"].lower()
base_url = data.get("api_key", "").strip()
session_id = data.get("session_id", "default")
diff --git a/server/nodes/scraper/_credentials.py b/server/nodes/scraper/_credentials.py
index 88172cac..d8c538cd 100644
--- a/server/nodes/scraper/_credentials.py
+++ b/server/nodes/scraper/_credentials.py
@@ -6,7 +6,7 @@ subclasses here in future.
from __future__ import annotations
-from services.plugin.credential import ApiKeyCredential
+from services.plugin.credential import ApiKeyCredential, ProbeResult
class ApifyCredential(ApiKeyCredential):
@@ -17,3 +17,31 @@ class ApifyCredential(ApiKeyCredential):
key_name = "Authorization"
key_location = "bearer"
docs_url = "https://docs.apify.com/api/v2"
+
+ @classmethod
+ async def _probe(cls, api_key: str) -> ProbeResult:
+ """Probe Apify ``/users/me`` to verify the token + capture
+ username / email / plan for display in the credentials panel.
+
+ ``validate_apify_token`` lives on the plugin module
+ (``apify_actor.py``) and uses the official ``apify_client`` SDK.
+ It returns a dict; we translate to :class:`ProbeResult` so the
+ base ``Credential.validate`` handles storage / broadcast.
+ """
+ from .apify_actor import validate_apify_token
+
+ result = await validate_apify_token(api_key)
+ if not result.get("valid"):
+ return ProbeResult(
+ valid=False,
+ message=result.get("error", "Invalid API token"),
+ )
+ return ProbeResult(
+ valid=True,
+ message=f"Apify token validated — user: {result.get('username', 'unknown')}",
+ extra={
+ "username": result.get("username"),
+ "email": result.get("email"),
+ "plan": result.get("plan"),
+ },
+ )
diff --git a/server/routers/websocket.py b/server/routers/websocket.py
index 55b34f61..61a1f9a6 100644
--- a/server/routers/websocket.py
+++ b/server/routers/websocket.py
@@ -1231,71 +1231,34 @@ async def handle_get_ai_models(data: Dict[str, Any], websocket: WebSocket) -> Di
async def handle_validate_api_key(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
"""Validate and store an API key.
- Single entry point for all providers. Dispatches to provider-specific
- validators (Google Maps geocode probe, Apify /users/me probe) for
- non-LLM providers; otherwise falls through to the default LLM
- ``/v1/models`` probe via ``ai_service.fetch_models``. The frontend
- calls this one handler for every provider — no per-provider branching
- on the TypeScript side.
-
- Invalid-key responses (401/403) and provider-side errors (4xx/5xx,
- timeouts, DNS failures) are mapped to a clean
- ``{success: True, valid: False, message: "..."}`` envelope — same
- shape the Maps/Apify validators return — so the frontend toast
- surfaces the actual reason instead of the generic
- "Validation failed" fallback. These are user-correctable input
- failures, not handler bugs, so they log at WARNING with a one-liner
- rather than ERROR with a stacktrace.
+ Pure dispatch — looks up the plugin's ``Credential`` subclass in
+ ``CREDENTIAL_REGISTRY`` and calls its ``validate`` classmethod. The
+ base ``Credential.validate`` (defined in
+ ``services/plugin/credential.py``) wires the shared scaffold
+ (storage + status broadcast + error classification + response
+ envelope) and dispatches the per-provider probe via the
+ subclass-supplied ``_probe`` hook. Cloud LLM providers inherit
+ ``_LLMApiKey._probe`` (``ai_service.fetch_models``); Maps + Apify +
+ local-LLM credentials override ``_probe`` (or the whole ``validate``
+ method, in the local-LLM case) with their own bespoke probes.
+
+ The router doesn't know about specific providers — adding a new
+ provider with a special validator is a single new ``_probe``
+ override on the plugin's ``Credential`` subclass.
"""
- import httpx
+ from services.plugin.credential import CREDENTIAL_REGISTRY
provider = data["provider"].lower()
normalized = dict(data, provider=provider)
- if provider in _SPECIAL_PROVIDER_VALIDATORS:
- return await _SPECIAL_PROVIDER_VALIDATORS[provider](normalized, websocket)
-
- ai_service = container.ai_service()
- auth_service = container.auth_service()
- broadcaster = get_status_broadcaster()
- api_key = data["api_key"].strip()
-
- # Fetch models for AI providers (any provider with a models_endpoint in llm_defaults.json)
- from services.ai import PROVIDER_CONFIGS
- try:
- models = await ai_service.fetch_models(provider, api_key) if provider in PROVIDER_CONFIGS else []
- except httpx.HTTPStatusError as e:
- status = e.response.status_code
- if status in (401, 403):
- msg = "Invalid API key"
- elif status == 429:
- msg = "Rate limited by provider — try again in a moment"
- elif 500 <= status < 600:
- msg = f"Provider error ({status}) — try again later"
- else:
- msg = f"Provider rejected the key ({status})"
- logger.warning("API key validation failed for %s: HTTP %s", provider, status)
- await broadcaster.update_api_key_status(
- provider=provider, valid=False, message=msg, has_key=False, models=[]
- )
- return {"provider": provider, "valid": False, "message": msg, "timestamp": time.time()}
- except (httpx.TimeoutException, httpx.RequestError) as e:
- # DNS, connect, read timeouts — the provider is unreachable.
- logger.warning("API key validation could not reach %s: %s", provider, e)
- msg = "Could not reach provider — check your network and try again"
- await broadcaster.update_api_key_status(
- provider=provider, valid=False, message=msg, has_key=False, models=[]
- )
- return {"provider": provider, "valid": False, "message": msg, "timestamp": time.time()}
-
- await auth_service.store_api_key(provider=provider, api_key=api_key, models=models,
- session_id=data.get("session_id", "default"))
- # Broadcast with hasKey and models so frontend can update reactively
- await broadcaster.update_api_key_status(
- provider=provider, valid=True, message="API key validated",
- has_key=True, models=models
- )
- return {"provider": provider, "valid": True, "models": models, "timestamp": time.time()}
+ cred_cls = CREDENTIAL_REGISTRY.get(provider)
+ if cred_cls is None:
+ return {
+ "success": False,
+ "valid": False,
+ "error": f"Unknown provider '{provider}' — no Credential class registered.",
+ }
+ return await cred_cls.validate(normalized)
@ws_handler("provider")
@@ -1929,168 +1892,15 @@ async def handle_android_relay_reconnect(data: Dict[str, Any], websocket: WebSoc
return {"success": False, "error": str(e)}
-# ============================================================================
-# Maps Handlers
-# ============================================================================
-
-async def handle_validate_maps_key(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
- """Validate Google Maps API key and save to database if valid."""
- import httpx
- broadcaster = get_status_broadcaster()
- auth_service = container.auth_service()
-
- api_key = data.get("api_key", "").strip()
- session_id = data.get("session_id", "default")
-
- if not api_key:
- return {"success": False, "valid": False, "error": "api_key required"}
-
- try:
- # Test the API key with a simple geocoding request
- async with httpx.AsyncClient() as client:
- response = await client.get(
- "https://maps.googleapis.com/maps/api/geocode/json",
- params={
- "address": "1600 Amphitheatre Parkway, Mountain View, CA",
- "key": api_key
- },
- timeout=10.0
- )
-
- response_data = response.json()
-
- if response_data.get("status") == "OK":
- # Save the validated key to database
- await auth_service.store_api_key(
- provider="google_maps",
- api_key=api_key,
- models=[],
- session_id=session_id
- )
- await broadcaster.update_api_key_status(
- provider="google_maps",
- valid=True,
- message="API key validated successfully"
- )
- return {"success": True, "valid": True, "message": "Google Maps API key is valid"}
-
- elif response_data.get("status") == "REQUEST_DENIED":
- error_msg = response_data.get("error_message", "Invalid API key")
- await broadcaster.update_api_key_status(
- provider="google_maps",
- valid=False,
- message=error_msg
- )
- return {"success": True, "valid": False, "message": error_msg}
-
- else:
- # Other statuses like ZERO_RESULTS still mean the key works
- # Save the validated key to database
- await auth_service.store_api_key(
- provider="google_maps",
- api_key=api_key,
- models=[],
- session_id=session_id
- )
- await broadcaster.update_api_key_status(
- provider="google_maps",
- valid=True,
- message="API key validated"
- )
- return {"success": True, "valid": True, "message": f"API key is valid (status: {response_data.get('status')})"}
-
- except httpx.TimeoutException:
- await broadcaster.update_api_key_status(
- provider="google_maps",
- valid=False,
- message="Validation request timed out"
- )
- return {"success": False, "valid": False, "error": "Validation request timed out"}
-
- except Exception as e:
- logger.error("Maps key validation failed", error=str(e))
- await broadcaster.update_api_key_status(
- provider="google_maps",
- valid=False,
- message=str(e)
- )
- return {"success": False, "valid": False, "error": str(e)}
-
-
-# ============================================================================
-# Apify Handlers
-# ============================================================================
-
-async def handle_validate_apify_key(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
- """Validate Apify API token and save to database if valid."""
- from nodes.scraper.apify_actor import validate_apify_token
-
- broadcaster = get_status_broadcaster()
- auth_service = container.auth_service()
-
- api_key = data.get("api_key", "").strip()
- session_id = data.get("session_id", "default")
-
- if not api_key:
- return {"success": False, "valid": False, "error": "api_key required"}
-
- try:
- result = await validate_apify_token(api_key)
-
- if result.get("valid"):
- # Save the validated key to database
- await auth_service.store_api_key(
- provider="apify",
- api_key=api_key,
- models=[],
- session_id=session_id
- )
- await broadcaster.update_api_key_status(
- provider="apify",
- valid=True,
- message=f"Apify token validated - user: {result.get('username', 'unknown')}"
- )
- return {
- "success": True,
- "valid": True,
- "message": "Apify API token is valid",
- "username": result.get("username"),
- "email": result.get("email"),
- "plan": result.get("plan")
- }
- else:
- error_msg = result.get("error", "Invalid API token")
- await broadcaster.update_api_key_status(
- provider="apify",
- valid=False,
- message=error_msg
- )
- return {"success": True, "valid": False, "message": error_msg}
-
- except Exception as e:
- logger.error("Apify key validation failed", error=str(e))
- await broadcaster.update_api_key_status(
- provider="apify",
- valid=False,
- message=str(e)
- )
- return {"success": False, "valid": False, "error": str(e)}
-
-
-# Per-provider validation strategies. Register any non-LLM provider here
-# and `handle_validate_api_key` will dispatch to it automatically, so the
-# frontend only ever calls one WS message type. Local-LLM validators
-# live in their plugin folder (see `nodes/model/_local_validator.py`)
-# so all per-provider behaviour for ollama/lmstudio stays in `nodes/model/`.
-from nodes.model._local_validator import validate_local_llm as _validate_local_llm
-
-_SPECIAL_PROVIDER_VALIDATORS = {
- "google_maps": handle_validate_maps_key,
- "apify": handle_validate_apify_key,
- "ollama": _validate_local_llm,
- "lmstudio": _validate_local_llm,
-}
+# ----------------------------------------------------------------------------
+# Per-provider credential validators (Maps geocode probe, Apify /users/me,
+# Ollama / LM Studio SDK probes) live on their plugins Credential
+# subclass via the shared Credential._probe / Credential.validate scaffold
+# in services/plugin/credential.py. handle_validate_api_key (above) is a
+# pure dispatch through CREDENTIAL_REGISTRY no per-provider branches in
+# this router.
+# ----------------------------------------------------------------------------
# ============================================================================
# WhatsApp Handlers - Wrappers for services.whatsapp_service functions
@@ -3451,11 +3261,12 @@ MESSAGE_HANDLERS: Dict[str, MessageHandler] = {
"android_relay_disconnect": handle_android_relay_disconnect,
"android_relay_reconnect": handle_android_relay_reconnect,
- # Maps operations
- "validate_maps_key": handle_validate_maps_key,
-
- # Apify operations
- "validate_apify_key": handle_validate_apify_key,
+ # Maps + Apify validation now flow through ``handle_validate_api_key``
+ # (which dispatches via ``CREDENTIAL_REGISTRY`` to
+ # ``GoogleMapsCredential._probe`` / ``ApifyCredential._probe``).
+ # The legacy ``validate_maps_key`` / ``validate_apify_key`` WS message
+ # types are no longer needed — the frontend already uses
+ # ``validate_api_key`` for all providers.
# WhatsApp operations
"whatsapp_status": handle_whatsapp_status,
diff --git a/server/services/plugin/credential.py b/server/services/plugin/credential.py
index eec9f361..8a49e5a5 100644
--- a/server/services/plugin/credential.py
+++ b/server/services/plugin/credential.py
@@ -13,16 +13,134 @@ Two concrete bases:
Both are discovered at import time via :data:`CREDENTIAL_REGISTRY`
(populated by ``__init_subclass__``). Nothing else needs to wire them.
+
+Validation is also a base-class concern. Every "validate this key"
+flow shares the same wiring (read api_key + session_id from request,
+call provider probe, store on success, broadcast status, return
+envelope). Only the probe itself varies. That common scaffold lives on
+:meth:`Credential.validate`; subclasses override the lighter
+:meth:`Credential._probe` to supply the per-provider call. See
+:class:`ProbeResult` for the typed return shape.
"""
from __future__ import annotations
-from typing import Any, ClassVar, Dict, Literal, Optional, Sequence
+import logging
+import time
+from dataclasses import dataclass, field
+from typing import Any, ClassVar, Dict, List, Literal, Optional, Sequence
+
+import httpx
+
+logger = logging.getLogger(__name__)
CREDENTIAL_REGISTRY: Dict[str, type] = {}
+@dataclass
+class ProbeResult:
+ """Outcome of a per-provider validation probe.
+
+ Carries the common ``valid`` / ``message`` flags every validator
+ returns, plus optional fields a few providers extend with
+ (``models`` for LLM ``/v1/models`` lists, ``model_params`` for
+ Ollama / LM Studio per-model context, ``extra`` for
+ provider-specific extensions like Apify's ``username`` / ``email``
+ / ``plan``). The base ``Credential.validate`` reads these fields
+ when wiring storage / broadcast / response envelope so subclasses
+ don't repeat any of that scaffolding.
+ """
+
+ valid: bool
+ message: str = ""
+ models: List[str] = field(default_factory=list)
+ model_params: Optional[Dict[str, Dict[str, Any]]] = None
+ # Free-form passthrough fields for provider-specific extensions
+ # (Apify returns username / email / plan; Twitter returns user id;
+ # Maps returns nothing). Merged into the response envelope.
+ extra: Dict[str, Any] = field(default_factory=dict)
+
+
+def classify_credential_error(
+ exc: BaseException, *, display_name: str
+) -> ProbeResult:
+ """Map a transport / SDK exception to a typed ``ProbeResult``.
+
+ Single source of truth for credential-error → user-message mapping.
+ Used by the base ``Credential.validate`` after a ``_probe`` call
+ raises, and by the local-LLM probe directly. Catches the documented
+ ``httpx`` / ``openai`` exception hierarchy so operator logs see
+ "HTTP 401" / "connect-refused" / "timeout" instead of an opaque
+ repr.
+
+ Returns a ``ProbeResult(valid=False, message=...)`` carrying the
+ user-facing string. Operator logs are emitted at WARN by the
+ caller — this helper just classifies, doesn't log.
+ """
+ import openai # local import: openai is a heavy SDK
+
+ if isinstance(exc, httpx.TimeoutException) or isinstance(exc, openai.APITimeoutError):
+ return ProbeResult(
+ valid=False,
+ message=f"Request to {display_name} timed out — try again or check the network.",
+ )
+
+ if isinstance(exc, httpx.ConnectError) or isinstance(exc, openai.APIConnectionError):
+ return ProbeResult(
+ valid=False,
+ message=f"Could not reach {display_name}. Is the server running?",
+ )
+
+ if isinstance(exc, httpx.HTTPStatusError):
+ status = exc.response.status_code
+ return _classify_status(status, display_name)
+
+ if isinstance(exc, openai.AuthenticationError):
+ return _classify_status(401, display_name)
+ if isinstance(exc, openai.PermissionDeniedError):
+ return _classify_status(403, display_name)
+ if isinstance(exc, openai.NotFoundError):
+ return _classify_status(404, display_name)
+ if isinstance(exc, openai.RateLimitError):
+ return _classify_status(429, display_name)
+ if isinstance(exc, openai.APIStatusError):
+ status = getattr(getattr(exc, "response", None), "status_code", 500)
+ return _classify_status(status, display_name)
+
+ # Unknown exception: surface the type name so the operator log line
+ # is still useful, but don't dump a stacktrace into the user's toast.
+ return ProbeResult(
+ valid=False,
+ message=f"Could not validate {display_name}: {type(exc).__name__}: {exc}",
+ )
+
+
+def _classify_status(status: int, display_name: str) -> ProbeResult:
+ """Map an HTTP status code to a user-facing message."""
+ if status in (401, 403):
+ return ProbeResult(valid=False, message=f"{display_name} rejected the API key.")
+ if status == 404:
+ return ProbeResult(
+ valid=False,
+ message=f"{display_name} returned 404 — endpoint not found. Check the URL.",
+ )
+ if status == 429:
+ return ProbeResult(
+ valid=False,
+ message=f"{display_name} rate-limited the request — try again shortly.",
+ )
+ if 500 <= status < 600:
+ return ProbeResult(
+ valid=False,
+ message=f"{display_name} returned HTTP {status} — try again later.",
+ )
+ return ProbeResult(
+ valid=False,
+ message=f"{display_name} returned HTTP {status}.",
+ )
+
+
class Credential:
"""Base class for provider credentials.
@@ -73,6 +191,105 @@ class Credential:
"""
return request
+ # ---- Validation -------------------------------------------------
+ #
+ # Every "validate this credential" flow follows the same wiring:
+ # read api_key + session_id from the request, run a per-provider
+ # probe, store on success, broadcast status, return the standard
+ # response envelope. Only the probe call genuinely varies — so the
+ # scaffolding lives on the base and subclasses override the lighter
+ # :meth:`_probe` hook. The dispatch entry point (called by the WS
+ # router) is :meth:`validate`; subclasses with non-standard
+ # side-effect ordering (e.g. local-LLM credentials store under TWO
+ # keys) override :meth:`validate` directly.
+
+ @classmethod
+ async def validate(cls, data: Dict[str, Any]) -> Dict[str, Any]:
+ """Run the credential validation probe and wire side effects.
+
+ The shared scaffold:
+ 1. Read ``api_key`` + ``session_id`` from the request data.
+ 2. Guard: missing key → fast-fail envelope.
+ 3. Call :meth:`_probe` (subclass-supplied; provider-specific).
+ 4. On exception, classify via :func:`classify_credential_error`.
+ 5. On valid result, persist via ``auth_service.store_api_key``.
+ 6. Broadcast the new status via
+ ``StatusBroadcaster.update_api_key_status`` (always — invalid
+ results clear stale state on connected clients).
+ 7. Return the standard response envelope.
+
+ Subclasses with non-standard storage / broadcast (e.g. local-LLM
+ credentials that store both URL and placeholder key) override
+ this method directly.
+ """
+ from core.container import container
+ from services.status_broadcaster import get_status_broadcaster
+
+ api_key = (data.get("api_key") or "").strip()
+ session_id = data.get("session_id", "default")
+ if not api_key:
+ return {
+ "success": False,
+ "valid": False,
+ "error": f"{cls.id} api_key required",
+ }
+
+ try:
+ result = await cls._probe(api_key)
+ except Exception as exc: # noqa: BLE001 — classified below
+ display = cls.display_name or cls.id
+ result = classify_credential_error(exc, display_name=display)
+ logger.warning(
+ "[%s] credential probe failed: %s",
+ cls.id,
+ result.message,
+ )
+
+ broadcaster = get_status_broadcaster()
+ auth_service = container.auth_service()
+
+ if result.valid:
+ await auth_service.store_api_key(
+ provider=cls.id,
+ api_key=api_key,
+ models=result.models,
+ session_id=session_id,
+ model_params=result.model_params,
+ )
+
+ await broadcaster.update_api_key_status(
+ provider=cls.id,
+ valid=result.valid,
+ message=result.message,
+ has_key=result.valid,
+ models=result.models,
+ )
+
+ return {
+ "success": True,
+ "provider": cls.id,
+ "valid": result.valid,
+ "message": result.message,
+ "models": result.models,
+ "timestamp": time.time(),
+ **result.extra,
+ }
+
+ @classmethod
+ async def _probe(cls, api_key: str) -> ProbeResult:
+ """Run the per-provider validation probe.
+
+ Subclass override point — the probe MUST NOT do storage,
+ broadcasts, or registry mutation. It returns a
+ :class:`ProbeResult` describing what the upstream returned;
+ :meth:`validate` does the rest. Raise ``httpx.*`` /
+ ``openai.OpenAIError`` to let the base map them to a typed
+ message via :func:`classify_credential_error`.
+ """
+ raise NotImplementedError(
+ f"Credential subclass {cls.__name__} must override _probe()"
+ )
+
class OAuth2Credential(Credential):
"""OAuth 2.0 with refresh-token support.
diff --git a/server/services/ws_handler_registry.py b/server/services/ws_handler_registry.py
index c314ea4b..48d882fb 100644
--- a/server/services/ws_handler_registry.py
+++ b/server/services/ws_handler_registry.py
@@ -1,33 +1,40 @@
-"""WebSocket handler registry for plugin-owned messages.
+"""Plugin self-registration registries.
-Mirrors the pattern used by :data:`services.node_registry._HANDLER_REGISTRY`
-(plugin nodes self-register via ``BaseNode.__init_subclass__``) but for
-side-channel WebSocket commands like ``telegram_connect``,
-``whatsapp_status``, etc.
+Two 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):
-Each ``nodes/<group>/__init__.py`` calls :func:`register_ws_handlers`
-with a dict of ``message_type -> async handler``; the central WebSocket
-router reads :func:`get_ws_handlers` at dispatch time and merges the
-result into its own legacy ``MESSAGE_HANDLERS`` table.
+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``.
-No hardcoded plugin names anywhere in the router. Adding a new
-plugin's WS surface is a one-line registration call inside that
-plugin's package.
+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.
+
+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.
"""
from __future__ import annotations
import logging
-from typing import Any, Awaitable, Callable, Dict
+from typing import Any, Awaitable, Callable, Dict, List
-from fastapi import WebSocket
+from fastapi import APIRouter, WebSocket
logger = logging.getLogger(__name__)
WSHandler = Callable[[Dict[str, Any], WebSocket], Awaitable[Dict[str, Any]]]
-_REGISTRY: Dict[str, WSHandler] = {}
+_WS_REGISTRY: Dict[str, WSHandler] = {}
+_ROUTER_REGISTRY: Dict[str, APIRouter] = {}
+
+# ---- WebSocket handlers --------------------------------------------------
def register_ws_handlers(handlers: Dict[str, WSHandler]) -> None:
"""Publish a batch of ``message_type -> handler`` mappings.
@@ -37,14 +44,14 @@ def register_ws_handlers(handlers: Dict[str, WSHandler]) -> None:
``ValueError`` to surface plugin namespace collisions early.
"""
for msg_type, handler in handlers.items():
- existing = _REGISTRY.get(msg_type)
+ 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__}"
)
- _REGISTRY[msg_type] = handler
+ _WS_REGISTRY[msg_type] = handler
def get_ws_handlers() -> Dict[str, WSHandler]:
@@ -53,9 +60,39 @@ 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(_REGISTRY)
+ return dict(_WS_REGISTRY)
def list_registered_types() -> list[str]:
"""For diagnostics / startup logging."""
- return sorted(_REGISTRY.keys())
+ 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.
+ """
+ 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
+
+
+def get_routers() -> List[APIRouter]:
+ """Snapshot of registered routers in registration order."""
+ return list(_ROUTER_REGISTRY.values())
+
+
+def list_registered_routers() -> List[str]:
+ """For diagnostics / startup logging."""
+ return sorted(_ROUTER_REGISTRY.keys())
diff --git a/server/tests/credentials/test_credential_broadcasts.py b/server/tests/credentials/test_credential_broadcasts.py
index 0624ed65..51ca21e6 100644
--- a/server/tests/credentials/test_credential_broadcasts.py
+++ b/server/tests/credentials/test_credential_broadcasts.py
@@ -57,13 +57,20 @@ class TestCredentialMutationHandlersBroadcast:
"""
def test_validate_api_key_broadcasts(self):
- """Sanity — already correct path; confirms the matcher works."""
- from routers import websocket as ws_module
+ """Validation broadcasts come from ``Credential.validate`` now.
+
+ ``handle_validate_api_key`` is a pure dispatcher that calls
+ ``CREDENTIAL_REGISTRY[provider].validate(...)``. The broadcast
+ happens inside ``Credential.validate`` (the shared scaffold in
+ ``services/plugin/credential.py``). This test checks the
+ invariant at the point where it actually lives.
+ """
+ from services.plugin.credential import Credential
- src = _handler_source(ws_module.handle_validate_api_key)
+ src = inspect.getsource(Credential.validate)
assert _BROADCAST_PATTERN.search(src), (
- "handle_validate_api_key must broadcast api_key_status "
- "or credential_catalogue_updated"
+ "Credential.validate must broadcast via update_api_key_status — "
+ "every credential mutation must surface to connected clients."
)
def test_save_api_key_broadcasts(self):
diff --git a/server/tests/credentials/test_websocket_handlers.py b/server/tests/credentials/test_websocket_handlers.py
index b6e2f27c..d2828275 100644
--- a/server/tests/credentials/test_websocket_handlers.py
+++ b/server/tests/credentials/test_websocket_handlers.py
@@ -114,22 +114,23 @@ class TestValidateApiKey:
# Broadcaster notified with hasKey + models
patched_container.broadcaster.update_api_key_status.assert_awaited_once()
- @patch("services.ai.PROVIDER_CONFIGS", {})
- @patch.object(ws_module, "_SPECIAL_PROVIDER_VALIDATORS", {})
- async def test_validate_skips_model_fetch_for_non_llm(
+ async def test_validate_unknown_provider_returns_error(
self, patched_container, fake_ws
):
- # Pick a provider that's neither in PROVIDER_CONFIGS (LLM) nor in
- # _SPECIAL_PROVIDER_VALIDATORS (Google Maps / Apify probe). The
- # handler should fall through to the empty-models path.
+ # ``handle_validate_api_key`` dispatches via
+ # ``CREDENTIAL_REGISTRY``; a provider without a registered
+ # ``Credential`` subclass is an explicit error (no fall-through
+ # to the default LLM probe — every supported provider must own
+ # its credential class).
result = await _call(
ws_module.handle_validate_api_key,
{"provider": "anonymous_provider", "api_key": "any-test"},
fake_ws,
)
- assert result["valid"] is True
- assert result["models"] == []
+ assert result["success"] is False
+ assert result["valid"] is False
+ assert "anonymous_provider" in result["error"]
patched_container.ai.fetch_models.assert_not_called()
async def test_missing_required_fields_returns_error(