gecko-web-runtime-client 1.0.0__py3-none-any.whl

gecko_web_runtime/__init__.py

@@ -0,0 +1,17 @@
+"""Portable Python client for the Firefox-derived WPR runtime bundle."""
+
+from .session import (
+    AsyncGeckoWorkerSession,
+    GeckoWorkerSession,
+    RuntimeConfig,
+    WprProtocolError,
+)
+from .installer import install_runtime
+
+__all__ = [
+    "AsyncGeckoWorkerSession",
+    "GeckoWorkerSession",
+    "RuntimeConfig",
+    "WprProtocolError",
+    "install_runtime",
+]

gecko_web_runtime/__main__.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+import argparse
+
+from .installer import install_runtime
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(prog="python -m gecko_web_runtime")
+    commands = parser.add_subparsers(dest="command", required=True)
+    install = commands.add_parser("install-runtime", help="download a pinned Gecko runtime")
+    install.add_argument("--version", required=True, help="runtime major version, e.g. 155")
+    install.add_argument("--runtime-home", help="optional installation directory")
+    install.add_argument("--force", action="store_true", help="replace an existing installation")
+    args = parser.parse_args()
+    if args.command == "install-runtime":
+        location = install_runtime(args.version, args.runtime_home, force=args.force)
+        print(location)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

gecko_web_runtime/installer.py

@@ -0,0 +1,187 @@
+"""Download and install a pinned WPR runtime release."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import shutil
+import subprocess
+import tempfile
+import urllib.request
+import uuid
+import zipfile
+from pathlib import Path
+
+
+RUNTIME_RELEASES = {
+    "155": {
+        "version": "155.0.3",
+        "repository": "childclm/gecko-web-runtime",
+        "tag": "v155.0.3",
+        "asset": "wpr-runtime-155-win64.zip",
+        "url": "https://github.com/childclm/gecko-web-runtime/releases/download/v155.0.3/wpr-runtime-155-win64.zip",
+        "sha256": "c8321d3eeed0dfa0978c70c84ad57126c0a131f825aa0a475db5f6ae7c178f7d",
+    }
+}
+
+
+def _github_token() -> str | None:
+    for name in ("WPR_GITHUB_TOKEN", "GITHUB_TOKEN", "GH_TOKEN"):
+        value = os.environ.get(name)
+        if value:
+            return value.strip()
+    # Git Credential Manager may already hold the user's HTTPS credential.
+    try:
+        query = "protocol=https\nhost=github.com\n\n"
+        result = subprocess.run(
+            ["git", "credential", "fill"],
+            input=query,
+            text=True,
+            capture_output=True,
+            timeout=10,
+            check=True,
+        )
+        for line in result.stdout.splitlines():
+            if line.startswith("password=") and line[9:]:
+                return line[9:].strip()
+    except (OSError, subprocess.SubprocessError):
+        pass
+    return None
+
+
+def _github_asset_request(release: dict[str, str]) -> urllib.request.Request:
+    token = _github_token()
+    if not token:
+        return urllib.request.Request(
+            release["url"],
+            headers={"User-Agent": "gecko-web-runtime-client/1.0.0"},
+        )
+
+    api = (
+        f"https://api.github.com/repos/{release['repository']}"
+        f"/releases/tags/{release['tag']}"
+    )
+    metadata_request = urllib.request.Request(
+        api,
+        headers={
+            "Accept": "application/vnd.github+json",
+            "Authorization": f"Bearer {token}",
+            "User-Agent": "gecko-web-runtime-client/1.0.0",
+            "X-GitHub-Api-Version": "2022-11-28",
+        },
+    )
+    with urllib.request.urlopen(metadata_request, timeout=30) as response:
+        metadata = json.load(response)
+    asset = next(
+        (item for item in metadata.get("assets", []) if item.get("name") == release["asset"]),
+        None,
+    )
+    if not asset:
+        raise RuntimeError(f"GitHub release asset not found: {release['asset']}")
+    return urllib.request.Request(
+        f"https://api.github.com/repos/{release['repository']}"
+        f"/releases/assets/{asset['id']}",
+        headers={
+            "Accept": "application/octet-stream",
+            "Authorization": f"Bearer {token}",
+            "User-Agent": "gecko-web-runtime-client/1.0.0",
+            "X-GitHub-Api-Version": "2022-11-28",
+        },
+    )
+
+
+def config_path() -> Path:
+    base = os.environ.get("LOCALAPPDATA")
+    if not base:
+        base = str(Path.home() / "AppData" / "Local")
+    return Path(base) / "WPR" / "config.json"
+
+
+def configured_runtime_home() -> Path | None:
+    path = config_path()
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        value = data.get("runtime_home")
+        return Path(value).resolve() if value else None
+    except (FileNotFoundError, OSError, json.JSONDecodeError):
+        return None
+
+
+def _sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _extract_safely(archive: Path, destination: Path) -> None:
+    destination.mkdir(parents=True, exist_ok=True)
+    root = destination.resolve()
+    with zipfile.ZipFile(archive) as source:
+        for member in source.infolist():
+            target = (destination / member.filename).resolve()
+            if target != root and root not in target.parents:
+                raise RuntimeError(f"unsafe path in runtime archive: {member.filename}")
+        source.extractall(destination)
+
+
+def install_runtime(version: str, runtime_home: str | os.PathLike[str] | None = None,
+                    *, force: bool = False) -> Path:
+    """Install a pinned runtime and persist its location for the client."""
+    if os.name != "nt":
+        raise OSError("wpr-runtime-155 requires Windows")
+    key = str(version).split(".", 1)[0]
+    release = RUNTIME_RELEASES.get(key)
+    if release is None:
+        raise ValueError(f"unsupported runtime version: {version}")
+
+    if runtime_home is None:
+        local = os.environ.get("LOCALAPPDATA") or str(Path.home() / "AppData" / "Local")
+        destination = Path(local) / "WPR" / "runtime" / key
+    else:
+        destination = Path(runtime_home)
+    destination = destination.expanduser().resolve()
+
+    if destination.exists() and not force:
+        worker = destination / "runtime" / "gecko-web-worker.exe"
+        if worker.is_file():
+            _write_config(destination)
+            return destination
+        raise FileExistsError(f"runtime destination already exists: {destination}")
+
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    stage = destination.parent / f".{destination.name}.staging-{uuid.uuid4().hex}"
+    try:
+        with tempfile.TemporaryDirectory(prefix="wpr-runtime-download-") as temp:
+            archive = Path(temp) / "runtime.zip"
+            request = _github_asset_request(release)
+            with urllib.request.urlopen(request, timeout=120) as response, archive.open("wb") as output:
+                shutil.copyfileobj(response, output)
+            actual = _sha256(archive)
+            if actual != release["sha256"]:
+                raise RuntimeError(
+                    f"runtime SHA256 mismatch: expected {release['sha256']}, got {actual}"
+                )
+            _extract_safely(archive, stage)
+
+        if not (stage / "runtime" / "gecko-web-worker.exe").is_file():
+            raise RuntimeError("runtime archive does not contain runtime/gecko-web-worker.exe")
+        if destination.exists():
+            shutil.rmtree(destination)
+        stage.replace(destination)
+        _write_config(destination)
+        return destination
+    finally:
+        if stage.exists():
+            shutil.rmtree(stage, ignore_errors=True)
+
+
+def _write_config(destination: Path) -> None:
+    path = config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        json.dumps({"runtime_home": str(destination)}, indent=2) + "\n",
+        encoding="utf-8",
+    )

gecko_web_runtime/pipe.py

@@ -0,0 +1,52 @@
+"""Windows named-pipe transport for the public WPR JSON protocol."""
+
+from __future__ import annotations
+
+import ctypes
+import json
+import msvcrt
+import os
+import time
+from typing import Any
+
+
+KERNEL32 = ctypes.WinDLL("kernel32", use_last_error=True)
+GENERIC_READ = 0x80000000
+GENERIC_WRITE = 0x40000000
+OPEN_EXISTING = 3
+INVALID_HANDLE_VALUE = ctypes.c_void_p(-1).value
+
+
+def connect_pipe(pipe_name: str, timeout_seconds: float = 60.0):
+    deadline = time.monotonic() + timeout_seconds
+    while time.monotonic() < deadline:
+        handle = KERNEL32.CreateFileW(
+            pipe_name,
+            GENERIC_READ | GENERIC_WRITE,
+            0,
+            None,
+            OPEN_EXISTING,
+            0,
+            None,
+        )
+        invalid = {-1, 0xFFFFFFFF, 0xFFFFFFFFFFFFFFFF, INVALID_HANDLE_VALUE}
+        if int(handle) not in invalid and int(handle) != 0:
+            return os.fdopen(msvcrt.open_osfhandle(handle, 0), "r+b", buffering=0)
+        KERNEL32.WaitNamedPipeW(pipe_name, 1000)
+    raise TimeoutError(f"named pipe did not become available: {pipe_name}")
+
+
+def request(payload: dict[str, Any], pipe_name: str) -> dict[str, Any]:
+    """Send one JSON request. The Worker creates one pipe instance per RPC."""
+    pipe = connect_pipe(pipe_name)
+    try:
+        pipe.write((json.dumps(payload, separators=(",", ":")) + "\n").encode())
+        line = pipe.readline()
+        if not line:
+            raise RuntimeError("gecko worker closed the RPC pipe")
+        value = json.loads(line)
+        if not isinstance(value, dict):
+            raise RuntimeError("invalid WPR RPC envelope")
+        return value
+    finally:
+        pipe.close()

gecko_web_runtime/session.py

@@ -0,0 +1,281 @@
+"""Relocatable sync/async client for one real Gecko Worker session."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import shutil
+import subprocess
+import tempfile
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .pipe import request
+from .installer import configured_runtime_home
+
+
+PACKAGE_ROOT = Path(__file__).resolve().parents[2]
+
+
+@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
+    profile_root: Path | None = None
+    log_root: Path | None = None
+
+    @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()
+        profile = os.environ.get("WPR_PROFILE_ROOT")
+        logs = os.environ.get("WPR_LOG_ROOT")
+        return cls(
+            package_root=root,
+            runtime_dir=runtime,
+            worker_exe=worker,
+            profile_root=Path(profile).resolve() if profile else None,
+            log_root=Path(logs).resolve() if logs else None,
+        )
+
+    def validate(self) -> None:
+        if os.name != "nt":
+            raise OSError("wpr-runtime-155-win64 requires Windows")
+        if not self.worker_exe.is_file():
+            raise FileNotFoundError(f"Worker executable not found: {self.worker_exe}")
+
+
+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:
+            self.code = "UNKNOWN_ERROR"
+            self.phase = "unknown"
+            message = str(error or "request failed")
+        self.method = method
+        self.response = response
+        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)
+    return response.get("value") or {}
+
+
+class GeckoWorkerSession:
+    """One Worker process and one BrowsingContext/CookieStore session."""
+
+    def __init__(self, config: RuntimeConfig | None = None):
+        self.config = config or RuntimeConfig.bundled()
+        self.config.validate()
+        self.session_id = uuid.uuid4().hex[:12]
+        self.pipe_name = rf"\\.\pipe\wpr-gecko-{self.session_id}"
+        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)
+        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()
+        env.update(
+            {
+                "WPR_RPC": "1",
+                "WPR_REMOTE_PAGE": "1",
+                "WPR_PIPE_NAME": self.pipe_name,
+                "WPR_PROFILE_DIR": str(self.profile_dir),
+            }
+        )
+        env["PATH"] = str(self.config.runtime_dir) + os.pathsep + env.get("PATH", "")
+        self.process = subprocess.Popen(
+            [str(self.config.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]) -> dict[str, Any]:
+        if self.closed:
+            raise RuntimeError("GeckoWorkerSession is closed")
+        return request(payload, self.pipe_name)
+
+    def page_create(self) -> dict[str, Any]:
+        return self.request({"method": "page.create"})
+
+    def page_navigate(self, url: str) -> dict[str, Any]:
+        return self.request({"method": "page.navigate", "url": url})
+
+    def page_eval(self, source: str, args: Any = None) -> Any:
+        payload: dict[str, Any] = {"method": "page.eval", "source": source}
+        if args is not None:
+            payload["args"] = args
+        return require_ok("page.eval", self.request(payload))
+
+    def controlled_navigation_begin(self, url: str) -> Any:
+        return require_ok(
+            "controlled_navigation_begin",
+            self.request({"method": "controlled_navigation_begin", "url": url}),
+        )
+
+    def navigation_allow_scripts(self, transaction_id: str, scripts: list[str]) -> Any:
+        return require_ok(
+            "navigation.allow_scripts",
+            self.request(
+                {
+                    "method": "navigation.allow_scripts",
+                    "transaction_id": transaction_id,
+                    "scripts": scripts,
+                }
+            ),
+        )
+
+    def navigation_commit(self, transaction_id: str) -> Any:
+        return require_ok(
+            "navigation.commit",
+            self.request({"method": "navigation.commit", "transaction_id": transaction_id}),
+        )
+
+    def navigation_wait(self, transaction_id: str) -> Any:
+        return require_ok(
+            "navigation.wait",
+            self.request({"method": "navigation.wait", "transaction_id": transaction_id}),
+        )
+
+    def page_cookie_snapshot(self) -> Any:
+        return self.page_eval(
+            "(() => ({url: location.href, cookie: document.cookie, "
+            "readyState: document.readyState}))()"
+        )
+
+    def page_close(self) -> dict[str, Any]:
+        return self.request({"method": "page.close"})
+
+    def close(self) -> None:
+        if self.closed:
+            return
+        try:
+            if self.process.poll() is None:
+                try:
+                    self.request({"method": "runtime.shutdown"})
+                except Exception:
+                    pass
+                try:
+                    self.process.wait(timeout=15)
+                except subprocess.TimeoutExpired:
+                    self.process.kill()
+                    self.process.wait(timeout=5)
+        finally:
+            self.closed = True
+            self.stdout.close()
+            self.stderr.close()
+            shutil.rmtree(self.profile_dir, ignore_errors=True)
+
+    def __enter__(self) -> "GeckoWorkerSession":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+
+
+class AsyncGeckoWorkerSession:
+    """Async facade; DOM/JS still run only on Gecko's owner thread."""
+
+    def __init__(self, config: RuntimeConfig | None = None):
+        self.config = config
+        self._sync: GeckoWorkerSession | None = None
+        self._lock = asyncio.Lock()
+
+    async def __aenter__(self) -> "AsyncGeckoWorkerSession":
+        self._sync = await asyncio.to_thread(GeckoWorkerSession, self.config)
+        return self
+
+    async def request(self, payload: dict[str, Any]) -> dict[str, Any]:
+        if self._sync is None:
+            raise RuntimeError("AsyncGeckoWorkerSession is not open")
+        async with self._lock:
+            return await asyncio.to_thread(self._sync.request, payload)
+
+    async def page_create(self) -> dict[str, Any]:
+        return await self.request({"method": "page.create"})
+
+    async def page_navigate(self, url: str) -> dict[str, Any]:
+        return await self.request({"method": "page.navigate", "url": url})
+
+    async def page_eval(self, source: str, args: Any = None) -> Any:
+        payload: dict[str, Any] = {"method": "page.eval", "source": source}
+        if args is not None:
+            payload["args"] = args
+        return require_ok("page.eval", await self.request(payload))
+
+    async def controlled_navigation_begin(self, url: str) -> Any:
+        return require_ok(
+            "controlled_navigation_begin",
+            await self.request({"method": "controlled_navigation_begin", "url": url}),
+        )
+
+    async def navigation_allow_scripts(self, transaction_id: str, scripts: list[str]) -> Any:
+        return require_ok(
+            "navigation.allow_scripts",
+            await self.request(
+                {
+                    "method": "navigation.allow_scripts",
+                    "transaction_id": transaction_id,
+                    "scripts": scripts,
+                }
+            ),
+        )
+
+    async def navigation_commit(self, transaction_id: str) -> Any:
+        return require_ok(
+            "navigation.commit",
+            await self.request({"method": "navigation.commit", "transaction_id": transaction_id}),
+        )
+
+    async def navigation_wait(self, transaction_id: str) -> Any:
+        return require_ok(
+            "navigation.wait",
+            await self.request({"method": "navigation.wait", "transaction_id": transaction_id}),
+        )
+
+    async def page_cookie_snapshot(self) -> Any:
+        return await self.page_eval(
+            "(() => ({url: location.href, cookie: document.cookie, "
+            "readyState: document.readyState}))()"
+        )
+
+    async def page_close(self) -> dict[str, Any]:
+        return await self.request({"method": "page.close"})
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        if self._sync is not None:
+            await asyncio.to_thread(self._sync.close)
+            self._sync = None

gecko_web_runtime_client-1.0.0.dist-info/METADATA

@@ -0,0 +1,34 @@
+Metadata-Version: 2.4
+Name: gecko-web-runtime-client
+Version: 1.0.0
+Summary: Thin Python client for the Firefox-derived WPR Gecko Worker protocol
+Author: WPR project
+License: MPL-2.0-compatible client; see the runtime bundle notices
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Python client
+
+The client uses only Python's standard library. From this directory:
+
+```powershell
+$env:PYTHONPATH = "$PWD"
+python ..\examples\normal_navigation.py
+```
+
+The package resolves `runtime/gecko-web-worker.exe` relative to its own
+bundle. Override paths with `WPR_RUNTIME_HOME`, `WPR_RUNTIME_DIR`,
+`WPR_WORKER_EXE`, `WPR_PROFILE_ROOT`, or `WPR_LOG_ROOT` when embedding it in a
+larger application.
+
+To install the pinned runtime automatically from the GitHub Release:
+
+```powershell
+python -m gecko_web_runtime install-runtime --version 155
+```
+
+The command verifies the pinned SHA256 and stores the selected runtime under
+`%LOCALAPPDATA%\WPR\runtime\155`.
+
+For a private GitHub Release, set `GITHUB_TOKEN`, `GH_TOKEN`, or
+`WPR_GITHUB_TOKEN`, or configure Git Credential Manager for the GitHub account.

gecko_web_runtime_client-1.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+gecko_web_runtime/__init__.py,sha256=hkHerbBDOqtedS3xHYPWvgBwOPf5V-aRl-A5q1LojJc,372
+gecko_web_runtime/__main__.py,sha256=1crNdy71fYiQfTqH0FV-5SzlRftCQEO9rgtoUDMkT8g,875
+gecko_web_runtime/installer.py,sha256=htGjrYYzka8CTI51JPAEGNKdMXapsB-0-y0V_K2egbQ,6579
+gecko_web_runtime/pipe.py,sha256=DApeCdA0qa1iEvmPb_v9u5E-lXj4mJnXzIYbF_mWyew,1663
+gecko_web_runtime/session.py,sha256=2kPoqyNzK2ffy3HI8DwSHYY32DY8DIQqab5felnzxe0,10104
+gecko_web_runtime_client-1.0.0.dist-info/METADATA,sha256=DcutF_FYVsJJlyI5bruBAsklymChLAuRdSsrW4tsJhE,1146
+gecko_web_runtime_client-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+gecko_web_runtime_client-1.0.0.dist-info/top_level.txt,sha256=oSRLteQmBqmmSldH5FG_meNE87A7DortZyec99kekIs,18
+gecko_web_runtime_client-1.0.0.dist-info/RECORD,,

gecko_web_runtime_client-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

gecko_web_runtime_client-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+gecko_web_runtime