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

gecko_web_runtime/__init__.py

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

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,276 @@
+"""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
+
+
+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":
+        root = Path(os.environ.get("WPR_RUNTIME_HOME", 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-155.0.0.dist-info/METADATA

@@ -0,0 +1,22 @@
+Metadata-Version: 2.1
+Name: gecko-web-runtime-client
+Version: 155.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.

gecko_web_runtime_client-155.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+gecko_web_runtime/__init__.py,sha256=kVQLriTmJe1d3ngq0ECQS2HjgrIKgG7wSZb4u0DzF8U,310
+gecko_web_runtime/pipe.py,sha256=DApeCdA0qa1iEvmPb_v9u5E-lXj4mJnXzIYbF_mWyew,1663
+gecko_web_runtime/session.py,sha256=J6e23gi-yR_cYobCiu-hwquFGX0toK_w0FfgnAZ9ntk,9932
+gecko_web_runtime_client-155.0.0.dist-info/METADATA,sha256=O6ijQSint0P-0SNtOWE0Kgg3eQ4GQL9ZXOwug3dszho,731
+gecko_web_runtime_client-155.0.0.dist-info/WHEEL,sha256=2AKKnJ9mtikOHAUvaZxUB0niUxQWtKbUrC-HkIWuE1c,91
+gecko_web_runtime_client-155.0.0.dist-info/top_level.txt,sha256=oSRLteQmBqmmSldH5FG_meNE87A7DortZyec99kekIs,18
+gecko_web_runtime_client-155.0.0.dist-info/RECORD,,

gecko_web_runtime_client-155.0.0.dist-info/WHEEL

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

gecko_web_runtime_client-155.0.0.dist-info/top_level.txt

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