| 1 | # ws_manager.py DOX |
| 2 | |
| 3 | ## Purpose |
| 4 | |
| 5 | - Own the `ws_manager.py` helper module. |
| 6 | - This module manages WebSocket connections, event validation, buffering, and dispatch. |
| 7 | - Keep this file-level DOX profile synchronized with `ws_manager.py` because this directory is intentionally flat. |
| 8 | |
| 9 | ## Ownership |
| 10 | |
| 11 | - `ws_manager.py` owns the runtime implementation. |
| 12 | - `ws_manager.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. |
| 13 | - Classes: |
| 14 | - `WsResult` (no explicit base class) |
| 15 | - `ok(cls, data: dict[str, Any] | None=..., correlation_id: str | None=..., duration_ms: float | None=...) -> 'WsResult'` |
| 16 | - `error(cls, code: str, message: str, details: Any | None=..., correlation_id: str | None=..., duration_ms: float | None=...) -> 'WsResult'` |
| 17 | - `as_result(self, handler_id: str, fallback_correlation_id: str | None, duration_ms: float | None=...) -> dict[str, Any]` |
| 18 | - `BufferedEvent` (no explicit base class) |
| 19 | - `ConnectionInfo` (no explicit base class) |
| 20 | - `_HandlerExecution` (no explicit base class) |
| 21 | - `WsManager` (no explicit base class) |
| 22 | - `register_diagnostic_watcher(self, namespace: str, sid: str) -> bool` |
| 23 | - `unregister_diagnostic_watcher(self, namespace: str, sid: str) -> None` |
| 24 | - `register_handlers(self, handlers_by_namespace: dict[str, Iterable[WsHandler]]) -> None` |
| 25 | - `iter_namespaces(self) -> list[str]` |
| 26 | - `async process_client_event(self, namespace: str, event_type: str, data: dict[str, Any], sid: str, handlers: list[WsHandler]) -> dict[str, Any]` |
| 27 | - `async handle_connect(self, namespace: str, sid: str, user_id: str | None=...) -> None` |
| 28 | - `async handle_disconnect(self, namespace: str, sid: str) -> None` |
| 29 | - `async route_event(self, namespace: str, event_type: str, data: dict[str, Any], sid: str, ack: Optional[Callable[[Any], None]]=..., include_handlers: Set[str] | None=..., exclude_handlers: Set[str] | None=..., allow_exclude: bool=..., handler_id: str | None=...) -> dict[str, Any]` |
| 30 | - Top-level functions: |
| 31 | - `validate_event_type(event_type: str) -> str`: Validate an event name: must be lowercase_snake_case and not reserved. |
| 32 | - `async send_data(event_type: str, data: dict[str, Any], endpoint_name: str=..., connection_id: str | None=...) -> None`: Convenience wrapper around :pymeth:`WsManager.send_data`. |
| 33 | - `_utcnow() -> datetime` |
| 34 | - `set_shared_ws_manager(manager: 'WsManager') -> None` |
| 35 | - `get_shared_ws_manager() -> 'WsManager'` |
| 36 | - Notable constants/configuration names: `_EVENT_NAME_PATTERN`, `_RESERVED_EVENT_NAMES`, `BUFFER_MAX_SIZE`, `BUFFER_TTL`, `DIAGNOSTIC_EVENT`, `LIFECYCLE_CONNECT_EVENT`, `LIFECYCLE_DISCONNECT_EVENT`, `STATE_PUSH_EVENT`, `SERVER_RESTART_EVENT`, `ERR_NO_HANDLERS`, `ERR_HANDLER_ERROR`, `ERR_INVALID_FILTER`, `ERR_INVALID_EVENT`, `ERR_CONNECTION_NOT_FOUND`, `ERR_TIMEOUT`. |
| 37 | |
| 38 | ## Runtime Contracts |
| 39 | |
| 40 | - Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. |
| 41 | - Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. |
| 42 | - Observed side-effect areas: filesystem deletion, network calls, WebSocket state, settings/state persistence, scheduler state. |
| 43 | - Imported dependency areas include: `__future__`, `asyncio`, `collections`, `dataclasses`, `datetime`, `helpers`, `helpers.defer`, `helpers.print_style`, `helpers.ws`, `os`, `re`, `socketio`, `threading`, `time`, `typing`, `uuid`. |
| 44 | |
| 45 | ## Key Concepts |
| 46 | |
| 47 | - Important called helpers/classes observed in the source: `re.compile`, `timedelta`, `get_shared_ws_manager`, `datetime.now`, `field`, `cls`, `TypeError`, `_EVENT_NAME_PATTERN.fullmatch`, `ValueError`, `manager.send_data`, `RuntimeError`, `defaultdict`, `runtime.is_development`, `ws_debug`, `self._ensure_dispatcher_loop`, `dispatcher_loop.is_closed`, `asyncio.run_coroutine_threadsafe`, `_utcnow.isoformat.replace`, `self._copy_diagnostic_watchers`, `self._lifecycle_tasks.add`. |
| 48 | - Keep request/response, tool, or helper semantics documented here at the same time as source changes. |
| 49 | |
| 50 | ## Work Guidance |
| 51 | |
| 52 | - Preserve public helper APIs used by core code and plugins unless every caller is updated. |
| 53 | - Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. |
| 54 | - Prefer adding cohesive helper functions here only when behavior is reused across modules. |
| 55 | |
| 56 | ## Verification |
| 57 | |
| 58 | - Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. |
| 59 | - Related tests observed by source search: |
| 60 | - `tests/test_browser_agent_regressions.py` |
| 61 | - `tests/test_host_browser_connector.py` |
| 62 | - `tests/test_state_sync_handler.py` |
| 63 | - `tests/test_state_sync_welcome_screen.py` |
| 64 | - `tests/test_tool_action_contracts.py` |
| 65 | - `tests/test_ws_handlers.py` |
| 66 | - `tests/test_ws_manager.py` |
| 67 | |
| 68 | ## Child DOX Index |
| 69 | |
| 70 | No child DOX files. |