| 1 | # virtual_desktop_routes.py DOX |
| 2 | |
| 3 | ## Purpose |
| 4 | |
| 5 | - Own the `virtual_desktop_routes.py` helper module. |
| 6 | - This module installs virtual desktop gateway route hooks. |
| 7 | - Keep this file-level DOX profile synchronized with `virtual_desktop_routes.py` because this directory is intentionally flat. |
| 8 | |
| 9 | ## Ownership |
| 10 | |
| 11 | - `virtual_desktop_routes.py` owns the runtime implementation. |
| 12 | - `virtual_desktop_routes.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. |
| 13 | - Classes: |
| 14 | - `VirtualDesktopGateway` (no explicit base class) |
| 15 | - `async http(self, scope: Scope, receive: Receive, send: Send) -> None` |
| 16 | - `async resize(self, scope: Scope, receive: Receive, send: Send) -> None` |
| 17 | - `async proxy_http(self, scope: Scope, receive: Receive, send: Send, token: str, upstream_path: str) -> None` |
| 18 | - `async websocket(self, scope: Scope, receive: Receive, send: Send) -> None` |
| 19 | - `async open_websocket(self, endpoint: virtual_desktop.VirtualDesktopEndpoint, target: str, subprotocols: tuple[str, ...]) -> tuple[asyncio.StreamReader, asyncio.StreamWriter, WSConnection, str | None]` |
| 20 | - `async browser_to_xpra(self, websocket: WebSocket, upstream: WSConnection, writer: asyncio.StreamWriter) -> None` |
| 21 | - `async xpra_to_browser(self, websocket: WebSocket, upstream: WSConnection, reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None` |
| 22 | - `session_request(self, path: str) -> tuple[str, str] | None` |
| 23 | - Top-level functions: |
| 24 | - `install_route_hooks() -> None` |
| 25 | - `is_installed() -> bool` |
| 26 | - Notable constants/configuration names: `HOP_BY_HOP_HEADERS`, `XPRA_MENU_CUSTOM_PATCH`, `XPRA_WINDOW_OFFSET_WARNING`, `XPRA_WINDOW_OFFSET_WARNING_PATCH`, `XPRA_WINDOW_SCRIPT`, `XPRA_WINDOW_SCRIPT_PATCH`. |
| 27 | |
| 28 | ## Runtime Contracts |
| 29 | |
| 30 | - Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. |
| 31 | - Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. |
| 32 | - Observed side-effect areas: filesystem deletion, network calls, subprocess/runtime control, WebSocket state, settings/state persistence, secret handling. |
| 33 | - Imported dependency areas include: `__future__`, `asyncio`, `flask.sessions`, `helpers`, `http.client`, `http.cookies`, `starlette.requests`, `starlette.responses`, `starlette.types`, `starlette.websockets`, `urllib.parse`, `wsproto`, `wsproto.events`. |
| 34 | |
| 35 | ## Key Concepts |
| 36 | |
| 37 | - Important called helpers/classes observed in the source: `self.relative_path`, `self.session_request`, `self.query`, `virtual_desktop.proxy_for_token`, `WebSocket`, `self.upstream_target`, `WSConnection`, `writer.write`, `rest.partition`, `unquote`, `quote`, `http.client.HTTPConnection`, `query_string.decode`, `urlsplit`, `location.startswith`, `path.startswith`, `parse_qs`, `login.get_credentials_hash`, `SecureCookieSessionInterface.get_signing_serializer`, `dict.get.decode`. |
| 38 | - Keep request/response, tool, or helper semantics documented here at the same time as source changes. |
| 39 | |
| 40 | ## Work Guidance |
| 41 | |
| 42 | - Preserve public helper APIs used by core code and plugins unless every caller is updated. |
| 43 | - Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. |
| 44 | - Prefer adding cohesive helper functions here only when behavior is reused across modules. |
| 45 | |
| 46 | ## Verification |
| 47 | |
| 48 | - Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. |
| 49 | - Related tests observed by source search: |
| 50 | - `tests/test_office_canvas_setup.py` |
| 51 | - `tests/test_office_document_store.py` |
| 52 | |
| 53 | ## Child DOX Index |
| 54 | |
| 55 | No child DOX files. |