wpr-runtime-core 0.2.0__py3-none-any.whl

wpr_runtime_core/session.py

@@ -0,0 +1,867 @@
+"""Relocatable sync/async client for one real Gecko Worker session."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import shutil
+import subprocess
+import tempfile
+import time
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlsplit
+
+from ._leases import DeferredBlobReleases
+from .installer import configured_runtime_home
+from .pipe import JsonLinePipe, request
+
+PACKAGE_ROOT = Path(__file__).resolve().parents[2]
+_logger = logging.getLogger("wpr_runtime_core.session")
+
+
+@dataclass(frozen=True)
+class RuntimeConfig:
+    """Runtime paths resolved from the bundle, not from a developer checkout."""
+
+    package_root: Path
+    runtime_dir: Path
+    worker_exe: Path
+    network_worker_exe: Path | None = None
+    profile_root: Path | None = None
+    log_root: Path | None = None
+    fpfile: Path | None = None
+    proxy: str | None = None
+    webrtc_permission: str = "allow"
+    webrtc_allowed_origins: tuple[str, ...] | None = None
+
+    def __post_init__(self) -> None:
+        if self.webrtc_permission not in {"allow", "deny", "observe"}:
+            raise ValueError("webrtc_permission must be allow, deny, or observe")
+        if self.webrtc_allowed_origins is not None:
+            if not isinstance(self.webrtc_allowed_origins, tuple):
+                raise TypeError(
+                    "webrtc_allowed_origins must be a tuple of HTTP(S) origins"
+                )
+            for origin in self.webrtc_allowed_origins:
+                if not isinstance(origin, str):
+                    raise ValueError("webrtc_allowed_origins requires HTTP(S) origins")  # noqa: TRY004
+                parsed = urlsplit(origin)
+                if (
+                    parsed.scheme not in {"http", "https"}
+                    or not parsed.hostname
+                    or parsed.username is not None
+                    or parsed.path
+                    or parsed.query
+                    or parsed.fragment
+                    or origin != self._origin(parsed)
+                ):
+                    raise ValueError(
+                        "webrtc_allowed_origins requires canonical HTTP(S) origins without paths"
+                    )
+
+    @staticmethod
+    def _origin(parsed: Any) -> str:
+        host = parsed.hostname or ""
+        if ":" in host:
+            host = "[" + host + "]"
+        port = parsed.port
+        if port is not None and port != (443 if parsed.scheme == "https" else 80):
+            host += ":" + str(port)
+        return parsed.scheme + "://" + host
+
+    @classmethod
+    def bundled(cls) -> RuntimeConfig:
+        configured = configured_runtime_home()
+        root = Path(
+            os.environ.get("WPR_RUNTIME_HOME")
+            or (str(configured) if configured else str(PACKAGE_ROOT))
+        ).resolve()
+        runtime = Path(os.environ.get("WPR_RUNTIME_DIR", root / "runtime")).resolve()
+        worker = Path(
+            os.environ.get("WPR_WORKER_EXE", runtime / "gecko-web-worker.exe")
+        ).resolve()
+        network_worker = Path(
+            os.environ.get(
+                "WPR_NETWORK_WORKER_EXE",
+                runtime / "net-v155" / "gecko-net-worker.exe",
+            )
+        ).resolve()
+        profile = os.environ.get("WPR_PROFILE_ROOT")
+        logs = os.environ.get("WPR_LOG_ROOT")
+        fpfile = os.environ.get("WPR_FPFILE")
+        proxy = os.environ.get("WPR_PROXY")
+        origins = os.environ.get("WPR_WEBRTC_ALLOWED_ORIGINS")
+        allowed_origins = json.loads(origins) if origins is not None else None
+        if allowed_origins is not None and not isinstance(allowed_origins, list):
+            raise ValueError("WPR_WEBRTC_ALLOWED_ORIGINS must be a JSON array or null")
+        return cls(
+            package_root=root,
+            runtime_dir=runtime,
+            worker_exe=worker,
+            network_worker_exe=network_worker,
+            profile_root=Path(profile).resolve() if profile else None,
+            log_root=Path(logs).resolve() if logs else None,
+            fpfile=Path(fpfile).resolve() if fpfile else None,
+            proxy=proxy,
+            webrtc_permission=os.environ.get("WPR_WEBRTC_PERMISSION", "allow"),
+            webrtc_allowed_origins=tuple(allowed_origins)
+            if allowed_origins is not None
+            else None,
+        )
+
+    def validate(self, *, network_only: bool = False) -> None:
+        if os.name != "nt":
+            raise OSError("wpr-runtime-155-win64 requires Windows")
+        worker = self.network_worker_exe if network_only else self.worker_exe
+        if worker is None or not worker.is_file():
+            label = "network worker" if network_only else "worker"
+            raise FileNotFoundError(f"{label} executable not found: {worker}")
+
+
+class WprProtocolError(RuntimeError):
+    def __init__(self, method: str, response: dict[str, Any]):
+        error = response.get("error")
+        if isinstance(error, dict):
+            self.code = str(error.get("code", "UNKNOWN_ERROR"))
+            self.phase = str(error.get("phase", "unknown"))
+            message = str(error.get("message", self.code))
+        else:
+            # Older/minimal Worker responses use a string error code. Keep it
+            # as the public code instead of hiding useful diagnostics behind
+            # UNKNOWN_ERROR (for example stale_frame_handle).
+            self.code = str(error or "UNKNOWN_ERROR")
+            self.phase = "unknown"
+            message = str(error or "request failed")
+        self.method = method
+        self.response = response
+        self.rv = error.get("rv") if isinstance(error, dict) else None
+        self.details = error.get("details", {}) if isinstance(error, dict) else {}
+        super().__init__(f"{method} [{self.code}] {message}")
+
+
+def require_ok(method: str, response: dict[str, Any]) -> Any:
+    if not response.get("ok"):
+        raise WprProtocolError(method, response)
+    # Preserve protocol values exactly.  In particular, an empty list is the
+    # valid result for page.permission_requests() when no native request is
+    # pending; coercing false-y values to {} changes the public data model.
+    return response.get("value", {})
+
+
+class WorkerSession:
+    """One Worker process, profile and transport lifetime."""
+
+    def __init__(
+        self,
+        config: RuntimeConfig | None = None,
+        fpfile: str | Path | None = None,
+        proxy: str | None = None,
+        *,
+        network_only: bool = False,
+        pipe_mode: str | None = None,
+        network_channels: int = 1,
+    ):
+        self.config = config or RuntimeConfig.bundled()
+        self.network_only = bool(network_only)
+        self.fpfile = (
+            Path(fpfile).resolve() if fpfile is not None else self.config.fpfile
+        )
+        self.proxy = proxy if proxy is not None else self.config.proxy
+        if self.fpfile is not None and not self.fpfile.is_file():
+            raise FileNotFoundError(f"fpfile not found: {self.fpfile}")
+        self.config.validate(network_only=self.network_only)
+        self.worker_exe = (
+            self.config.network_worker_exe
+            if self.network_only
+            else self.config.worker_exe
+        )
+        assert self.worker_exe is not None
+        self.session_id = uuid.uuid4().hex[:12]
+        self.pipe_name = rf"\\.\pipe\wpr-gecko-{self.session_id}"
+        self.pipe_mode = (
+            pipe_mode or os.environ.get("WPR_PIPE_MODE", "rpc")
+            if self.network_only
+            else "rpc"
+        )
+        if self.pipe_mode not in {"rpc", "persistent"}:
+            raise ValueError("WPR_PIPE_MODE must be 'rpc' or 'persistent'")
+        self._persistent_rpc = (
+            JsonLinePipe(self.pipe_name, persistent=True)
+            if self.network_only and self.pipe_mode == "persistent"
+            else None
+        )
+        profile_parent = self.config.profile_root
+        if profile_parent:
+            profile_parent.mkdir(parents=True, exist_ok=True)
+        else:
+            profile_parent = Path(tempfile.gettempdir())
+        self.profile_dir = Path(
+            tempfile.mkdtemp(
+                prefix=f"wpr-profile-{self.session_id}-", dir=profile_parent
+            )
+        )
+        (self.profile_dir / "local").mkdir(parents=True, exist_ok=True)
+        # GPU/WebGPU A/B runs must set these prefs before Gecko loads the
+        # profile and initializes the blocklist.  Setting them later from the
+        # parent JS runtime is too late for StaticPrefs/graphics startup.
+        if os.environ.get("WPR_ENABLE_GPU_PATH") == "1":
+            gpu_prefs = [
+                'user_pref("layers.gpu-process.enabled", true);',
+                'user_pref("dom.webgpu.enabled", true);',
+            ]
+            if os.environ.get("WPR_IGNORE_GPU_BLOCKLIST") == "1":
+                gpu_prefs.append('user_pref("gfx.webgpu.ignore-blocklist", true);')
+            extra_prefs = []
+            nursery_max_kb = os.environ.get("WPR_JS_NURSERY_MAX_KB")
+            if nursery_max_kb and nursery_max_kb.isdigit():
+                extra_prefs.append(
+                    f'user_pref("javascript.options.mem.nursery.max_kb", {int(nursery_max_kb)});'
+                )
+            debugger_pref = os.environ.get("WPR_PAGE_DEBUGGER")
+            if debugger_pref in {"0", "1"}:
+                extra_prefs.append(
+                    'user_pref("wpr.page_control.use_debugger", '
+                    + ("true" if debugger_pref == "1" else "false")
+                    + ");"
+                )
+            jit_mode = os.environ.get("WPR_JS_JIT_MODE")
+            if jit_mode == "baseline-off":
+                extra_prefs.append(
+                    'user_pref("javascript.options.baselinejit", false);'
+                )
+            elif jit_mode == "ion-off":
+                extra_prefs.append('user_pref("javascript.options.ion", false);')
+            elif jit_mode == "all-off":
+                extra_prefs.extend(
+                    [
+                        'user_pref("javascript.options.baselinejit", false);',
+                        'user_pref("javascript.options.ion", false);',
+                    ]
+                )
+            keepalive = os.environ.get("WPR_KEEP_WEB_PROCESSES_ALIVE")
+            if keepalive in {"0", "1"}:
+                extra_prefs.append(
+                    f'user_pref("dom.ipc.keepProcessesAlive.web", {keepalive});'
+                )
+            (self.profile_dir / "user.js").write_text(
+                "\n".join(gpu_prefs + extra_prefs) + "\n", encoding="utf-8"
+            )
+        elif (
+            os.environ.get("WPR_JS_NURSERY_MAX_KB", "").isdigit()
+            or os.environ.get("WPR_PAGE_DEBUGGER") in {"0", "1"}
+            or os.environ.get("WPR_JS_JIT_MODE")
+            in {"baseline-off", "ion-off", "all-off"}
+            or os.environ.get("WPR_KEEP_WEB_PROCESSES_ALIVE") in {"0", "1"}
+        ):
+            prefs = []
+            if os.environ.get("WPR_JS_NURSERY_MAX_KB", "").isdigit():
+                prefs.append(
+                    'user_pref("javascript.options.mem.nursery.max_kb", '
+                    f"{int(os.environ['WPR_JS_NURSERY_MAX_KB'])});"
+                )
+            debugger_pref = os.environ.get("WPR_PAGE_DEBUGGER")
+            if debugger_pref in {"0", "1"}:
+                prefs.append(
+                    'user_pref("wpr.page_control.use_debugger", '
+                    + ("true" if debugger_pref == "1" else "false")
+                    + ");"
+                )
+            jit_mode = os.environ.get("WPR_JS_JIT_MODE")
+            if jit_mode == "baseline-off":
+                prefs.append('user_pref("javascript.options.baselinejit", false);')
+            elif jit_mode == "ion-off":
+                prefs.append('user_pref("javascript.options.ion", false);')
+            elif jit_mode == "all-off":
+                prefs.extend(
+                    [
+                        'user_pref("javascript.options.baselinejit", false);',
+                        'user_pref("javascript.options.ion", false);',
+                    ]
+                )
+            keepalive = os.environ.get("WPR_KEEP_WEB_PROCESSES_ALIVE")
+            if keepalive in {"0", "1"}:
+                prefs.append(
+                    f'user_pref("dom.ipc.keepProcessesAlive.web", {keepalive});'
+                )
+            (self.profile_dir / "user.js").write_text(
+                "\n".join(prefs) + "\n",
+                encoding="utf-8",
+            )
+        if not self.network_only:
+            prefs_path = self.profile_dir / "user.js"
+            existing = (
+                prefs_path.read_text(encoding="utf-8") if prefs_path.exists() else ""
+            )
+            policy_prefs = [
+                'user_pref("wpr.webrtc.permission.default", '
+                + json.dumps(self.config.webrtc_permission)
+                + ");",
+                'user_pref("wpr.webrtc.permission.allowed_origins", '
+                + json.dumps(json.dumps(self.config.webrtc_allowed_origins))
+                + ");",
+            ]
+            prefs_path.write_text(
+                existing + "\n" + "\n".join(policy_prefs) + "\n", encoding="utf-8"
+            )
+        if self.proxy == "":
+            prefs_path = self.profile_dir / "user.js"
+            existing = (
+                prefs_path.read_text(encoding="utf-8") if prefs_path.exists() else ""
+            )
+            prefs_path.write_text(
+                existing + '\nuser_pref("network.proxy.type", 0);\n', encoding="utf-8"
+            )
+        if self.proxy:
+            parsed = urlsplit(str(self.proxy).strip())
+            scheme = parsed.scheme.lower()
+            if scheme not in {"http", "https", "socks4", "socks5"}:
+                raise ValueError("proxy scheme must be http, https, socks4, or socks5")
+            if not parsed.hostname or not parsed.port:
+                raise ValueError("proxy must include host and port")
+            host = parsed.hostname.replace("\\", "\\\\").replace('"', '\\"')
+            prefs_path = self.profile_dir / "user.js"
+            existing = (
+                prefs_path.read_text(encoding="utf-8") if prefs_path.exists() else ""
+            )
+            proxy_prefs = [
+                'user_pref("network.proxy.type", 1);',
+                'user_pref("network.proxy.no_proxies_on", "");',
+                'user_pref("network.proxy.share_proxy_settings", true);',
+                'user_pref("network.captive-portal-service.enabled", false);',
+                'user_pref("network.connectivity-service.enabled", false);',
+                'user_pref("signon.autologin.proxy", true);',
+                'user_pref("network.auth.subresource-http-auth-allow", 2);',
+            ]
+            if scheme.startswith("socks"):
+                proxy_prefs.extend(
+                    [
+                        f'user_pref("network.proxy.socks", "{host}");',
+                        f'user_pref("network.proxy.socks_port", {parsed.port});',
+                        f'user_pref("network.proxy.socks_version", {5 if scheme == "socks5" else 4});',
+                        'user_pref("network.proxy.socks_remote_dns", true);',
+                    ]
+                )
+            else:
+                proxy_prefs.extend(
+                    [
+                        f'user_pref("network.proxy.http", "{host}");',
+                        f'user_pref("network.proxy.http_port", {parsed.port});',
+                        f'user_pref("network.proxy.ssl", "{host}");',
+                        f'user_pref("network.proxy.ssl_port", {parsed.port});',
+                    ]
+                )
+            prefs_path.write_text(
+                existing.rstrip()
+                + ("\n" if existing.strip() else "")
+                + "\n".join(proxy_prefs)
+                + "\n",
+                encoding="utf-8",
+            )
+        log_root = (
+            self.config.log_root or Path(tempfile.gettempdir()) / "wpr-runtime-logs"
+        )
+        log_root.mkdir(parents=True, exist_ok=True)
+        self.stdout = (log_root / f"wpr-{self.session_id}.stdout.log").open(
+            "w", encoding="utf-8", errors="replace"
+        )
+        self.stderr = (log_root / f"wpr-{self.session_id}.stderr.log").open(
+            "w", encoding="utf-8", errors="replace"
+        )
+        env = os.environ.copy()
+        if self.proxy == "":
+            env = {
+                key: value
+                for key, value in env.items()
+                if not key.startswith("WPR_PROXY")
+            }
+        env.update(
+            {
+                "WPR_RPC": "1",
+                "WPR_PIPE_NAME": self.pipe_name,
+                "WPR_PROFILE_DIR": str(self.profile_dir),
+                "WPR_PIPE_MODE": self.pipe_mode,
+                "WPR_NETWORK_CHANNELS": str(network_channels),
+            }
+        )
+        if self.network_only:
+            env["WPR_NETWORK_ONLY"] = "1"
+        else:
+            env["WPR_REMOTE_PAGE"] = "1"
+        if self.fpfile is not None:
+            env["WPR_FPFILE"] = str(self.fpfile)
+        if self.proxy:
+            parsed_proxy = urlsplit(str(self.proxy).strip())
+            if parsed_proxy.hostname:
+                env["WPR_PROXY_HOST"] = parsed_proxy.hostname
+            if parsed_proxy.port:
+                env["WPR_PROXY_PORT"] = str(parsed_proxy.port)
+            if parsed_proxy.username is not None:
+                env["WPR_PROXY_USERNAME"] = parsed_proxy.username
+            if parsed_proxy.password is not None:
+                env["WPR_PROXY_PASSWORD"] = parsed_proxy.password
+        env["PATH"] = str(self.config.runtime_dir) + os.pathsep + env.get("PATH", "")
+        self.process = subprocess.Popen(
+            [str(self.worker_exe)],
+            cwd=str(self.config.runtime_dir),
+            env=env,
+            stdout=self.stdout,
+            stderr=self.stderr,
+        )
+        self.closed = False
+
+    def request(
+        self,
+        payload: dict[str, Any],
+        timing_out: dict[str, float] | None = None,
+    ) -> dict[str, Any]:
+        if self.closed:
+            raise RuntimeError("WorkerSession is closed")
+        if self._persistent_rpc is not None:
+            return self._persistent_rpc.request(payload, timing_out)
+        return request(payload, self.pipe_name, timing_out)
+
+    def network_fetch(
+        self,
+        url: str,
+        *,
+        method: str = "GET",
+        headers: dict[str, str] | None = None,
+        body: str | None = None,
+        follow_redirects: bool = True,
+        timing_out: dict[str, float] | None = None,
+    ) -> dict[str, Any]:
+        if not self.network_only:
+            raise RuntimeError("network_fetch requires network_only=True")
+        if isinstance(body, bytes):
+            raise TypeError(
+                "binary request bodies are not supported by this Worker protocol"
+            )
+        payload: dict[str, Any] = {
+            "method": "network.fetch",
+            "url": str(url),
+            "http_method": str(method).upper(),
+            "headers": headers or {},
+            "follow_redirects": bool(follow_redirects),
+        }
+        if body is not None:
+            payload["body"] = body
+        return self.request(payload, timing_out)
+
+    def diagnostic_dump_network_log(self) -> Any:
+        """Return bounded, metadata-only Gecko network events."""
+        return require_ok(
+            "diagnostic.dump_network_log",
+            self.request({"method": "diagnostic.dump_network_log"}),
+        )
+
+    def diagnostic_wait_network_event(
+        self, after_seq: int = 0, timeout_ms: int = 1000
+    ) -> Any:
+        """Wait in Gecko until a network-log sequence advances or times out."""
+        return require_ok(
+            "diagnostic.wait_network_event",
+            self.request(
+                {
+                    "method": "diagnostic.wait_network_event",
+                    "after_seq": int(after_seq),
+                    "timeout_ms": int(timeout_ms),
+                }
+            ),
+        )
+
+    def diagnostic_clear_network_log(self) -> Any:
+        """Clear the current session's bounded network event buffer."""
+        return require_ok(
+            "diagnostic.clear_network_log",
+            self.request({"method": "diagnostic.clear_network_log"}),
+        )
+
+    def close(self, *, request_shutdown: bool = True) -> None:
+        if self.closed:
+            return
+        try:
+            if self.process.poll() is None:
+                if request_shutdown:
+                    try:
+                        self.request({"method": "runtime.shutdown"})
+                    except Exception as exc:  # noqa: BLE001 -- continue process teardown
+                        _logger.debug("Worker shutdown RPC failed: %s", exc)
+                try:
+                    self.process.wait(timeout=15)
+                except subprocess.TimeoutExpired:
+                    self.process.kill()
+                    self.process.wait(timeout=5)
+        finally:
+            self.closed = True
+            if self._persistent_rpc is not None:
+                self._persistent_rpc.close()
+            self.stdout.close()
+            self.stderr.close()
+            shutil.rmtree(self.profile_dir, ignore_errors=True)
+
+    def abort(self) -> None:
+        """Terminate immediately, used to enforce a request deadline."""
+        if self.closed:
+            return
+        try:
+            if self.process.poll() is None:
+                self.process.kill()
+                self.process.wait(timeout=5)
+        finally:
+            self.closed = True
+            if self._persistent_rpc is not None:
+                self._persistent_rpc.close()
+            self.stdout.close()
+            self.stderr.close()
+            shutil.rmtree(self.profile_dir, ignore_errors=True)
+
+    def __enter__(self) -> WorkerSession:  # noqa: PYI034
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+
+
+class AsyncWorkerSession:
+    sync_session_type = WorkerSession
+
+    """Async process/RPC facade with optional multiplexed network channels."""
+
+    def __init__(
+        self,
+        config: RuntimeConfig | None = None,
+        fpfile: str | Path | None = None,
+        proxy: str | None = None,
+        *,
+        network_only: bool = False,
+        defer_body_releases: bool = False,
+        ipc_backend: str = "threaded",
+        network_channels: int = 1,
+    ):
+        self.config = config
+        self.fpfile = fpfile
+        self.proxy = proxy
+        self.network_only = bool(network_only)
+        if ipc_backend not in {"threaded", "iocp"}:
+            raise ValueError("ipc_backend must be 'threaded' or 'iocp'")
+        if ipc_backend == "iocp" and not self.network_only:
+            raise ValueError("IOCP backend is currently network-only")
+        self.ipc_backend = ipc_backend
+        if type(network_channels) is not int or not 1 <= network_channels <= 64:
+            raise ValueError("network_channels must be an integer between 1 and 64")
+        if network_channels > 1 and ipc_backend != "iocp":
+            raise ValueError("multiple channels require the IOCP backend")
+        self.network_channels = network_channels
+        self.supports_request_cancel = False
+        self._async_rpc = None
+        self.defer_body_releases = bool(defer_body_releases)
+        if self.defer_body_releases and not self.network_only:
+            raise ValueError("deferred body release requires a network-only session")
+        self._blob_releases: DeferredBlobReleases | None = None
+        self._rpc_dispatches: dict[str, int] = {}
+        self._sync: WorkerSession | None = None
+        self._lock = asyncio.Lock()
+
+    async def __aenter__(self) -> AsyncWorkerSession:  # noqa: PYI034
+        starting = asyncio.create_task(
+            asyncio.to_thread(
+                self.sync_session_type,
+                self.config,
+                self.fpfile,
+                self.proxy,
+                network_only=self.network_only,
+                pipe_mode="persistent" if self.ipc_backend == "iocp" else None,
+                network_channels=self.network_channels,
+            )
+        )
+        try:
+            self._sync = await asyncio.shield(starting)
+        except asyncio.CancelledError:
+            sync = await starting
+            await asyncio.to_thread(sync.abort)
+            raise
+        if self.ipc_backend == "iocp":
+            from .iocp_pipe import IocpJsonLinePipe
+
+            self._async_rpc = IocpJsonLinePipe(
+                self._sync.pipe_name,
+                multiplex=self.network_channels > 1,
+                on_cancel=self._cancel_network_rpc,
+            )
+        if self.defer_body_releases or self._async_rpc is not None:
+            try:
+                capabilities = require_ok(
+                    "runtime.capabilities",
+                    await asyncio.wait_for(
+                        self.request({"method": "runtime.capabilities"}), 15
+                    ),
+                )
+                if not capabilities.get("network_release_batch"):
+                    raise RuntimeError(
+                        "piggyback release requires a Worker with network_release_batch support"
+                    )
+                if self.network_channels > 1:
+                    if (
+                        not capabilities.get("network_multiplex")
+                        or capabilities.get("max_channels", 0) < self.network_channels
+                    ):
+                        raise RuntimeError(
+                            "Worker does not support the requested channel concurrency"
+                        )
+                    self.supports_request_cancel = True
+                if self.defer_body_releases:
+                    self._blob_releases = DeferredBlobReleases(
+                        self._flush_blob_release_batch
+                    )
+            except BaseException:
+                await self.abort()
+                raise
+        return self
+
+    @property
+    def is_open(self) -> bool:
+        return self._sync is not None
+
+    async def request(self, payload: dict[str, Any]) -> dict[str, Any]:
+        response, _timings = await self.request_with_timing(payload)
+        return response
+
+    async def request_with_timing(
+        self, payload: dict[str, Any]
+    ) -> tuple[dict[str, Any], dict[str, Any]]:
+        if self._sync is None:
+            raise RuntimeError("AsyncWorkerSession is not open")
+        lock_started = time.perf_counter_ns()
+        await self._lock.acquire()
+        lock_acquired = time.perf_counter_ns()
+        lock_held = True
+        batch: list[int] = []
+        try:
+            pipe_timings: dict[str, Any] = {}
+            wire_payload = payload
+            if self._blob_releases is not None and payload.get("method") in {
+                "network.fetch",
+                "data.release_batch",
+            }:
+                batch = (
+                    self._blob_releases.reserve_batch()
+                    if self.supports_request_cancel
+                    else self._blob_releases.snapshot()
+                )
+                if payload.get("method") == "data.release_batch" and not batch:
+                    return {"ok": True, "released_blob_ids": []}, {}
+                wire_payload = {**payload, "release_blob_ids": batch}
+            rpc_started = time.perf_counter_ns()
+            rpc_method = str(payload.get("method", ""))
+            self._rpc_dispatches[rpc_method] = (
+                self._rpc_dispatches.get(rpc_method, 0) + 1
+            )
+            if self._async_rpc is None:
+                response = await asyncio.to_thread(
+                    self._sync.request, wire_payload, pipe_timings
+                )
+            else:
+                if self.supports_request_cancel:
+                    self._lock.release()
+                    lock_held = False
+                response = await self._async_rpc.request(wire_payload, pipe_timings)
+            rpc_finished = time.perf_counter_ns()
+            if batch:
+                assert self._blob_releases is not None
+                receipt = response.get("released_blob_ids")
+                if receipt is not None or response.get("ok"):
+                    self._blob_releases.acknowledge(batch, receipt)
+                    pipe_timings["piggyback_release_count"] = float(len(batch))
+        except (RuntimeError, OSError, ValueError, TypeError):
+            if self._async_rpc is not None:
+                await self.abort()
+            raise
+        finally:
+            if self._blob_releases is not None and self.supports_request_cancel:
+                self._blob_releases.unreserve(batch)
+            if lock_held:
+                self._lock.release()
+        executor_roundtrip_ms = (rpc_finished - rpc_started) / 1_000_000
+        pipe_total_ms = pipe_timings.get("pipe_total_ms", 0.0)
+        timings = {
+            "session_lock_wait_ms": (lock_acquired - lock_started) / 1_000_000,
+            **pipe_timings,
+        }
+        if self._async_rpc is None:
+            timings["executor_roundtrip_ms"] = executor_roundtrip_ms
+            timings["python_executor_overhead_est_ms"] = max(
+                0.0, executor_roundtrip_ms - pipe_total_ms
+            )
+        else:
+            timings["iocp_rpc_roundtrip_ms"] = executor_roundtrip_ms
+        return response, timings
+
+    async def _cancel_network_rpc(self, request_id, future, payload):
+        assert self._async_rpc is not None
+        self._rpc_dispatches["network.cancel"] = (
+            self._rpc_dispatches.get("network.cancel", 0) + 1
+        )
+        try:
+            await asyncio.wait_for(
+                self._async_rpc.request(
+                    {
+                        "method": "network.cancel",
+                        "target_request_id": request_id,
+                    }
+                ),
+                2,
+            )
+            raw, _decode_ms, _size = await asyncio.wait_for(asyncio.shield(future), 3)
+            batch = payload.get("release_blob_ids") or []
+            if (
+                batch
+                and self._blob_releases is not None
+                and raw.get("released_blob_ids") is not None
+            ):
+                self._blob_releases.acknowledge(batch, raw["released_blob_ids"])
+            body = raw.get("body") if raw.get("ok") else None
+            if isinstance(body, dict) and "blob_id" in body:
+                await self.data_release(int(body["blob_id"]))
+        except BaseException:
+            await self.abort()
+            raise
+
+    async def network_fetch(
+        self,
+        url: str,
+        *,
+        method: str = "GET",
+        headers: dict[str, str] | None = None,
+        body: str | None = None,
+        follow_redirects: bool = True,
+    ) -> dict[str, Any]:
+        response, _timings = await self.network_fetch_with_timing(
+            url,
+            method=method,
+            headers=headers,
+            body=body,
+            follow_redirects=follow_redirects,
+        )
+        return response
+
+    async def network_fetch_with_timing(
+        self,
+        url: str,
+        *,
+        method: str = "GET",
+        headers: dict[str, str] | None = None,
+        body: str | None = None,
+        follow_redirects: bool = True,
+    ) -> tuple[dict[str, Any], dict[str, Any]]:
+        if not self.network_only:
+            raise RuntimeError("network_fetch requires network_only=True")
+        if isinstance(body, bytes):
+            raise TypeError(
+                "binary request bodies are not supported by this Worker protocol"
+            )
+        payload: dict[str, Any] = {
+            "method": "network.fetch",
+            "url": str(url),
+            "http_method": str(method).upper(),
+            "headers": headers or {},
+            "follow_redirects": bool(follow_redirects),
+        }
+        if body is not None:
+            payload["body"] = body
+        return await self.request_with_timing(payload)
+
+    async def data_release(self, blob_id: int) -> Any:
+        value, _timings = await self.data_release_with_timing(blob_id)
+        return value
+
+    async def queue_body_release(self, blob_id: int, size: int) -> dict[str, Any]:
+        if self._blob_releases is None:
+            raise RuntimeError("deferred release queue is not enabled")
+        return await self._blob_releases.enqueue(int(blob_id), int(size))
+
+    async def _flush_blob_release_batch(self) -> None:
+        response = await self.request({"method": "data.release_batch"})
+        require_ok("data.release_batch", response)
+
+    async def flush_body_releases(self) -> None:
+        if self._blob_releases is not None:
+            await self._blob_releases.drain()
+
+    @property
+    def transport_stats(self) -> dict[str, Any]:
+        pending = self._blob_releases.pending if self._blob_releases else {}
+        return {
+            "rpc_dispatches": dict(self._rpc_dispatches),
+            "pending_blob_count": len(pending),
+            "pending_blob_bytes": sum(pending.values()),
+        }
+
+    async def data_release_with_timing(
+        self, blob_id: int
+    ) -> tuple[Any, dict[str, float]]:
+        response, timings = await self.request_with_timing(
+            {"method": "data.release", "blob_id": int(blob_id)}
+        )
+        return require_ok("data.release", response), timings
+
+    async def diagnostic_dump_network_log(self) -> Any:
+        """Return bounded, metadata-only Gecko network events."""
+        return require_ok(
+            "diagnostic.dump_network_log",
+            await self.request({"method": "diagnostic.dump_network_log"}),
+        )
+
+    async def diagnostic_wait_network_event(
+        self, after_seq: int = 0, timeout_ms: int = 1000
+    ) -> Any:
+        """Wait in Gecko until a network-log sequence advances or times out."""
+        return require_ok(
+            "diagnostic.wait_network_event",
+            await self.request(
+                {
+                    "method": "diagnostic.wait_network_event",
+                    "after_seq": int(after_seq),
+                    "timeout_ms": int(timeout_ms),
+                }
+            ),
+        )
+
+    async def diagnostic_clear_network_log(self) -> Any:
+        """Clear the current session's bounded network event buffer."""
+        return require_ok(
+            "diagnostic.clear_network_log",
+            await self.request({"method": "diagnostic.clear_network_log"}),
+        )
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        if self._sync is not None:
+            sync = self._sync
+            try:
+                if self._blob_releases is not None:
+                    await self._blob_releases.close()
+            finally:
+                if self._async_rpc is not None:
+                    try:
+                        await self.request({"method": "runtime.shutdown"})
+                    finally:
+                        await self._async_rpc.aclose()
+                        await asyncio.to_thread(sync.close, request_shutdown=False)
+                else:
+                    await asyncio.to_thread(sync.close)
+                self._sync = None
+                if self._blob_releases is not None:
+                    self._blob_releases.discard()
+
+    async def abort(self) -> None:
+        if self._blob_releases is not None:
+            self._blob_releases.discard()
+        if self._sync is not None:
+            sync, self._sync = self._sync, None
+            await asyncio.to_thread(sync.abort)
+        if self._async_rpc is not None:
+            await self._async_rpc.aclose()