pycodex-ws 0.4.0__tar.gz → 0.4.1__tar.gz

{pycodex_ws-0.4.0 → pycodex_ws-0.4.1}/PKG-INFO

@@ -1,21 +1,20 @@
 Metadata-Version: 2.1
 Name: pycodex-ws
-Version: 0.4.0
-Summary: Browser workspace, Feishu and IPython integrations for python-codex
+Version: 0.4.1
+Summary: Browser workspace and optional Feishu integration for python-codex
 License-File: LICENSE
 Requires-Python: >=3.7
-Requires-Dist: ipython>=7
-Requires-Dist: lark-oapi
 Requires-Dist: pillow>=9.0.0
-Requires-Dist: python-codex==0.4.0
+Requires-Dist: python-codex==0.4.1
+Requires-Dist: websockets<16,>=11
 Description-Content-Type: text/markdown
 
 # pycodex-ws
 
 `pycodex-ws` provides the browser workspace, Canvas and file/diff viewer,
-Feishu integration and IPython tools for
+and optional Feishu integration for
 [`python-codex`](https://pypi.org/project/python-codex/). It installs the exact
-matching core version and all integration dependencies.
+matching core version.
 
 Pillow is a direct dependency of this package for image preview validation.
 Core can run without it; `view_image` then sends original image bytes.
@@ -53,8 +52,18 @@ its range, or only the cursor position. Context appears as a separate block amon
 text; click a block to edit or remove it before sending.
 
 Workspace sessions include `/link` and `/unlink` for Feishu. Python callers use
-`pycodex_ws.build_runtime(agent)` for the same assembly, or
-`from pycodex_ws.ipython import ipython_agent` inside an IPython session.
+`pycodex_ws.build_runtime(agent)` for the same assembly.
+
+The Feishu SDK is optional and is not installed automatically. To enable
+`/link`, install it in the same Python environment as the workspace:
+
+```bash
+python3 -m pip install lark-oapi
+```
+
+`/link` checks that `lark_oapi` can be imported before creating a connection.
+If it cannot, the command reports that it is unavailable and shows the manual
+installation command. Other workspace features work without the SDK.
 
 For initial Feishu user authorization, run the module included in this package:
 
@@ -105,6 +114,6 @@ root to install both, then `uv run pycodex-ws --help`. Build this package with
 `uv build packages/pycodex-ws`.
 
 Run `uv run --dev pytest packages/pycodex-ws/tests` from the repository root for
-workspace, Feishu, IPython and cross-frontend integration tests. Core tests live
+workspace, Feishu and cross-frontend integration tests. Core tests live
 in the root `tests/` directory and use the independent `test` dependency group.
 `uv run --dev pytest` runs both suites; see [test documentation](../../tests/TESTS.md).

{pycodex_ws-0.4.0 → pycodex_ws-0.4.1}/README.md

@@ -1,9 +1,9 @@
 # pycodex-ws
 
 `pycodex-ws` provides the browser workspace, Canvas and file/diff viewer,
-Feishu integration and IPython tools for
+and optional Feishu integration for
 [`python-codex`](https://pypi.org/project/python-codex/). It installs the exact
-matching core version and all integration dependencies.
+matching core version.
 
 Pillow is a direct dependency of this package for image preview validation.
 Core can run without it; `view_image` then sends original image bytes.
@@ -41,8 +41,18 @@ its range, or only the cursor position. Context appears as a separate block amon
 text; click a block to edit or remove it before sending.
 
 Workspace sessions include `/link` and `/unlink` for Feishu. Python callers use
-`pycodex_ws.build_runtime(agent)` for the same assembly, or
-`from pycodex_ws.ipython import ipython_agent` inside an IPython session.
+`pycodex_ws.build_runtime(agent)` for the same assembly.
+
+The Feishu SDK is optional and is not installed automatically. To enable
+`/link`, install it in the same Python environment as the workspace:
+
+```bash
+python3 -m pip install lark-oapi
+```
+
+`/link` checks that `lark_oapi` can be imported before creating a connection.
+If it cannot, the command reports that it is unavailable and shows the manual
+installation command. Other workspace features work without the SDK.
 
 For initial Feishu user authorization, run the module included in this package:
 
@@ -93,6 +103,6 @@ root to install both, then `uv run pycodex-ws --help`. Build this package with
 `uv build packages/pycodex-ws`.
 
 Run `uv run --dev pytest packages/pycodex-ws/tests` from the repository root for
-workspace, Feishu, IPython and cross-frontend integration tests. Core tests live
+workspace, Feishu and cross-frontend integration tests. Core tests live
 in the root `tests/` directory and use the independent `test` dependency group.
 `uv run --dev pytest` runs both suites; see [test documentation](../../tests/TESTS.md).

pycodex_ws-0.4.1/pycodex_router/__init__.py

@@ -0,0 +1 @@
+"""Reverse connections for pycodex workspaces."""

pycodex_ws-0.4.1/pycodex_router/__main__.py

@@ -0,0 +1,3 @@
+from .server import main
+
+raise SystemExit(main())

pycodex_ws-0.4.1/pycodex_router/browser.py

@@ -0,0 +1,175 @@
+"""Separate device origins while sharing the router's HttpOnly login."""
+
+import ipaddress
+import re
+from http.cookies import SimpleCookie
+from urllib.parse import urlencode, urlsplit
+
+from starlette.exceptions import HTTPException
+from starlette.requests import HTTPConnection
+from starlette.responses import JSONResponse, RedirectResponse
+
+from .protocol import route_path
+
+
+def origins(connection):
+    try:
+        parsed = urlsplit("//" + connection.headers["host"])
+        port = parsed.port
+    except ValueError:
+        raise HTTPException(400, "Invalid router host.")
+    host = parsed.hostname
+    if (
+        not host
+        or parsed.username is not None
+        or parsed.password is not None
+        or parsed.path
+        or parsed.query
+        or parsed.fragment
+    ):
+        raise HTTPException(400, "Invalid router host.")
+    try:
+        ipaddress.ip_address(host)
+    except ValueError:
+        if len(host) > 253 or any(
+            not re.fullmatch(r"[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?", label)
+            for label in host.split(".")
+        ):
+            raise HTTPException(400, "Invalid router host.")
+    scheme = "https" if connection.scope["scheme"] in {"https", "wss"} else "http"
+    suffix = "" if port in (None, 443 if scheme == "https" else 80) else ":" + str(port)
+    authority = "[" + host + "]" if ":" in host else host
+    origin = scheme + "://" + authority + suffix
+    first, separator, parent = host.partition(".")
+    node_id = first[2:] if separator and re.fullmatch("n-[a-z2-7]{52}", first) else None
+    base = scheme + "://" + parent + suffix if node_id else origin
+    return origin, base, node_id
+
+
+def device_url(connection, node_id, path):
+    if not re.fullmatch("[a-z2-7]{52}", node_id):
+        raise HTTPException(404, "Invalid device id.")
+    unused_origin, base, unused_node = origins(connection)
+    parsed = urlsplit(base)
+    if len("n-" + node_id + "." + parsed.hostname) > 253:
+        raise HTTPException(400, "Router domain is too long for device subdomains.")
+    try:
+        ipaddress.ip_address(parsed.hostname)
+    except ValueError:
+        pass
+    else:
+        raise HTTPException(
+            400,
+            "Device isolation requires a dedicated router domain with wildcard DNS "
+            "and, for HTTPS, a wildcard certificate; a bare IP cannot isolate pages.",
+        )
+    return parsed.scheme + "://n-" + node_id + "." + parsed.netloc + path
+
+
+class BrowserOrigins:
+    def __init__(self, router, admin_app, node_app):
+        self.router = router
+        self.admin_app = admin_app
+        self.node_app = node_app
+
+    async def __call__(self, scope, receive, send):
+        connection = HTTPConnection(scope)
+        origin, base, node_id = origins(connection)
+        path = route_path(scope)
+
+        async def secured_send(message):
+            if message["type"] == "http.response.start":
+                headers = []
+                for name, value in message["headers"]:
+                    if name.lower() == b"set-cookie" and node_id is None:
+                        # Only router-controlled subdomains share this cookie;
+                        # request_scope() never forwards it to a device.
+                        cookies = SimpleCookie()
+                        cookies.load(value.decode("latin-1"))
+                        if "pycodex_router_auth" in cookies:
+                            cookie = cookies["pycodex_router_auth"]
+                            try:
+                                ipaddress.ip_address(connection.url.hostname)
+                            except ValueError:
+                                cookie["domain"] = connection.url.hostname
+                            value = cookie.OutputString().encode("latin-1")
+                    headers.append((name, value))
+                message = dict(
+                    message,
+                    headers=headers
+                    + [
+                        (b"content-security-policy", b"frame-ancestors 'self'"),
+                        (b"x-frame-options", b"SAMEORIGIN"),
+                        (b"x-content-type-options", b"nosniff"),
+                        (b"referrer-policy", b"no-referrer"),
+                        (b"permissions-policy", b"document-domain=()"),
+                        (b"origin-agent-cluster", b"?1"),
+                    ],
+                )
+            await send(message)
+
+        try:
+            if connection.client.host in self.router.blocked_ips:
+                raise HTTPException(
+                    403,
+                    "Too many incorrect passwords. This IP is blocked "
+                    "until the router restarts.",
+                )
+            if connection.headers.get("origin") not in (None, origin):
+                raise HTTPException(
+                    403, "Cross-origin router requests are not allowed."
+                )
+            if node_id:
+                prefix = "/n/" + node_id
+                if path != prefix and not path.startswith(prefix + "/"):
+                    raise HTTPException(
+                        404, "Workspace route not found on this origin."
+                    )
+                await self.node_app(scope, receive, secured_send)
+            else:
+                await self.admin_app(scope, receive, secured_send)
+        except HTTPException as exc:
+            if scope["type"] == "websocket":
+                await send({"type": "websocket.close", "code": 1008})
+            else:
+                await JSONResponse({"error": exc.detail}, exc.status_code)(
+                    scope, receive, secured_send
+                )
+
+
+async def redirect_device(scope, receive, send):
+    if scope["type"] != "http" or scope["method"] not in {"GET", "HEAD"}:
+        if scope["type"] == "websocket":
+            await send({"type": "websocket.close", "code": 1008})
+        else:
+            await JSONResponse({"error": "Use the device's own origin."}, 403)(
+                scope, receive, send
+            )
+        return
+    connection = HTTPConnection(scope)
+    target = scope.get("root_path", "") + route_path(scope)
+    if connection.url.query:
+        target += "?" + connection.url.query
+    await RedirectResponse(
+        device_url(connection, scope["path_params"]["node_id"], target), 307
+    )(scope, receive, send)
+
+
+async def require_login(scope, receive, send):
+    connection = HTTPConnection(scope)
+    if scope["type"] == "websocket":
+        await send({"type": "websocket.close", "code": 1008})
+    elif "/api/" in route_path(scope) or scope["method"] not in {"GET", "HEAD"}:
+        await JSONResponse({"error": "authentication required"}, 401)(
+            scope, receive, send
+        )
+    else:
+        unused_origin, base, node_id = origins(connection)
+        prefix = scope.get("root_path", "")
+        root = prefix[: -len("/n/" + node_id)]
+        target = prefix + route_path(scope)
+        if connection.url.query:
+            target += "?" + connection.url.query
+        await RedirectResponse(
+            base + root + "/login?" + urlencode({"next": target}), 303
+        )(scope, receive, send)

pycodex_ws-0.4.1/pycodex_router/client.py

@@ -0,0 +1,250 @@
+import asyncio
+import logging
+import secrets
+import socket
+from contextlib import asynccontextmanager
+
+from websockets.exceptions import ConnectionClosed, InvalidHandshake
+from websockets.legacy.client import connect
+from .protocol import decode, device_id, encode, send_event, tunnel_url
+
+
+class NodeIdInUse(Exception):
+    pass
+
+
+class RouterClient:
+    def __init__(
+        self,
+        app,
+        target,
+        name,
+        port,
+        workspaces,
+        refresh_seconds=2.0,
+        reconnect_seconds=1.0,
+    ):
+        self.app = app
+        self.control_url = tunnel_url(target, "control")
+        self.data_url = tunnel_url(target, "data")
+        self._identity_key = secrets.token_hex(32)
+        self.node_id = device_id(self._identity_key)
+        self.name = name
+        self.port = port
+        self.workspaces = workspaces
+        self.refresh_seconds = refresh_seconds
+        self.reconnect_seconds = reconnect_seconds
+        self.connected = False
+        self._task = None
+        self._channels = set()
+        self._requests = set()
+        self._logger = logging.getLogger(__name__)
+
+    def _connect(self, url):
+        return connect(
+            url,
+            open_timeout=10,
+            close_timeout=2,
+            ping_interval=20,
+            ping_timeout=20,
+            max_size=32 * 1024 * 1024,
+            max_queue=4,
+        )
+
+    async def start(self):
+        if self._task is not None:
+            raise RuntimeError("router client is already started")
+        self._task = asyncio.create_task(self._run())
+
+    async def close(self):
+        if self._task is not None:
+            self._task.cancel()
+            await asyncio.gather(self._task, return_exceptions=True)
+            self._task = None
+        await self._close_channels()
+        if self._requests:
+            await asyncio.gather(*tuple(self._requests))
+
+    async def _close_channels(self):
+        await asyncio.gather(*(channel.close() for channel in tuple(self._channels)))
+
+    async def _run(self):
+        delay = self.reconnect_seconds
+        while True:
+            failure = None
+            try:
+                async with self._connect(self.control_url) as channel:
+                    await self._register(channel)
+                    self.connected = True
+                    delay = self.reconnect_seconds
+                    self._logger.info("Workspace connected to router as %s", self.name)
+                    await self._session(channel)
+            except asyncio.CancelledError:
+                # close() performs cleanup after stopping this loop.
+                raise
+            except Exception as exc:
+                failure = exc
+            finally:
+                self.connected = False
+
+            try:
+                await self._close_channels()
+            except asyncio.CancelledError:
+                raise
+            except Exception as exc:
+                failure = exc
+
+            # Retry every failure, including registration and connection cleanup.
+            # Peer-supplied close reasons and URLs must not enter the log.
+            reason = (
+                type(failure).__name__ if failure is not None else "connection closed"
+            )
+            if isinstance(failure, ConnectionClosed) and failure.rcvd is not None:
+                reason += ", close_code={0}".format(failure.rcvd.code)
+            self._logger.warning(
+                "Router node %s disconnected (%s); retrying in %g seconds",
+                self.name,
+                reason,
+                delay,
+            )
+            await asyncio.sleep(delay)
+            delay = min(delay * 2, 30)
+
+    async def _register(self, channel):
+        await channel.send(
+            encode(
+                {
+                    "type": "register",
+                    "version": 2,
+                    "identity_key": self._identity_key,
+                    "name": self.name,
+                    "port": self.port,
+                    "workspaces": self.workspaces(),
+                }
+            )
+        )
+        reply = decode(await asyncio.wait_for(channel.recv(), 10))
+        if reply.get("type") == "rejected":
+            raise NodeIdInUse("router node id is still registered")
+        if reply.get("type") != "registered" or reply.get("id") != self.node_id:
+            raise ValueError("unexpected router registration response")
+
+    async def _session(self, channel):
+        async def receive_requests():
+            async for payload in channel:
+                message = decode(payload)
+                if message.get("type") != "connect":
+                    raise ValueError("unknown router control message")
+                task = asyncio.create_task(self._serve(message["stream_id"]))
+                self._requests.add(task)
+                task.add_done_callback(self._requests.discard)
+
+        tasks = [
+            asyncio.create_task(self._refresh(channel)),
+            asyncio.create_task(receive_requests()),
+        ]
+        try:
+            done, _pending = await asyncio.wait(
+                tasks, return_when=asyncio.FIRST_COMPLETED
+            )
+            for task in done:
+                task.result()
+        finally:
+            for task in tasks:
+                task.cancel()
+            await asyncio.gather(*tasks, return_exceptions=True)
+
+    async def _refresh(self, channel):
+        while True:
+            await asyncio.sleep(self.refresh_seconds)
+            await channel.send(
+                encode(
+                    {
+                        "type": "workspaces",
+                        "workspaces": self.workspaces(),
+                    }
+                )
+            )
+
+    async def _serve(self, stream_id):
+        try:
+            async with self._connect(self.data_url) as channel:
+                self._channels.add(channel)
+                try:
+                    await channel.send(
+                        encode(
+                            {"stream_id": stream_id, "identity_key": self._identity_key}
+                        )
+                    )
+                    opening = decode(await asyncio.wait_for(channel.recv(), 10))
+                    if opening.get("type") != "open":
+                        raise ValueError("expected a router request")
+                    scope = opening["scope"]
+                    if scope["type"] not in {"http", "websocket"}:
+                        raise ValueError("unsupported router request type")
+
+                    async def receive():
+                        try:
+                            message = decode(await channel.recv())
+                        except ConnectionClosed:
+                            if scope["type"] == "http":
+                                return {"type": "http.disconnect"}
+                            return {"type": "websocket.disconnect", "code": 1001}
+                        allowed = (
+                            {"http.request", "http.disconnect"}
+                            if scope["type"] == "http"
+                            else {
+                                "websocket.connect",
+                                "websocket.receive",
+                                "websocket.disconnect",
+                            }
+                        )
+                        if message.get("type") not in allowed:
+                            raise ValueError("invalid router request event")
+                        return message
+
+                    async def send(message):
+                        await send_event(channel.send, message)
+
+                    await self.app(scope, receive, send)
+                finally:
+                    self._channels.discard(channel)
+        except (
+            ConnectionClosed,
+            OSError,
+            asyncio.TimeoutError,
+            InvalidHandshake,
+        ) as exc:
+            self._logger.warning("Router request disconnected (%s)", type(exc).__name__)
+        except Exception as exc:
+            self._logger.error("Router request failed (%s)", type(exc).__name__)
+
+
+def attach_router(app, registry, target, port):
+    def inventory():
+        return [
+            {
+                "id": workspace["id"],
+                "work_dir": workspace["work_dir"],
+                "state_path": workspace["state_path"],
+                "enable_board": workspace["enable_board"],
+                "session_count": len(workspace["sessions"]),
+                "running": any(session["running"] for session in workspace["sessions"]),
+            }
+            for workspace in registry.list_workspaces()
+        ]
+
+    client = RouterClient(app, target, socket.gethostname(), port, inventory)
+    original_lifespan = app.router.lifespan_context
+
+    @asynccontextmanager
+    async def lifespan(application):
+        async with original_lifespan(application) as state:
+            await client.start()
+            try:
+                yield state
+            finally:
+                await client.close()
+
+    app.router.lifespan_context = lifespan
+    app.state.router_client = client