Skip to content

Agent Zero AI framework

chore: delete all legacy WebSocket system files

keyboardstaff07b5e056e00d
diff --git a/helpers/websocket.py b/helpers/websocket.py
deleted file mode 100644
index cbae4ae03..000000000
--- a/helpers/websocket.py
+++ /dev/null
@@ -1,550 +0,0 @@
-from __future__ import annotations
-
-import re
-import threading
-from abc import ABC, abstractmethod
-from urllib.parse import urlparse
-from typing import Any, Iterable, Optional, TYPE_CHECKING
-
-import socketio
-
-if TYPE_CHECKING: # pragma: no cover - hints only
- from helpers.websocket_manager import WebSocketManager
-
-_EVENT_NAME_PATTERN = re.compile(r"^[a-z][a-z0-9_]*$")
-_RESERVED_EVENT_NAMES: set[str] = {
- "connect",
- "disconnect",
- "error",
- "ping",
- "pong",
- "connect_error",
- "reconnect",
- "reconnect_attempt",
- "reconnect_error",
- "reconnect_failed",
-}
-
-
-def _default_port_for_scheme(scheme: str) -> int | None:
- if scheme == "http":
- return 80
- if scheme == "https":
- return 443
- return None
-
-
-def normalize_origin(value: Any) -> str | None:
- """Normalize an Origin/Referer header value to scheme://host[:port]."""
- if not isinstance(value, str) or not value.strip():
- return None
- parsed = urlparse(value.strip())
- if not parsed.scheme or not parsed.hostname:
- return None
- origin = f"{parsed.scheme}://{parsed.hostname}"
- if parsed.port:
- origin += f":{parsed.port}"
- return origin
-
-
-def _parse_host_header(value: Any) -> tuple[str | None, int | None]:
- if not isinstance(value, str) or not value.strip():
- return None, None
- parsed = urlparse(f"http://{value.strip()}")
- return parsed.hostname, parsed.port
-
-
-def validate_ws_origin(environ: dict[str, Any]) -> tuple[bool, str | None]:
- """Validate the browser Origin during the Socket.IO handshake.
-
- This is the minimum baseline recommended by RFC 6455 (Origin considerations)
- and OWASP (CSWSH mitigation): reject cross-origin WebSocket handshakes when
- the server is intended for a specific web UI origin.
- """
-
- raw_origin = environ.get("HTTP_ORIGIN") or environ.get("HTTP_REFERER")
- origin = normalize_origin(raw_origin)
- if origin is None:
- return False, "missing_origin"
-
- origin_parsed = urlparse(origin)
- origin_host = origin_parsed.hostname.lower() if origin_parsed.hostname else None
- origin_port = origin_parsed.port or _default_port_for_scheme(origin_parsed.scheme)
- if origin_host is None or origin_port is None:
- return False, "invalid_origin"
-
- # Build candidate request host/port pairs. Prefer explicit Host header, fall back to
- # forwarded headers (reverse proxies) and finally SERVER_NAME.
- raw_host = environ.get("HTTP_HOST")
- req_host, req_port = _parse_host_header(raw_host)
- if not req_host:
- req_host = environ.get("SERVER_NAME")
-
- if req_port is None:
- server_port_raw = environ.get("SERVER_PORT")
- try:
- server_port = int(server_port_raw) if server_port_raw is not None else None
- except (TypeError, ValueError):
- server_port = None
- if server_port is not None and server_port > 0:
- req_port = server_port
-
- if req_host:
- req_host = req_host.lower()
- if req_port is None:
- req_port = origin_port
-
- forwarded_host_raw = environ.get("HTTP_X_FORWARDED_HOST")
- forwarded_host = None
- forwarded_port = None
- if isinstance(forwarded_host_raw, str) and forwarded_host_raw.strip():
- first = forwarded_host_raw.split(",")[0].strip()
- forwarded_host, forwarded_port = _parse_host_header(first)
- if forwarded_host:
- forwarded_host = forwarded_host.lower()
-
- forwarded_proto_raw = environ.get("HTTP_X_FORWARDED_PROTO")
- forwarded_scheme = None
- if isinstance(forwarded_proto_raw, str) and forwarded_proto_raw.strip():
- forwarded_scheme = forwarded_proto_raw.split(",")[0].strip().lower()
- forwarded_scheme = forwarded_scheme or origin_parsed.scheme
- forwarded_port = (
- forwarded_port
- if forwarded_port is not None
- else _default_port_for_scheme(forwarded_scheme) or origin_port
- )
-
- candidates: list[tuple[str, int]] = []
- if req_host:
- candidates.append((req_host, int(req_port)))
- if forwarded_host:
- candidates.append((forwarded_host, int(forwarded_port)))
-
- if not candidates:
- return False, "missing_host"
-
- for host, port in candidates:
- if origin_host == host and origin_port == port:
- return True, None
-
- # Preserve the original mismatch semantics for debugging.
- if origin_host not in {host for host, _ in candidates}:
- return False, "origin_host_mismatch"
- return False, "origin_port_mismatch"
-
-
-class SingletonInstantiationError(RuntimeError):
- """Raised when a WebSocketHandler subclass is instantiated directly.
-
- Handlers must be retrieved via ``get_instance`` to guarantee singleton
- semantics and consistent lifecycle behaviour.
- """
-
-
-class ConnectionNotFoundError(RuntimeError):
- """Raised when attempting to emit to a non-existent WebSocket connection."""
-
- def __init__(self, sid: str, *, namespace: str | None = None) -> None:
- self.sid = sid
- self.namespace = namespace
- if namespace:
- super().__init__(f"Connection not found: namespace={namespace} sid={sid}")
- else:
- super().__init__(f"Connection not found: {sid}")
-
-
-class WebSocketResult:
- """Helper wrapper for standardized handler results.
-
- Instances are converted to the canonical ``RequestResultItem`` shape by
- :class:`WebSocketManager`. Helper constructors enforce payload validation so
- handlers no longer need to hand‑craft dictionaries.
- """
-
- __slots__ = ("_ok", "_data", "_error", "_correlation_id", "_duration_ms")
-
- def __init__(
- self,
- ok: bool,
- data: dict[str, Any] | None = None,
- error: dict[str, Any] | None = None,
- correlation_id: str | None = None,
- duration_ms: float | None = None,
- ) -> None:
- if ok and error:
- raise ValueError("Cannot be both ok and have an error")
- if not ok and not error:
- raise ValueError("Must either be ok or have an error")
- if data is not None and not isinstance(data, dict):
- raise TypeError("Data payload must be a dictionary or None")
- if error is not None and not isinstance(error, dict):
- raise TypeError("Error payload must be a dictionary or None")
- if correlation_id is not None and not isinstance(correlation_id, str):
- raise TypeError("Correlation ID must be a string or None")
- if duration_ms is not None and not isinstance(duration_ms, (int, float)):
- raise TypeError("Duration must be a number or None")
-
- self._ok = bool(ok)
- self._data = dict(data) if data is not None else None
- self._error = dict(error) if error is not None else None
- self._correlation_id = correlation_id
- self._duration_ms = float(duration_ms) if duration_ms is not None else None
-
- @classmethod
- def ok(
- cls,
- data: dict[str, Any] | None = None,
- *,
- correlation_id: str | None = None,
- duration_ms: float | None = None,
- ) -> "WebSocketResult":
- if data is not None and not isinstance(data, dict):
- raise TypeError("WebSocketResult.ok data must be a dict or None")
- payload = dict(data) if data is not None else None
- return cls(
- ok=True,
- data=payload,
- correlation_id=correlation_id,
- duration_ms=duration_ms,
- )
-
- @classmethod
- def error(
- cls,
- *,
- code: str,
- message: str,
- details: Any | None = None,
- correlation_id: str | None = None,
- duration_ms: float | None = None,
- ) -> "WebSocketResult":
- if not isinstance(code, str) or not code.strip():
- raise ValueError("Error code must be a non-empty string")
- if not isinstance(message, str) or not message.strip():
- raise ValueError("Error message must be a non-empty string")
-
- error_payload: dict[str, Any] = {"code": code, "error": message}
- if details is not None:
- error_payload["details"] = details
- return cls(
- ok=False,
- error=error_payload,
- correlation_id=correlation_id,
- duration_ms=duration_ms,
- )
-
- def as_result(
- self,
- *,
- handler_id: str,
- fallback_correlation_id: str | None,
- duration_ms: float | None = None,
- ) -> dict[str, Any]:
- result: dict[str, Any] = {
- "handlerId": handler_id,
- "ok": self._ok,
- }
-
- effective_duration = (
- self._duration_ms if self._duration_ms is not None else duration_ms
- )
- if effective_duration is not None:
- result["durationMs"] = round(effective_duration, 4)
-
- correlation = (
- self._correlation_id
- if self._correlation_id is not None
- else fallback_correlation_id
- )
- if correlation is not None:
- result["correlationId"] = correlation
-
- if self._ok:
- result["data"] = dict(self._data) if self._data is not None else {}
- else:
- result["error"] = dict(self._error) if self._error is not None else {
- "code": "INTERNAL_ERROR",
- "error": "Internal server error",
- }
- return result
-
-
-class WebSocketHandler(ABC):
- """Base class for WebSocket event handlers.
-
- The interface mirrors :class:`helpers.api.ApiHandler` with declarative
- security configuration and lifecycle hooks. Handlers are namespace-wide:
- every inbound event for the bound namespace is dispatched to
- :meth:`process_event`, which decides whether and how to respond.
- """
-
- _instances: dict[type["WebSocketHandler"], "WebSocketHandler"] = {}
- _construction_tokens: dict[type["WebSocketHandler"], bool] = {}
- _singleton_lock = threading.RLock()
-
- def __init__(self, socketio: socketio.AsyncServer, lock: threading.RLock) -> None:
- """Create a handler bound to the shared Socket.IO instance."""
-
- cls = self.__class__
- if not WebSocketHandler._construction_tokens.get(cls):
- raise SingletonInstantiationError(
- f"{cls.__name__} must be instantiated via {cls.__name__}.get_instance()"
- )
-
- self.socketio: socketio.AsyncServer = socketio
- self.lock: threading.RLock = lock
- self._manager: Optional[WebSocketManager] = None
- self._namespace: str | None = None
-
- @classmethod
- def get_instance(
- cls,
- socketio: socketio.AsyncServer | None = None,
- lock: threading.RLock | None = None,
- *args: Any,
- **kwargs: Any,
- ) -> "WebSocketHandler":
- """Return the singleton instance for ``cls``.
-
- Args:
- socketio: Shared AsyncServer instance (required on first call).
- lock: Shared threading lock (required on first call).
- *args: Optional subclass-specific constructor args.
- **kwargs: Optional subclass-specific constructor kwargs.
- """
-
- if cls is WebSocketHandler:
- raise TypeError("WebSocketHandler must be subclassed before use")
-
- with WebSocketHandler._singleton_lock:
- instance = WebSocketHandler._instances.get(cls)
- if instance is not None:
- return instance
-
- if socketio is None or lock is None:
- raise ValueError(
- f"{cls.__name__}.get_instance() requires socketio and lock on first call"
- )
-
- WebSocketHandler._construction_tokens[cls] = True
- try:
- instance = cls(socketio, lock, *args, **kwargs)
- finally:
- WebSocketHandler._construction_tokens.pop(cls, None)
-
- WebSocketHandler._instances[cls] = instance
- return instance
-
- @classmethod
- def _reset_instance_for_testing(cls) -> None:
- """Reset the cached singleton instance (testing helper)."""
-
- with WebSocketHandler._singleton_lock:
- WebSocketHandler._instances.pop(cls, None)
- WebSocketHandler._construction_tokens.pop(cls, None)
-
- @classmethod
- def validate_event_type(cls, event_type: str) -> str:
- """Validate a runtime event name before dispatch."""
-
- if not isinstance(event_type, str):
- raise TypeError("Event type must be a string")
- if not _EVENT_NAME_PATTERN.fullmatch(event_type):
- raise ValueError(
- f"Invalid event type '{event_type}' – must match lowercase_snake_case"
- )
- if event_type in _RESERVED_EVENT_NAMES:
- raise ValueError(
- f"Event type '{event_type}' is reserved by Socket.IO and cannot be used"
- )
- return event_type
-
- @classmethod
- def requires_auth(cls) -> bool:
- """Return whether an authenticated Flask session is required."""
-
- return True
-
- @classmethod
- def requires_csrf(cls) -> bool:
- """Return whether CSRF validation is required for the handler.
-
- This mirrors ApiHandler.requires_csrf(): by default, authenticated
- WebSocket handlers also require CSRF validation during the Socket.IO
- connect step.
- """
-
- return cls.requires_auth()
-
- async def on_connect(self, sid: str) -> None:
- """Lifecycle hook invoked when a client connects."""
-
- return None
-
- async def on_disconnect(self, sid: str) -> None:
- """Lifecycle hook invoked when a client disconnects."""
-
- return None
-
- @abstractmethod
- async def process_event(
- self,
- event_type: str,
- data: dict[str, Any],
- sid: str,
- ) -> dict[str, Any] | WebSocketResult | None:
- """Process an incoming event dispatched to the handler.
-
- Returning ``None`` indicates fire-and-forget semantics. Returning a
- dictionary includes the payload in the Socket.IO acknowledgement.
- """
-
- def bind_manager(self, manager: WebSocketManager, *, namespace: str) -> None:
- """Associate this handler instance with the shared WebSocket manager."""
-
- self._manager = manager
- self._namespace = namespace
-
- @property
- def namespace(self) -> str:
- if not self._namespace:
- raise RuntimeError("WebSocketHandler is missing namespace binding")
- return self._namespace
-
- @property
- def manager(self) -> WebSocketManager:
- """Return the bound WebSocket manager.
-
- Raises:
- RuntimeError: If the handler has not been registered yet.
- """
-
- if not self._manager:
- raise RuntimeError("WebSocketHandler is not registered with a manager")
- return self._manager
-
- @property
- def identifier(self) -> str:
- """Return a stable identifier used in aggregated responses."""
-
- return f"{self.__class__.__module__}.{self.__class__.__name__}"
-
- async def emit_to(
- self,
- sid: str,
- event_type: str,
- data: dict[str, Any],
- *,
- correlation_id: str | None = None,
- ) -> None:
- """Emit an event to a specific connection or buffer it if offline."""
- await self.manager.emit_to(
- self.namespace,
- sid,
- event_type,
- data,
- handler_id=self.identifier,
- correlation_id=correlation_id,
- )
-
- async def broadcast(
- self,
- event_type: str,
- data: dict[str, Any],
- *,
- exclude_sids: str | Iterable[str] | None = None,
- correlation_id: str | None = None,
- ) -> None:
- """Broadcast an event to all connections, optionally excluding one."""
- await self.manager.broadcast(
- self.namespace,
- event_type,
- data,
- exclude_sids=exclude_sids,
- handler_id=self.identifier,
- correlation_id=correlation_id,
- )
-
- # ------------------------------------------------------------------
- # Convenience wrappers for standardized result helpers
- # ------------------------------------------------------------------
-
- @staticmethod
- def result_ok(
- data: dict[str, Any] | None = None,
- *,
- correlation_id: str | None = None,
- duration_ms: float | None = None,
- ) -> WebSocketResult:
- """Return a standardized success result."""
-
- return WebSocketResult.ok(
- data=data,
- correlation_id=correlation_id,
- duration_ms=duration_ms,
- )
-
- @staticmethod
- def result_error(
- *,
- code: str,
- message: str,
- details: Any | None = None,
- correlation_id: str | None = None,
- duration_ms: float | None = None,
- ) -> WebSocketResult:
- """Return a standardized error result."""
-
- return WebSocketResult.error(
- code=code,
- message=message,
- details=details,
- correlation_id=correlation_id,
- duration_ms=duration_ms,
- )
-
- async def request(
- self,
- sid: str,
- event_type: str,
- data: dict[str, Any],
- *,
- timeout_ms: int = 0,
- include_handlers: Iterable[str] | None = None,
- ) -> dict[str, Any]:
- """Send a request-response event to a specific connection and aggregate results.
-
- Returns a payload shaped as ``{"correlationId": str, "results": RequestResultItem[]}``.
- """
-
- return await self.manager.request_for_sid(
- namespace=self.namespace,
- sid=sid,
- event_type=event_type,
- data=data,
- timeout_ms=timeout_ms,
- handler_id=self.identifier,
- include_handlers=set(include_handlers) if include_handlers else None,
- )
-
- async def request_all(
- self,
- event_type: str,
- data: dict[str, Any],
- *,
- timeout_ms: int = 0,
- exclude_handlers: Iterable[str] | None = None,
- ) -> list[dict[str, Any]]:
- """Fan a request out to every active connection and aggregate responses.
-
- Each entry in the returned list is ``{"sid": str, "correlationId": str, "results": RequestResultItem[]}``.
- """
-
- return await self.manager.route_event_all(
- self.namespace,
- event_type=event_type,
- data=data,
- timeout_ms=timeout_ms,
- exclude_handlers=set(exclude_handlers) if exclude_handlers else None,
- handler_id=self.identifier,
- )
diff --git a/helpers/websocket_manager.py b/helpers/websocket_manager.py
deleted file mode 100644
index 67d9fd782..000000000
--- a/helpers/websocket_manager.py
+++ /dev/null
@@ -1,1189 +0,0 @@
-from __future__ import annotations
-
-import asyncio, os
-import time
-import threading
-from collections import defaultdict, deque
-from dataclasses import dataclass, field
-from datetime import datetime, timedelta, timezone
-from typing import Any, Callable, Deque, Dict, Iterable, List, Optional, Set
-
-import socketio
-import uuid
-
-from helpers.defer import DeferredTask
-from helpers.print_style import PrintStyle
-from helpers import runtime
-from helpers.websocket import ConnectionNotFoundError, WebSocketHandler, WebSocketResult
-from helpers.state_monitor import _ws_debug_enabled
-
-BUFFER_MAX_SIZE = 100
-BUFFER_TTL = timedelta(hours=1)
-_shared_websocket_manager: WebSocketManager | None = None
-
-
-async def send_data(
- event_name: str,
- data: dict[str, Any],
- endpoint_name: str = "/webui",
- connection_id: str | None = None,
-) -> None:
- manager = get_shared_websocket_manager()
- print(f"Sending data to {endpoint_name}/{event_name} with data {data}")
- await manager.send_data(endpoint_name, event_name, data, connection_id)
-
-
-def _utcnow() -> datetime:
- return datetime.now(timezone.utc)
-
-
-def set_shared_websocket_manager(manager: "WebSocketManager") -> None:
- global _shared_websocket_manager
- _shared_websocket_manager = manager
-
-
-def get_shared_websocket_manager() -> "WebSocketManager":
- manager = _shared_websocket_manager
- if manager is None:
- raise RuntimeError("Shared WebSocketManager has not been initialized")
- return manager
-
-
-@dataclass
-class BufferedEvent:
- event_type: str
- data: dict[str, Any]
- handler_id: str | None = None
- correlation_id: str | None = None
- timestamp: datetime = field(default_factory=_utcnow)
-
-
-@dataclass
-class ConnectionInfo:
- namespace: str
- sid: str
- connected_at: datetime = field(default_factory=_utcnow)
- last_activity: datetime = field(default_factory=_utcnow)
-
-
-ConnectionIdentity = tuple[str, str] # (namespace, sid)
-
-
-@dataclass
-class _HandlerExecution:
- handler: WebSocketHandler
- value: Any
- duration_ms: float | None
-
-
-DIAGNOSTIC_EVENT = "ws_dev_console_event"
-LIFECYCLE_CONNECT_EVENT = "ws_lifecycle_connect"
-LIFECYCLE_DISCONNECT_EVENT = "ws_lifecycle_disconnect"
-
-
-class WebSocketManager:
- def __init__(self, socketio: socketio.AsyncServer, lock) -> None:
- self.socketio = socketio
- self.lock = lock
- self.handlers: defaultdict[str, List[WebSocketHandler]] = defaultdict(list)
- self.connections: Dict[ConnectionIdentity, ConnectionInfo] = {}
- self.buffers: defaultdict[ConnectionIdentity, Deque[BufferedEvent]] = (
- defaultdict(deque)
- )
- self._known_sids: Set[ConnectionIdentity] = set()
- self._identifier: str = f"{self.__class__.__module__}.{self.__class__.__name__}"
- # Session tracking (single-user default)
- self.user_to_sids: defaultdict[str, Set[ConnectionIdentity]] = defaultdict(set)
- self.sid_to_user: Dict[ConnectionIdentity, str | None] = {}
- self._ALL_USERS_BUCKET = "allUsers"
- self._server_restart_enabled: bool = False
- self._diagnostic_watchers: Set[ConnectionIdentity] = set()
- self._diagnostics_enabled: bool = runtime.is_development()
- self._dispatcher_loop: asyncio.AbstractEventLoop | None = None
- self._handler_worker: DeferredTask | None = None
-
- # Internal: development-only debug logging to avoid noise in production
- def _debug(self, message: str) -> None:
- value = os.getenv("A0_WS_DEBUG", "").strip().lower()
- if value in {"1", "true", "yes", "on"}:
- PrintStyle.debug(message)
-
- def _ensure_dispatcher_loop(self) -> None:
- if self._dispatcher_loop is None:
- try:
- self._dispatcher_loop = asyncio.get_running_loop()
- except RuntimeError:
- return
-
- def _get_handler_worker(self) -> DeferredTask:
- if self._handler_worker is None:
- self._handler_worker = DeferredTask(thread_name="WebSocketHandlers")
- return self._handler_worker
-
- async def _run_on_dispatcher_loop(self, coro: Any) -> Any:
- self._ensure_dispatcher_loop()
- dispatcher_loop = self._dispatcher_loop
- if dispatcher_loop is None:
- return await coro
- if dispatcher_loop.is_closed():
- try:
- coro.close()
- except Exception: # pragma: no cover - best-effort cleanup
- pass
- raise RuntimeError("Dispatcher event loop is closed")
-
- try:
- running_loop = asyncio.get_running_loop()
- except RuntimeError:
- running_loop = None
-
- if running_loop is dispatcher_loop:
- return await coro
-
- future = asyncio.run_coroutine_threadsafe(coro, dispatcher_loop)
- return await asyncio.wrap_future(future)
-
- def _diagnostics_active(self) -> bool:
- if not self._diagnostics_enabled:
- return False
- with self.lock:
- return bool(self._diagnostic_watchers)
-
- def _copy_diagnostic_watchers(self) -> list[ConnectionIdentity]:
- with self.lock:
- return list(self._diagnostic_watchers)
-
- def register_diagnostic_watcher(self, namespace: str, sid: str) -> bool:
- if not self._diagnostics_enabled:
- return False
- identity: ConnectionIdentity = (namespace, sid)
- with self.lock:
- if identity not in self.connections:
- return False
- self._diagnostic_watchers.add(identity)
- return True
-
- def unregister_diagnostic_watcher(self, namespace: str, sid: str) -> None:
- identity: ConnectionIdentity = (namespace, sid)
- with self.lock:
- self._diagnostic_watchers.discard(identity)
-
- def _timestamp(self) -> str:
- return _utcnow().isoformat(timespec="milliseconds").replace("+00:00", "Z")
-
- def _summarize_payload(self, payload: dict[str, Any] | None) -> dict[str, Any]:
- if not isinstance(payload, dict):
- return {}
- summary: dict[str, Any] = {}
- for key in list(payload.keys())[:5]:
- value = payload[key]
- if isinstance(value, (str, int, float, bool)) or value is None:
- preview = value
- elif isinstance(value, dict):
- preview = f"dict({len(value)})"
- elif isinstance(value, list):
- preview = f"list({len(value)})"
- else:
- preview = value.__class__.__name__
- summary[key] = preview
- summary["__sizeBytes__"] = len(str(payload).encode("utf-8"))
- return summary
-
- def _summarize_results(self, results: List[dict[str, Any]]) -> dict[str, Any]:
- summary = {"ok": 0, "error": 0, "handlers": []}
- for result in results:
- handler_id = result.get("handlerId")
- ok = bool(result.get("ok"))
- if ok:
- summary["ok"] += 1
- else:
- summary["error"] += 1
- summary["handlers"].append(
- {
- "handlerId": handler_id,
- "ok": ok,
- "errorCode": (result.get("error") or {}).get("code"),
- "durationMs": result.get("durationMs"),
- }
- )
- summary["handlerCount"] = len(summary["handlers"])
- return summary
-
- async def _publish_diagnostic_event(
- self, payload: dict[str, Any] | Callable[[], dict[str, Any]]
- ) -> None:
- if not self._diagnostics_enabled:
- return
- watchers = self._copy_diagnostic_watchers()
- if not watchers:
- return
- effective_payload = payload() if callable(payload) else payload
- if (
- isinstance(effective_payload, dict)
- and "sourceNamespace" not in effective_payload
- ):
- origin = effective_payload.get("namespace")
- if isinstance(origin, str) and origin.strip():
- effective_payload = {
- **effective_payload,
- "sourceNamespace": origin.strip(),
- }
-
- async def _emit_to_watcher(identity: ConnectionIdentity) -> None:
- namespace, sid = identity
- try:
- await self.emit_to(
- namespace,
- sid,
- DIAGNOSTIC_EVENT,
- effective_payload,
- handler_id=self._identifier,
- diagnostic=True,
- )
- except ConnectionNotFoundError:
- self.unregister_diagnostic_watcher(namespace, sid)
-
- await asyncio.gather(*(_emit_to_watcher(identity) for identity in watchers))
-
- def _schedule_lifecycle_broadcast(
- self, namespace: str, event_type: str, payload: dict[str, Any]
- ) -> None:
- async def _broadcast() -> None:
- try:
- await self.broadcast(
- namespace,
- event_type,
- payload,
- diagnostic=True,
- )
- except Exception as exc: # pragma: no cover - diagnostic
- self._debug(f"Failed to broadcast lifecycle event {event_type}: {exc}")
-
- asyncio.create_task(_broadcast())
-
- def _normalize_handler_filter(self, value: Any, field_name: str) -> Set[str] | None:
- if value is None:
- return None
- if isinstance(value, str):
- return {value}
- try:
- iterator = iter(value)
- except TypeError as exc: # pragma: no cover - defensive
- raise ValueError(
- f"{field_name} must be an array of handler identifiers"
- ) from exc
-
- normalized: Set[str] = set()
- for item in iterator:
- if not isinstance(item, str):
- raise ValueError(
- f"{field_name} values must be handler identifier strings"
- )
- normalized.add(item)
- return normalized
-
- def _normalize_sid_filter(self, value: str | Iterable[str] | None) -> Set[str]:
- if value is None:
- return set()
- if isinstance(value, str):
- return {value}
- normalized: Set[str] = set()
- for item in value:
- normalized.add(str(item))
- return normalized
-
- def _select_handlers(
- self,
- namespace: str,
- *,
- include: Set[str] | None,
- exclude: Set[str] | None,
- ) -> tuple[list[WebSocketHandler], Set[str]]:
- registered = self.handlers.get(namespace, [])
- available_ids = {handler.identifier for handler in registered}
-
- if include is not None:
- unknown = include - available_ids
- if unknown:
- raise ValueError(
- f"Unknown handler(s) in includeHandlers for namespace '{namespace}': "
- f"{', '.join(sorted(unknown))}"
- )
- if exclude is not None:
- unknown = exclude - available_ids
- if unknown:
- raise ValueError(
- f"Unknown handler(s) in excludeHandlers for namespace '{namespace}': "
- f"{', '.join(sorted(unknown))}"
- )
-
- selected: list[WebSocketHandler] = []
- for handler in registered:
- ident = handler.identifier
- if include is not None and ident not in include:
- continue
- if exclude is not None and ident in exclude:
- continue
- selected.append(handler)
-
- return selected, available_ids
-
- def _resolve_correlation_id(self, payload: dict[str, Any]) -> str:
- value = payload.get("correlationId")
- if isinstance(value, str) and value.strip():
- correlation_id = value.strip()
- else:
- correlation_id = uuid.uuid4().hex
- payload["correlationId"] = correlation_id
- return correlation_id
-
- def register_handlers(
- self, handlers_by_namespace: dict[str, Iterable[WebSocketHandler]]
- ) -> None:
- for namespace, handlers in handlers_by_namespace.items():
- for handler in handlers:
- handler.bind_manager(self, namespace=namespace)
- if _ws_debug_enabled():
- PrintStyle.info(
- "Registered WebSocket handler %s namespace=%s"
- % (handler.identifier, namespace)
- )
- existing = self.handlers.get(namespace, [])
- if handler in existing:
- PrintStyle.warning(
- f"Duplicate handler registration for namespace '{namespace}'"
- )
- self.handlers[namespace].append(handler)
- self._debug(
- f"Registered handler {handler.identifier} namespace={namespace}"
- )
-
- def iter_event_types(self, namespace: str) -> Iterable[str]:
- return []
-
- def iter_namespaces(self) -> list[str]:
- return list(self.handlers.keys())
-
- async def _invoke_handler(
- self,
- handler: WebSocketHandler,
- event_type: str,
- payload: dict[str, Any],
- sid: str,
- ) -> _HandlerExecution:
- instrument = self._diagnostics_active()
- start = time.perf_counter() if instrument else None
- try:
- value = await self._get_handler_worker().execute_inside(
- handler.process_event, event_type, payload, sid
- )
- except Exception as exc: # pragma: no cover - handled by caller
- duration_ms = (
- (time.perf_counter() - start) * 1000 if start is not None else None
- )
- return _HandlerExecution(handler, exc, duration_ms)
- duration_ms = (
- (time.perf_counter() - start) * 1000 if start is not None else None
- )
- return _HandlerExecution(handler, value, duration_ms)
-
- async def handle_connect(
- self, namespace: str, sid: str, user_id: str | None = None
- ) -> None:
- self._ensure_dispatcher_loop()
- user_bucket = user_id or "single_user"
- identity: ConnectionIdentity = (namespace, sid)
- with self.lock:
- self.connections[identity] = ConnectionInfo(namespace=namespace, sid=sid)
- self._known_sids.add(identity)
- self.sid_to_user[identity] = user_bucket
- self.user_to_sids[self._ALL_USERS_BUCKET].add(identity)
- self.user_to_sids[user_bucket].add(identity)
- connection_count = sum(
- 1 for conn_identity in self.connections if conn_identity[0] == namespace
- )
- if _ws_debug_enabled():
- PrintStyle.info(f"WebSocket connected: namespace={namespace} sid={sid}")
- await self._run_lifecycle(namespace, lambda h: h.on_connect(sid))
- await self._flush_buffer(identity)
- if self._server_restart_enabled:
- await self.emit_to(
- namespace,
- sid,
- "server_restart",
- {
- "emittedAt": _utcnow()
- .isoformat(timespec="milliseconds")
- .replace("+00:00", "Z"),
- "runtimeId": runtime.get_runtime_id(),
- },
- handler_id=self._identifier,
- )
- if _ws_debug_enabled():
- PrintStyle.info(
- f"server_restart broadcast emitted to namespace={namespace} sid={sid}"
- )
- lifecycle_payload = {
- "namespace": namespace,
- "sid": sid,
- "connectionCount": connection_count,
- "timestamp": self._timestamp(),
- }
- await self._publish_diagnostic_event(
- {
- "kind": "lifecycle",
- "event": "connect",
- **lifecycle_payload,
- }
- )
- self._schedule_lifecycle_broadcast(
- namespace, LIFECYCLE_CONNECT_EVENT, lifecycle_payload
- )
-
- async def handle_disconnect(self, namespace: str, sid: str) -> None:
- self._ensure_dispatcher_loop()
- identity: ConnectionIdentity = (namespace, sid)
- with self.lock:
- self.connections.pop(identity, None)
- # session tracking cleanup
- user_bucket = self.sid_to_user.pop(identity, None)
- if self._ALL_USERS_BUCKET in self.user_to_sids:
- self.user_to_sids[self._ALL_USERS_BUCKET].discard(identity)
- if not self.user_to_sids[self._ALL_USERS_BUCKET]:
- self.user_to_sids.pop(self._ALL_USERS_BUCKET, None)
- if user_bucket and user_bucket in self.user_to_sids:
- self.user_to_sids[user_bucket].discard(identity)
- if not self.user_to_sids[user_bucket]:
- self.user_to_sids.pop(user_bucket, None)
- connection_count = sum(
- 1 for conn_identity in self.connections if conn_identity[0] == namespace
- )
- self.unregister_diagnostic_watcher(namespace, sid)
- PrintStyle.info(f"WebSocket disconnected: namespace={namespace} sid={sid}")
- await self._run_lifecycle(namespace, lambda h: h.on_disconnect(sid))
- lifecycle_payload = {
- "namespace": namespace,
- "sid": sid,
- "connectionCount": connection_count,
- "timestamp": self._timestamp(),
- }
- await self._publish_diagnostic_event(
- {
- "kind": "lifecycle",
- "event": "disconnect",
- **lifecycle_payload,
- }
- )
- self._schedule_lifecycle_broadcast(
- namespace, LIFECYCLE_DISCONNECT_EVENT, lifecycle_payload
- )
-
- async def route_event(
- self,
- namespace: str,
- event_type: str,
- data: dict[str, Any],
- sid: str,
- ack: Optional[Callable[[Any], None]] = None,
- *,
- include_handlers: Set[str] | None = None,
- exclude_handlers: Set[str] | None = None,
- allow_exclude: bool = False,
- handler_id: str | None = None,
- ) -> dict[str, Any]:
- self._ensure_dispatcher_loop()
- incoming = dict(data or {})
- correlation_id = self._resolve_correlation_id(incoming)
- self._debug(
- f"Routing event namespace={namespace} '{event_type}' sid={sid} correlation={correlation_id}"
- )
-
- include_meta_raw = incoming.pop("includeHandlers", None)
- exclude_meta_raw = incoming.pop("excludeHandlers", None)
-
- if "data" in incoming and isinstance(incoming.get("data"), dict):
- handler_payload = dict(incoming.get("data") or {})
- if "excludeSids" in incoming:
- handler_payload["excludeSids"] = incoming.get("excludeSids")
- else:
- handler_payload = dict(incoming)
-
- handler_payload["correlationId"] = correlation_id
-
- try:
- include_meta = self._normalize_handler_filter(
- include_meta_raw, "includeHandlers"
- )
- except ValueError as exc:
- error = self._build_error_result(
- handler_id=handler_id or self._identifier,
- code="INVALID_FILTER",
- message=str(exc),
- correlation_id=correlation_id,
- )
- if ack:
- ack({"correlationId": correlation_id, "results": [error]})
- return {"correlationId": correlation_id, "results": [error]}
-
- try:
- exclude_meta = self._normalize_handler_filter(
- exclude_meta_raw, "excludeHandlers"
- )
- except ValueError as exc:
- error = self._build_error_result(
- handler_id=handler_id or self._identifier,
- code="INVALID_FILTER",
- message=str(exc),
- correlation_id=correlation_id,
- )
- payload_error = {"correlationId": correlation_id, "results": [error]}
- if ack:
- ack(payload_error)
- return payload_error
-
- if exclude_meta_raw is not None and not allow_exclude:
- error = self._build_error_result(
- handler_id=handler_id or self._identifier,
- code="INVALID_FILTER",
- message="excludeHandlers is not supported for this operation",
- correlation_id=correlation_id,
- )
- if ack:
- ack({"correlationId": correlation_id, "results": [error]})
- return {"correlationId": correlation_id, "results": [error]}
-
- if include_handlers is not None and include_meta is not None:
- if include_handlers != include_meta:
- error = self._build_error_result(
- handler_id=handler_id or self._identifier,
- code="INVALID_FILTER",
- message="Conflicting includeHandlers filters supplied",
- correlation_id=correlation_id,
- )
- if ack:
- ack({"correlationId": correlation_id, "results": [error]})
- return {"correlationId": correlation_id, "results": [error]}
-
- if allow_exclude and exclude_handlers is not None and exclude_meta is not None:
- if exclude_handlers != exclude_meta:
- error = self._build_error_result(
- handler_id=handler_id or self._identifier,
- code="INVALID_FILTER",
- message="Conflicting excludeHandlers filters supplied",
- correlation_id=correlation_id,
- )
- if ack:
- ack({"correlationId": correlation_id, "results": [error]})
- return {"correlationId": correlation_id, "results": [error]}
-
- include = include_handlers or include_meta
- exclude = exclude_handlers or (exclude_meta if allow_exclude else None)
-
- try:
- WebSocketHandler.validate_event_type(event_type)
- except (TypeError, ValueError) as exc:
- error = self._build_error_result(
- handler_id=handler_id or self._identifier,
- code="INVALID_EVENT",
- message=str(exc),
- correlation_id=correlation_id,
- )
- if ack:
- ack({"correlationId": correlation_id, "results": [error]})
- return {"correlationId": correlation_id, "results": [error]}
-
- registered = self.handlers.get(namespace, [])
- if not registered:
- PrintStyle.warning(f"No handlers registered for namespace '{namespace}'")
- error = self._build_error_result(
- handler_id=handler_id or self._identifier,
- code="NO_HANDLERS",
- message=f"No handler for namespace '{namespace}'",
- correlation_id=correlation_id,
- )
- if ack:
- ack({"correlationId": correlation_id, "results": [error]})
- return {"correlationId": correlation_id, "results": [error]}
-
- try:
- selected_handlers, _ = self._select_handlers(
- namespace, include=include, exclude=exclude
- )
- except ValueError as exc:
- error = self._build_error_result(
- handler_id=handler_id or self._identifier,
- code="INVALID_FILTER",
- message=str(exc),
- correlation_id=correlation_id,
- )
- if ack:
- ack({"correlationId": correlation_id, "results": [error]})
- return {"correlationId": correlation_id, "results": [error]}
-
- if not selected_handlers:
- error = self._build_error_result(
- handler_id=handler_id or self._identifier,
- code="NO_HANDLERS",
- message=f"No handler for '{event_type}' after applying filters",
- correlation_id=correlation_id,
- )
- if ack:
- ack({"correlationId": correlation_id, "results": [error]})
- return {"correlationId": correlation_id, "results": [error]}
-
- with self.lock:
- info = self.connections.get((namespace, sid))
- if info:
- info.last_activity = _utcnow()
-
- executions = await asyncio.gather(
- *[
- self._invoke_handler(handler, event_type, dict(handler_payload), sid)
- for handler in selected_handlers
- ]
- )
-
- results: List[dict[str, Any]] = []
- for execution in executions:
- handler = execution.handler
- value = execution.value
- duration_ms = execution.duration_ms
-
- if isinstance(value, Exception): # pragma: no cover - defensive logging
- PrintStyle.error(
- f"Error in handler {handler.identifier} for '{event_type}' (correlation {correlation_id}): {value}"
- )
- results.append(
- self._build_error_result(
- handler_id=handler.identifier,
- code="HANDLER_ERROR",
- message="Internal server error",
- details=str(value),
- correlation_id=correlation_id,
- duration_ms=duration_ms,
- )
- )
- continue
-
- if isinstance(value, WebSocketResult):
- results.append(
- value.as_result(
- handler_id=handler.identifier,
- fallback_correlation_id=correlation_id,
- duration_ms=duration_ms,
- )
- )
- continue
-
- if value is None:
- helper_result = WebSocketResult(ok=True)
- elif isinstance(value, dict):
- helper_result = WebSocketResult(ok=True, data=value)
- else:
- helper_result = WebSocketResult(ok=True, data={"result": value})
-
- results.append(
- helper_result.as_result(
- handler_id=handler.identifier,
- fallback_correlation_id=correlation_id,
- duration_ms=duration_ms,
- )
- )
-
- await self._publish_diagnostic_event(
- lambda: {
- "kind": "inbound",
- "sourceNamespace": namespace,
- "namespace": namespace,
- "eventType": event_type,
- "sid": sid,
- "correlationId": correlation_id,
- "timestamp": self._timestamp(),
- "handlerCount": len(selected_handlers),
- "durationMs": sum((exec.duration_ms or 0.0) for exec in executions),
- "resultSummary": self._summarize_results(results),
- "payloadSummary": self._summarize_payload(handler_payload),
- }
- )
-
- response_payload = {"correlationId": correlation_id, "results": results}
- if ack:
- ack(response_payload)
- self._debug(
- f"Completed event namespace={namespace} '{event_type}' sid={sid} correlation={correlation_id}"
- )
- return response_payload
-
- async def request_for_sid(
- self,
- *,
- namespace: str,
- sid: str,
- event_type: str,
- data: dict[str, Any],
- timeout_ms: int = 0,
- handler_id: str | None = None,
- include_handlers: Set[str] | None = None,
- ) -> dict[str, Any]:
- payload = dict(data or {})
- correlation_id = self._resolve_correlation_id(payload)
-
- with self.lock:
- connected = (namespace, sid) in self.connections
- if not connected:
- return {
- "correlationId": correlation_id,
- "results": [
- self._build_error_result(
- handler_id=handler_id or self._identifier,
- code="CONNECTION_NOT_FOUND",
- message=f"Connection '{sid}' not found in namespace '{namespace}'",
- correlation_id=correlation_id,
- )
- ],
- }
-
- async def _invoke() -> dict[str, Any]:
- return await self.route_event(
- namespace,
- event_type,
- payload,
- sid,
- include_handlers=include_handlers,
- handler_id=handler_id,
- )
-
- if timeout_ms and timeout_ms > 0:
- try:
- return await asyncio.wait_for(_invoke(), timeout=timeout_ms / 1000)
- except asyncio.TimeoutError:
- PrintStyle.warning(
- f"request timeout for sid {sid} event '{event_type}'"
- )
- return {
- "correlationId": correlation_id,
- "results": [
- self._build_error_result(
- handler_id=handler_id or self._identifier,
- code="TIMEOUT",
- message="Request timeout",
- correlation_id=correlation_id,
- )
- ],
- }
- return await _invoke()
-
- async def route_event_all(
- self,
- namespace: str,
- event_type: str,
- data: dict[str, Any],
- *,
- timeout_ms: int = 0,
- exclude_handlers: Set[str] | None = None,
- handler_id: str | None = None,
- ) -> list[dict[str, Any]]:
- """Fan-out a request to all active connections and aggregate responses."""
-
- base_payload = dict(data or {})
- exclude_meta_raw = base_payload.pop("excludeHandlers", None)
- exclude_combined: Set[str] | None = exclude_handlers
- correlation_id = self._resolve_correlation_id(base_payload)
-
- if exclude_meta_raw is not None:
- try:
- exclude_meta = self._normalize_handler_filter(
- exclude_meta_raw, "excludeHandlers"
- )
- except ValueError as exc:
- error = self._build_error_result(
- handler_id=handler_id or self._identifier,
- code="INVALID_FILTER",
- message=str(exc),
- correlation_id=correlation_id,
- )
- return [
- {
- "sid": "__invalid__",
- "correlationId": correlation_id,
- "results": [error],
- }
- ]
-
- if exclude_combined is None:
- exclude_combined = exclude_meta
- elif exclude_meta is not None and exclude_combined != exclude_meta:
- error = self._build_error_result(
- handler_id=handler_id or self._identifier,
- code="INVALID_FILTER",
- message="Conflicting excludeHandlers filters supplied",
- correlation_id=correlation_id,
- )
- return [
- {
- "sid": "__invalid__",
- "correlationId": correlation_id,
- "results": [error],
- }
- ]
-
- self._debug(
- f"Starting requestAll namespace={namespace} for '{event_type}' correlation={correlation_id}"
- )
-
- with self.lock:
- active_sids = [
- conn_identity[1]
- for conn_identity in self.connections.keys()
- if conn_identity[0] == namespace
- ]
- if not active_sids:
- self._debug(
- f"No active connections for requestAll namespace={namespace} '{event_type}' correlation={correlation_id}"
- )
- return []
-
- timeout_seconds = timeout_ms / 1000 if timeout_ms and timeout_ms > 0 else None
-
- async def _invoke_for_sid(target_sid: str) -> dict[str, Any]:
- async def _dispatch() -> dict[str, Any]:
- return await self.route_event(
- namespace,
- event_type,
- base_payload,
- target_sid,
- allow_exclude=True,
- exclude_handlers=exclude_combined,
- handler_id=handler_id,
- )
-
- if timeout_seconds is None:
- return await _dispatch()
-
- try:
- task = asyncio.create_task(_dispatch())
- return await asyncio.wait_for(
- asyncio.shield(task), timeout=timeout_seconds
- )
- except asyncio.TimeoutError:
- PrintStyle.warning(
- f"requestAll timeout for sid {target_sid} correlation={correlation_id}"
- )
- # Ensure any late exceptions are observed so asyncio does not log
- # "Task exception was never retrieved".
- try:
- task.add_done_callback(lambda t: t.exception()) # type: ignore[arg-type]
- except Exception: # pragma: no cover - defensive
- pass
- return {
- "correlationId": correlation_id,
- "results": [
- self._build_error_result(
- handler_id=handler_id or self._identifier,
- code="TIMEOUT",
- message="Request timeout",
- correlation_id=correlation_id,
- )
- ],
- }
-
- tasks = {sid: asyncio.create_task(_invoke_for_sid(sid)) for sid in active_sids}
-
- aggregated: list[dict[str, Any]] = []
- for sid, task in tasks.items():
- result = await task
- if isinstance(result, dict):
- aggregated.append(
- {
- "sid": sid,
- "correlationId": result.get("correlationId", correlation_id),
- "results": result.get("results", []),
- }
- )
- else:
- aggregated.append(
- {
- "sid": sid,
- "correlationId": correlation_id,
- "results": result,
- }
- )
-
- self._debug(
- f"Completed requestAll namespace={namespace} for '{event_type}' correlation={correlation_id}"
- )
- return aggregated
-
- def _wrap_envelope(
- self,
- handler_id: str | None,
- data: dict[str, Any],
- *,
- correlation_id: str | None = None,
- ) -> dict[str, Any]:
- hid = handler_id or self._identifier
- ts = _utcnow().isoformat(timespec="milliseconds").replace("+00:00", "Z")
- event_id = str(uuid.uuid4())
- correlation = correlation_id or str(uuid.uuid4())
- return {
- "handlerId": hid,
- "eventId": event_id,
- "correlationId": correlation,
- "ts": ts,
- "data": data or {},
- }
-
- async def emit_to(
- self,
- namespace: str,
- sid: str,
- event_type: str,
- data: dict[str, Any],
- *,
- handler_id: str | None = None,
- correlation_id: str | None = None,
- diagnostic: bool = False,
- ) -> None:
- envelope = self._wrap_envelope(
- handler_id,
- data,
- correlation_id=correlation_id,
- )
- delivered = False
- buffered = False
- identity: ConnectionIdentity = (namespace, sid)
-
- with self.lock:
- connected = identity in self.connections
- known = identity in self._known_sids or identity in self.buffers
-
- if connected:
- self._debug(
- "Emit to namespace=%s sid=%s event=%s eventId=%s correlationId=%s handlerId=%s"
- % (
- namespace,
- sid,
- event_type,
- envelope.get("eventId"),
- envelope.get("correlationId"),
- envelope.get("handlerId"),
- )
- )
- await self._run_on_dispatcher_loop(
- self.socketio.emit(event_type, envelope, to=sid, namespace=namespace)
- )
- delivered = True
- else:
- if not known:
- raise ConnectionNotFoundError(sid, namespace=namespace)
- with self.lock:
- self._buffer_event(
- identity,
- event_type,
- data,
- handler_id,
- envelope["correlationId"],
- )
- buffered = True
-
- if not diagnostic:
- await self._publish_diagnostic_event(
- lambda: {
- "kind": "outbound",
- "direction": "emit_to",
- "eventType": event_type,
- "namespace": namespace,
- "sid": sid,
- "correlationId": envelope["correlationId"],
- "handlerId": envelope["handlerId"],
- "timestamp": self._timestamp(),
- "delivered": delivered,
- "buffered": buffered,
- "payloadSummary": self._summarize_payload(data),
- }
- )
-
- async def send_data(
- self,
- endpoint_name: str,
- event_name: str,
- data: dict[str, Any],
- connection_id: str | None = None,
- ) -> None:
- if connection_id is not None:
- await self.emit_to(endpoint_name, connection_id, event_name, data)
- return
- await self.broadcast(endpoint_name, event_name, data)
-
- async def broadcast(
- self,
- namespace: str,
- event_type: str,
- data: dict[str, Any],
- *,
- exclude_sids: str | Iterable[str] | None = None,
- handler_id: str | None = None,
- correlation_id: str | None = None,
- diagnostic: bool = False,
- ) -> None:
- excluded = self._normalize_sid_filter(exclude_sids)
-
- targets: list[str] = []
- with self.lock:
- current_identities = list(self.connections.keys())
- for conn_identity in current_identities:
- if conn_identity[0] != namespace:
- continue
- sid = conn_identity[1]
- if sid in excluded:
- continue
- targets.append(sid)
- await self.emit_to(
- namespace,
- sid,
- event_type,
- data,
- handler_id=handler_id,
- correlation_id=correlation_id,
- diagnostic=diagnostic,
- )
-
- if not diagnostic:
- await self._publish_diagnostic_event(
- lambda: {
- "kind": "outbound",
- "direction": "broadcast",
- "eventType": event_type,
- "namespace": namespace,
- "targets": targets[:10],
- "targetCount": len(targets),
- "correlationId": correlation_id,
- "handlerId": handler_id or self._identifier,
- "timestamp": self._timestamp(),
- "payloadSummary": self._summarize_payload(data),
- }
- )
-
- async def _run_lifecycle(
- self, namespace: str, fn: Callable[[WebSocketHandler], Any]
- ) -> None:
- seen: Set[WebSocketHandler] = set()
- coros: list[Any] = []
- for handler in self.handlers.get(namespace, []):
- if handler in seen:
- continue
- seen.add(handler)
- coros.append(self._get_handler_worker().execute_inside(fn, handler))
- if coros:
- await asyncio.gather(*coros, return_exceptions=True)
-
- def _buffer_event(
- self,
- identity: ConnectionIdentity,
- event_type: str,
- data: dict[str, Any],
- handler_id: str | None,
- correlation_id: str | None,
- ) -> None:
- namespace, sid = identity
- buffer = self.buffers[identity]
- buffer.append(
- BufferedEvent(
- event_type=event_type,
- data=data,
- handler_id=handler_id,
- correlation_id=correlation_id,
- )
- )
- while len(buffer) > BUFFER_MAX_SIZE:
- dropped = buffer.popleft()
- PrintStyle.warning(
- f"Dropping buffered event '{dropped.event_type}' for namespace={namespace} sid={sid} (overflow)"
- )
- self._debug(
- f"Buffered event namespace={namespace} '{event_type}' sid={sid} (queue length={len(buffer)})"
- )
-
- async def _flush_buffer(self, identity: ConnectionIdentity) -> None:
- self._ensure_dispatcher_loop()
- buffer = self.buffers.get(identity)
- if not buffer:
- return
- namespace, sid = identity
- now = _utcnow()
- delivered = 0
- while buffer:
- event = buffer.popleft()
- if now - event.timestamp > BUFFER_TTL:
- self._debug(
- f"Discarding expired buffered event '{event.event_type}' for sid {sid}"
- )
- continue
- envelope = self._wrap_envelope(
- event.handler_id,
- event.data,
- correlation_id=event.correlation_id,
- )
- self._debug(
- "Flush to sid=%s event=%s eventId=%s correlationId=%s handlerId=%s"
- % (
- sid,
- event.event_type,
- envelope.get("eventId"),
- envelope.get("correlationId"),
- envelope.get("handlerId"),
- )
- )
- await self._run_on_dispatcher_loop(
- self.socketio.emit(
- event.event_type, envelope, to=sid, namespace=namespace
- )
- )
- delivered += 1
- if identity in self.buffers:
- self.buffers.pop(identity, None)
- if delivered:
- PrintStyle.info(
- f"Flushed {delivered} buffered event(s) to namespace={namespace} sid={sid}"
- )
-
- def _build_error_result(
- self,
- *,
- handler_id: str | None = None,
- code: str,
- message: str,
- details: str | None = None,
- correlation_id: str | None = None,
- duration_ms: float | None = None,
- ) -> dict[str, Any]:
- error_payload = {"code": code, "error": message}
- if details:
- error_payload["details"] = details
- result: dict[str, Any] = {
- "handlerId": handler_id or self._identifier,
- "ok": False,
- "error": error_payload,
- }
- if correlation_id is not None:
- result["correlationId"] = correlation_id
- if duration_ms is not None:
- result["durationMs"] = round(duration_ms, 4)
- return result
-
- # Session tracking helpers (single-user defaults)
- def get_sids_for_user(self, user: str | None = None) -> list[str]:
- """Return SIDs for a user; single-user default returns all active SIDs."""
- with self.lock:
- bucket = self._ALL_USERS_BUCKET if user is None else user
- return list(self.user_to_sids.get(bucket, set())) # type: ignore
-
- def get_user_for_sid(self, sid: str) -> str | None:
- """Return user identifier for a SID or None."""
- with self.lock:
- return self.sid_to_user.get(sid) # type: ignore
-
- def set_server_restart_broadcast(self, enabled: bool) -> None:
- """Enable or disable automatic server restart broadcasts."""
-
- self._server_restart_enabled = bool(enabled)
diff --git a/helpers/websocket_namespace_discovery.py b/helpers/websocket_namespace_discovery.py
deleted file mode 100644
index 4f7b60b70..000000000
--- a/helpers/websocket_namespace_discovery.py
+++ /dev/null
@@ -1,186 +0,0 @@
-from __future__ import annotations
-
-import importlib.util
-import inspect
-import os
-from dataclasses import dataclass
-from types import ModuleType
-from typing import Iterable
-
-from helpers.files import get_abs_path
-from helpers.print_style import PrintStyle
-from helpers.websocket import WebSocketHandler
-
-
-@dataclass(frozen=True)
-class NamespaceDiscovery:
- namespace: str
- handler_classes: tuple[type[WebSocketHandler], ...]
- source_files: tuple[str, ...]
-
-
-def _to_namespace(entry_name: str) -> str:
- if entry_name == "_default":
- return "/"
- stripped = entry_name[: -len("_handler")] if entry_name.endswith("_handler") else entry_name
- if not stripped:
- raise ValueError(f"Invalid handler entry name: {entry_name!r}")
- return f"/{stripped}"
-
-
-def _unique_module_name(file_path: str) -> str:
- # Use a stable, unique module name derived from the relative path to avoid
- # collisions when importing different files with the same basename.
- rel_path = os.path.relpath(file_path, get_abs_path("."))
- rel_no_ext = os.path.splitext(rel_path)[0]
- safe = "".join(ch if ch.isalnum() else "_" for ch in rel_no_ext)
- return f"a0_ws_ns_{safe}"
-
-
-def _import_module(file_path: str) -> ModuleType:
- abs_path = get_abs_path(file_path)
- module_name = _unique_module_name(abs_path)
- spec = importlib.util.spec_from_file_location(module_name, abs_path)
- if spec is None or spec.loader is None:
- raise ImportError(f"Could not load module from {abs_path}")
- module = importlib.util.module_from_spec(spec)
- spec.loader.exec_module(module)
- return module
-
-
-def _get_handler_classes(module: ModuleType) -> list[type[WebSocketHandler]]:
- discovered: list[type[WebSocketHandler]] = []
- for _name, cls in inspect.getmembers(module, inspect.isclass):
- if cls is WebSocketHandler:
- continue
- if not issubclass(cls, WebSocketHandler):
- continue
- if cls.__module__ != module.__name__:
- continue
- discovered.append(cls)
- return discovered
-
-
-def discover_websocket_namespaces(
- *,
- handlers_folder: str = "python/websocket_handlers",
- include_root_default: bool = True,
-) -> list[NamespaceDiscovery]:
- """
- Discover websocket namespaces from first-level filesystem entries.
-
- Supported entries:
- - File entry: `*_handler.py` defines an application namespace.
- - Folder entry: `<name>/` or `<name>_handler/` defines an application namespace and loads
- `*.py` files one level deep (ignores `__init__.py` and ignores deeper nesting).
- - Reserved root mapping: `_default.py` maps to `/` when `include_root_default=True`.
- """
-
- abs_folder = get_abs_path(handlers_folder)
- entries: list[NamespaceDiscovery] = []
-
- try:
- filenames = sorted(os.listdir(abs_folder))
- except FileNotFoundError:
- PrintStyle.warning(f"WebSocket handlers folder not found: {abs_folder}")
- return []
-
- for entry in filenames:
- entry_path = os.path.join(abs_folder, entry)
-
- # Folder entries define namespaces and can host multiple handler modules.
- if os.path.isdir(entry_path):
- if entry.startswith("__"):
- continue
- namespace = _to_namespace(entry)
-
- handler_classes: list[type[WebSocketHandler]] = []
- source_files: list[str] = []
-
- try:
- child_names = sorted(os.listdir(entry_path))
- except FileNotFoundError:
- continue
-
- for child in child_names:
- if not child.endswith(".py"):
- continue
- if child == "__init__.py":
- continue
- child_path = os.path.join(entry_path, child)
- if not os.path.isfile(child_path):
- # Ignore deeper nesting.
- continue
-
- module = _import_module(child_path)
- discovered = _get_handler_classes(module)
- if not discovered:
- raise RuntimeError(
- f"WebSocket handler module {child_path} defines no WebSocketHandler subclasses"
- )
- if len(discovered) > 1:
- raise RuntimeError(
- f"WebSocket handler module {child_path} defines multiple WebSocketHandler subclasses: "
- f"{', '.join(sorted(cls.__name__ for cls in discovered))}"
- )
- handler_classes.append(discovered[0])
- source_files.append(child_path)
-
- if not handler_classes:
- PrintStyle.warning(
- f"WebSocket handlers folder entry '{entry_path}' is empty; treating namespace '{namespace}' as unregistered"
- )
- continue
-
- entries.append(
- NamespaceDiscovery(
- namespace=namespace,
- handler_classes=tuple(handler_classes),
- source_files=tuple(source_files),
- )
- )
- continue
-
- # File entries define namespaces.
- if not entry.endswith(".py"):
- continue
- if entry == "__init__.py":
- continue
-
- if entry == "_default.py":
- if not include_root_default:
- continue
- entry_name = "_default"
- else:
- if not entry.endswith("_handler.py"):
- continue
- entry_name = entry[: -len("_handler.py")]
-
- namespace = _to_namespace(entry_name)
- module_path = os.path.join(abs_folder, entry)
-
- module = _import_module(module_path)
- handler_classes = _get_handler_classes(module)
- if not handler_classes:
- raise RuntimeError(
- f"WebSocket handler module {module_path} defines no WebSocketHandler subclasses"
- )
- if len(handler_classes) > 1:
- raise RuntimeError(
- f"WebSocket handler module {module_path} defines multiple WebSocketHandler subclasses: "
- f"{', '.join(sorted(cls.__name__ for cls in handler_classes))}"
- )
-
- entries.append(
- NamespaceDiscovery(
- namespace=namespace,
- handler_classes=(handler_classes[0],),
- source_files=(module_path,),
- )
- )
-
- return entries
-
-
-def iter_discovered_namespaces(discoveries: Iterable[NamespaceDiscovery]) -> list[str]:
- return [entry.namespace for entry in discoveries]
diff --git a/python/websocket_handlers/_default.py b/python/websocket_handlers/_default.py
deleted file mode 100644
index 7fdbc4505..000000000
--- a/python/websocket_handlers/_default.py
+++ /dev/null
@@ -1,26 +0,0 @@
-from __future__ import annotations
-
-from typing import Any
-
-from helpers.websocket import WebSocketHandler, WebSocketResult
-
-
-class RootDefaultHandler(WebSocketHandler):
- """Reserved root (`/`) namespace diagnostics-only handler.
-
- Root is intentionally *not* used for application traffic. This handler exists to support
- optional low-risk diagnostics on `/` without making root behave like a global namespace.
- """
-
- @classmethod
- def requires_auth(cls) -> bool:
- return False
-
- @classmethod
- def requires_csrf(cls) -> bool:
- return False
-
- async def process_event(
- self, event_type: str, data: dict[str, Any], sid: str
- ) -> dict[str, Any] | WebSocketResult | None:
- return {"ok": True, "namespace": self.namespace, "sid": sid, "echo": data}
diff --git a/python/websocket_handlers/dev_websocket_test_handler.py b/python/websocket_handlers/dev_websocket_test_handler.py
deleted file mode 100644
index a55546e3a..000000000
--- a/python/websocket_handlers/dev_websocket_test_handler.py
+++ /dev/null
@@ -1,117 +0,0 @@
-from __future__ import annotations
-
-import asyncio
-from typing import Any, Dict
-
-from helpers.print_style import PrintStyle
-from helpers import runtime
-from helpers.websocket import WebSocketHandler, WebSocketResult
-
-
-class DevWebsocketTestHandler(WebSocketHandler):
- """Test harness handler powering the developer WebSocket validation component."""
-
- async def process_event(
- self, event_type: str, data: Dict[str, Any], sid: str
- ) -> dict[str, Any] | WebSocketResult | None:
- if event_type == "ws_event_console_subscribe":
- if not runtime.is_development():
- return self.result_error(
- code="NOT_AVAILABLE",
- message="Event console is available only in development mode",
- )
- registered = self.manager.register_diagnostic_watcher(self.namespace, sid)
- if not registered:
- return self.result_error(
- code="SUBSCRIBE_FAILED",
- message="Unable to subscribe to diagnostics",
- )
- return self.result_ok(
- {"status": "subscribed", "timestamp": data.get("requestedAt")}
- )
-
- if event_type == "ws_event_console_unsubscribe":
- self.manager.unregister_diagnostic_watcher(self.namespace, sid)
- return self.result_ok({"status": "unsubscribed"})
-
- if event_type == "ws_tester_emit":
- message = data.get("message", "emit")
- payload = {
- "message": message,
- "echo": True,
- "timestamp": data.get("timestamp"),
- }
- await self.broadcast("ws_tester_broadcast", payload)
- PrintStyle.info(f"Harness emit broadcasted message='{message}'")
- return None
-
- if event_type == "ws_tester_request":
- value = data.get("value")
- response = {
- "echo": value,
- "handler": self.identifier,
- "status": "ok",
- }
- PrintStyle.debug("Harness request responded with echo %s", value)
- return self.result_ok(
- response,
- correlation_id=data.get("correlationId"),
- )
-
- if event_type == "ws_tester_request_delayed":
- delay_ms = int(data.get("delay_ms", 0))
- await asyncio.sleep(delay_ms / 1000)
- PrintStyle.warning(
- "Harness delayed request finished after %s ms", delay_ms
- )
- return self.result_ok(
- {
- "status": "delayed",
- "delay_ms": delay_ms,
- "handler": self.identifier,
- },
- correlation_id=data.get("correlationId"),
- )
-
- if event_type == "ws_tester_trigger_persistence":
- phase = data.get("phase", "unknown")
- payload = {
- "phase": phase,
- "handler": self.identifier,
- }
- await self.emit_to(sid, "ws_tester_persistence", payload)
- PrintStyle.info(f"Harness persistence event phase='{phase}' -> {sid}")
- return None
-
- if event_type == "ws_tester_request_all":
- marker = data.get("marker")
- PrintStyle.debug(
- "Harness requestAll invoked by %s marker='%s'", sid, marker
- )
- exclude_handlers = data.get("excludeHandlers")
- aggregated = await self.request_all(
- "ws_tester_request",
- data,
- timeout_ms=2_000,
- exclude_handlers=exclude_handlers,
- )
- return self.result_ok(
- {"results": aggregated},
- correlation_id=data.get("correlationId"),
- )
-
- if event_type == "ws_tester_broadcast_demo_trigger":
- payload = {
- "demo": True,
- "requested_at": data.get("requested_at"),
- }
- await self.broadcast("ws_tester_broadcast_demo", payload)
- PrintStyle.info("Harness broadcast demo event dispatched")
- return None
-
- PrintStyle.warning(f"Harness received unknown event '{event_type}'")
- return self.result_error(
- code="HARNESS_UNKNOWN_EVENT",
- message="Unhandled event",
- details=event_type,
- )
diff --git a/python/websocket_handlers/hello_handler.py b/python/websocket_handlers/hello_handler.py
deleted file mode 100644
index 58eb51d77..000000000
--- a/python/websocket_handlers/hello_handler.py
+++ /dev/null
@@ -1,15 +0,0 @@
-from __future__ import annotations
-
-from helpers.print_style import PrintStyle
-from helpers.websocket import WebSocketHandler
-
-
-class HelloHandler(WebSocketHandler):
- """Sample handler used for foundational testing."""
-
- async def process_event(self, event_type: str, data: dict, sid: str):
- name = data.get("name") or "stranger"
- PrintStyle.info(f"hello_request from {sid} ({name})")
- return {"message": f"Hello, {name}!", "handler": self.identifier}
-
-
diff --git a/python/websocket_handlers/webui_handler.py b/python/websocket_handlers/webui_handler.py
deleted file mode 100644
index 016e5c4a3..000000000
--- a/python/websocket_handlers/webui_handler.py
+++ /dev/null
@@ -1,34 +0,0 @@
-from helpers.websocket import WebSocketHandler, WebSocketResult
-from helpers import extension
-
-
-class WebuiHandler(WebSocketHandler):
- async def on_connect(self, sid: str) -> None:
- await extension.call_extensions_async(
- "webui_ws_connect", agent=None, instance=self, sid=sid
- )
-
- async def on_disconnect(self, sid: str) -> None:
- await extension.call_extensions_async(
- "webui_ws_disconnect", agent=None, instance=self, sid=sid
- )
-
- async def process_event(
- self, event_type: str, data: dict, sid: str
- ) -> dict | WebSocketResult | None:
- response_data: dict = {}
-
- await extension.call_extensions_async(
- "webui_ws_event",
- agent=None,
- instance=self,
- sid=sid,
- event_type=event_type,
- data=data,
- response_data=response_data,
- )
-
- return self.result_ok(
- response_data,
- correlation_id=data.get("correlationId"),
- )
diff --git a/tests/test_websocket_client_api_surface.py b/tests/test_websocket_client_api_surface.py
deleted file mode 100644
index 2d683bec3..000000000
--- a/tests/test_websocket_client_api_surface.py
+++ /dev/null
@@ -1,41 +0,0 @@
-import re
-import sys
-from pathlib import Path
-
-
-PROJECT_ROOT = Path(__file__).resolve().parents[1]
-if str(PROJECT_ROOT) not in sys.path:
- sys.path.insert(0, str(PROJECT_ROOT))
-
-
-def _get_named_exports(source: str) -> set[str]:
- exports: set[str] = set()
-
- exports.update(re.findall(r"^export\s+function\s+([A-Za-z0-9_]+)\s*\(", source, flags=re.M))
- exports.update(re.findall(r"^export\s+const\s+([A-Za-z0-9_]+)\s*=", source, flags=re.M))
- exports.update(re.findall(r"^export\s+class\s+([A-Za-z0-9_]+)\s*[\{:]", source, flags=re.M))
-
- for m in re.findall(r"^export\s*\{([^}]+)\}\s*;?", source, flags=re.M):
- for item in m.split(","):
- item = item.strip()
- if not item:
- continue
- # Handle: `foo as bar`
- parts = item.split()
- if len(parts) >= 3 and parts[-2] == "as":
- exports.add(parts[-1])
- else:
- exports.add(parts[0])
-
- return exports
-
-
-def test_websocket_js_exports_minimal_namespaced_api_surface() -> None:
- source = (PROJECT_ROOT / "webui" / "js" / "websocket.js").read_text(encoding="utf-8")
- exports = _get_named_exports(source)
-
- assert "createNamespacedClient" in exports
- assert "getNamespacedClient" in exports
-
- assert "broadcast" not in exports
- assert "requestAll" not in exports
diff --git a/tests/test_websocket_csrf.py b/tests/test_websocket_csrf.py
deleted file mode 100644
index 1fc61c3c2..000000000
--- a/tests/test_websocket_csrf.py
+++ /dev/null
@@ -1,51 +0,0 @@
-import sys
-from pathlib import Path
-
-PROJECT_ROOT = Path(__file__).resolve().parents[1]
-if str(PROJECT_ROOT) not in sys.path:
- sys.path.insert(0, str(PROJECT_ROOT))
-
-from helpers.websocket import validate_ws_origin
-
-
-def test_validate_ws_origin_allows_same_origin_with_explicit_port():
- ok, reason = validate_ws_origin(
- {
- "HTTP_ORIGIN": "http://localhost:5000",
- "HTTP_HOST": "localhost:5000",
- }
- )
- assert ok is True
- assert reason is None
-
-
-def test_validate_ws_origin_allows_default_https_port_without_explicit_port():
- ok, reason = validate_ws_origin(
- {
- "HTTP_ORIGIN": "https://example.com",
- "HTTP_HOST": "example.com",
- }
- )
- assert ok is True
- assert reason is None
-
-
-def test_validate_ws_origin_rejects_missing_origin():
- ok, reason = validate_ws_origin(
- {
- "HTTP_HOST": "localhost:5000",
- }
- )
- assert ok is False
- assert reason == "missing_origin"
-
-
-def test_validate_ws_origin_rejects_cross_origin():
- ok, reason = validate_ws_origin(
- {
- "HTTP_ORIGIN": "http://evil.test",
- "HTTP_HOST": "localhost:5000",
- }
- )
- assert ok is False
- assert reason == "origin_host_mismatch"
diff --git a/tests/test_websocket_handlers.py b/tests/test_websocket_handlers.py
deleted file mode 100644
index 9c965f299..000000000
--- a/tests/test_websocket_handlers.py
+++ /dev/null
@@ -1,176 +0,0 @@
-import sys
-import threading
-from pathlib import Path
-
-import pytest
-
-PROJECT_ROOT = Path(__file__).resolve().parents[1]
-if str(PROJECT_ROOT) not in sys.path:
- sys.path.insert(0, str(PROJECT_ROOT))
-
-from helpers.websocket import (
- WebSocketHandler,
- WebSocketResult,
- SingletonInstantiationError,
-)
-
-
-class _FakeSocketIO:
- async def emit(self, *_args, **_kwargs): # pragma: no cover - helper stub
- return None
-
- async def disconnect(self, *_args, **_kwargs): # pragma: no cover - helper stub
- return None
-
-
-class _TestHandler(WebSocketHandler):
- @classmethod
- def get_event_types(cls) -> list[str]:
- return ["test_event"]
-
- async def process_event(self, event_type: str, data: dict, sid: str) -> None:
- return None
-
-
-def _make_handler() -> _TestHandler:
- _TestHandler._reset_instance_for_testing()
- return _TestHandler.get_instance(_FakeSocketIO(), threading.RLock())
-
-
-def test_websocket_result_ok_clones_payload():
- payload = {"value": 1}
- result = WebSocketResult.ok(payload)
-
- assert result.as_result(
- handler_id="handler",
- fallback_correlation_id="corr",
- )["data"] == payload
-
- payload["value"] = 2
- assert result.as_result(
- handler_id="handler",
- fallback_correlation_id="corr",
- )["data"] == {"value": 1}
-
-
-def test_websocket_result_error_contains_metadata():
- result = WebSocketResult.error(
- code="E_TEST",
- message="failure",
- details="additional",
- correlation_id="corr",
- duration_ms=12.5,
- )
-
- as_payload = result.as_result(handler_id="handler", fallback_correlation_id=None)
- assert as_payload["ok"] is False
- assert as_payload["error"] == {
- "code": "E_TEST",
- "error": "failure",
- "details": "additional",
- }
- assert as_payload["correlationId"] == "corr"
- assert as_payload["durationMs"] == pytest.approx(12.5, rel=1e-3)
-
-
-def test_websocket_result_applies_fallback_correlation_and_duration():
- result = WebSocketResult.ok(duration_ms=5.4321)
- payload = result.as_result(
- handler_id="handler",
- fallback_correlation_id="corr-fallback",
- )
- assert payload["correlationId"] == "corr-fallback"
- assert payload["durationMs"] == pytest.approx(5.4321, rel=1e-3)
-
-
-def test_handler_result_helpers_return_websocket_result_instances():
- handler = _make_handler()
-
- ok_result = handler.result_ok({"foo": "bar"}, correlation_id="cid")
- assert isinstance(ok_result, WebSocketResult)
- ok_payload = ok_result.as_result(
- handler_id="handler",
- fallback_correlation_id=None,
- )
- assert ok_payload["ok"] is True
- assert ok_payload["data"] == {"foo": "bar"}
- assert ok_payload["correlationId"] == "cid"
-
- err_result = handler.result_error(
- code="E_BAD",
- message="boom",
- details="missing",
- correlation_id="err",
- )
- assert isinstance(err_result, WebSocketResult)
- err_payload = err_result.as_result(
- handler_id="handler",
- fallback_correlation_id=None,
- )
- assert err_payload["ok"] is False
- assert err_payload["error"] == {
- "code": "E_BAD",
- "error": "boom",
- "details": "missing",
- }
- assert err_payload["correlationId"] == "err"
-
-
-def test_result_error_requires_error_payload():
- with pytest.raises(ValueError):
- WebSocketResult(ok=False)
-
- with pytest.raises(ValueError):
- WebSocketResult.error(code="", message="boom")
-
-
-def test_handler_direct_instantiation_disallowed():
- with pytest.raises(SingletonInstantiationError):
- _TestHandler(_FakeSocketIO(), threading.RLock())
-
-
-def test_get_instance_returns_singleton():
- _TestHandler._reset_instance_for_testing()
- socketio = _FakeSocketIO()
- lock = threading.RLock()
- first = _TestHandler.get_instance(socketio, lock)
- second = _TestHandler.get_instance(None, None)
- assert first is second
-
-
-async def test_state_sync_handler_registers_and_routes_state_request():
- from helpers.websocket_manager import WebSocketManager
- from python.websocket_handlers.webui_handler import WebuiHandler
- from helpers.state_monitor import _reset_state_monitor_for_testing
-
- _reset_state_monitor_for_testing()
- WebuiHandler._reset_instance_for_testing()
-
- socketio = _FakeSocketIO()
- lock = threading.RLock()
- manager = WebSocketManager(socketio, lock)
- handler = WebuiHandler.get_instance(socketio, lock)
- namespace = "/webui"
- manager.register_handlers({namespace: [handler]})
- await manager.handle_connect(namespace, "sid-1")
-
- response = await manager.route_event(
- namespace,
- "state_request",
- {
- "correlationId": "smoke-1",
- "ts": "2025-12-28T00:00:00.000Z",
- "data": {
- "context": None,
- "log_from": 0,
- "notifications_from": 0,
- "timezone": "UTC",
- },
- },
- "sid-1",
- )
-
- assert response["correlationId"] == "smoke-1"
- assert response["results"] and response["results"][0]["ok"] is True
- await manager.handle_disconnect(namespace, "sid-1")
diff --git a/tests/test_websocket_harness.py b/tests/test_websocket_harness.py
deleted file mode 100644
index b94cfa3d5..000000000
--- a/tests/test_websocket_harness.py
+++ /dev/null
@@ -1,173 +0,0 @@
-import sys
-import threading
-from pathlib import Path
-from typing import Any
-
-import pytest
-
-PROJECT_ROOT = Path(__file__).resolve().parents[1]
-if str(PROJECT_ROOT) not in sys.path:
- sys.path.insert(0, str(PROJECT_ROOT))
-
-from helpers.websocket_manager import WebSocketManager
-from python.websocket_handlers.dev_websocket_test_handler import (
- DevWebsocketTestHandler,
-)
-
-NAMESPACE = "/dev_websocket_test"
-
-
-class FakeSocketIOServer:
- def __init__(self) -> None:
- from unittest.mock import AsyncMock
-
- self.emit = AsyncMock()
- self.disconnect = AsyncMock()
-
-
-async def _create_manager() -> tuple[WebSocketManager, DevWebsocketTestHandler, FakeSocketIOServer]:
- socketio = FakeSocketIOServer()
- manager = WebSocketManager(socketio, threading.RLock())
- DevWebsocketTestHandler._reset_instance_for_testing()
- handler = DevWebsocketTestHandler.get_instance(socketio, threading.RLock())
- manager.register_handlers({NAMESPACE: [handler]})
- await manager.handle_connect(NAMESPACE, "sid-primary")
- return manager, handler, socketio
-
-
-async def test_harness_emit_broadcasts_to_active_connections():
- manager, _handler, socketio = await _create_manager()
-
- await manager.route_event(
- NAMESPACE,
- "ws_tester_emit",
- {"message": "emit-check", "timestamp": "2025-10-29T12:00:00Z"},
- "sid-primary",
- )
-
- socketio.emit.assert_awaited()
- emit_calls = [(call.args, call.kwargs) for call in socketio.emit.await_args_list]
- match = next((c for c in emit_calls if c[0] and c[0][0] == "ws_tester_broadcast"), None)
- assert match is not None
- args, kwargs = match
- envelope = args[1]
- assert envelope["handlerId"].endswith("DevWebsocketTestHandler")
- assert envelope["data"]["message"] == "emit-check"
- assert kwargs == {"to": "sid-primary", "namespace": NAMESPACE}
-
-
-async def test_harness_request_returns_per_handler_result():
- manager, _handler, _socketio = await _create_manager()
-
- response = await manager.route_event(
- NAMESPACE,
- "ws_tester_request",
- {"value": 42},
- "sid-primary",
- )
-
- assert isinstance(response, dict)
- assert response["results"]
- first = response["results"][0]
- assert first["ok"] is True
- assert first["data"]["echo"] == 42
- assert response["correlationId"]
- assert first["handlerId"].endswith("DevWebsocketTestHandler")
- assert first["correlationId"] == response["correlationId"]
-
-
-async def test_harness_request_delayed_waits_for_sleep(monkeypatch):
- manager, _handler, _socketio = await _create_manager()
-
- calls: list[float] = []
-
- async def _fake_sleep(delay: float) -> None: # pragma: no cover - helper
- calls.append(delay)
-
- monkeypatch.setattr(
- "python.websocket_handlers.dev_websocket_test_handler.asyncio.sleep",
- _fake_sleep,
- )
-
- await manager.route_event(
- NAMESPACE,
- "ws_tester_request_delayed",
- {"delay_ms": 1500},
- "sid-primary",
- )
-
- assert calls == [1.5]
-
-
-async def test_harness_persistence_emit_targets_requesting_sid():
- manager, _handler, socketio = await _create_manager()
-
- await manager.route_event(
- NAMESPACE,
- "ws_tester_trigger_persistence",
- {"phase": "after"},
- "sid-primary",
- )
-
- socketio.emit.assert_awaited()
- emit_calls = [(call.args, call.kwargs) for call in socketio.emit.await_args_list]
- match = next((c for c in emit_calls if c[0] and c[0][0] == "ws_tester_persistence"), None)
- assert match is not None
- args, kwargs = match
- payload = args[1]
- assert payload["handlerId"] == _handler.identifier
- assert payload["data"] == {"phase": "after", "handler": _handler.identifier}
- assert kwargs == {"to": "sid-primary", "namespace": NAMESPACE}
-
-
-async def test_harness_request_all_aggregates_all_connections():
- manager, _handler, _socketio = await _create_manager()
- await manager.handle_connect(NAMESPACE, "sid-secondary")
-
- response = await manager.route_event(
- NAMESPACE,
- "ws_tester_request_all",
- {"marker": "aggregate"},
- "sid-primary",
- )
-
- assert response["results"] and response["results"][0]["ok"] is True
- data = response["results"][0]["data"]
- aggregated = data.get("results") or data.get("result")
- assert isinstance(aggregated, list)
- by_sid: dict[str, Any] = {entry["sid"]: entry["results"] for entry in aggregated}
- assert set(by_sid.keys()) == {"sid-primary", "sid-secondary"}
- for results in by_sid.values():
- assert results and results[0]["ok"] is True
- payload = results[0]["data"]
- assert payload["handler"].endswith("DevWebsocketTestHandler")
- assert results[0]["handlerId"].endswith("DevWebsocketTestHandler")
- assert results[0]["correlationId"] == response["results"][0]["correlationId"]
- assert response["correlationId"]
-
-
-async def test_harness_request_all_respects_exclude_handlers():
- manager, handler, _socketio = await _create_manager()
- await manager.handle_connect(NAMESPACE, "sid-secondary")
-
- response = await manager.route_event(
- NAMESPACE,
- "ws_tester_request_all",
- {
- "marker": "exclude",
- "excludeHandlers": [handler.identifier],
- },
- "sid-primary",
- )
-
- assert response["correlationId"]
- first = response["results"][0]
- assert first["ok"] is False
- assert first["error"]["code"] == "INVALID_FILTER"
- assert "excludeHandlers" in first["error"]["error"]
diff --git a/tests/test_websocket_manager.py b/tests/test_websocket_manager.py
deleted file mode 100644
index dacdb7c86..000000000
--- a/tests/test_websocket_manager.py
+++ /dev/null
@@ -1,853 +0,0 @@
-import asyncio
-import sys
-import threading
-import time
-from pathlib import Path
-from typing import Any
-from unittest.mock import AsyncMock, patch
-
-import pytest
-
-PROJECT_ROOT = Path(__file__).resolve().parents[1]
-if str(PROJECT_ROOT) not in sys.path:
- sys.path.insert(0, str(PROJECT_ROOT))
-
-from helpers.websocket import ConnectionNotFoundError, WebSocketHandler, WebSocketResult
-from helpers.websocket_manager import (
- WebSocketManager,
- BUFFER_TTL,
- DIAGNOSTIC_EVENT,
- LIFECYCLE_CONNECT_EVENT,
- LIFECYCLE_DISCONNECT_EVENT,
-)
-
-NAMESPACE = "/test"
-
-
-class FakeSocketIOServer:
- def __init__(self):
- self.emit = AsyncMock()
- self.disconnect = AsyncMock()
-
-
-class DummyHandler(WebSocketHandler):
- def __init__(self, socketio, lock, results):
- super().__init__(socketio, lock)
- self.results = results
-
- @classmethod
- def get_event_types(cls) -> list[str]:
- return ["dummy"]
-
- async def process_event(self, event_type: str, data: dict[str, Any], sid: str):
- response = {"sid": sid, "data": data}
- self.results.append(response)
- return response
-
-
-async def test_connect_disconnect_updates_registry():
- socketio = FakeSocketIOServer()
- manager = WebSocketManager(socketio, threading.RLock())
-
- await manager.handle_connect(NAMESPACE, "abc")
- assert (NAMESPACE, "abc") in manager.connections
-
- await manager.handle_disconnect(NAMESPACE, "abc")
- assert (NAMESPACE, "abc") not in manager.connections
-
-
-async def test_server_restart_broadcast_emitted_when_enabled():
- socketio = FakeSocketIOServer()
- manager = WebSocketManager(socketio, threading.RLock())
- manager.set_server_restart_broadcast(True)
-
- await manager.handle_connect(NAMESPACE, "sid-restart")
-
- socketio.emit.assert_awaited()
- args, kwargs = socketio.emit.await_args_list[0]
- assert args[0] == "server_restart"
- envelope = args[1]
- assert envelope["handlerId"] == manager._identifier # noqa: SLF001
- assert envelope["data"]["runtimeId"]
- assert kwargs == {"to": "sid-restart", "namespace": NAMESPACE}
-
-
-async def test_server_restart_broadcast_skipped_when_disabled():
- socketio = FakeSocketIOServer()
- manager = WebSocketManager(socketio, threading.RLock())
- manager.set_server_restart_broadcast(False)
-
- await manager.handle_connect(NAMESPACE, "sid-no-restart")
-
- assert socketio.emit.await_count == 0
-
-
-async def test_broadcast_performance_smoke(monkeypatch):
- socketio = FakeSocketIOServer()
- manager = WebSocketManager(socketio, threading.RLock())
-
- for idx in range(50):
- await manager.handle_connect(NAMESPACE, f"sid-{idx}")
-
- import time
-
- start = time.perf_counter()
- await manager.broadcast(NAMESPACE, "perf_event", {"ok": True})
- duration_ms = (time.perf_counter() - start) * 1000
-
- assert socketio.emit.await_count == 50
- assert duration_ms < 300
-
-
-async def test_route_event_invokes_handler_and_ack():
- socketio = FakeSocketIOServer()
- manager = WebSocketManager(socketio, threading.RLock())
-
- results = []
- DummyHandler._reset_instance_for_testing()
- handler = DummyHandler.get_instance(socketio, threading.RLock(), results)
- manager.register_handlers({NAMESPACE: [handler]})
- await manager.handle_connect(NAMESPACE, "sid-1")
-
- response = await manager.route_event(NAMESPACE, "dummy", {"foo": "bar"}, "sid-1")
-
- assert results[0]["sid"] == "sid-1"
- assert results[0]["data"]["foo"] == "bar"
- assert "correlationId" in results[0]["data"]
-
- assert isinstance(response, dict)
- assert "correlationId" in response
- assert isinstance(response["results"], list)
- entry = response["results"][0]
- assert entry["ok"] is True
- assert entry["data"]["sid"] == "sid-1"
- assert entry["data"]["data"]["foo"] == "bar"
-
-
-async def test_route_event_no_handler_returns_standard_error():
- socketio = FakeSocketIOServer()
- manager = WebSocketManager(socketio, threading.RLock())
- await manager.handle_connect(NAMESPACE, "sid-1")
-
- response = await manager.route_event(NAMESPACE, "missing", {}, "sid-1")
-
- assert len(response["results"]) == 1
- result = response["results"][0]
- assert result["handlerId"].endswith("WebSocketManager")
- assert result["ok"] is False
- assert result["error"]["code"] == "NO_HANDLERS"
- assert (
- result["error"]["error"]
- == f"No handler for namespace '{NAMESPACE}' event 'missing'"
- )
-
-
-async def test_route_event_all_returns_empty_when_no_connections():
- socketio = FakeSocketIOServer()
- manager = WebSocketManager(socketio, threading.RLock())
-
- results = await manager.route_event_all(NAMESPACE, "event", {}, timeout_ms=1000)
-
- assert results == []
-
-
-async def test_route_event_all_aggregates_results():
- socketio = FakeSocketIOServer()
- manager = WebSocketManager(socketio, threading.RLock())
-
- class EchoHandler(WebSocketHandler):
- @classmethod
- def get_event_types(cls) -> list[str]:
- return ["multi"]
-
- async def process_event(self, event_type: str, data: dict[str, Any], sid: str):
- return {"sid": sid, "echo": data}
-
- EchoHandler._reset_instance_for_testing()
- handler = EchoHandler.get_instance(socketio, threading.RLock())
- manager.register_handlers({NAMESPACE: [handler]})
-
- await manager.handle_connect(NAMESPACE, "sid-1")
- await manager.handle_connect(NAMESPACE, "sid-2")
-
- aggregated = await manager.route_event_all(
- NAMESPACE, "multi", {"value": 42}, timeout_ms=1000
- )
-
- assert len(aggregated) == 2
- by_sid = {entry["sid"]: entry for entry in aggregated}
- assert by_sid["sid-1"]["results"][0]["ok"] is True
- payload_sid1 = by_sid["sid-1"]["results"][0]["data"]
- assert payload_sid1["sid"] == "sid-1"
- assert payload_sid1["echo"]["value"] == 42
- assert "correlationId" in payload_sid1["echo"]
- assert by_sid["sid-2"]["results"][0]["ok"] is True
- payload_sid2 = by_sid["sid-2"]["results"][0]["data"]
- assert payload_sid2["sid"] == "sid-2"
- assert payload_sid2["echo"]["value"] == 42
- assert by_sid["sid-1"]["correlationId"]
-
-
-async def test_route_event_all_timeout_marks_error():
- socketio = FakeSocketIOServer()
- manager = WebSocketManager(socketio, threading.RLock())
-
- class SlowHandler(WebSocketHandler):
- @classmethod
- def get_event_types(cls) -> list[str]:
- return ["slow"]
-
- async def process_event(self, event_type: str, data: dict[str, Any], sid: str):
- await asyncio.sleep(0.2)
- return {"status": "done"}
-
- SlowHandler._reset_instance_for_testing()
- handler = SlowHandler.get_instance(socketio, threading.RLock())
- manager.register_handlers({NAMESPACE: [handler]})
- await manager.handle_connect(NAMESPACE, "sid-1")
-
- aggregated = await manager.route_event_all(NAMESPACE, "slow", {}, timeout_ms=50)
-
- assert len(aggregated) == 1
- first_entry = aggregated[0]
- result = first_entry["results"][0]
- assert result["ok"] is False
- assert result["error"] == {"code": "TIMEOUT", "error": "Request timeout"}
- assert first_entry["correlationId"]
-
-
-async def test_route_event_exception_standardizes_error_payload():
- socketio = FakeSocketIOServer()
- manager = WebSocketManager(socketio, threading.RLock())
-
- class FailingHandler(WebSocketHandler):
- @classmethod
- def get_event_types(cls) -> list[str]:
- return ["boom"]
-
- async def process_event(self, event_type: str, data: dict[str, Any], sid: str):
- raise RuntimeError("kaboom")
-
- FailingHandler._reset_instance_for_testing()
- handler = FailingHandler.get_instance(socketio, threading.RLock())
- manager.register_handlers({NAMESPACE: [handler]})
- await manager.handle_connect(NAMESPACE, "sid-1")
-
- response = await manager.route_event(NAMESPACE, "boom", {}, "sid-1")
-
- assert len(response["results"]) == 1
- result = response["results"][0]
- assert result["handlerId"].endswith("FailingHandler")
- assert result["ok"] is False
- assert result["error"]["code"] == "HANDLER_ERROR"
- assert result["error"]["error"] == "Internal server error"
- assert "details" in result["error"]
-
-
-async def test_route_event_offloads_blocking_handlers():
- socketio = FakeSocketIOServer()
- manager = WebSocketManager(socketio, threading.RLock())
-
- class BlockingHandler(WebSocketHandler):
- @classmethod
- def get_event_types(cls) -> list[str]:
- return ["block"]
-
- async def process_event(self, event_type: str, data: dict[str, Any], sid: str):
- time.sleep(0.2)
- return {"status": "done"}
-
- BlockingHandler._reset_instance_for_testing()
- handler = BlockingHandler.get_instance(socketio, threading.RLock())
- manager.register_handlers({NAMESPACE: [handler]})
- await manager.handle_connect(NAMESPACE, "sid-1")
-
- route_task = asyncio.create_task(
- manager.route_event(NAMESPACE, "block", {}, "sid-1")
- )
- await asyncio.sleep(0)
-
- t0 = time.perf_counter()
- await asyncio.sleep(0.05)
- elapsed = time.perf_counter() - t0
- assert elapsed < 0.15
-
- response = await route_task
- assert response["results"]
-
-
-async def test_route_event_unwraps_ts_data_envelope_and_preserves_correlation_id():
- socketio = FakeSocketIOServer()
- manager = WebSocketManager(socketio, threading.RLock())
-
- results: list[dict[str, Any]] = []
- DummyHandler._reset_instance_for_testing()
- handler = DummyHandler.get_instance(socketio, threading.RLock(), results)
- manager.register_handlers({NAMESPACE: [handler]})
- await manager.handle_connect(NAMESPACE, "sid-1")
-
- response = await manager.route_event(
- NAMESPACE,
- "dummy",
- {
- "correlationId": "client-1",
- "ts": "2025-10-29T12:00:00.000Z",
- "data": {"value": 123},
- },
- "sid-1",
- )
-
- assert response["correlationId"] == "client-1"
- assert len(results) == 1
- handler_payload = results[0]["data"]
- assert handler_payload["value"] == 123
- assert handler_payload["correlationId"] == "client-1"
- assert "ts" not in handler_payload
- assert "data" not in handler_payload
-
-
-async def test_emit_to_unknown_sid_raises_error():
- socketio = FakeSocketIOServer()
- manager = WebSocketManager(socketio, threading.RLock())
-
- with pytest.raises(ConnectionNotFoundError):
- await manager.emit_to(NAMESPACE, "unknown", "event", {})
-
-
-async def test_emit_to_known_disconnected_sid_buffers():
- socketio = FakeSocketIOServer()
- manager = WebSocketManager(socketio, threading.RLock())
- await manager.handle_connect(NAMESPACE, "sid-1")
- await manager.handle_disconnect(NAMESPACE, "sid-1")
-
- await manager.emit_to(
- NAMESPACE, "sid-1", "event", {"a": 1}, correlation_id="corr-1"
- )
-
- assert (NAMESPACE, "sid-1") in manager.buffers
- buffered = list(manager.buffers[(NAMESPACE, "sid-1")])
- assert len(buffered) == 1
- assert buffered[0].event_type == "event"
- assert buffered[0].data == {"a": 1}
- assert buffered[0].correlation_id == "corr-1"
-
-
-async def test_buffer_overflow_drops_oldest(monkeypatch):
- socketio = FakeSocketIOServer()
- manager = WebSocketManager(socketio, threading.RLock())
-
- await manager.handle_connect(NAMESPACE, "offline")
- await manager.handle_disconnect(NAMESPACE, "offline")
-
- monkeypatch.setattr("helpers.websocket_manager.BUFFER_MAX_SIZE", 2)
-
- await manager.emit_to(NAMESPACE, "offline", "event", {"idx": 0})
- await manager.emit_to(NAMESPACE, "offline", "event", {"idx": 1})
- await manager.emit_to(NAMESPACE, "offline", "event", {"idx": 2})
-
- buffer = manager.buffers[(NAMESPACE, "offline")]
- assert len(buffer) == 2
- assert buffer[0].data["idx"] == 1
- assert buffer[1].data["idx"] == 2
-
-
-async def test_expired_buffer_entries_are_discarded(monkeypatch):
- socketio = FakeSocketIOServer()
- manager = WebSocketManager(socketio, threading.RLock())
-
- await manager.handle_connect(NAMESPACE, "sid-expired")
- await manager.handle_disconnect(NAMESPACE, "sid-expired")
-
- from datetime import timedelta, timezone, datetime
-
- past = datetime.now(timezone.utc) - (BUFFER_TTL + timedelta(seconds=5))
- future = past + BUFFER_TTL + timedelta(seconds=10)
-
- await manager.emit_to(NAMESPACE, "sid-expired", "event", {"a": 1})
- manager.buffers[(NAMESPACE, "sid-expired")][0].timestamp = past
-
- socketio.emit.reset_mock()
-
- monkeypatch.setattr(
- "helpers.websocket_manager._utcnow",
- lambda: future,
- )
- await manager.handle_connect(NAMESPACE, "sid-expired")
-
- assert socketio.emit.await_count == 0
- assert (NAMESPACE, "sid-expired") not in manager.buffers
-
-
-async def test_flush_buffer_delivers_and_logs(monkeypatch):
- socketio = FakeSocketIOServer()
- manager = WebSocketManager(socketio, threading.RLock())
- await manager.handle_connect(NAMESPACE, "sid-1")
- await manager.handle_disconnect(NAMESPACE, "sid-1")
-
- await manager.emit_to(NAMESPACE, "sid-1", "event", {"a": 1})
-
- await manager.handle_connect(NAMESPACE, "sid-1")
-
- assert len(socketio.emit.await_args_list) == 1
- awaited_call = socketio.emit.await_args_list[0]
- assert awaited_call.args[0] == "event"
- envelope = awaited_call.args[1]
- assert envelope["data"] == {"a": 1}
- assert "eventId" in envelope and "handlerId" in envelope and "ts" in envelope
- assert awaited_call.kwargs == {"to": "sid-1", "namespace": NAMESPACE}
- assert (NAMESPACE, "sid-1") not in manager.buffers
-
-
-async def test_broadcast_excludes_multiple_sids():
- socketio = FakeSocketIOServer()
- manager = WebSocketManager(socketio, threading.RLock())
-
- for sid in ("sid-1", "sid-2", "sid-3"):
- await manager.handle_connect(NAMESPACE, sid)
-
- await manager.broadcast(
- NAMESPACE,
- "event",
- {"foo": "bar"},
- exclude_sids={"sid-1", "sid-3"},
- handler_id="custom.broadcast",
- correlation_id="corr-b",
- )
-
- assert len(socketio.emit.await_args_list) == 1
- awaited_call = socketio.emit.await_args_list[0]
- assert awaited_call.args[0] == "event"
- envelope = awaited_call.args[1]
- assert envelope["data"] == {"foo": "bar"}
- assert envelope["handlerId"] == "custom.broadcast"
- assert envelope["correlationId"] == "corr-b"
- assert "eventId" in envelope and "ts" in envelope
- assert awaited_call.kwargs == {"to": "sid-2", "namespace": NAMESPACE}
-
-
-async def test_emit_to_wraps_envelope_with_metadata():
- socketio = FakeSocketIOServer()
- manager = WebSocketManager(socketio, threading.RLock())
- await manager.handle_connect(NAMESPACE, "sid-meta")
-
- await manager.emit_to(
- NAMESPACE,
- "sid-meta",
- "meta_event",
- {"payload": True},
- handler_id="custom.handler",
- correlation_id="corr-meta",
- )
-
- socketio.emit.assert_awaited_once()
- args, kwargs = socketio.emit.await_args_list[0]
- assert args[0] == "meta_event"
- envelope = args[1]
- assert envelope["handlerId"] == "custom.handler"
- assert envelope["correlationId"] == "corr-meta"
- assert envelope["data"] == {"payload": True}
- assert kwargs == {"to": "sid-meta", "namespace": NAMESPACE}
-
-
-async def test_timestamps_are_timezone_aware():
- socketio = FakeSocketIOServer()
- manager = WebSocketManager(socketio, threading.RLock())
-
- await manager.handle_connect(NAMESPACE, "sid-utc")
- info = manager.connections[(NAMESPACE, "sid-utc")]
-
- assert info.connected_at.tzinfo is not None
- assert info.last_activity.tzinfo is not None
-
- with patch("helpers.websocket_manager._utcnow") as mocked_now:
- mocked_now.return_value = info.last_activity
- await manager.route_event(NAMESPACE, "unknown", {}, "sid-utc")
- assert info.last_activity.tzinfo is not None
-
-class DuplicateHandler(WebSocketHandler):
- @classmethod
- def get_event_types(cls) -> list[str]:
- return ["dup_event"]
-
- async def process_event(self, event_type: str, data: dict[str, Any], sid: str):
- return {"handledBy": self.identifier}
-
-
-class AnotherDuplicateHandler(WebSocketHandler):
- @classmethod
- def get_event_types(cls) -> list[str]:
- return ["dup_event"]
-
- async def process_event(self, event_type: str, data: dict[str, Any], sid: str):
- return {"handledBy": self.identifier}
-
-
-def test_register_handlers_warns_on_duplicates(monkeypatch):
- socketio = FakeSocketIOServer()
- manager = WebSocketManager(socketio, threading.RLock())
-
- warnings: list[str] = []
-
- def capture_warning(message: str) -> None:
- warnings.append(message)
-
- monkeypatch.setattr(
- "helpers.print_style.PrintStyle.warning", staticmethod(capture_warning)
- )
-
- DuplicateHandler._reset_instance_for_testing()
- AnotherDuplicateHandler._reset_instance_for_testing()
- handler_a = DuplicateHandler.get_instance(socketio, threading.RLock())
- handler_b = AnotherDuplicateHandler.get_instance(socketio, threading.RLock())
-
- manager.register_handlers({NAMESPACE: [handler_a, handler_b]})
-
- assert any("Duplicate handler registration" in msg for msg in warnings)
-
-
-class NonDictHandler(WebSocketHandler):
- @classmethod
- def get_event_types(cls) -> list[str]:
- return ["non_dict"]
-
- async def process_event(self, event_type: str, data: dict[str, Any], sid: str):
- return "raw-value"
-
-
-async def test_route_event_standardizes_success_payload():
- socketio = FakeSocketIOServer()
- manager = WebSocketManager(socketio, threading.RLock())
-
- NonDictHandler._reset_instance_for_testing()
- handler = NonDictHandler.get_instance(socketio, threading.RLock())
- manager.register_handlers({NAMESPACE: [handler]})
-
- response = await manager.route_event(NAMESPACE, "non_dict", {}, "sid-123")
-
- assert len(response["results"]) == 1
- assert response["results"][0]["ok"] is True
- assert response["results"][0]["data"] == {"result": "raw-value"}
-
-
-class ErrorHandler(WebSocketHandler):
- @classmethod
- def get_event_types(cls) -> list[str]:
- return ["boom"]
-
- async def process_event(self, event_type: str, data: dict[str, Any], sid: str):
- raise RuntimeError("BOOM")
-
-
-class ResultHandler(WebSocketHandler):
- @classmethod
- def get_event_types(cls) -> list[str]: # pragma: no cover - simple declaration
- return ["result_event", "result_error"]
-
- async def process_event(self, event_type: str, data: dict[str, Any], sid: str):
- if event_type == "result_event":
- return WebSocketResult.ok({"sid": sid}, correlation_id="explicit", duration_ms=1.234)
- return WebSocketResult.error(
- code="E_RESULT",
- message="boom",
- details="test",
- )
-
-
-async def test_route_event_standardizes_error_payload():
- socketio = FakeSocketIOServer()
- manager = WebSocketManager(socketio, threading.RLock())
-
- ErrorHandler._reset_instance_for_testing()
- handler = ErrorHandler.get_instance(socketio, threading.RLock())
- manager.register_handlers({NAMESPACE: [handler]})
-
- response = await manager.route_event(NAMESPACE, "boom", {}, "sid-123")
-
- assert len(response["results"]) == 1
- payload = response["results"][0]
- assert payload["ok"] is False
- assert payload["error"]["code"] == "HANDLER_ERROR"
- assert payload["error"]["error"] == "Internal server error"
-
-
-async def test_route_event_accepts_websocket_result_instances():
- socketio = FakeSocketIOServer()
- manager = WebSocketManager(socketio, threading.RLock())
-
- ResultHandler._reset_instance_for_testing()
- handler = ResultHandler.get_instance(socketio, threading.RLock())
- manager.register_handlers({NAMESPACE: [handler]})
-
- response = await manager.route_event(NAMESPACE, "result_event", {}, "sid-123")
-
- assert response["results"]
- payload = response["results"][0]
- assert payload["ok"] is True
- assert payload["data"] == {"sid": "sid-123"}
- assert payload["correlationId"] == "explicit"
- assert payload["durationMs"] == pytest.approx(1.234, rel=1e-3)
-
-
-async def test_route_event_preserves_websocket_result_errors():
- socketio = FakeSocketIOServer()
- manager = WebSocketManager(socketio, threading.RLock())
-
- ResultHandler._reset_instance_for_testing()
- handler = ResultHandler.get_instance(socketio, threading.RLock())
- manager.register_handlers({NAMESPACE: [handler]})
-
- response = await manager.route_event(NAMESPACE, "result_error", {}, "sid-123")
-
- payload = response["results"][0]
- assert payload["ok"] is False
- assert payload["error"] == {"code": "E_RESULT", "error": "boom", "details": "test"}
-
-
-class AlphaFilterHandler(WebSocketHandler):
- @classmethod
- def get_event_types(cls) -> list[str]:
- return ["filter_event"]
-
- async def process_event(self, event_type: str, data: dict[str, Any], sid: str):
- return {"handledBy": self.identifier, "sid": sid}
-
-
-class BetaFilterHandler(WebSocketHandler):
- @classmethod
- def get_event_types(cls) -> list[str]:
- return ["filter_event"]
-
- async def process_event(self, event_type: str, data: dict[str, Any], sid: str):
- return {"handledBy": self.identifier, "sid": sid}
-
-
-async def test_route_event_include_handlers_filters_results():
- socketio = FakeSocketIOServer()
- manager = WebSocketManager(socketio, threading.RLock())
-
- AlphaFilterHandler._reset_instance_for_testing()
- BetaFilterHandler._reset_instance_for_testing()
- alpha = AlphaFilterHandler.get_instance(socketio, threading.RLock())
- beta = BetaFilterHandler.get_instance(socketio, threading.RLock())
- manager.register_handlers({NAMESPACE: [alpha, beta]})
- await manager.handle_connect(NAMESPACE, "sid-filter")
-
- response = await manager.route_event(
- NAMESPACE,
- "filter_event",
- {
- "includeHandlers": [alpha.identifier],
- "payload": True,
- },
- "sid-filter",
- )
-
- assert response["correlationId"]
- results = response["results"]
- assert len(results) == 1
- assert results[0]["handlerId"] == alpha.identifier
- assert results[0]["data"]["handledBy"] == alpha.identifier
-
-
-async def test_route_event_rejects_exclude_handlers_without_permission():
- socketio = FakeSocketIOServer()
- manager = WebSocketManager(socketio, threading.RLock())
-
- AlphaFilterHandler._reset_instance_for_testing()
- handler = AlphaFilterHandler.get_instance(socketio, threading.RLock())
- manager.register_handlers({NAMESPACE: [handler]})
- await manager.handle_connect(NAMESPACE, "sid-exclude")
-
- response = await manager.route_event(
- NAMESPACE,
- "filter_event",
- {"excludeHandlers": [handler.identifier]},
- "sid-exclude",
- )
-
- result = response["results"][0]
- assert result["error"]["code"] == "INVALID_FILTER"
- assert "excludeHandlers" in result["error"]["error"]
-
-
-async def test_route_event_all_respects_exclude_handlers():
- socketio = FakeSocketIOServer()
- manager = WebSocketManager(socketio, threading.RLock())
-
- AlphaFilterHandler._reset_instance_for_testing()
- BetaFilterHandler._reset_instance_for_testing()
- alpha = AlphaFilterHandler.get_instance(socketio, threading.RLock())
- beta = BetaFilterHandler.get_instance(socketio, threading.RLock())
- manager.register_handlers({NAMESPACE: [alpha, beta]})
-
- await manager.handle_connect(NAMESPACE, "sid-a")
- await manager.handle_connect(NAMESPACE, "sid-b")
-
- aggregated = await manager.route_event_all(
- NAMESPACE,
- "filter_event",
- {"excludeHandlers": [beta.identifier]},
- handler_id="test.manager",
- )
-
- assert aggregated
- for entry in aggregated:
- assert entry["correlationId"]
- assert entry["results"]
- assert all(result["handlerId"] == alpha.identifier for result in entry["results"])
-
-
-async def test_route_event_preserves_correlation_id():
- socketio = FakeSocketIOServer()
- manager = WebSocketManager(socketio, threading.RLock())
-
- results = []
- DummyHandler._reset_instance_for_testing()
- handler = DummyHandler.get_instance(socketio, threading.RLock(), results)
- manager.register_handlers({NAMESPACE: [handler]})
- await manager.handle_connect(NAMESPACE, "sid-correlation")
-
- response = await manager.route_event(
- NAMESPACE,
- "dummy",
- {"foo": "bar", "correlationId": "manual-correlation"},
- "sid-correlation",
- )
-
- assert response["correlationId"] == "manual-correlation"
- result = response["results"][0]
- assert result["correlationId"] == "manual-correlation"
-
-
-async def test_request_preserves_explicit_correlation_id():
- socketio = FakeSocketIOServer()
- manager = WebSocketManager(socketio, threading.RLock())
-
- DummyHandler._reset_instance_for_testing()
- handler = DummyHandler.get_instance(socketio, threading.RLock(), [])
- manager.register_handlers({NAMESPACE: [handler]})
- await manager.handle_connect(NAMESPACE, "sid-request")
-
- response = await manager.request_for_sid(
- namespace=NAMESPACE,
- sid="sid-request",
- event_type="dummy",
- data={"payload": True, "correlationId": "req-correlation"},
- handler_id="tester",
- )
-
- assert response["correlationId"] == "req-correlation"
- result = response["results"][0]
- assert result["correlationId"] == "req-correlation"
-
-
-async def test_request_all_entries_include_correlation_id():
- socketio = FakeSocketIOServer()
- manager = WebSocketManager(socketio, threading.RLock())
-
- DummyHandler._reset_instance_for_testing()
- handler = DummyHandler.get_instance(socketio, threading.RLock(), [])
- manager.register_handlers({NAMESPACE: [handler]})
-
- await manager.handle_connect(NAMESPACE, "sid-1")
- await manager.handle_connect(NAMESPACE, "sid-2")
-
- aggregated = await manager.route_event_all(
- NAMESPACE,
- "dummy",
- {"value": 1, "correlationId": "agg-correlation"},
- )
-
- assert aggregated
- for entry in aggregated:
- assert entry["correlationId"] == "agg-correlation"
- assert entry["results"]
- assert entry["results"][0]["correlationId"] == "agg-correlation"
-
-
-def test_debug_logging_respects_runtime_flag(monkeypatch):
- socketio = FakeSocketIOServer()
- manager = WebSocketManager(socketio, threading.RLock())
-
- logs: list[str] = []
-
- def capture(message: str) -> None:
- logs.append(message)
-
- monkeypatch.setattr("helpers.print_style.PrintStyle.debug", staticmethod(capture))
- monkeypatch.setattr("helpers.websocket_manager.runtime.is_development", lambda: False)
-
- manager._debug("should-not-log") # noqa: SLF001
- assert logs == []
-
- monkeypatch.setattr("helpers.websocket_manager.runtime.is_development", lambda: True)
- manager._debug("should-log") # noqa: SLF001
- assert logs == ["should-log"]
-
-
-async def test_diagnostic_event_emitted_for_inbound():
- socketio = FakeSocketIOServer()
- manager = WebSocketManager(socketio, threading.RLock())
-
- results: list[dict[str, Any]] = []
- DummyHandler._reset_instance_for_testing()
- handler = DummyHandler.get_instance(socketio, threading.RLock(), results)
- manager.register_handlers({NAMESPACE: [handler]})
-
- await manager.handle_connect(NAMESPACE, "observer")
- assert manager.register_diagnostic_watcher(NAMESPACE, "observer") is True
- await manager.handle_connect(NAMESPACE, "sid-client")
-
- await manager.route_event(NAMESPACE, "dummy", {"payload": "value"}, "sid-client")
-
- emitted_events = [call.args[0] for call in socketio.emit.await_args_list]
- assert DIAGNOSTIC_EVENT in emitted_events
-
-
-async def test_lifecycle_events_broadcast(monkeypatch):
- socketio = FakeSocketIOServer()
- manager = WebSocketManager(socketio, threading.RLock())
-
- broadcast_mock = AsyncMock()
- monkeypatch.setattr(manager, "broadcast", broadcast_mock)
-
- await manager.handle_connect(NAMESPACE, "sid-life")
- await asyncio.sleep(0)
- await manager.handle_disconnect(NAMESPACE, "sid-life")
- await asyncio.sleep(0)
-
- events = [call.args[1] for call in broadcast_mock.await_args_list]
- assert LIFECYCLE_CONNECT_EVENT in events
- assert LIFECYCLE_DISCONNECT_EVENT in events
diff --git a/tests/test_websocket_namespace_discovery.py b/tests/test_websocket_namespace_discovery.py
deleted file mode 100644
index 1a0284ebc..000000000
--- a/tests/test_websocket_namespace_discovery.py
+++ /dev/null
@@ -1,225 +0,0 @@
-import asyncio
-import contextlib
-import socket
-import sys
-from pathlib import Path
-from typing import Any, AsyncIterator
-
-import pytest
-
-PROJECT_ROOT = Path(__file__).resolve().parents[1]
-if str(PROJECT_ROOT) not in sys.path:
- sys.path.insert(0, str(PROJECT_ROOT))
-
-
-async def _run_asgi_app(app: Any) -> AsyncIterator[str]:
- import uvicorn
-
- sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
- sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
- sock.bind(("127.0.0.1", 0))
- sock.listen(128)
-
- port = sock.getsockname()[1]
-
- config = uvicorn.Config(
- app,
- host="127.0.0.1",
- port=port,
- log_level="warning",
- access_log=False,
- lifespan="off",
- )
- server = uvicorn.Server(config)
- server.install_signal_handlers = lambda: None # type: ignore[method-assign]
-
- task = asyncio.create_task(server.serve(sockets=[sock]))
- try:
- while not server.started:
- await asyncio.sleep(0.01)
- yield f"http://127.0.0.1:{port}"
- finally:
- server.should_exit = True
- try:
- await asyncio.wait_for(task, timeout=5)
- finally:
- sock.close()
-
-
-def _write_handler_module(path: Path, class_name: str, event_type: str) -> None:
- path.write_text(
- "\n".join(
- [
- "from __future__ import annotations",
- "",
- "from typing import Any",
- "",
- "from helpers.websocket import WebSocketHandler",
- "",
- f"class {class_name}(WebSocketHandler):",
- " @classmethod",
- " def requires_auth(cls) -> bool:",
- " return False",
- "",
- " @classmethod",
- " def requires_csrf(cls) -> bool:",
- " return False",
- "",
- " @classmethod",
- " def get_event_types(cls) -> list[str]:",
- f" return ['{event_type}']",
- "",
- " async def process_event(self, event_type: str, data: dict[str, Any], sid: str):",
- " return {'ok': True}",
- "",
- ]
- ),
- encoding="utf-8",
- )
-
-
-def test_discovery_supports_folder_entries_and_ignores_deeper_nesting(tmp_path: Path) -> None:
- from helpers.websocket_namespace_discovery import discover_websocket_namespaces
-
- folder = tmp_path / "orders"
- folder.mkdir()
- _write_handler_module(folder / "orders.py", "OrdersHandler", "orders_request")
-
- # Deeper nesting must be ignored (and must not be imported).
- nested = folder / "nested"
- nested.mkdir()
- (nested / "boom.py").write_text("raise RuntimeError('should-not-import')\n", encoding="utf-8")
-
- discoveries = discover_websocket_namespaces(handlers_folder=str(tmp_path), include_root_default=False)
- by_ns = {d.namespace: d for d in discoveries}
-
- assert "/orders" in by_ns
- entry = by_ns["/orders"]
- assert [cls.__name__ for cls in entry.handler_classes] == ["OrdersHandler"]
-
-
-def test_discovery_folder_suffix_handler_stripped(tmp_path: Path) -> None:
- from helpers.websocket_namespace_discovery import discover_websocket_namespaces
-
- folder = tmp_path / "sales_handler"
- folder.mkdir()
- _write_handler_module(folder / "main.py", "SalesHandler", "sales_request")
-
- discoveries = discover_websocket_namespaces(handlers_folder=str(tmp_path), include_root_default=False)
- namespaces = {d.namespace for d in discoveries}
- assert "/sales" in namespaces
-
-
-def test_discovery_empty_folder_warns_and_treats_namespace_unregistered(tmp_path: Path, monkeypatch) -> None:
- from flask import Flask
- import socketio
-
- from helpers.websocket_manager import WebSocketManager
- from helpers.websocket_namespace_discovery import discover_websocket_namespaces
- from run_ui import configure_websocket_namespaces
-
- empty = tmp_path / "empty"
- empty.mkdir()
- (empty / "__init__.py").write_text("# init\n", encoding="utf-8")
-
- warnings: list[str] = []
-
- def _warn(message: str) -> None:
- warnings.append(message)
-
- monkeypatch.setattr("helpers.print_style.PrintStyle.warning", staticmethod(_warn))
-
- discoveries = discover_websocket_namespaces(handlers_folder=str(tmp_path), include_root_default=False)
- assert "/empty" not in {d.namespace for d in discoveries}
- assert any("empty" in msg.lower() for msg in warnings)
-
- # Integration check: treat as unregistered -> UNKNOWN_NAMESPACE connect_error.
- app = Flask("test_empty_folder_unregistered")
- app.secret_key = "test-secret"
- sio = socketio.AsyncServer(async_mode="asgi", cors_allowed_origins="*", namespaces="*")
- lock = __import__("threading").RLock()
- manager = WebSocketManager(sio, lock)
-
- handlers_by_namespace: dict[str, list[Any]] = {}
- for discovery in discoveries:
- handlers_by_namespace[discovery.namespace] = [
- cls.get_instance(sio, lock) for cls in discovery.handler_classes
- ]
-
- configure_websocket_namespaces(
- webapp=app,
- socketio_server=sio,
- websocket_manager=manager,
- handlers_by_namespace=handlers_by_namespace,
- )
-
- asgi_app = socketio.ASGIApp(sio)
- async def _run() -> None:
- async with _run_asgi_app(asgi_app) as base_url:
- client = socketio.AsyncClient()
- connect_error_fut: asyncio.Future[Any] = asyncio.get_running_loop().create_future()
-
- async def _on_connect_error(data: Any) -> None:
- if not connect_error_fut.done():
- connect_error_fut.set_result(data)
-
- client.on("connect_error", _on_connect_error, namespace="/empty")
- try:
- with pytest.raises(socketio.exceptions.ConnectionError):
- await client.connect(base_url, namespaces=["/empty"])
- err = await asyncio.wait_for(connect_error_fut, timeout=2)
- assert err["message"] == "UNKNOWN_NAMESPACE"
- assert err["data"]["namespace"] == "/empty"
- finally:
- try:
- await client.disconnect()
- except Exception:
- pass
-
- asyncio.run(_run())
-
-
-def test_discovery_invalid_modules_fail_fast_with_descriptive_errors(tmp_path: Path) -> None:
- from helpers.websocket_namespace_discovery import discover_websocket_namespaces
-
- # 0 handlers in a *_handler.py module
- (tmp_path / "bad_handler.py").write_text(
- "class NotAHandler:\n pass\n", encoding="utf-8"
- )
- with pytest.raises(RuntimeError) as excinfo:
- discover_websocket_namespaces(handlers_folder=str(tmp_path), include_root_default=False)
- assert "defines no WebSocketHandler subclasses" in str(excinfo.value)
-
- # 2+ handlers in a *_handler.py module
- tmp_path.joinpath("bad_handler.py").unlink()
- (tmp_path / "two_handler.py").write_text(
- "\n".join(
- [
- "from helpers.websocket import WebSocketHandler",
- "class A(WebSocketHandler):",
- " @classmethod",
- " def requires_auth(cls): return False",
- " @classmethod",
- " def requires_csrf(cls): return False",
- " @classmethod",
- " def get_event_types(cls): return ['two_a']",
- " async def process_event(self, event_type, data, sid): return {'ok': True}",
- "class B(WebSocketHandler):",
- " @classmethod",
- " def requires_auth(cls): return False",
- " @classmethod",
- " def requires_csrf(cls): return False",
- " @classmethod",
- " def get_event_types(cls): return ['two_b']",
- " async def process_event(self, event_type, data, sid): return {'ok': True}",
- "",
- ]
- ),
- encoding="utf-8",
- )
- with pytest.raises(RuntimeError) as excinfo2:
- discover_websocket_namespaces(handlers_folder=str(tmp_path), include_root_default=False)
- message = str(excinfo2.value)
- assert "defines multiple WebSocketHandler subclasses" in message
- assert "A" in message and "B" in message
diff --git a/tests/test_websocket_namespace_security.py b/tests/test_websocket_namespace_security.py
deleted file mode 100644
index 489ec2c20..000000000
--- a/tests/test_websocket_namespace_security.py
+++ /dev/null
@@ -1,464 +0,0 @@
-import asyncio
-import contextlib
-import socket
-import sys
-import threading
-from pathlib import Path
-from typing import Any, AsyncIterator
-
-import pytest
-
-PROJECT_ROOT = Path(__file__).resolve().parents[1]
-if str(PROJECT_ROOT) not in sys.path:
- sys.path.insert(0, str(PROJECT_ROOT))
-
-
-async def _run_asgi_app(app: Any) -> AsyncIterator[str]:
- import uvicorn
-
- sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
- sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
- sock.bind(("127.0.0.1", 0))
- sock.listen(128)
-
- port = sock.getsockname()[1]
-
- config = uvicorn.Config(
- app,
- host="127.0.0.1",
- port=port,
- log_level="warning",
- access_log=False,
- lifespan="off",
- )
- server = uvicorn.Server(config)
- server.install_signal_handlers = lambda: None # type: ignore[method-assign]
-
- task = asyncio.create_task(server.serve(sockets=[sock]))
- try:
- while not server.started:
- await asyncio.sleep(0.01)
- yield f"http://127.0.0.1:{port}"
- finally:
- server.should_exit = True
- try:
- await asyncio.wait_for(task, timeout=5)
- finally:
- sock.close()
-
-
-def _make_session_cookie(app: Any, data: dict[str, Any]) -> str:
- from flask.sessions import SecureCookieSessionInterface
-
- serializer = SecureCookieSessionInterface().get_signing_serializer(app)
- assert serializer is not None
- return serializer.dumps(data)
-
-
-async def test_connect_security_is_computed_per_namespace_and_enforced(monkeypatch) -> None:
- from flask import Flask
- import socketio
-
- from helpers.websocket import WebSocketHandler
- from helpers.websocket_manager import WebSocketManager
- from helpers import runtime
- from run_ui import configure_websocket_namespaces
-
- class OpenHandler(WebSocketHandler):
- @classmethod
- def requires_auth(cls) -> bool:
- return False
-
- @classmethod
- def requires_csrf(cls) -> bool:
- return False
-
- @classmethod
- def get_event_types(cls) -> list[str]:
- return ["open_ping"]
-
- async def process_event(self, event_type: str, data: dict[str, Any], sid: str) -> dict[str, Any]:
- return {"ok": True}
-
- class SecureHandler(WebSocketHandler):
- @classmethod
- def get_event_types(cls) -> list[str]:
- return ["secure_ping"]
-
- async def process_event(self, event_type: str, data: dict[str, Any], sid: str) -> dict[str, Any]:
- return {"ok": True}
-
- OpenHandler._reset_instance_for_testing()
- SecureHandler._reset_instance_for_testing()
-
- monkeypatch.setattr("helpers.login.get_credentials_hash", lambda: "hash")
-
- webapp = Flask("test_websocket_namespace_security")
- webapp.secret_key = "test-secret"
-
- sio = socketio.AsyncServer(async_mode="asgi", cors_allowed_origins="*", namespaces="*")
- lock = threading.RLock()
- manager = WebSocketManager(sio, lock)
- handlers_by_namespace = {
- "/open": [OpenHandler.get_instance(sio, lock)],
- "/secure": [SecureHandler.get_instance(sio, lock)],
- }
-
- configure_websocket_namespaces(
- webapp=webapp,
- socketio_server=sio,
- websocket_manager=manager,
- handlers_by_namespace=handlers_by_namespace,
- )
-
- asgi_app = socketio.ASGIApp(sio)
-
- async with _run_asgi_app(asgi_app) as base_url:
- # Open namespace should not require auth/csrf (but Origin validation is always enforced).
- open_client = socketio.AsyncClient()
- await open_client.connect(
- base_url,
- namespaces=["/open"],
- headers={"Origin": base_url},
- wait_timeout=2,
- )
- try:
- res = await open_client.call("open_ping", {}, namespace="/open", timeout=2)
- assert isinstance(res, dict)
- assert res.get("results")
- res_unhandled = await open_client.call("unhandled_event", {"x": 1}, namespace="/open", timeout=2)
- assert res_unhandled["results"]
- assert res_unhandled["results"][0]["ok"] is False
- assert res_unhandled["results"][0]["error"]["code"] == "NO_HANDLERS"
- finally:
- await open_client.disconnect()
-
- # Secure namespace rejects without valid session+csrf when credentials are configured.
- secure_client = socketio.AsyncClient()
- with pytest.raises(socketio.exceptions.ConnectionError):
- await secure_client.connect(
- base_url,
- namespaces=["/secure"],
- headers={"Origin": base_url},
- wait_timeout=2,
- )
- await secure_client.disconnect()
-
- # Secure namespace accepts valid session + auth csrf_token + runtime-scoped csrf cookie.
- csrf_token = "csrf-1"
- session_cookie = _make_session_cookie(
- webapp,
- {
- "authentication": "hash",
- "csrf_token": csrf_token,
- "user_id": "u1",
- },
- )
- session_cookie_name = webapp.config.get("SESSION_COOKIE_NAME", "session")
- csrf_cookie_name = f"csrf_token_{runtime.get_runtime_id()}"
- cookie_header = f"{session_cookie_name}={session_cookie}; {csrf_cookie_name}={csrf_token}"
-
- secure_client_ok = socketio.AsyncClient()
- await secure_client_ok.connect(
- base_url,
- namespaces=["/secure"],
- headers={"Origin": base_url, "Cookie": cookie_header},
- auth={"csrf_token": csrf_token},
- wait_timeout=2,
- )
- try:
- res2 = await secure_client_ok.call("secure_ping", {}, namespace="/secure", timeout=2)
- assert isinstance(res2, dict)
- assert res2.get("results")
- finally:
- await secure_client_ok.disconnect()
-
-
-async def test_unknown_namespace_rejected_with_deterministic_connect_error_payload() -> None:
- from flask import Flask
- import socketio
-
- from helpers.websocket import WebSocketHandler
- from helpers.websocket_manager import WebSocketManager
- from run_ui import configure_websocket_namespaces
-
- class OpenHandler(WebSocketHandler):
- @classmethod
- def requires_auth(cls) -> bool:
- return False
-
- @classmethod
- def requires_csrf(cls) -> bool:
- return False
-
- @classmethod
- def get_event_types(cls) -> list[str]:
- return ["open_ping"]
-
- async def process_event(self, event_type: str, data: dict[str, Any], sid: str) -> dict[str, Any]:
- return {"ok": True}
-
- OpenHandler._reset_instance_for_testing()
-
- webapp = Flask("test_unknown_namespace_rejection")
- webapp.secret_key = "test-secret"
-
- sio = socketio.AsyncServer(async_mode="asgi", cors_allowed_origins="*", namespaces="*")
- lock = threading.RLock()
- manager = WebSocketManager(sio, lock)
-
- configure_websocket_namespaces(
- webapp=webapp,
- socketio_server=sio,
- websocket_manager=manager,
- handlers_by_namespace={"/open": [OpenHandler.get_instance(sio, lock)]},
- )
-
- asgi_app = socketio.ASGIApp(sio)
-
- async with _run_asgi_app(asgi_app) as base_url:
- client = socketio.AsyncClient()
- connect_error_fut: asyncio.Future[Any] = asyncio.get_running_loop().create_future()
-
- async def _on_connect_error(data: Any) -> None:
- if not connect_error_fut.done():
- connect_error_fut.set_result(data)
-
- client.on("connect_error", _on_connect_error, namespace="/unknown")
-
- try:
- with pytest.raises(socketio.exceptions.ConnectionError):
- await client.connect(base_url, namespaces=["/unknown"])
-
- err = await asyncio.wait_for(connect_error_fut, timeout=2)
- assert err["message"] == "UNKNOWN_NAMESPACE"
- assert err["data"] == {"code": "UNKNOWN_NAMESPACE", "namespace": "/unknown"}
- finally:
- try:
- await client.disconnect()
- except Exception:
- pass
-
-
-async def test_secure_namespace_rejects_missing_auth_even_with_valid_csrf(monkeypatch) -> None:
- from flask import Flask
- import socketio
-
- from helpers.websocket import WebSocketHandler
- from helpers.websocket_manager import WebSocketManager
- from helpers import runtime
- from run_ui import configure_websocket_namespaces
-
- class SecureHandler(WebSocketHandler):
- @classmethod
- def get_event_types(cls) -> list[str]:
- return ["secure_ping"]
-
- async def process_event(self, event_type: str, data: dict[str, Any], sid: str) -> dict[str, Any]:
- return {"ok": True}
-
- SecureHandler._reset_instance_for_testing()
-
- monkeypatch.setattr("helpers.login.get_credentials_hash", lambda: "hash")
-
- webapp = Flask("test_ws_secure_missing_auth")
- webapp.secret_key = "test-secret"
-
- sio = socketio.AsyncServer(async_mode="asgi", cors_allowed_origins="*", namespaces="*")
- lock = threading.RLock()
- manager = WebSocketManager(sio, lock)
- handlers_by_namespace = {
- "/secure": [SecureHandler.get_instance(sio, lock)],
- }
-
- configure_websocket_namespaces(
- webapp=webapp,
- socketio_server=sio,
- websocket_manager=manager,
- handlers_by_namespace=handlers_by_namespace,
- )
-
- asgi_app = socketio.ASGIApp(sio)
-
- async with _run_asgi_app(asgi_app) as base_url:
- csrf_token = "csrf-auth-missing"
- session_cookie = _make_session_cookie(
- webapp,
- {
- "csrf_token": csrf_token,
- "user_id": "u1",
- },
- )
- session_cookie_name = webapp.config.get("SESSION_COOKIE_NAME", "session")
- csrf_cookie_name = f"csrf_token_{runtime.get_runtime_id()}"
- cookie_header = f"{session_cookie_name}={session_cookie}; {csrf_cookie_name}={csrf_token}"
-
- client = socketio.AsyncClient()
- with pytest.raises(socketio.exceptions.ConnectionError):
- await client.connect(
- base_url,
- namespaces=["/secure"],
- headers={"Origin": base_url, "Cookie": cookie_header},
- auth={"csrf_token": csrf_token},
- wait_timeout=2,
- )
- await client.disconnect()
-
-
-async def test_secure_namespace_rejects_invalid_csrf_cookie(monkeypatch) -> None:
- from flask import Flask
- import socketio
-
- from helpers.websocket import WebSocketHandler
- from helpers.websocket_manager import WebSocketManager
- from helpers import runtime
- from run_ui import configure_websocket_namespaces
-
- class SecureHandler(WebSocketHandler):
- @classmethod
- def get_event_types(cls) -> list[str]:
- return ["secure_ping"]
-
- async def process_event(self, event_type: str, data: dict[str, Any], sid: str) -> dict[str, Any]:
- return {"ok": True}
-
- SecureHandler._reset_instance_for_testing()
-
- monkeypatch.setattr("helpers.login.get_credentials_hash", lambda: "hash")
-
- webapp = Flask("test_ws_secure_invalid_csrf")
- webapp.secret_key = "test-secret"
-
- sio = socketio.AsyncServer(async_mode="asgi", cors_allowed_origins="*", namespaces="*")
- lock = threading.RLock()
- manager = WebSocketManager(sio, lock)
- handlers_by_namespace = {
- "/secure": [SecureHandler.get_instance(sio, lock)],
- }
-
- configure_websocket_namespaces(
- webapp=webapp,
- socketio_server=sio,
- websocket_manager=manager,
- handlers_by_namespace=handlers_by_namespace,
- )
-
- asgi_app = socketio.ASGIApp(sio)
-
- async with _run_asgi_app(asgi_app) as base_url:
- csrf_token = "csrf-good"
- session_cookie = _make_session_cookie(
- webapp,
- {
- "authentication": "hash",
- "csrf_token": csrf_token,
- "user_id": "u1",
- },
- )
- session_cookie_name = webapp.config.get("SESSION_COOKIE_NAME", "session")
- csrf_cookie_name = f"csrf_token_{runtime.get_runtime_id()}"
- cookie_header = f"{session_cookie_name}={session_cookie}; {csrf_cookie_name}=csrf-bad"
-
- client = socketio.AsyncClient()
- with pytest.raises(socketio.exceptions.ConnectionError):
- await client.connect(
- base_url,
- namespaces=["/secure"],
- headers={"Origin": base_url, "Cookie": cookie_header},
- auth={"csrf_token": csrf_token},
- wait_timeout=2,
- )
- await client.disconnect()
-
-
-async def test_csrf_required_without_auth_is_enforced(monkeypatch) -> None:
- from flask import Flask
- import socketio
-
- from helpers.websocket import WebSocketHandler
- from helpers.websocket_manager import WebSocketManager
- from helpers import runtime
- from run_ui import configure_websocket_namespaces
-
- class CsrfOnlyHandler(WebSocketHandler):
- @classmethod
- def requires_auth(cls) -> bool:
- return False
-
- @classmethod
- def requires_csrf(cls) -> bool:
- return True
-
- @classmethod
- def get_event_types(cls) -> list[str]:
- return ["csrf_only_ping"]
-
- async def process_event(self, event_type: str, data: dict[str, Any], sid: str) -> dict[str, Any]:
- return {"ok": True}
-
- CsrfOnlyHandler._reset_instance_for_testing()
-
- monkeypatch.setattr("helpers.login.get_credentials_hash", lambda: None)
-
- webapp = Flask("test_ws_csrf_only")
- webapp.secret_key = "test-secret"
-
- sio = socketio.AsyncServer(async_mode="asgi", cors_allowed_origins="*", namespaces="*")
- lock = threading.RLock()
- manager = WebSocketManager(sio, lock)
- handlers_by_namespace = {
- "/csrf_only": [CsrfOnlyHandler.get_instance(sio, lock)],
- }
-
- configure_websocket_namespaces(
- webapp=webapp,
- socketio_server=sio,
- websocket_manager=manager,
- handlers_by_namespace=handlers_by_namespace,
- )
-
- asgi_app = socketio.ASGIApp(sio)
-
- async with _run_asgi_app(asgi_app) as base_url:
- client = socketio.AsyncClient()
- with pytest.raises(socketio.exceptions.ConnectionError):
- await client.connect(
- base_url,
- namespaces=["/csrf_only"],
- headers={"Origin": base_url},
- wait_timeout=2,
- )
- await client.disconnect()
-
- csrf_token = "csrf-only"
- session_cookie = _make_session_cookie(
- webapp,
- {
- "csrf_token": csrf_token,
- "user_id": "u1",
- },
- )
- session_cookie_name = webapp.config.get("SESSION_COOKIE_NAME", "session")
- csrf_cookie_name = f"csrf_token_{runtime.get_runtime_id()}"
- cookie_header = f"{session_cookie_name}={session_cookie}; {csrf_cookie_name}={csrf_token}"
-
- client_ok = socketio.AsyncClient()
- await client_ok.connect(
- base_url,
- namespaces=["/csrf_only"],
- headers={"Origin": base_url, "Cookie": cookie_header},
- auth={"csrf_token": csrf_token},
- wait_timeout=2,
- )
- try:
- res = await client_ok.call("csrf_only_ping", {}, namespace="/csrf_only", timeout=2)
- assert isinstance(res, dict)
- assert res.get("results")
- finally:
- await client_ok.disconnect()
diff --git a/tests/test_websocket_namespaces.py b/tests/test_websocket_namespaces.py
deleted file mode 100644
index 9857e16e1..000000000
--- a/tests/test_websocket_namespaces.py
+++ /dev/null
@@ -1,497 +0,0 @@
-import asyncio
-import contextlib
-import socket
-import sys
-import threading
-from pathlib import Path
-from typing import Any, AsyncIterator
-from unittest.mock import AsyncMock
-
-import pytest
-
-PROJECT_ROOT = Path(__file__).resolve().parents[1]
-if str(PROJECT_ROOT) not in sys.path:
- sys.path.insert(0, str(PROJECT_ROOT))
-
-from helpers.state_monitor import StateMonitor
-from helpers.websocket_manager import WebSocketManager
-
-
-class FakeSocketIOServer:
- def __init__(self) -> None:
- self.emit = AsyncMock()
- self.disconnect = AsyncMock()
-
-
-async def _run_asgi_app(app: Any) -> AsyncIterator[str]:
- import uvicorn
-
- sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
- sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
- sock.bind(("127.0.0.1", 0))
- sock.listen(128)
-
- port = sock.getsockname()[1]
-
- config = uvicorn.Config(
- app,
- host="127.0.0.1",
- port=port,
- log_level="warning",
- access_log=False,
- lifespan="off",
- )
- server = uvicorn.Server(config)
- server.install_signal_handlers = lambda: None # type: ignore[method-assign]
-
- task = asyncio.create_task(server.serve(sockets=[sock]))
- try:
- while not server.started:
- await asyncio.sleep(0.01)
- yield f"http://127.0.0.1:{port}"
- finally:
- server.should_exit = True
- try:
- await asyncio.wait_for(task, timeout=5)
- finally:
- sock.close()
-
-
-async def test_manager_identity_is_namespace_and_sid_allows_same_sid_across_namespaces() -> None:
- socketio = FakeSocketIOServer()
- manager = WebSocketManager(socketio, threading.RLock())
- # Avoid flakiness from lifecycle broadcasts scheduled via asyncio.create_task.
- manager._schedule_lifecycle_broadcast = lambda *_args, **_kwargs: None # type: ignore[assignment]
-
- sid = "shared-sid"
- ns_a = "/a"
- ns_b = "/b"
-
- await manager.handle_connect(ns_a, sid)
- await manager.handle_connect(ns_b, sid)
-
- assert (ns_a, sid) in manager.connections
- assert (ns_b, sid) in manager.connections
-
- await manager.handle_disconnect(ns_a, sid)
- assert (ns_a, sid) not in manager.connections
- assert (ns_b, sid) in manager.connections
-
- await manager.emit_to(ns_a, sid, "test_event", {"value": 1}, correlation_id="corr-1")
-
- assert (ns_a, sid) in manager.buffers
- assert (ns_b, sid) not in manager.buffers
- assert socketio.emit.await_count == 0
-
-
-def test_state_monitor_tracks_two_identities_for_same_sid_across_namespaces() -> None:
- monitor = StateMonitor()
- sid = "shared-sid"
- monitor.register_sid("/a", sid)
- monitor.register_sid("/b", sid)
-
- debug = monitor._debug_state()
- assert ("/a", sid) in debug["identities"]
- assert ("/b", sid) in debug["identities"]
-
-
-async def test_namespace_isolation_state_sync_vs_dev_websocket_test() -> None:
- """
- CONTRACT.INVARIANT.NS.ISOLATION: no cross-namespace delivery for application events.
-
- Acceptance proof for `/webui` vs `/dev_websocket_test` namespaces.
- """
-
- from flask import Flask
- import socketio
-
- from helpers.websocket import WebSocketHandler
- from helpers.websocket_manager import WebSocketManager
- from run_ui import configure_websocket_namespaces
-
- class StateHandler(WebSocketHandler):
- @classmethod
- def requires_auth(cls) -> bool:
- return False
-
- @classmethod
- def requires_csrf(cls) -> bool:
- return False
-
- @classmethod
- def get_event_types(cls) -> list[str]:
- return ["state_request"]
-
- async def process_event(self, event_type: str, data: dict[str, Any], sid: str):
- await self.emit_to(sid, "state_push", {"source": "state_sync"})
- return {"ok": True}
-
- class DevHandler(WebSocketHandler):
- @classmethod
- def requires_auth(cls) -> bool:
- return False
-
- @classmethod
- def requires_csrf(cls) -> bool:
- return False
-
- @classmethod
- def get_event_types(cls) -> list[str]:
- return ["ws_tester_emit"]
-
- async def process_event(self, event_type: str, data: dict[str, Any], sid: str):
- await self.broadcast("ws_tester_broadcast", {"source": "dev_websocket_test"})
- return None
-
- StateHandler._reset_instance_for_testing()
- DevHandler._reset_instance_for_testing()
-
- webapp = Flask("test_namespace_isolation")
- webapp.secret_key = "test-secret"
-
- sio = socketio.AsyncServer(async_mode="asgi", cors_allowed_origins="*", namespaces="*")
- lock = threading.RLock()
- manager = WebSocketManager(sio, lock)
-
- configure_websocket_namespaces(
- webapp=webapp,
- socketio_server=sio,
- websocket_manager=manager,
- handlers_by_namespace={
- "/webui": [StateHandler.get_instance(sio, lock)],
- "/dev_websocket_test": [DevHandler.get_instance(sio, lock)],
- },
- )
-
- asgi_app = socketio.ASGIApp(sio)
-
- async with _run_asgi_app(asgi_app) as base_url:
- client = socketio.AsyncClient()
-
- state_push_state = asyncio.Event()
- state_push_dev = asyncio.Event()
- tester_broadcast_dev = asyncio.Event()
- tester_broadcast_state = asyncio.Event()
-
- async def _on_state_push_state(_payload: Any) -> None:
- state_push_state.set()
-
- async def _on_state_push_dev(_payload: Any) -> None:
- state_push_dev.set()
-
- async def _on_tester_broadcast_dev(_payload: Any) -> None:
- tester_broadcast_dev.set()
-
- async def _on_tester_broadcast_state(_payload: Any) -> None:
- tester_broadcast_state.set()
-
- client.on("state_push", _on_state_push_state, namespace="/webui")
- client.on("state_push", _on_state_push_dev, namespace="/dev_websocket_test")
- client.on("ws_tester_broadcast", _on_tester_broadcast_dev, namespace="/dev_websocket_test")
- client.on("ws_tester_broadcast", _on_tester_broadcast_state, namespace="/webui")
-
- await client.connect(
- base_url,
- namespaces=["/webui", "/dev_websocket_test"],
- headers={"Origin": base_url},
- wait_timeout=2,
- )
- try:
- await client.call("state_request", {"context": None}, namespace="/webui", timeout=2)
- await asyncio.wait_for(state_push_state.wait(), timeout=2)
- await asyncio.sleep(0.05)
- assert state_push_dev.is_set() is False
-
- await client.emit("ws_tester_emit", {"message": "hi"}, namespace="/dev_websocket_test")
- await asyncio.wait_for(tester_broadcast_dev.wait(), timeout=2)
- await asyncio.sleep(0.05)
- assert tester_broadcast_state.is_set() is False
- finally:
- await client.disconnect()
-
-
-async def test_diagnostics_include_source_namespace_and_deliver_on_dev_namespace_only() -> None:
- """
- CONTRACT.Diagnostics: dev console diagnostics are delivered on `/dev_websocket_test`,
- but must include `sourceNamespace` identifying the origin namespace.
- """
-
- from helpers.websocket import WebSocketHandler
- from helpers.websocket_manager import DIAGNOSTIC_EVENT, WebSocketManager
-
- class DummyHandler(WebSocketHandler):
- @classmethod
- def get_event_types(cls) -> list[str]:
- return ["dummy_event"]
-
- async def process_event(self, event_type: str, data: dict[str, Any], sid: str):
- return {"ok": True}
-
- DummyHandler._reset_instance_for_testing()
-
- socketio = FakeSocketIOServer()
- manager = WebSocketManager(socketio, threading.RLock())
- manager._schedule_lifecycle_broadcast = lambda *_args, **_kwargs: None # type: ignore[assignment]
-
- ns_state = "/webui"
- ns_dev = "/dev_websocket_test"
-
- handler = DummyHandler.get_instance(socketio, threading.RLock())
- manager.register_handlers({ns_state: [handler]})
-
- await manager.handle_connect(ns_dev, "sid-watcher")
- await manager.handle_connect(ns_state, "sid-client")
- assert manager.register_diagnostic_watcher(ns_dev, "sid-watcher") is True
-
- socketio.emit.reset_mock()
-
- await manager.route_event(ns_state, "dummy_event", {"payload": True}, "sid-client")
-
- calls = [(call.args, call.kwargs) for call in socketio.emit.await_args_list]
- diagnostic = next((c for c in calls if c[0] and c[0][0] == DIAGNOSTIC_EVENT), None)
- assert diagnostic is not None
-
- args, kwargs = diagnostic
- envelope = args[1]
- assert kwargs == {"to": "sid-watcher", "namespace": ns_dev}
- assert envelope["data"]["sourceNamespace"] == ns_state
-
-
-def test_namespace_discovery_maps_core_handlers_to_expected_namespaces() -> None:
- """
- US1 regression: ensure discovery assigns core handlers to their dedicated namespaces
- (no cross-registration).
- """
-
- from helpers.websocket_namespace_discovery import discover_websocket_namespaces
-
- discoveries = discover_websocket_namespaces(
- handlers_folder="python/websocket_handlers",
- include_root_default=True,
- )
- by_namespace = {entry.namespace: entry for entry in discoveries}
-
- assert "/webui" in by_namespace
- assert "/dev_websocket_test" in by_namespace
-
- state_cls_names = [cls.__name__ for cls in by_namespace["/webui"].handler_classes]
- dev_cls_names = [cls.__name__ for cls in by_namespace["/dev_websocket_test"].handler_classes]
-
- assert state_cls_names == ["WebuiHandler"]
- assert dev_cls_names == ["DevWebsocketTestHandler"]
-
-
-def test_run_ui_builds_namespace_handler_map_without_cross_registration() -> None:
- from run_ui import _build_websocket_handlers_by_namespace
-
- handlers_by_namespace = _build_websocket_handlers_by_namespace(object(), threading.RLock())
-
- assert "/webui" in handlers_by_namespace
- assert "/dev_websocket_test" in handlers_by_namespace
-
- assert all(
- handler.__class__.__name__ != "DevWebsocketTestHandler"
- for handler in handlers_by_namespace["/webui"]
- )
- assert all(
- handler.__class__.__name__ != "WebuiHandler"
- for handler in handlers_by_namespace["/dev_websocket_test"]
- )
-
-
-async def test_route_event_dispatches_only_within_connected_namespace_and_results_are_scoped() -> None:
- """
- CONTRACT.NS.ROUTING: inbound routing is restricted to handlers in the connected namespace.
- """
-
- from helpers.websocket import WebSocketHandler
-
- socketio = FakeSocketIOServer()
- manager = WebSocketManager(socketio, threading.RLock())
- manager._schedule_lifecycle_broadcast = lambda *_args, **_kwargs: None # type: ignore[assignment]
-
- ns_state = "/webui"
- ns_dev = "/dev_websocket_test"
-
- calls: list[str] = []
-
- class StatePingHandler(WebSocketHandler):
- @classmethod
- def get_event_types(cls) -> list[str]:
- return ["route_test"]
-
- async def process_event(self, event_type: str, data: dict[str, Any], sid: str):
- calls.append(f"state:{sid}")
- return {"ns": "state"}
-
- class DevPingHandler(WebSocketHandler):
- @classmethod
- def get_event_types(cls) -> list[str]:
- return ["route_test"]
-
- async def process_event(self, event_type: str, data: dict[str, Any], sid: str):
- calls.append(f"dev:{sid}")
- return {"ns": "dev"}
-
- StatePingHandler._reset_instance_for_testing()
- DevPingHandler._reset_instance_for_testing()
-
- state_handler = StatePingHandler.get_instance(socketio, threading.RLock())
- dev_handler = DevPingHandler.get_instance(socketio, threading.RLock())
-
- manager.register_handlers({ns_state: [state_handler], ns_dev: [dev_handler]})
- await manager.handle_connect(ns_state, "sid-state")
- await manager.handle_connect(ns_dev, "sid-dev")
-
- res_state = await manager.route_event(ns_state, "route_test", {"x": 1}, "sid-state")
- assert {item["handlerId"] for item in res_state["results"]} == {state_handler.identifier}
- assert res_state["results"][0]["data"]["ns"] == "state"
-
- res_dev = await manager.route_event(ns_dev, "route_test", {"x": 2}, "sid-dev")
- assert {item["handlerId"] for item in res_dev["results"]} == {dev_handler.identifier}
- assert res_dev["results"][0]["data"]["ns"] == "dev"
-
- assert calls == ["state:sid-state", "dev:sid-dev"]
-
-
-async def test_lifecycle_broadcasts_deliver_only_within_the_namespace() -> None:
- """
- CONTRACT.NS.DELIVERY: lifecycle broadcasts are namespace-scoped.
- """
-
- from helpers.websocket_manager import (
- LIFECYCLE_CONNECT_EVENT,
- LIFECYCLE_DISCONNECT_EVENT,
- )
-
- socketio = FakeSocketIOServer()
- manager = WebSocketManager(socketio, threading.RLock())
-
- ns_state = "/webui"
- ns_dev = "/dev_websocket_test"
-
- # Connect events should broadcast only within their namespace.
- await manager.handle_connect(ns_state, "sid-state-1")
- await asyncio.sleep(0)
- state_connect_calls = [
- call
- for call in socketio.emit.await_args_list
- if call.args and call.args[0] == LIFECYCLE_CONNECT_EVENT
- ]
- assert state_connect_calls
- assert all(call.kwargs.get("namespace") == ns_state for call in state_connect_calls)
-
- socketio.emit.reset_mock()
- await manager.handle_connect(ns_dev, "sid-dev-1")
- await asyncio.sleep(0)
- dev_connect_calls = [
- call
- for call in socketio.emit.await_args_list
- if call.args and call.args[0] == LIFECYCLE_CONNECT_EVENT
- ]
- assert dev_connect_calls
- assert all(call.kwargs.get("namespace") == ns_dev for call in dev_connect_calls)
-
- # Disconnect broadcasts go to remaining peers in that namespace only.
- socketio.emit.reset_mock()
- await manager.handle_connect(ns_state, "sid-state-2")
- await manager.handle_connect(ns_dev, "sid-dev-2")
- socketio.emit.reset_mock()
-
- await manager.handle_disconnect(ns_state, "sid-state-2")
- await asyncio.sleep(0)
- state_disconnect_calls = [
- call
- for call in socketio.emit.await_args_list
- if call.args and call.args[0] == LIFECYCLE_DISCONNECT_EVENT
- ]
- assert state_disconnect_calls
- assert all(call.kwargs.get("namespace") == ns_state for call in state_disconnect_calls)
- assert all(call.kwargs.get("to") == "sid-state-1" for call in state_disconnect_calls)
-
-
-async def test_request_semantics_no_handlers_and_timeouts_are_namespace_scoped_and_order_insensitive() -> None:
- """
- CONTRACT.REQUEST.RESULTS + CONTRACT.REQUEST.RESULTS.ORDERING + CONTRACT.NS.ROUTING.
- """
-
- from helpers.websocket import WebSocketHandler
-
- socketio = FakeSocketIOServer()
- manager = WebSocketManager(socketio, threading.RLock())
- manager._schedule_lifecycle_broadcast = lambda *_args, **_kwargs: None # type: ignore[assignment]
-
- ns_state = "/webui"
- ns_dev = "/dev_websocket_test"
-
- class Alpha(WebSocketHandler):
- @classmethod
- def get_event_types(cls) -> list[str]:
- return ["multi", "slow"]
-
- async def process_event(self, event_type: str, data: dict[str, Any], sid: str):
- if event_type == "slow":
- await asyncio.sleep(0.2)
- return {"alpha": True}
- return {"alpha": True}
-
- class Beta(WebSocketHandler):
- @classmethod
- def get_event_types(cls) -> list[str]:
- return ["multi"]
-
- async def process_event(self, event_type: str, data: dict[str, Any], sid: str):
- return {"beta": True}
-
- Alpha._reset_instance_for_testing()
- Beta._reset_instance_for_testing()
- alpha = Alpha.get_instance(socketio, threading.RLock())
- beta = Beta.get_instance(socketio, threading.RLock())
-
- manager.register_handlers({ns_state: [alpha, beta]})
- await manager.handle_connect(ns_state, "sid-a")
- await manager.handle_connect(ns_state, "sid-b")
- await manager.handle_connect(ns_dev, "sid-dev")
-
- # Unknown event name -> NO_HANDLERS (no hang), scoped to the namespace.
- no_handler = await manager.route_event(ns_dev, "missing_event", {"x": 1}, "sid-dev")
- assert no_handler["results"][0]["ok"] is False
- assert no_handler["results"][0]["error"]["code"] == "NO_HANDLERS"
- assert ns_dev in no_handler["results"][0]["error"]["error"]
-
- # Unknown event name in a namespace that *does* have other handlers -> NO_HANDLERS.
- unhandled_in_state = await manager.route_event(ns_state, "unknown_event", {"x": 1}, "sid-a")
- assert unhandled_in_state["results"][0]["ok"] is False
- assert unhandled_in_state["results"][0]["error"]["code"] == "NO_HANDLERS"
- assert ns_state in unhandled_in_state["results"][0]["error"]["error"]
-
- # Known event name in the wrong namespace -> NO_HANDLERS (no cross-namespace fallback).
- wrong_namespace = await manager.route_event(ns_dev, "multi", {"x": 1}, "sid-dev")
- assert wrong_namespace["results"][0]["ok"] is False
- assert wrong_namespace["results"][0]["error"]["code"] == "NO_HANDLERS"
- assert ns_dev in wrong_namespace["results"][0]["error"]["error"]
-
- # Order-insensitive results[]: both handlers must be present regardless of ordering.
- multi = await manager.route_event(ns_state, "multi", {"x": 1}, "sid-a")
- handler_ids = {item["handlerId"] for item in multi["results"]}
- assert handler_ids == {alpha.identifier, beta.identifier}
-
- # Timeout results are represented as TIMEOUT items and scoped to the namespace.
- aggregated = await manager.route_event_all(ns_state, "slow", {"x": 1}, timeout_ms=50)
- assert len(aggregated) == 2 # only state namespace connections
- assert {entry["sid"] for entry in aggregated} == {"sid-a", "sid-b"}
- for entry in aggregated:
- assert entry["results"]
- assert entry["results"][0]["ok"] is False
- assert entry["results"][0]["error"]["code"] == "TIMEOUT"
-
- # Allow the underlying slow route_event coroutines to complete so pytest's event loop
- # teardown does not cancel them mid-flight (avoids noisy InvalidStateError callbacks).
- await asyncio.sleep(0.3)
diff --git a/tests/test_websocket_namespaces_integration.py b/tests/test_websocket_namespaces_integration.py
deleted file mode 100644
index 3be3495a8..000000000
--- a/tests/test_websocket_namespaces_integration.py
+++ /dev/null
@@ -1,113 +0,0 @@
-import asyncio
-import contextlib
-import socket
-from typing import Any, AsyncIterator
-
-import pytest
-
-
-async def _run_asgi_app(app: Any) -> AsyncIterator[str]:
- import uvicorn
-
- sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
- sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
- sock.bind(("127.0.0.1", 0))
- sock.listen(128)
-
- port = sock.getsockname()[1]
-
- config = uvicorn.Config(
- app,
- host="127.0.0.1",
- port=port,
- log_level="warning",
- access_log=False,
- lifespan="off",
- )
- server = uvicorn.Server(config)
- server.install_signal_handlers = lambda: None # type: ignore[method-assign]
-
- task = asyncio.create_task(server.serve(sockets=[sock]))
- try:
- while not server.started:
- await asyncio.sleep(0.01)
- yield f"http://127.0.0.1:{port}"
- finally:
- server.should_exit = True
- try:
- await asyncio.wait_for(task, timeout=5)
- finally:
- sock.close()
-
-
-async def test_unregistered_namespace_connection_fails_with_unknown_namespace_connect_error() -> None:
- """
- US5 integration: unregistered namespace connections fail deterministically with a structured
- connect_error payload (UNKNOWN_NAMESPACE), independent of python-socketio defaults.
- """
-
- from flask import Flask
- import socketio
-
- from helpers.websocket import WebSocketHandler
- from helpers.websocket_manager import WebSocketManager
- from run_ui import configure_websocket_namespaces
-
- class OpenHandler(WebSocketHandler):
- @classmethod
- def requires_auth(cls) -> bool:
- return False
-
- @classmethod
- def requires_csrf(cls) -> bool:
- return False
-
- @classmethod
- def get_event_types(cls) -> list[str]:
- return ["open_ping"]
-
- async def process_event(self, event_type: str, data: dict[str, Any], sid: str):
- return {"ok": True}
-
- OpenHandler._reset_instance_for_testing()
-
- webapp = Flask("test_ws_namespaces_integration")
- webapp.secret_key = "test-secret"
-
- sio = socketio.AsyncServer(async_mode="asgi", cors_allowed_origins="*", namespaces="*")
- lock = __import__("threading").RLock()
- manager = WebSocketManager(sio, lock)
-
- configure_websocket_namespaces(
- webapp=webapp,
- socketio_server=sio,
- websocket_manager=manager,
- handlers_by_namespace={"/open": [OpenHandler.get_instance(sio, lock)]},
- )
-
- asgi_app = socketio.ASGIApp(sio)
-
- async with _run_asgi_app(asgi_app) as base_url:
- client = socketio.AsyncClient()
- connect_error_fut: asyncio.Future[Any] = asyncio.get_running_loop().create_future()
-
- async def _on_connect_error(data: Any) -> None:
- if not connect_error_fut.done():
- connect_error_fut.set_result(data)
-
- client.on("connect_error", _on_connect_error, namespace="/unknown")
-
- try:
- with pytest.raises(socketio.exceptions.ConnectionError):
- await client.connect(base_url, namespaces=["/unknown"])
-
- err = await asyncio.wait_for(connect_error_fut, timeout=2)
- assert err["message"] == "UNKNOWN_NAMESPACE"
- assert err["data"] == {"code": "UNKNOWN_NAMESPACE", "namespace": "/unknown"}
- finally:
- try:
- await client.disconnect()
- except Exception:
- pass
diff --git a/tests/test_websocket_root_namespace.py b/tests/test_websocket_root_namespace.py
deleted file mode 100644
index 4c23f5e69..000000000
--- a/tests/test_websocket_root_namespace.py
+++ /dev/null
@@ -1,183 +0,0 @@
-import asyncio
-import contextlib
-import socket
-from typing import Any, AsyncIterator
-
-import pytest
-
-
-async def _run_asgi_app(app: Any) -> AsyncIterator[str]:
- import uvicorn
-
- sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
- sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
- sock.bind(("127.0.0.1", 0))
- sock.listen(128)
-
- port = sock.getsockname()[1]
-
- config = uvicorn.Config(
- app,
- host="127.0.0.1",
- port=port,
- log_level="warning",
- access_log=False,
- lifespan="off",
- )
- server = uvicorn.Server(config)
- server.install_signal_handlers = lambda: None # type: ignore[method-assign]
-
- task = asyncio.create_task(server.serve(sockets=[sock]))
- try:
- while not server.started:
- await asyncio.sleep(0.01)
- yield f"http://127.0.0.1:{port}"
- finally:
- server.should_exit = True
- try:
- await asyncio.wait_for(task, timeout=5)
- finally:
- sock.close()
-
-
-async def test_root_namespace_request_style_calls_resolve_with_no_handlers() -> None:
- """
- CONTRACT.INVARIANT.NS.ROOT.UNHANDLED: root (`/`) is reserved and unhandled for application
- events by default, but request-style calls must not hang (NO_HANDLERS).
- """
-
- from flask import Flask
- import socketio
-
- from helpers.websocket import WebSocketHandler
- from helpers.websocket_manager import WebSocketManager
- from run_ui import configure_websocket_namespaces
-
- app = Flask("test_ws_root_namespace")
- app.secret_key = "test-secret"
-
- calls: list[str] = []
-
- class HelloHandler(WebSocketHandler):
- @classmethod
- def requires_auth(cls) -> bool:
- return False
-
- @classmethod
- def requires_csrf(cls) -> bool:
- return False
-
- @classmethod
- def get_event_types(cls) -> list[str]:
- return ["hello_request"]
-
- async def process_event(self, event_type: str, data: dict[str, Any], sid: str):
- calls.append(sid)
- return {"hello": True}
-
- HelloHandler._reset_instance_for_testing()
-
- sio = socketio.AsyncServer(async_mode="asgi", cors_allowed_origins="*", namespaces="*")
- lock = __import__("threading").RLock()
- manager = WebSocketManager(sio, lock)
-
- configure_websocket_namespaces(
- webapp=app,
- socketio_server=sio,
- websocket_manager=manager,
- handlers_by_namespace={
- "/webui": [HelloHandler.get_instance(sio, lock)],
- },
- )
-
- asgi_app = socketio.ASGIApp(sio)
-
- async with _run_asgi_app(asgi_app) as base_url:
- client = socketio.AsyncClient()
- await client.connect(
- base_url,
- namespaces=["/"],
- headers={"Origin": base_url},
- wait_timeout=2,
- )
- try:
- res_unknown = await client.call("unknown_event", {"x": 1}, namespace="/", timeout=2)
- assert res_unknown["results"][0]["ok"] is False
- assert res_unknown["results"][0]["error"]["code"] == "NO_HANDLERS"
-
- res_known_elsewhere = await client.call("hello_request", {"name": "x"}, namespace="/", timeout=2)
- assert res_known_elsewhere["results"][0]["ok"] is False
- assert res_known_elsewhere["results"][0]["error"]["code"] == "NO_HANDLERS"
- assert calls == []
- finally:
- await client.disconnect()
-
-
-async def test_root_namespace_fire_and_forget_does_not_invoke_application_handlers() -> None:
- """
- Fire-and-forget emits on `/` must not invoke any application handler.
- """
-
- from flask import Flask
- import socketio
-
- from helpers.websocket import WebSocketHandler
- from helpers.websocket_manager import WebSocketManager
- from run_ui import configure_websocket_namespaces
-
- app = Flask("test_ws_root_fire_and_forget")
- app.secret_key = "test-secret"
-
- calls: list[str] = []
-
- class SideEffectHandler(WebSocketHandler):
- @classmethod
- def requires_auth(cls) -> bool:
- return False
-
- @classmethod
- def requires_csrf(cls) -> bool:
- return False
-
- @classmethod
- def get_event_types(cls) -> list[str]:
- return ["hello_request"]
-
- async def process_event(self, event_type: str, data: dict[str, Any], sid: str):
- calls.append(sid)
- return {"ok": True}
-
- SideEffectHandler._reset_instance_for_testing()
-
- sio = socketio.AsyncServer(async_mode="asgi", cors_allowed_origins="*", namespaces="*")
- lock = __import__("threading").RLock()
- manager = WebSocketManager(sio, lock)
-
- configure_websocket_namespaces(
- webapp=app,
- socketio_server=sio,
- websocket_manager=manager,
- handlers_by_namespace={
- "/webui": [SideEffectHandler.get_instance(sio, lock)],
- },
- )
-
- asgi_app = socketio.ASGIApp(sio)
-
- async with _run_asgi_app(asgi_app) as base_url:
- client = socketio.AsyncClient()
- await client.connect(
- base_url,
- namespaces=["/"],
- headers={"Origin": base_url},
- wait_timeout=2,
- )
- try:
- await client.emit("hello_request", {"name": "x"}, namespace="/")
- await asyncio.sleep(0.1)
- assert calls == []
- finally:
- await client.disconnect()
diff --git a/tests/websocket_namespace_test_utils.py b/tests/websocket_namespace_test_utils.py
deleted file mode 100644
index f8252e97d..000000000
--- a/tests/websocket_namespace_test_utils.py
+++ /dev/null
@@ -1,56 +0,0 @@
-from __future__ import annotations
-
-from dataclasses import dataclass
-from typing import Any
-from unittest.mock import AsyncMock
-
-
-ConnectionIdentity = tuple[str, str] # (namespace, sid)
-
-
-def nsid(namespace: str, sid: str) -> ConnectionIdentity:
- return (namespace, sid)
-
-
-@dataclass(frozen=True)
-class SocketIOCall:
- args: tuple[Any, ...]
- kwargs: dict[str, Any]
-
- @property
- def namespace(self) -> str | None:
- value = self.kwargs.get("namespace")
- if value is None:
- return None
- if not isinstance(value, str):
- raise TypeError(f"Expected namespace to be str, got {type(value).__name__}")
- return value
-
-
-class FakeSocketIOServer:
- """
- Test double for python-socketio AsyncServer.
-
- Captures calls and surfaces the optional Socket.IO namespace dimension via recorded kwargs.
- """
-
- def __init__(self) -> None:
- self._emit_calls: list[SocketIOCall] = []
- self._disconnect_calls: list[SocketIOCall] = []
-
- self.emit = AsyncMock(side_effect=self._emit)
- self.disconnect = AsyncMock(side_effect=self._disconnect)
-
- async def _emit(self, *args: Any, **kwargs: Any) -> None:
- self._emit_calls.append(SocketIOCall(args=args, kwargs=dict(kwargs)))
-
- async def _disconnect(self, *args: Any, **kwargs: Any) -> None:
- self._disconnect_calls.append(SocketIOCall(args=args, kwargs=dict(kwargs)))
-
- @property
- def emit_calls(self) -> list[SocketIOCall]:
- return self._emit_calls
-
- @property
- def disconnect_calls(self) -> list[SocketIOCall]:
- return self._disconnect_calls