scalebrowser 0.2.0__py3-none-any.whl

scalebrowser/cdp.py

@@ -0,0 +1,429 @@
+"""Direct-CDP driver (nodriver-style) over websockets — **not** a Playwright /
+Puppeteer control plane (DEC-006 / AC-FP-005).
+
+``start`` returns a ``cdp_ws`` endpoint; we connect with our own minimal CDP
+client: send/await commands by ``id`` over a single multiplexed socket, demux
+events, attach to page targets (``flatten``), and create isolated worlds. We
+deliberately never call ``Runtime.enable`` (a documented detection leak — the
+svebaa ``console.*`` + proxy-chain bypass); ``Runtime.evaluate`` works without it.
+
+The ``humanize_*`` helpers route to the daemon trusted-input endpoint
+(``POST /v1/profiles/:id/input``) so real OS/CDP events carry humanization
+primitives (G8).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any, AsyncIterator, Awaitable, Callable, Optional, Union
+from urllib.parse import quote
+
+from websockets.asyncio.client import connect as ws_connect
+from websockets.exceptions import ConnectionClosed
+
+from ._http import AsyncTransport
+from .errors import CdpError, NetworkError, ScalebrowserError
+
+CdpEvent = dict[str, Any]
+"""A demuxed CDP event: ``{ "method", "params", "sessionId" }``."""
+
+EventCallback = Callable[[CdpEvent], Any]
+
+_CLOSED = object()
+"""Queue sentinel: the connection died, the event stream is over."""
+
+
+class _EventIterator:
+    """Async iterator over CDP events. Registers its queue **eagerly** (on
+    construction) so events emitted before the first ``__anext__`` are not lost.
+    """
+
+    def __init__(self, connection: "_Connection") -> None:
+        self._connection = connection
+        self._queue: asyncio.Queue[Any] = asyncio.Queue()
+        if connection._closed:
+            # Connection already gone → the stream is immediately exhausted.
+            self._queue.put_nowait(_CLOSED)
+        else:
+            connection._queues.append(self._queue)
+
+    def __aiter__(self) -> "_EventIterator":
+        return self
+
+    async def __anext__(self) -> CdpEvent:
+        event = await self._queue.get()
+        if event is _CLOSED:
+            raise StopAsyncIteration
+        return event
+
+    async def aclose(self) -> None:
+        if self._queue in self._connection._queues:
+            self._connection._queues.remove(self._queue)
+
+
+class _Connection:
+    """Owns the websocket, the request/response id map and the event fan-out.
+
+    A single connection backs the root session and every attached child session
+    (flatten mode multiplexes all sessions over one socket and one id space).
+    """
+
+    def __init__(self, ws: Any) -> None:
+        self._ws = ws
+        self._next_id = 0
+        self._pending: dict[int, asyncio.Future[dict[str, Any]]] = {}
+        self._listeners: dict[str, list[EventCallback]] = {}
+        self._queues: list[asyncio.Queue[CdpEvent]] = []
+        self._closed = False
+        self._reader: asyncio.Task[None] = asyncio.create_task(self._read_loop())
+
+    def _new_id(self) -> int:
+        self._next_id += 1
+        return self._next_id
+
+    async def send(
+        self,
+        method: str,
+        params: Optional[dict[str, Any]] = None,
+        session_id: Optional[str] = None,
+    ) -> dict[str, Any]:
+        if self._closed:
+            raise ScalebrowserError("CDP connection is closed.")
+        msg_id = self._new_id()
+        message: dict[str, Any] = {"id": msg_id, "method": method}
+        if params is not None:
+            message["params"] = params
+        if session_id is not None:
+            message["sessionId"] = session_id
+        future: asyncio.Future[dict[str, Any]] = asyncio.get_running_loop().create_future()
+        self._pending[msg_id] = future
+        try:
+            await self._ws.send(json.dumps(message))
+        except ConnectionClosed as exc:
+            self._pending.pop(msg_id, None)
+            raise NetworkError("CDP connection closed while sending.", exc) from exc
+        return await future
+
+    async def _read_loop(self) -> None:
+        try:
+            async for raw in self._ws:
+                try:
+                    message = json.loads(raw)
+                except (ValueError, TypeError):
+                    continue
+                msg_id = message.get("id")
+                if msg_id is not None and msg_id in self._pending:
+                    future = self._pending.pop(msg_id)
+                    if future.done():
+                        continue
+                    error = message.get("error")
+                    if error:
+                        future.set_exception(
+                            CdpError(error.get("code"), error.get("message", "unknown"), error.get("data"))
+                        )
+                    else:
+                        future.set_result(message.get("result", {}))
+                elif "method" in message:
+                    self._dispatch(message)
+        except ConnectionClosed:
+            pass
+        finally:
+            self._fail_pending()
+
+    def _dispatch(self, message: dict[str, Any]) -> None:
+        event: CdpEvent = {
+            "method": message["method"],
+            "params": message.get("params", {}),
+            "sessionId": message.get("sessionId"),
+        }
+        for callback in (*self._listeners.get(event["method"], ()), *self._listeners.get("*", ())):
+            try:
+                callback(event)
+            except Exception:  # noqa: BLE001 — a bad listener must not kill the reader
+                pass
+        for queue in self._queues:
+            queue.put_nowait(event)
+
+    def _fail_pending(self) -> None:
+        self._closed = True
+        for future in self._pending.values():
+            if not future.done():
+                future.set_exception(NetworkError("CDP connection closed."))
+        self._pending.clear()
+        # End every event stream: a pending ``__anext__`` must resolve with
+        # ``StopAsyncIteration`` instead of hanging forever after a disconnect.
+        for queue in self._queues:
+            queue.put_nowait(_CLOSED)
+        self._queues.clear()
+
+    def on(self, method: str, callback: EventCallback) -> Callable[[], None]:
+        self._listeners.setdefault(method, []).append(callback)
+
+        def unsubscribe() -> None:
+            handlers = self._listeners.get(method)
+            if handlers and callback in handlers:
+                handlers.remove(callback)
+
+        return unsubscribe
+
+    def events(self) -> _EventIterator:
+        return _EventIterator(self)
+
+    async def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        self._reader.cancel()
+        try:
+            await self._ws.close()
+        except Exception:  # noqa: BLE001
+            pass
+        self._fail_pending()
+
+
+class CdpSession:
+    """A handle on the CDP connection, optionally bound to a target ``session_id``.
+
+    The root session (no ``session_id``) drives the browser endpoint; children
+    returned by :meth:`attach_to_page` drive a page target.
+    """
+
+    def __init__(
+        self,
+        connection: _Connection,
+        session_id: Optional[str] = None,
+        *,
+        transport: Optional[AsyncTransport] = None,
+        profile_id: Optional[str] = None,
+        owns_connection: bool = False,
+    ) -> None:
+        self._conn = connection
+        self.session_id = session_id
+        self._transport = transport
+        self._profile_id = profile_id
+        self._owns = owns_connection
+
+    # ── raw protocol ──────────────────────────────────────────────────────────
+
+    async def send(self, method: str, params: Optional[dict[str, Any]] = None) -> dict[str, Any]:
+        """Send a CDP command and await its result (raises :class:`CdpError`)."""
+        return await self._conn.send(method, params, self.session_id)
+
+    def on(self, method: str, callback: EventCallback) -> Callable[[], None]:
+        """Subscribe to a CDP event method (``"*"`` for all). Returns an unsubscribe."""
+        return self._conn.on(method, callback)
+
+    def events(self) -> AsyncIterator[CdpEvent]:
+        """Async-iterate every CDP event seen on the connection."""
+        return self._conn.events()
+
+    # ── targets ───────────────────────────────────────────────────────────────
+
+    async def attach_to_page(
+        self,
+        target_id: Optional[str] = None,
+        *,
+        create: bool = False,
+        url: Optional[str] = None,
+    ) -> "CdpSession":
+        """Attach to a page target (flatten) and return a child session bound to it."""
+        if create:
+            created = await self.send("Target.createTarget", {"url": url or "about:blank"})
+            target_id = created["targetId"]
+        elif target_id is None:
+            targets = await self.send("Target.getTargets", {})
+            pages = [t for t in targets.get("targetInfos", []) if t.get("type") == "page"]
+            if pages:
+                target_id = pages[0]["targetId"]
+            else:
+                created = await self.send("Target.createTarget", {"url": url or "about:blank"})
+                target_id = created["targetId"]
+        attached = await self.send("Target.attachToTarget", {"targetId": target_id, "flatten": True})
+        return CdpSession(
+            self._conn,
+            attached["sessionId"],
+            transport=self._transport,
+            profile_id=self._profile_id,
+        )
+
+    # ── navigation & evaluation ──────────────────────────────────────────────
+
+    async def navigate(self, url: str, *, wait: bool = True, timeout: float = 30.0) -> dict[str, Any]:
+        """Navigate the page to ``url``; optionally wait for ``document.readyState``."""
+        result = await self.send("Page.navigate", {"url": url})
+        if wait:
+            await self._wait_ready(timeout)
+        return result
+
+    async def _wait_ready(self, timeout: float) -> None:
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + timeout
+        while loop.time() < deadline:
+            try:
+                state = await self.evaluate("document.readyState")
+            except CdpError:
+                state = None
+            if state in ("interactive", "complete"):
+                return
+            await asyncio.sleep(0.05)
+        raise TimeoutError(f"Timed out after {timeout}s waiting for the page to load.")
+
+    async def evaluate(
+        self,
+        expression: str,
+        *,
+        await_promise: bool = True,
+        return_by_value: bool = True,
+        isolated: bool = False,
+    ) -> Any:
+        """Evaluate JS via ``Runtime.evaluate`` (never ``Runtime.enable``)."""
+        params: dict[str, Any] = {
+            "expression": expression,
+            "returnByValue": return_by_value,
+            "awaitPromise": await_promise,
+        }
+        if isolated:
+            params["contextId"] = await self.create_isolated_world()
+        result = await self.send("Runtime.evaluate", params)
+        details = result.get("exceptionDetails")
+        if details:
+            raise CdpError(None, details.get("text", "evaluation failed"), details)
+        remote = result.get("result", {})
+        return remote.get("value") if return_by_value else remote
+
+    async def create_isolated_world(
+        self,
+        frame_id: Optional[str] = None,
+        world_name: str = "__sb",
+    ) -> int:
+        """Create an isolated world and return its ``executionContextId``."""
+        if frame_id is None:
+            tree = await self.send("Page.getFrameTree", {})
+            frame_id = tree["frameTree"]["frame"]["id"]
+        world = await self.send(
+            "Page.createIsolatedWorld",
+            {"frameId": frame_id, "worldName": world_name},
+        )
+        return world["executionContextId"]
+
+    # ── humanized trusted input (G8) ─────────────────────────────────────────
+
+    async def _input(self, body: dict[str, Any]) -> None:
+        if self._transport is None or self._profile_id is None:
+            raise ScalebrowserError(
+                "Humanized input needs a profile-bound CDP session. "
+                "Use client.connect_cdp(result, profile_id=...) or client.launch()."
+            )
+        await self._transport.post(f"/v1/profiles/{quote(self._profile_id)}/input", body)
+
+    async def humanize_move(self, x: float, y: float, *, width: float | None = None) -> None:
+        # B5: `width` = an element's effective target width; the daemon's Fitts-law
+        # approach lands within the element instead of a fixed corner.
+        body: dict[str, Any] = {"action": "move", "x": x, "y": y, "humanize": True}
+        if width is not None:
+            body["width"] = width
+        await self._input(body)
+
+    async def humanize_click(
+        self,
+        x: float,
+        y: float,
+        *,
+        button: str = "left",
+        click_count: int = 1,
+        width: float | None = None,
+    ) -> None:
+        body: dict[str, Any] = {
+            "action": "click",
+            "x": x,
+            "y": y,
+            "button": button,
+            "click_count": click_count,
+            "humanize": True,
+        }
+        if width is not None:
+            body["width"] = width
+        await self._input(body)
+
+    async def humanize_move_to_element(
+        self, box: dict[str, float]
+    ) -> None:
+        """B5: humanized move to the CENTRE of an element box ``{x, y, width, height}``
+        (e.g. from ``getBoundingClientRect()``), feeding the width to the daemon's
+        Fitts-law approach so the pointer lands within the element."""
+        await self.humanize_move(
+            box["x"] + box["width"] / 2, box["y"] + box["height"] / 2, width=box["width"]
+        )
+
+    async def humanize_click_element(
+        self, box: dict[str, float], *, button: str = "left", click_count: int = 1
+    ) -> None:
+        """B5: humanized click at the centre of an element box (see
+        :meth:`humanize_move_to_element`)."""
+        await self.humanize_click(
+            box["x"] + box["width"] / 2,
+            box["y"] + box["height"] / 2,
+            button=button,
+            click_count=click_count,
+            width=box["width"],
+        )
+
+    async def humanize_type(self, text: str) -> None:
+        await self._input({"action": "type", "text": text, "humanize": True})
+
+    async def humanize_scroll(
+        self, x: float, y: float, *, delta_x: float = 0, delta_y: float = 0
+    ) -> None:
+        await self._input(
+            {"action": "scroll", "x": x, "y": y, "delta_x": delta_x, "delta_y": delta_y, "humanize": True}
+        )
+
+    # ── lifecycle ─────────────────────────────────────────────────────────────
+
+    async def close(self) -> None:
+        if self._owns:
+            await self._conn.close()
+
+    async def __aenter__(self) -> "CdpSession":
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.close()
+
+
+async def connect_cdp(
+    cdp_ws: str,
+    *,
+    token: Optional[str] = None,
+    transport: Optional[AsyncTransport] = None,
+    profile_id: Optional[str] = None,
+    attach: bool = True,
+) -> CdpSession:
+    """Open a direct-CDP session against a ``cdp_ws`` endpoint.
+
+    With ``attach=True`` (default) the returned session is bound to a page target
+    so :meth:`CdpSession.navigate` / :meth:`CdpSession.evaluate` work immediately.
+    """
+    headers: dict[str, str] = {}
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    try:
+        ws = await ws_connect(cdp_ws, additional_headers=headers, max_size=None)
+    except Exception as exc:  # noqa: BLE001 — normalize handshake/transport failures
+        raise NetworkError(f"Could not connect to CDP endpoint {cdp_ws}.", exc) from exc
+
+    connection = _Connection(ws)
+    root = CdpSession(
+        connection, None, transport=transport, profile_id=profile_id, owns_connection=True
+    )
+    if not attach:
+        return root
+    try:
+        page = await root.attach_to_page()
+    except Exception:
+        await connection.close()
+        raise
+    page._owns = True
+    root._owns = False
+    return page