modcdp 0.0.2__py3-none-any.whl

modcdp/ModCDPClient.py

@@ -0,0 +1,912 @@
+"""ModCDPClient (Python): importable, no CLI, no demo code.
+
+Constructor parameter names mirror the JS / Go ports:
+    cdp_url           upstream CDP URL (str)
+    extension_path    extension directory (str)
+    routes            client-side routing dict
+    server            { 'loopback_cdp_url'?, 'routes'? } passed to ModCDPServer.configure
+    scan_for_existing_localhost_9222
+                      when true and cdp_url is unset, attach to localhost:9222 before autolaunching
+    mirror_upstream_events
+                      when false, do not mirror server-side upstream CDP events back through Runtime bindings
+    *_timeout_ms / *_interval_ms
+                      override default CDP send, service-worker probe, event, and poll timings
+
+Public methods: connect(), send(method, params), on(event, handler), close(), _cdp.send(), _cdp.on().
+Synchronous (blocking) API; one background thread reads frames off the WS.
+"""
+
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import threading
+import time
+import tempfile
+import urllib.error
+import urllib.parse
+import urllib.request
+import socket
+import zipfile
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from queue import Queue, Empty
+from typing import cast
+
+from websocket import create_connection
+
+from .translate import (
+    CUSTOM_EVENT_BINDING_NAME,
+    DEFAULT_CLIENT_ROUTES,
+    UPSTREAM_EVENT_BINDING_NAME,
+    wrap_command_if_needed,
+    unwrap_event_if_needed,
+    unwrap_response_if_needed,
+)
+from .types import (
+    ModCDPAddCustomCommandParams,
+    ModCDPAddCustomEventObjectParams,
+    ModCDPAddCustomEventParams,
+    ModCDPAddMiddlewareParams,
+    ModCDPCommandTiming,
+    ModCDPConnectTiming,
+    ModCDPPingLatency,
+    ModCDPRawTiming,
+    ModCDPRoutes,
+    ModCDPServerConfig,
+    BorrowedExtensionInfo,
+    CdpFrame,
+    ExtensionInfo,
+    ExtensionProbe,
+    FrameParams,
+    Handler,
+    JsonValue,
+    LaunchOptions,
+    PendingEntry,
+    ProtocolParams,
+    ProtocolPayload,
+    ProtocolResult,
+    TargetInfo,
+    TranslatedCommand,
+    WebSocketLike,
+)
+
+EXT_ID_FROM_URL_RE = re.compile(r"^chrome-extension://([a-z]+)/")
+MODCDP_READY_EXPRESSION = (
+    "Boolean(globalThis.ModCDP?.__ModCDPServerVersion === 1 && "
+    "globalThis.ModCDP?.handleCommand && globalThis.ModCDP?.addCustomEvent)"
+)
+DEFAULT_SERVER = object()
+DEFAULT_LIVE_CDP_URL = "http://127.0.0.1:9222"
+DEFAULT_CDP_SEND_TIMEOUT_MS = 10_000
+DEFAULT_EVENT_WAIT_TIMEOUT_MS = 10_000
+DEFAULT_EXECUTION_CONTEXT_TIMEOUT_MS = 10_000
+DEFAULT_CHROME_READY_TIMEOUT_MS = 45_000
+DEFAULT_SERVICE_WORKER_PROBE_TIMEOUT_MS = 10_000
+DEFAULT_SERVICE_WORKER_READY_TIMEOUT_MS = 60_000
+DEFAULT_SERVICE_WORKER_POLL_INTERVAL_MS = 100
+DEFAULT_TARGET_SESSION_POLL_INTERVAL_MS = 20
+DEFAULT_WS_CONNECT_ERROR_SETTLE_TIMEOUT_MS = 250
+
+
+class _DomainMethods:
+    def __init__(self, client: "ModCDPClient", domain: str) -> None:
+        self._client = client
+        self._domain = domain
+
+    def __getattr__(self, method: str):
+        def call(*args: ProtocolParams, **kwargs: JsonValue) -> JsonValue:
+            if len(args) > 1:
+                raise TypeError(f"{self._domain}.{method} accepts at most one positional params object")
+            params: ProtocolParams = dict(args[0]) if args else {}
+            params.update(kwargs)
+            return self._client.send(f"{self._domain}.{method}", params)
+
+        return call
+
+
+class _RawCDP:
+    def __init__(self, client: "ModCDPClient") -> None:
+        self._client = client
+
+    def send(
+        self,
+        method: str,
+        params: ProtocolParams | None = None,
+        session_id: str | None = None,
+    ) -> ProtocolResult:
+        return self._client._send_frame(method, params or {}, session_id=session_id, record_raw_timing=True)
+
+    def on(self, event: str, handler: Handler) -> "ModCDPClient":
+        return self._client.on(event, handler)
+
+
+def websocket_url_for(endpoint: str) -> str:
+    if re.match(r"^wss?://", endpoint, re.I):
+        return endpoint
+    http_endpoint = endpoint if re.match(r"^[a-z][a-z\d+\-.]*://", endpoint, re.I) else f"http://{endpoint}"
+    try:
+        r = urllib.request.urlopen(f"{http_endpoint}/json/version", timeout=5)
+    except urllib.error.HTTPError as e:
+        if e.code != 404:
+            raise
+        parsed = urllib.parse.urlparse(http_endpoint)
+        scheme = "wss" if parsed.scheme == "https" else "ws"
+        return urllib.parse.urlunparse((scheme, parsed.netloc, "/devtools/browser", "", "", ""))
+    with r:
+        parsed: object = json.loads(r.read())
+    if not isinstance(parsed, dict):
+        raise RuntimeError(f"HTTP discovery for {endpoint} returned invalid JSON")
+    parsed_obj = cast(Mapping[str, object], parsed)
+    ws_url = parsed_obj.get("webSocketDebuggerUrl")
+    if not ws_url:
+        raise RuntimeError(f"HTTP discovery for {endpoint} returned no webSocketDebuggerUrl")
+    if not isinstance(ws_url, str):
+        raise RuntimeError(f"HTTP discovery for {endpoint} returned a non-string webSocketDebuggerUrl")
+    return ws_url
+
+
+def live_websocket_url_for(endpoint: str = DEFAULT_LIVE_CDP_URL) -> str | None:
+    try:
+        return websocket_url_for(endpoint)
+    except Exception:
+        return None
+
+
+def _free_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.bind(("127.0.0.1", 0))
+        return sock.getsockname()[1]
+
+
+def _json_object(value: JsonValue | None) -> ProtocolResult:
+    return value if isinstance(value, dict) else {}
+
+
+def modcdp_server_path(extension_path: str) -> Path:
+    candidates = [Path(extension_path) / "ModCDPServer.js"]
+    for parent in Path(__file__).resolve().parents:
+        candidates.append(parent / "dist" / "extension" / "ModCDPServer.js")
+    for candidate in candidates:
+        if candidate.exists():
+            return candidate
+    checked = ", ".join(str(candidate) for candidate in candidates)
+    raise FileNotFoundError(f"Unable to locate ModCDPServer.js; checked: {checked}")
+
+
+def modcdp_server_bootstrap_expression(extension_path: str) -> str:
+    server_path = modcdp_server_path(extension_path)
+    source = server_path.read_text()
+    start = source.index("export function installModCDPServer")
+    end = source.index("export const ModCDPServer")
+    installer = source[start:end].replace("export function", "function", 1)
+    return (
+        "(() => {\n"
+        f"{installer}\n"
+        "const ModCDP = installModCDPServer(globalThis);\n"
+        "return {\n"
+        "  ok: Boolean(ModCDP?.__ModCDPServerVersion === 1 && ModCDP?.handleCommand && ModCDP?.addCustomEvent),\n"
+        "  extension_id: globalThis.chrome?.runtime?.id ?? null,\n"
+        "  has_tabs: Boolean(globalThis.chrome?.tabs?.query),\n"
+        "  has_debugger: Boolean(globalThis.chrome?.debugger?.sendCommand),\n"
+        "};\n"
+        "})()"
+    )
+
+
+class ModCDPClient:
+    def __init__(
+        self,
+        cdp_url: str | None = None,
+        extension_path: str | None = None,
+        routes: Mapping[str, str] | None = None,
+        server: Mapping[str, JsonValue] | None | object = DEFAULT_SERVER,
+        custom_commands: Sequence[ModCDPAddCustomCommandParams] | None = None,
+        custom_events: Sequence[ModCDPAddCustomEventParams] | None = None,
+        custom_middlewares: Sequence[ModCDPAddMiddlewareParams] | None = None,
+        service_worker_url_includes: Sequence[str] | None = None,
+        service_worker_url_suffixes: Sequence[str] | None = None,
+        trust_service_worker_target: bool = False,
+        require_service_worker_target: bool = False,
+        service_worker_ready_expression: str | None = None,
+        mirror_upstream_events: bool = True,
+        scan_for_existing_localhost_9222: bool = False,
+        cdp_send_timeout_ms: int = DEFAULT_CDP_SEND_TIMEOUT_MS,
+        event_wait_timeout_ms: int = DEFAULT_EVENT_WAIT_TIMEOUT_MS,
+        execution_context_timeout_ms: int = DEFAULT_EXECUTION_CONTEXT_TIMEOUT_MS,
+        service_worker_probe_timeout_ms: int = DEFAULT_SERVICE_WORKER_PROBE_TIMEOUT_MS,
+        service_worker_ready_timeout_ms: int = DEFAULT_SERVICE_WORKER_READY_TIMEOUT_MS,
+        service_worker_poll_interval_ms: int = DEFAULT_SERVICE_WORKER_POLL_INTERVAL_MS,
+        target_session_poll_interval_ms: int = DEFAULT_TARGET_SESSION_POLL_INTERVAL_MS,
+        ws_connect_error_settle_timeout_ms: int = DEFAULT_WS_CONNECT_ERROR_SETTLE_TIMEOUT_MS,
+        launch_options: LaunchOptions | None = None,
+    ) -> None:
+        self.cdp_url: str | None = cdp_url
+        self.extension_path: str | None = extension_path
+        self.routes: ModCDPRoutes = {**DEFAULT_CLIENT_ROUTES, **dict(routes or {})}
+        if server is DEFAULT_SERVER:
+            self.server: ModCDPServerConfig | None = {}
+        elif server is None:
+            self.server = None
+        elif isinstance(server, Mapping):
+            self.server = cast(ModCDPServerConfig, dict(server))
+        else:
+            raise TypeError("server must be a mapping, None, or omitted")
+        self.custom_commands: list[ModCDPAddCustomCommandParams] = list(custom_commands or [])
+        self.custom_events: list[ModCDPAddCustomEventParams] = list(custom_events or [])
+        self.custom_middlewares: list[ModCDPAddMiddlewareParams] = list(custom_middlewares or [])
+        self.service_worker_url_includes: list[str] = list(service_worker_url_includes or [])
+        self.service_worker_url_suffixes: list[str] = list(service_worker_url_suffixes or ["/service_worker.js", "/background.js"])
+        self.trust_service_worker_target = trust_service_worker_target
+        self.require_service_worker_target = require_service_worker_target
+        self.service_worker_ready_expression = service_worker_ready_expression
+        self.mirror_upstream_events = mirror_upstream_events
+        self.scan_for_existing_localhost_9222 = scan_for_existing_localhost_9222
+        self.cdp_send_timeout_ms = cdp_send_timeout_ms
+        self.event_wait_timeout_ms = event_wait_timeout_ms
+        self.execution_context_timeout_ms = execution_context_timeout_ms
+        self.service_worker_probe_timeout_ms = service_worker_probe_timeout_ms
+        self.service_worker_ready_timeout_ms = service_worker_ready_timeout_ms
+        self.service_worker_poll_interval_ms = service_worker_poll_interval_ms
+        self.target_session_poll_interval_ms = target_session_poll_interval_ms
+        self.ws_connect_error_settle_timeout_ms = ws_connect_error_settle_timeout_ms
+        self.server_options: ModCDPServerConfig = {
+            "cdp_send_timeout_ms": cdp_send_timeout_ms,
+            "loopback_execution_context_timeout_ms": execution_context_timeout_ms,
+            "ws_connect_error_settle_timeout_ms": ws_connect_error_settle_timeout_ms,
+        }
+        self.launch_options = cast(LaunchOptions, dict(launch_options or {}))
+
+        self.extension_id: str | None = None
+        self.ext_target_id: str | None = None
+        self.ext_session_id: str | None = None
+        self.latency: ModCDPPingLatency | None = None
+        self.connect_timing: ModCDPConnectTiming | None = None
+        self.last_command_timing: ModCDPCommandTiming | None = None
+        self.last_raw_timing: ModCDPRawTiming | None = None
+
+        self._ws: WebSocketLike | None = None
+        self._next_id = 0
+        self._pending: dict[int, PendingEntry] = {}
+        self._handlers: dict[str, list[Handler]] = {}
+        self._lock = threading.Lock()
+        self._target_sessions: dict[str, str] = {}
+        self._session_targets: dict[str, TargetInfo] = {}
+        self._reader_thread: threading.Thread | None = None
+        self._closed = False
+        self._launched_process: subprocess.Popen[bytes] | None = None
+        self._profile_dir: tempfile.TemporaryDirectory[str] | None = None
+        self._prepared_extension_dir: tempfile.TemporaryDirectory[str] | None = None
+        self._cdp = _RawCDP(self)
+
+    def connect(self) -> "ModCDPClient":
+        connect_started_at = int(time.time() * 1000)
+        if self.cdp_url is None:
+            self.cdp_url = live_websocket_url_for() if self.scan_for_existing_localhost_9222 else None
+            if self.cdp_url is None:
+                self._prepare_extension_path()
+                launched = self._launch_chrome()
+                self.cdp_url = launched["cdp_url"]
+        input_cdp_url = self.cdp_url
+        self.cdp_url = websocket_url_for(input_cdp_url)
+        if self.server is not None and "loopback_cdp_url" not in self.server:
+            self.server = {**self.server, "loopback_cdp_url": self.cdp_url}
+        elif self.server and isinstance(self.server.get("loopback_cdp_url"), str):
+            loopback_url = self.server["loopback_cdp_url"]
+            if loopback_url == input_cdp_url or loopback_url == self.cdp_url:
+                self.server = {**self.server, "loopback_cdp_url": self.cdp_url}
+        self._ws = cast(WebSocketLike, create_connection(self.cdp_url, timeout=self.cdp_send_timeout_ms / 1000))
+        self._reader_thread = threading.Thread(target=self._reader, daemon=True)
+        self._reader_thread.start()
+
+        self._send_frame("Target.setAutoAttach", {
+            "autoAttach": True,
+            "waitForDebuggerOnStart": False,
+            "flatten": True,
+        })
+        self._send_frame("Target.setDiscoverTargets", {"discover": True})
+
+        extension_started_at = int(time.time() * 1000)
+        self._prepare_extension_path()
+        ext = self._ensure_extension()
+        extension_completed_at = int(time.time() * 1000)
+        self.extension_id = ext["extension_id"]
+        self.ext_target_id = ext["target_id"]
+        self.ext_session_id = ext["session_id"]
+        self._send_frame("Runtime.enable", {}, self.ext_session_id)
+        self._send_frame("Runtime.addBinding", {"name": CUSTOM_EVENT_BINDING_NAME}, self.ext_session_id)
+        if self.mirror_upstream_events:
+            self._send_frame("Runtime.addBinding", {"name": UPSTREAM_EVENT_BINDING_NAME}, self.ext_session_id)
+
+        if self.server is not None:
+            custom_events: list[ModCDPAddCustomEventObjectParams] = []
+            for event in self.custom_events:
+                custom_events.append({"name": event} if isinstance(event, str) else event)
+            custom_commands: list[ModCDPAddCustomCommandParams] = [
+                command
+                for command in self.custom_commands
+                if isinstance(command.get("expression"), str) and command.get("expression")
+            ]
+            custom_middlewares: list[ModCDPAddMiddlewareParams] = list(self.custom_middlewares)
+            configure_params: ModCDPServerConfig = {
+                **self.server_options,
+                **self.server,
+                "custom_events": custom_events,
+                "custom_commands": custom_commands,
+                "custom_middlewares": custom_middlewares,
+            }
+            self._send_raw(wrap_command_if_needed(
+                "Mod.configure",
+                cast(ProtocolParams, configure_params),
+                routes=self.routes,
+                cdp_session_id=self.ext_session_id,
+            ))
+        threading.Thread(target=self._measure_ping_latency, daemon=True).start()
+        connected_at = int(time.time() * 1000)
+        self.connect_timing = {
+            "started_at": connect_started_at,
+            "extension_source": ext.get("source"),
+            "extension_started_at": extension_started_at,
+            "extension_completed_at": extension_completed_at,
+            "extension_duration_ms": extension_completed_at - extension_started_at,
+            "connected_at": connected_at,
+            "duration_ms": connected_at - connect_started_at,
+        }
+        return self
+
+    def send(self, method: str, params: ProtocolParams | None = None) -> JsonValue:
+        started_at = int(time.time() * 1000)
+        command = wrap_command_if_needed(
+            method,
+            params or {},
+            routes=self.routes,
+            cdp_session_id=self.ext_session_id,
+        )
+        result = self._send_raw(command)
+        completed_at = int(time.time() * 1000)
+        self.last_command_timing = {
+            "method": method,
+            "target": command["target"],
+            "started_at": started_at,
+            "completed_at": completed_at,
+            "duration_ms": completed_at - started_at,
+        }
+        return result
+
+    def raw_send(self, method: str, params: ProtocolParams | None = None) -> ProtocolResult:
+        return self._send_frame(method, params or {}, record_raw_timing=True)
+
+    def on(self, event: str, handler: Handler) -> "ModCDPClient":
+        self._handlers.setdefault(event, []).append(handler)
+        return self
+
+    def __getattr__(self, domain: str) -> _DomainMethods:
+        if domain.startswith("_"):
+            raise AttributeError(domain)
+        return _DomainMethods(self, domain)
+
+    def close(self) -> None:
+        if self._closed:
+            return
+        if self._ws is not None:
+            try:
+                with self._lock:
+                    self._next_id += 1
+                    msg_id = self._next_id
+                self._ws.send(json.dumps({"id": msg_id, "method": "Browser.close", "params": {}}))
+            except Exception:
+                pass
+        self._closed = True
+        try:
+            if self._ws:
+                self._ws.close()
+        except Exception:
+            pass
+        if self._reader_thread is not None and self._reader_thread.is_alive():
+            self._reader_thread.join(timeout=1)
+        self._ws = None
+        if self._launched_process is not None:
+            self._launched_process.terminate()
+            try:
+                self._launched_process.wait(timeout=2)
+            except subprocess.TimeoutExpired:
+                self._launched_process.kill()
+                self._launched_process.wait(timeout=2)
+            self._launched_process = None
+        if self._profile_dir is not None:
+            self._cleanup_temp_dir(self._profile_dir)
+            self._profile_dir = None
+        if self._prepared_extension_dir is not None:
+            self._cleanup_temp_dir(self._prepared_extension_dir)
+            self._prepared_extension_dir = None
+
+    def _cleanup_temp_dir(self, temp_dir: tempfile.TemporaryDirectory[str]) -> None:
+        for attempt in range(20):
+            try:
+                temp_dir.cleanup()
+                return
+            except OSError:
+                if attempt == 19:
+                    shutil.rmtree(temp_dir.name, ignore_errors=True)
+                    return
+                time.sleep(0.1)
+
+    def _ready_expression(self) -> str:
+        if not self.service_worker_ready_expression:
+            return MODCDP_READY_EXPRESSION
+        return f"({MODCDP_READY_EXPRESSION}) && Boolean({self.service_worker_ready_expression})"
+
+    def _session_id_for_target(self, target_id: str, timeout: float = 0) -> str | None:
+        if timeout <= 0:
+            return self._target_sessions.get(target_id)
+        deadline = time.time() + timeout
+        while time.time() <= deadline:
+            session_id = self._target_sessions.get(target_id)
+            if session_id:
+                return session_id
+            time.sleep(self.target_session_poll_interval_ms / 1000)
+        return None
+
+    def _ensure_session_id_for_target(self, target_id: str, timeout: float = 0, allow_attach: bool = False) -> str | None:
+        session_id = self._target_sessions.get(target_id)
+        if session_id:
+            return session_id
+        if allow_attach:
+            result = self._send_frame(
+                "Target.attachToTarget",
+                {"targetId": target_id, "flatten": True},
+                timeout=max(timeout, self.cdp_send_timeout_ms / 1000),
+            )
+            attached_session_id = result.get("sessionId")
+            if isinstance(attached_session_id, str) and attached_session_id:
+                self._target_sessions[target_id] = attached_session_id
+                return attached_session_id
+        return self._session_id_for_target(target_id, timeout=timeout)
+
+    def _launch_chrome(self) -> dict[str, str]:
+        executable_path = self.launch_options.get("executable_path") or os.environ.get("CHROME_PATH")
+        candidates = [
+            executable_path,
+            "/Applications/Chromium.app/Contents/MacOS/Chromium",
+            "/Applications/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing",
+            str(Path.home() / "Library/Caches/ms-playwright/chromium-1217/chrome-mac-arm64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing"),
+            "/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary",
+            "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+            "/usr/bin/chromium",
+            "/usr/bin/chromium-browser",
+            "/usr/bin/google-chrome-canary",
+            "/usr/bin/google-chrome-stable",
+            "/usr/bin/google-chrome",
+        ]
+        executable_path = next((candidate for candidate in candidates if candidate and Path(candidate).exists()), None)
+        if executable_path is None:
+            raise RuntimeError("No Chrome/Chromium binary found. Set CHROME_PATH or pass launch_options.executable_path.")
+        port = int(self.launch_options.get("port") or _free_port())
+        self._profile_dir = tempfile.TemporaryDirectory(prefix="modcdp.")
+        args = [
+            "--enable-unsafe-extension-debugging",
+            "--remote-allow-origins=*",
+            "--no-first-run",
+            "--no-default-browser-check",
+            "--disable-default-apps",
+            "--disable-dev-shm-usage",
+            "--disable-background-networking",
+            "--disable-backgrounding-occluded-windows",
+            "--disable-renderer-backgrounding",
+            "--disable-background-timer-throttling",
+            "--disable-sync",
+            "--disable-features=DisableLoadExtensionCommandLineSwitch",
+            "--password-store=basic",
+            "--use-mock-keychain",
+            "--disable-gpu",
+            f"--user-data-dir={self._profile_dir.name}",
+            "--remote-debugging-address=127.0.0.1",
+            f"--remote-debugging-port={port}",
+        ]
+        default_headless = sys.platform.startswith("linux") and not os.environ.get("DISPLAY")
+        if self.launch_options.get("headless", default_headless):
+            args.append("--headless=new")
+        if self.launch_options.get("sandbox", False) is False:
+            args.append("--no-sandbox")
+        if self.extension_path:
+            args.append(f"--load-extension={self.extension_path}")
+        extra_args = self.launch_options.get("extra_args") or []
+        args.extend(extra_args)
+        args.append("about:blank")
+        self._launched_process = subprocess.Popen([executable_path, *args], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+        cdp_url = f"http://127.0.0.1:{port}"
+        chrome_ready_timeout_s = DEFAULT_CHROME_READY_TIMEOUT_MS / 1000
+        deadline = time.time() + chrome_ready_timeout_s
+        while time.time() < deadline:
+            try:
+                with urllib.request.urlopen(f"{cdp_url}/json/version", timeout=0.5) as response:
+                    json.loads(response.read())
+                    return {"cdp_url": cdp_url}
+            except Exception:
+                time.sleep(0.1)
+        self.close()
+        raise RuntimeError(f"Chrome at {cdp_url} did not become ready within {chrome_ready_timeout_s}s")
+
+    # --- internals ---------------------------------------------------------
+
+    def _prepare_extension_path(self) -> None:
+        if not self.extension_path or not self.extension_path.endswith(".zip"):
+            return
+        self._prepared_extension_dir = tempfile.TemporaryDirectory(prefix="modcdp-extension.")
+        with zipfile.ZipFile(self.extension_path) as archive:
+            archive.extractall(self._prepared_extension_dir.name)
+        self.extension_path = self._prepared_extension_dir.name
+
+    def _send_raw(self, wrapped: TranslatedCommand) -> JsonValue:
+        if wrapped["target"] == "direct_cdp":
+            step = wrapped["steps"][0]
+            return self._send_frame(step["method"], step.get("params") or {})
+        if wrapped["target"] != "service_worker":
+            raise RuntimeError(f"Unsupported command target {wrapped['target']!r}")
+
+        result: ProtocolResult = {}
+        unwrap: str | None = None
+        for step in wrapped["steps"]:
+            result = self._send_frame(step["method"], step.get("params") or {}, self.ext_session_id)
+            unwrap = step.get("unwrap")
+        return unwrap_response_if_needed(result, unwrap)
+
+    def _measure_ping_latency(self) -> ModCDPPingLatency:
+        sent_at = int(time.time() * 1000)
+        done: Queue[ProtocolPayload] = Queue()
+
+        def on_pong(payload: ProtocolPayload) -> None:
+            done.put(payload or {})
+
+        self._handlers.setdefault("Mod.pong", []).append(on_pong)
+        try:
+            self.send("Mod.ping", {"sentAt": sent_at})
+            payload = done.get(timeout=10)
+        except Empty:
+            raise RuntimeError("Mod.pong timed out")
+        finally:
+            handlers = self._handlers.get("Mod.pong") or []
+            if on_pong in handlers:
+                handlers.remove(on_pong)
+
+        returned_at = int(time.time() * 1000)
+        raw_received_at = payload.get("receivedAt")
+        received_at = raw_received_at if isinstance(raw_received_at, (int, float)) else None
+        latency: ModCDPPingLatency = {
+            "sentAt": sent_at,
+            "receivedAt": received_at,
+            "returnedAt": returned_at,
+            "roundTripMs": returned_at - sent_at,
+            "serviceWorkerMs": received_at - sent_at if received_at is not None else None,
+            "returnPathMs": returned_at - received_at if received_at is not None else None,
+        }
+        self.latency = latency
+        return latency
+
+    def _send_frame(
+        self,
+        method: str,
+        params: FrameParams | None = None,
+        session_id: str | None = None,
+        timeout: float | None = None,
+        record_raw_timing: bool = False,
+    ) -> ProtocolResult:
+        effective_timeout = self.cdp_send_timeout_ms / 1000 if timeout is None else timeout
+        with self._lock:
+            self._next_id += 1
+            msg_id = self._next_id
+            done: Queue[CdpFrame] = Queue()
+            self._pending[msg_id] = (method, done)
+        started_at = int(time.time() * 1000)
+        msg: CdpFrame = {"id": msg_id, "method": method, "params": params or {}}
+        if session_id:
+            msg["sessionId"] = session_id
+        ws = self._ws
+        if ws is None:
+            with self._lock:
+                self._pending.pop(msg_id, None)
+            raise RuntimeError("CDP websocket is not connected")
+        try:
+            ws.send(json.dumps(msg))
+        except Exception:
+            with self._lock:
+                self._pending.pop(msg_id, None)
+            raise
+        try:
+            response = done.get(timeout=effective_timeout)
+        except Empty:
+            with self._lock:
+                self._pending.pop(msg_id, None)
+            raise RuntimeError(f"{method} timed out after {int(effective_timeout * 1000)}ms")
+        err = response.get("error")
+        if err:
+            raise RuntimeError(f"{method} failed: {err.get('message', err)}")
+        if record_raw_timing:
+            completed_at = int(time.time() * 1000)
+            self.last_raw_timing = {
+                "method": method,
+                "started_at": started_at,
+                "completed_at": completed_at,
+                "duration_ms": completed_at - started_at,
+            }
+        return _json_object(response.get("result"))
+
+    def _reader(self) -> None:
+        ws = self._ws
+        if ws is None:
+            return
+        try:
+            while True:
+                raw = ws.recv()
+                if not raw:
+                    break
+                if isinstance(raw, bytes):
+                    raw = raw.decode()
+                parsed: object = json.loads(raw)
+                if not isinstance(parsed, dict):
+                    continue
+                msg = cast(CdpFrame, parsed)
+                if "id" in msg and msg["id"] is not None:
+                    with self._lock:
+                        entry = self._pending.pop(msg["id"], None)
+                    if entry:
+                        entry[1].put(msg)
+                    continue
+                method = msg.get("method")
+                raw_params = msg.get("params")
+                params = cast(ProtocolParams, raw_params) if isinstance(raw_params, Mapping) else {}
+                if method == "Target.attachedToTarget":
+                    session_id = params.get("sessionId")
+                    raw_target_info = params.get("targetInfo")
+                    target_info = cast(TargetInfo, raw_target_info) if isinstance(raw_target_info, dict) else None
+                    target_id = target_info.get("targetId") if target_info else None
+                    if isinstance(session_id, str) and isinstance(target_id, str) and target_info:
+                        self._target_sessions[target_id] = session_id
+                        self._session_targets[session_id] = target_info
+                elif method == "Target.detachedFromTarget":
+                    session_id = params.get("sessionId")
+                    target_info = self._session_targets.pop(session_id, None) if isinstance(session_id, str) else None
+                    target_id = target_info.get("targetId") if target_info else None
+                    if target_id:
+                        self._target_sessions.pop(target_id, None)
+                if method and msg.get("sessionId") == self.ext_session_id:
+                    session_id = msg.get("sessionId")
+                    u = unwrap_event_if_needed(
+                        method,
+                        params,
+                        session_id if isinstance(session_id, str) else None,
+                        self.ext_session_id,
+                    )
+                    if u:
+                        for h in self._handlers.get(u["event"], []):
+                            def run_wrapped_event(handler=h, payload=u["data"], event_name=u["event"]):
+                                try: handler(payload)
+                                except Exception as e: print(f"[ModCDPClient] handler error for {event_name}: {e}")
+                            threading.Thread(target=run_wrapped_event, daemon=True).start()
+                    continue
+                if method:
+                    for h in self._handlers.get(method, []):
+                        def run_method_event(handler=h, payload=dict(params), event_name=method):
+                            try: handler(payload)
+                            except Exception as e: print(f"[ModCDPClient] handler error for {event_name}: {e}")
+                        threading.Thread(target=run_method_event, daemon=True).start()
+        except Exception as e:
+            if not self._closed:
+                print(f"[ModCDPClient] reader exited: {e}")
+        finally:
+            with self._lock:
+                pending = list(self._pending.values())
+                self._pending.clear()
+            for _, done in pending:
+                done.put({"error": {"message": "connection closed"}})
+
+    def _target_infos(self) -> list[TargetInfo]:
+        value = self._send_frame("Target.getTargets").get("targetInfos")
+        if not isinstance(value, list):
+            return []
+        targets: list[TargetInfo] = []
+        for item in value:
+            if not isinstance(item, dict):
+                continue
+            target_id = item.get("targetId")
+            target_type = item.get("type")
+            target_url = item.get("url")
+            if isinstance(target_id, str) and isinstance(target_type, str) and isinstance(target_url, str):
+                targets.append({"targetId": target_id, "type": target_type, "url": target_url})
+        return targets
+
+    def _ensure_extension(self) -> ExtensionInfo:
+        ready_expression = self._ready_expression()
+        trust_service_worker_target = (
+            self.trust_service_worker_target
+            or len(self.service_worker_url_includes) > 0
+            or any(len([part for part in suffix.split("/") if part]) > 1 for suffix in self.service_worker_url_suffixes)
+        )
+
+        def probe_target(target: TargetInfo, timeout: float = 0, allow_attach: bool = False) -> ExtensionProbe | None:
+            target_id = target.get("targetId")
+            target_url = target.get("url")
+            if not target_id or not target_url:
+                return None
+            session_id = self._ensure_session_id_for_target(target_id, timeout=timeout, allow_attach=allow_attach)
+            if not session_id:
+                return None
+            self._send_frame("Runtime.enable", {}, session_id, timeout=self.cdp_send_timeout_ms / 1000)
+            probe = self._send_frame("Runtime.evaluate", {
+                "expression": ready_expression,
+                "returnByValue": True,
+            }, session_id, timeout=self.cdp_send_timeout_ms / 1000)
+            if _json_object(probe.get("result")).get("value") is not True:
+                return None
+            match = EXT_ID_FROM_URL_RE.match(target_url)
+            if match is None:
+                return None
+            return {
+                "extension_id": match.group(1),
+                "target_id": target_id,
+                "url": target_url,
+                "session_id": session_id,
+            }
+
+        def discover_ready_service_worker(matched_only: bool = False) -> ExtensionInfo | None:
+            target_infos = self._target_infos()
+            if trust_service_worker_target:
+                for t in target_infos:
+                    if self._service_worker_target_matches(t):
+                        try:
+                            result = probe_target(t, timeout=self.service_worker_probe_timeout_ms / 1000, allow_attach=True)
+                        except Exception:
+                            result = None
+                        if result:
+                            return {"source": "trusted", **result}
+            if trust_service_worker_target or matched_only:
+                return None
+            for t in target_infos:
+                if t["type"] != "service_worker": continue
+                if not t["url"].startswith("chrome-extension://"): continue
+                try:
+                    result = probe_target(t, timeout=self.service_worker_probe_timeout_ms / 1000)
+                except Exception:
+                    continue
+                if result:
+                    return {"source": "discovered", **result}
+            return None
+
+        def wait_for_ready_service_worker(timeout: float, matched_only: bool = False) -> ExtensionInfo | None:
+            deadline = time.monotonic() + timeout
+            while time.monotonic() < deadline:
+                result = discover_ready_service_worker(matched_only=matched_only)
+                if result:
+                    return result
+                time.sleep(self.service_worker_poll_interval_ms / 1000)
+            return None
+
+        # 1. Discover an existing ModCDP service worker. Browserbase loads the
+        # extension for the session, but the service-worker target can appear a
+        # moment after the browser CDP websocket accepts connections.
+        discovered = discover_ready_service_worker()
+        if discovered:
+            return discovered
+        if self.require_service_worker_target:
+            discovered = wait_for_ready_service_worker(
+                self.service_worker_probe_timeout_ms / 1000,
+                matched_only=trust_service_worker_target,
+            )
+            if discovered:
+                return discovered
+            raise RuntimeError(
+                "Required ModCDP service worker target did not become ready "
+                f"({', '.join([*self.service_worker_url_includes, *self.service_worker_url_suffixes]) or 'no matcher'})."
+            )
+        if self.extension_path is None:
+            raise RuntimeError("extension_path is required when no existing ModCDP service worker can be discovered.")
+
+        # 2. Try Extensions.loadUnpacked.
+        try:
+            r = self._send_frame("Extensions.loadUnpacked", {"path": self.extension_path})
+            extension_id = r.get("id") or r.get("extensionId")
+        except RuntimeError as e:
+            if "Method not available" in str(e) or "wasn't found" in str(e):
+                discovered = wait_for_ready_service_worker(
+                    self.service_worker_probe_timeout_ms / 1000,
+                    matched_only=trust_service_worker_target,
+                )
+                if discovered:
+                    return discovered
+                return self._borrow_extension_worker(str(e))
+            raise
+        if not isinstance(extension_id, str) or not extension_id:
+            raise RuntimeError(f"Extensions.loadUnpacked returned no id: {r}")
+
+        # 3. Wait for the loaded extension's SW.
+        sw_url_prefix = f"chrome-extension://{extension_id}/"
+        deadline = time.monotonic() + self.service_worker_ready_timeout_ms / 1000
+        while time.monotonic() < deadline:
+            for t in self._target_infos():
+                target_url = t.get("url") or ""
+                if t.get("type") == "service_worker" and target_url.startswith(sw_url_prefix):
+                    result = probe_target(t, timeout=self.service_worker_probe_timeout_ms / 1000, allow_attach=True)
+                    if result:
+                        return {
+                            "source": "injected", "extension_id": extension_id,
+                            "target_id": t["targetId"], "url": target_url, "session_id": result["session_id"],
+                        }
+            time.sleep(self.service_worker_poll_interval_ms / 1000)
+        raise RuntimeError(
+            f"Timed out after {self.service_worker_ready_timeout_ms}ms waiting for service worker target for extension {extension_id}."
+        )
+
+    def _service_worker_target_matches(self, target: TargetInfo) -> bool:
+        url = target.get("url") or ""
+        if target.get("type") != "service_worker" or not url.startswith("chrome-extension://"):
+            return False
+        if self.service_worker_url_includes and not all(part in url for part in self.service_worker_url_includes):
+            return False
+        if self.service_worker_url_suffixes and not any(url.endswith(suffix) for suffix in self.service_worker_url_suffixes):
+            return False
+        return bool(self.service_worker_url_includes or self.service_worker_url_suffixes)
+
+    def _borrow_extension_worker(self, load_error: str) -> ExtensionInfo:
+        if self.extension_path is None:
+            raise RuntimeError("extension_path is required to bootstrap a borrowed extension worker.")
+        borrowed: list[BorrowedExtensionInfo] = []
+        bootstrap = modcdp_server_bootstrap_expression(self.extension_path)
+        for t in self._target_infos():
+            target_id = t.get("targetId")
+            target_url = t.get("url") or ""
+            if t.get("type") != "service_worker": continue
+            if not target_id or not target_url.startswith("chrome-extension://"): continue
+            session_id = None
+            try:
+                session_id = self._session_id_for_target(target_id, timeout=2)
+                if not session_id:
+                    continue
+                try: self._send_frame("Runtime.enable", {}, session_id, timeout=2)
+                except Exception: pass
+                result = self._send_frame("Runtime.evaluate", {
+                    "expression": bootstrap,
+                    "awaitPromise": True,
+                    "returnByValue": True,
+                    "allowUnsafeEvalBlockedByCSP": True,
+                }, session_id, timeout=3)
+                result_object = result.get("result")
+                value = result_object.get("value") if isinstance(result_object, dict) else {}
+                if not isinstance(value, dict):
+                    value = {}
+                ready = bool(value.get("ok"))
+                if ready and self.service_worker_ready_expression:
+                    probe = self._send_frame("Runtime.evaluate", {
+                        "expression": self._ready_expression(),
+                        "returnByValue": True,
+                    }, session_id, timeout=2)
+                    ready = _json_object(probe.get("result")).get("value") is True
+                if ready:
+                    m = EXT_ID_FROM_URL_RE.match(target_url)
+                    extension_id = value.get("extension_id") or (m.group(1) if m else None)
+                    if not isinstance(extension_id, str):
+                        continue
+                    borrowed.append({
+                        "source": "borrowed",
+                        "extension_id": extension_id,
+                        "target_id": target_id,
+                        "url": target_url,
+                        "session_id": session_id,
+                        "has_tabs": bool(value.get("has_tabs")),
+                        "has_debugger": bool(value.get("has_debugger")),
+                    })
+            except Exception:
+                pass
+        borrowed.sort(key=lambda item: (item.get("has_debugger", False), item.get("has_tabs", False)), reverse=True)
+        if borrowed:
+            selected = borrowed[0]
+            selected.pop("has_tabs", None)
+            selected.pop("has_debugger", None)
+            return selected
+        raise RuntimeError(
+            "Cannot install or borrow ModCDP in the running browser.\n"
+            "  - No existing service worker with globalThis.ModCDP was found.\n"
+            f"  - Extensions.loadUnpacked is unavailable ({load_error}).\n"
+            "  - No running chrome-extension:// service worker accepted the ModCDP bootstrap."
+        )

modcdp/__init__.py

@@ -0,0 +1,3 @@
+from .ModCDPClient import ModCDPClient
+
+__all__ = ["ModCDPClient"]

modcdp/translate.py

@@ -0,0 +1,262 @@
+"""Pure ModCDP <-> CDP translation helpers for the Python client."""
+
+import json
+import time
+from typing import cast
+
+from .types import (
+    ModCDPRoutes,
+    JsonObject,
+    JsonValue,
+    ProtocolParams,
+    ProtocolPayload,
+    ProtocolResult,
+    RuntimeEvaluateParams,
+    TranslatedCommand,
+    TranslatedStep,
+    UnwrappedModCDPEvent,
+)
+
+UPSTREAM_EVENT_BINDING_NAME = "__ModCDP_event_from_upstream__"
+CUSTOM_EVENT_BINDING_NAME = "__ModCDP_custom_event__"
+
+DEFAULT_CLIENT_ROUTES: ModCDPRoutes = {
+    "Mod.*": "service_worker",
+    "Custom.*": "service_worker",
+    "*.*": "service_worker",
+}
+
+
+def route_for(method: str, routes: ModCDPRoutes) -> str:
+    routes = routes or {}
+    if method in routes:
+        return routes[method]
+    best_prefix_len = -1
+    best_route = None
+    for pattern, route in routes.items():
+        if pattern == "*.*" or not pattern.endswith(".*"):
+            continue
+        prefix = pattern[:-1]
+        if method.startswith(prefix) and len(prefix) > best_prefix_len:
+            best_prefix_len = len(prefix)
+            best_route = route
+    if best_route is not None:
+        return best_route
+    if "*.*" in routes:
+        return routes["*.*"]
+    return "direct_cdp"
+
+
+def _required_string(params: ProtocolParams, name: str) -> str:
+    value = params.get(name)
+    if not isinstance(value, str) or not value:
+        raise TypeError(f"{name} must be a non-empty string")
+    return value
+
+
+def _optional_string(params: ProtocolParams, name: str) -> str | None:
+    value = params.get(name)
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise TypeError(f"{name} must be a string")
+    return value
+
+
+def _object_or_empty(value: JsonValue | None) -> JsonObject:
+    return value if isinstance(value, dict) else {}
+
+
+def _eval_params(expression: str) -> RuntimeEvaluateParams:
+    return {
+        "expression": expression,
+        "awaitPromise": True,
+        "returnByValue": True,
+        "allowUnsafeEvalBlockedByCSP": True,
+    }
+
+
+def _wrap_modcdp_evaluate(params: ProtocolParams, session_id: str) -> RuntimeEvaluateParams:
+    expression = _required_string(params, "expression")
+    user_params = params.get("params", {})
+    cdp_session_id = _optional_string(params, "cdpSessionId") or session_id
+    return _eval_params(
+        "(async () => {\n"
+        f"  const params = {json.dumps(user_params)};\n"
+        f"  const cdp = globalThis.ModCDP.attachToSession({json.dumps(cdp_session_id)});\n"
+        "  const ModCDP = globalThis.ModCDP;\n"
+        "  const chrome = globalThis.chrome;\n"
+        f"  const value = ({expression});\n"
+        "  return typeof value === 'function' ? await value(params) : value;\n"
+        "})()"
+    )
+
+
+def _wrap_modcdp_add_custom_command(params: ProtocolParams) -> RuntimeEvaluateParams:
+    name = _required_string(params, "name")
+    expression = _required_string(params, "expression")
+    return _eval_params(
+        "(() => {\n"
+        "  return globalThis.ModCDP.addCustomCommand({\n"
+        f"    name: {json.dumps(name)},\n"
+        f"    paramsSchema: {json.dumps(params.get('paramsSchema'))},\n"
+        f"    resultSchema: {json.dumps(params.get('resultSchema'))},\n"
+        f"    expression: {json.dumps(expression)},\n"
+        "    handler: async (params, cdpSessionId, method) => {\n"
+        "      const cdp = globalThis.ModCDP.attachToSession(cdpSessionId);\n"
+        "      const ModCDP = globalThis.ModCDP;\n"
+        "      const chrome = globalThis.chrome;\n"
+        f"      const handler = ({expression});\n"
+        "      return await handler(params || {}, method);\n"
+        "    },\n"
+        "  });\n"
+        "})()"
+    )
+
+
+def _wrap_modcdp_add_custom_event(params: ProtocolParams) -> RuntimeEvaluateParams:
+    name = _required_string(params, "name")
+    return _eval_params(
+        "globalThis.ModCDP.addCustomEvent({\n"
+        f"  name: {json.dumps(name)},\n"
+        f"  eventSchema: {json.dumps(params.get('eventSchema'))},\n"
+        "})"
+    )
+
+
+def _wrap_modcdp_add_middleware(params: ProtocolParams) -> RuntimeEvaluateParams:
+    phase = _required_string(params, "phase")
+    expression = _required_string(params, "expression")
+    name = _optional_string(params, "name") or "*"
+    return _eval_params(
+        "(() => {\n"
+        "  return globalThis.ModCDP.addMiddleware({\n"
+        f"    name: {json.dumps(name)},\n"
+        f"    phase: {json.dumps(phase)},\n"
+        f"    expression: {json.dumps(expression)},\n"
+        "    handler: async (payload, next, context = {}) => {\n"
+        "      const cdp = globalThis.ModCDP.attachToSession(context.cdpSessionId ?? null);\n"
+        "      const ModCDP = globalThis.ModCDP;\n"
+        "      const chrome = globalThis.chrome;\n"
+        f"      const middleware = ({expression});\n"
+        "      return await middleware(payload, next, context);\n"
+        "    },\n"
+        "  });\n"
+        "})()"
+    )
+
+
+def _wrap_custom_command(method: str, params: ProtocolParams, session_id: str) -> RuntimeEvaluateParams:
+    return _eval_params(
+        f"globalThis.ModCDP.handleCommand("
+        f"{json.dumps(method)}, {json.dumps(params)}, "
+        f"{json.dumps(session_id)})"
+    )
+
+
+def _wrap_service_worker_command(method: str, params: ProtocolParams, session_id: str) -> list[TranslatedStep]:
+    if method == "Mod.ping" and "sentAt" not in params:
+        params = {**params, "sentAt": int(time.time() * 1000)}
+
+    if method == "Mod.addCustomEvent":
+        return [
+            {
+                "method": "Runtime.evaluate",
+                "params": _wrap_modcdp_add_custom_event(params),
+                "unwrap": "evaluate",
+            },
+        ]
+    if method == "Mod.evaluate":
+        runtime_params = _wrap_modcdp_evaluate(params, session_id)
+    elif method == "Mod.addCustomCommand":
+        runtime_params = _wrap_modcdp_add_custom_command(params)
+    elif method == "Mod.addMiddleware":
+        runtime_params = _wrap_modcdp_add_middleware(params)
+    else:
+        runtime_params = _wrap_custom_command(method, params, _optional_string(params, "cdpSessionId") or session_id)
+    return [{"method": "Runtime.evaluate", "params": runtime_params, "unwrap": "evaluate"}]
+
+
+def wrap_command_if_needed(
+    method: str,
+    params: ProtocolParams | None = None,
+    *,
+    routes: ModCDPRoutes | None = None,
+    cdp_session_id: str | None = None,
+) -> TranslatedCommand:
+    params = params or {}
+    route = route_for(method, routes or DEFAULT_CLIENT_ROUTES)
+    if route == "direct_cdp":
+        return {"route": route, "target": "direct_cdp", "steps": [{"method": method, "params": params}]}
+    if route == "service_worker":
+        if cdp_session_id is None:
+            raise RuntimeError(f"service_worker route requires a CDP session id for {method}")
+        return {
+            "route": route,
+            "target": "service_worker",
+            "steps": _wrap_service_worker_command(method, params, cdp_session_id),
+        }
+    raise RuntimeError(f"Unsupported client route '{route}' for {method}")
+
+
+def _unwrap_evaluate_response(result: ProtocolResult) -> JsonValue:
+    if result.get("exceptionDetails"):
+        ex = _object_or_empty(result.get("exceptionDetails"))
+        exception = _object_or_empty(ex.get("exception"))
+        description = exception.get("description")
+        text = ex.get("text")
+        msg = (
+            description
+            if isinstance(description, str)
+            else text
+            if isinstance(text, str)
+            else "Runtime.evaluate failed"
+        )
+        raise RuntimeError(msg)
+    inner = _object_or_empty(result.get("result"))
+    return inner.get("value")
+
+
+def unwrap_response_if_needed(result: ProtocolResult, unwrap: str | None = None) -> JsonValue:
+    return _unwrap_evaluate_response(result) if unwrap == "evaluate" else (result or {})
+
+
+def unwrap_event_if_needed(
+    method: str,
+    params: ProtocolParams,
+    session_id: str | None = None,
+    our_session_id: str | None = None,
+) -> UnwrappedModCDPEvent | None:
+    if method != "Runtime.bindingCalled":
+        return None
+    binding_name = params.get("name")
+    if not isinstance(binding_name, str):
+        return None
+    raw_payload = params.get("payload")
+    if not isinstance(raw_payload, str):
+        return None
+    try:
+        parsed: object = json.loads(raw_payload)
+    except json.JSONDecodeError:
+        return None
+    if not isinstance(parsed, dict):
+        return None
+    payload = cast(ProtocolPayload, parsed)
+    is_upstream_event_binding = binding_name == UPSTREAM_EVENT_BINDING_NAME
+    is_custom_event_binding = binding_name == CUSTOM_EVENT_BINDING_NAME
+    if not is_upstream_event_binding and not is_custom_event_binding:
+        return None
+    payload_event = payload.get("event")
+    if not isinstance(payload_event, str) or not payload_event:
+        payload_event = None
+    if payload_event is None:
+        return None
+    resolved_event = payload_event
+    if resolved_event == UPSTREAM_EVENT_BINDING_NAME or resolved_event == CUSTOM_EVENT_BINDING_NAME:
+        return None
+    data_value = payload["data"] if "data" in payload else payload
+    data: ProtocolPayload = data_value if isinstance(data_value, dict) else {"value": data_value}
+    raw_source_session_id = payload.get("cdpSessionId")
+    source_session_id = raw_source_session_id if isinstance(raw_source_session_id, str) else session_id
+    unwrapped: UnwrappedModCDPEvent = {"event": resolved_event, "data": data, "sessionId": source_session_id}
+    return unwrapped

modcdp/types.py

@@ -0,0 +1,170 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from queue import Queue
+from typing import Literal, Protocol, TypeAlias, TypedDict
+
+JsonPrimitive: TypeAlias = None | bool | int | float | str
+JsonValue: TypeAlias = JsonPrimitive | list["JsonValue"] | dict[str, "JsonValue"]
+JsonObject: TypeAlias = dict[str, JsonValue]
+
+ProtocolParams: TypeAlias = Mapping[str, JsonValue]
+ProtocolResult: TypeAlias = dict[str, JsonValue]
+ProtocolPayload: TypeAlias = dict[str, JsonValue]
+FrameParams: TypeAlias = Mapping[str, object]
+ModCDPRoutes: TypeAlias = dict[str, str]
+
+
+class _ModCDPAddCustomCommandRequired(TypedDict):
+    name: str
+    expression: str
+
+
+class ModCDPAddCustomCommandParams(_ModCDPAddCustomCommandRequired, total=False):
+    paramsSchema: JsonValue
+    resultSchema: JsonValue
+
+
+class _ModCDPAddCustomEventObjectRequired(TypedDict):
+    name: str
+
+
+class ModCDPAddCustomEventObjectParams(_ModCDPAddCustomEventObjectRequired, total=False):
+    eventSchema: JsonValue
+
+
+ModCDPAddCustomEventParams: TypeAlias = str | ModCDPAddCustomEventObjectParams
+
+
+class _ModCDPAddMiddlewareRequired(TypedDict):
+    phase: Literal["request", "response", "event"]
+    expression: str
+
+
+class ModCDPAddMiddlewareParams(_ModCDPAddMiddlewareRequired, total=False):
+    name: str
+
+
+class ModCDPPingLatency(TypedDict):
+    sentAt: int
+    receivedAt: int | float | None
+    returnedAt: int
+    roundTripMs: int
+    serviceWorkerMs: int | float | None
+    returnPathMs: int | float | None
+
+
+class ModCDPConnectTiming(TypedDict):
+    started_at: int
+    extension_source: str | None
+    extension_started_at: int
+    extension_completed_at: int
+    extension_duration_ms: int
+    connected_at: int
+    duration_ms: int
+
+
+class ModCDPCommandTiming(TypedDict):
+    method: str
+    target: str
+    started_at: int
+    completed_at: int
+    duration_ms: int
+
+
+class ModCDPRawTiming(TypedDict):
+    method: str
+    started_at: int
+    completed_at: int
+    duration_ms: int
+
+
+class ModCDPServerConfig(TypedDict, total=False):
+    loopback_cdp_url: str | None
+    routes: ModCDPRoutes
+    cdp_send_timeout_ms: int
+    loopback_execution_context_timeout_ms: int
+    ws_connect_error_settle_timeout_ms: int
+    browserToken: str | None
+    custom_commands: list[ModCDPAddCustomCommandParams]
+    custom_events: list[ModCDPAddCustomEventObjectParams]
+    custom_middlewares: list[ModCDPAddMiddlewareParams]
+
+
+class LaunchOptions(TypedDict, total=False):
+    executable_path: str
+    port: int
+    headless: bool
+    sandbox: bool
+    extra_args: list[str]
+
+
+RuntimeEvaluateParams: TypeAlias = dict[str, JsonValue]
+
+
+class _TranslatedStepRequired(TypedDict):
+    method: str
+
+
+class TranslatedStep(_TranslatedStepRequired, total=False):
+    params: FrameParams
+    unwrap: Literal["evaluate"]
+
+
+class TranslatedCommand(TypedDict):
+    route: str
+    target: Literal["direct_cdp", "service_worker"]
+    steps: list[TranslatedStep]
+
+
+class CdpError(TypedDict, total=False):
+    message: str
+
+
+class CdpFrame(TypedDict, total=False):
+    id: int
+    method: str
+    params: FrameParams
+    sessionId: str
+    result: ProtocolResult
+    error: CdpError
+
+
+class TargetInfo(TypedDict):
+    targetId: str
+    type: str
+    url: str
+
+
+class ExtensionProbe(TypedDict):
+    extension_id: str
+    target_id: str
+    url: str
+    session_id: str
+
+
+class ExtensionInfo(ExtensionProbe):
+    source: str
+
+
+class BorrowedExtensionInfo(ExtensionInfo, total=False):
+    has_tabs: bool
+    has_debugger: bool
+
+
+class UnwrappedModCDPEvent(TypedDict):
+    event: str
+    data: ProtocolPayload
+    sessionId: str | None
+
+
+Handler: TypeAlias = Callable[[ProtocolPayload], None]
+PendingEntry: TypeAlias = tuple[str, Queue[CdpFrame]]
+
+
+class WebSocketLike(Protocol):
+    def send(self, payload: str) -> object: ...
+
+    def recv(self) -> str | bytes | None: ...
+
+    def close(self) -> object: ...

modcdp-0.0.2.dist-info/METADATA

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: modcdp
+Version: 0.0.2
+Summary: Python client for ModCDP.
+Project-URL: Repository, https://github.com/pirate/ModCDP
+Requires-Python: >=3.10
+Requires-Dist: websocket-client>=1.8.0
+Description-Content-Type: text/markdown
+
+# ModCDP Python Client
+
+Python client for ModCDP.

modcdp-0.0.2.dist-info/RECORD

@@ -0,0 +1,7 @@
+modcdp/ModCDPClient.py,sha256=LfVIcJ7pRhqRYAO-_fFB8_AHBtkdVqBWdU_HwXZIx5M,42172
+modcdp/__init__.py,sha256=A6MKAdgscmH-bu4a5kvoo-GpTJkM8r_07D1zXrATVgc,67
+modcdp/translate.py,sha256=rVWwJR5H5N4zvKHOnwW39k_cF26evOjRHS5BsEUzj4Y,9572
+modcdp/types.py,sha256=SFwzKGp_fNiE8POp_G_BqqGu_54-iR3NejQsPBqpXdc,3879
+modcdp-0.0.2.dist-info/METADATA,sha256=ATTwttHvPntecDd67FrJsYihlnkQn2-xfmPRIRp1nJc,297
+modcdp-0.0.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+modcdp-0.0.2.dist-info/RECORD,,

modcdp-0.0.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any