wpr-http 0.2.0__tar.gz

wpr_http-0.2.0/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: wpr-http
+Version: 0.2.0
+Summary: Standalone HTTP client using version-selected Firefox Necko/NSS Workers
+License: MPL-2.0-compatible client; see runtime bundle notices
+Project-URL: Repository, https://github.com/childclm/wpr-http
+Project-URL: Documentation, https://github.com/childclm/wpr-http/blob/main/README.md
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: wpr-runtime-core<0.3,>=0.2.0
+
+# WPR HTTP
+
+Standalone HTTP requests using real, version-selected Firefox Necko/NSS network
+Workers. Installing this package does not install the WPR browser client.
+The native runtime is downloaded separately and remains centrally built.
+
+```python
+import asyncio
+from wpr_http import AsyncClient
+
+async def main():
+    async with AsyncClient(firefox_version="155") as client:
+        response = await client.get("https://www.baidu.com/")
+        async with response:
+            response.raise_for_status()
+            print(response.status_code, await response.atext())
+
+asyncio.run(main())
+```
+
+`firefox_version` selects a genuine installed Gecko network engine, not a
+User-Agent string or a simulated browser. Only Firefox 155 is currently built
+and supported. Selecting another version raises an explicit compatibility error;
+it never silently uses 155. Different installed engine versions use separate
+runtime/profile locations and separate Worker processes.
+
+Runtime installation and supported versions:
+
+```powershell
+python -m wpr_http runtimes
+python -m wpr_http install-runtime --version 155
+```
+
+An explicit `runtime_home` can select another verified runtime installation.
+Existing `AsyncWprHttpClient`, Request/Response/Timeout and exception names remain
+available. `WprHttpClient` remains the historical asynchronous alias.
+
+The native network runtime is a separate download from the private
+`childclm/gecko-web-runtime` Release. Installation needs access to that repository. Set
+`WPR_GITHUB_TOKEN` or `GH_TOKEN`, or use Git Credential Manager, then run
+`python -m wpr_http install-runtime --version 155`.

wpr_http-0.2.0/README.md

@@ -0,0 +1,41 @@
+# WPR HTTP
+
+Standalone HTTP requests using real, version-selected Firefox Necko/NSS network
+Workers. Installing this package does not install the WPR browser client.
+The native runtime is downloaded separately and remains centrally built.
+
+```python
+import asyncio
+from wpr_http import AsyncClient
+
+async def main():
+    async with AsyncClient(firefox_version="155") as client:
+        response = await client.get("https://www.baidu.com/")
+        async with response:
+            response.raise_for_status()
+            print(response.status_code, await response.atext())
+
+asyncio.run(main())
+```
+
+`firefox_version` selects a genuine installed Gecko network engine, not a
+User-Agent string or a simulated browser. Only Firefox 155 is currently built
+and supported. Selecting another version raises an explicit compatibility error;
+it never silently uses 155. Different installed engine versions use separate
+runtime/profile locations and separate Worker processes.
+
+Runtime installation and supported versions:
+
+```powershell
+python -m wpr_http runtimes
+python -m wpr_http install-runtime --version 155
+```
+
+An explicit `runtime_home` can select another verified runtime installation.
+Existing `AsyncWprHttpClient`, Request/Response/Timeout and exception names remain
+available. `WprHttpClient` remains the historical asynchronous alias.
+
+The native network runtime is a separate download from the private
+`childclm/gecko-web-runtime` Release. Installation needs access to that repository. Set
+`WPR_GITHUB_TOKEN` or `GH_TOKEN`, or use Git Credential Manager, then run
+`python -m wpr_http install-runtime --version 155`.

wpr_http-0.2.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "wpr-http"
+version = "0.2.0"
+description = "Standalone HTTP client using version-selected Firefox Necko/NSS Workers"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MPL-2.0-compatible client; see runtime bundle notices"}
+dependencies = ["wpr-runtime-core>=0.2.0,<0.3"]
+
+[project.urls]
+Repository = "https://github.com/childclm/wpr-http"
+Documentation = "https://github.com/childclm/wpr-http/blob/main/README.md"
+
+[project.scripts]
+wpr-http = "wpr_http.__main__:main"
+
+[tool.setuptools.packages.find]
+include = ["wpr_http*"]

wpr_http-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

wpr_http-0.2.0/tests/test_contracts.py

@@ -0,0 +1,187 @@
+import hashlib
+import json
+import subprocess
+import sys
+
+import pytest
+from wpr_http import AsyncClient, Request, RuntimeCompatibilityError, Timeout
+from wpr_runtime_core.registry import RuntimeManifest, resolve_runtime
+from wpr_runtime_core.session import AsyncWorkerSession
+
+
+def make_runtime(tmp_path, major="155", protocol="wpr-http-v1", abi=None):
+    home = tmp_path / major
+    worker = home / "runtime" / f"net-v{major}" / "gecko-net-worker.exe"
+    worker.parent.mkdir(parents=True)
+    worker.write_bytes(b"not-an-executable-fixture")
+    relative = worker.relative_to(home).as_posix()
+    manifest = {
+        "schema": "wpr.runtime-manifest.v1",
+        "version": major + ".0.6",
+        "platform": "windows-x86_64",
+        "protocols": [protocol],
+        "network_worker": relative,
+        "components": {
+            "network": {
+                "firefox_major": int(major),
+                "protocol": protocol,
+                "client_api": abi or {"min": 1, "max": 1},
+                "worker": relative,
+            }
+        },
+        "files": {
+            relative: {"sha256": hashlib.sha256(worker.read_bytes()).hexdigest()}
+        },
+    }
+    (home / "manifest.json").write_text(json.dumps(manifest), encoding="utf-8")
+    return home, manifest
+
+
+def test_import_does_not_load_browser():
+    subprocess.run(
+        [
+            sys.executable,
+            "-c",
+            "import sys,wpr_http; assert not any(n.startswith('gecko_web_runtime') for n in sys.modules)",
+        ],
+        check=True,
+    )
+    assert not hasattr(AsyncWorkerSession, "page_create")
+    assert not hasattr(AsyncWorkerSession, "page_eval")
+    assert isinstance(AsyncWorkerSession.is_open, property)
+
+
+def test_requests_and_deadlines_are_standalone():
+    request = Request(
+        "get", "https://example.com", headers={"X-Test": "yes"}, timeout=0.2
+    )
+    assert request.method == "GET"
+    assert request.headers["x-test"] == "yes"
+    assert request.timeout == Timeout(total=0.2)
+
+
+@pytest.mark.asyncio
+async def test_response_accepts_a_body_lease_without_a_worker_session():
+    from types import SimpleNamespace
+
+    from wpr_http import Response
+
+    class MemoryLease:
+        descriptor = SimpleNamespace(encoding="utf-8")
+        mapping_open_ms = copy_ms = 0.0
+        released = False
+
+        def __init__(self):
+            self.release_timings = {}
+
+        def open(self):
+            return self
+
+        def read_bytes(self):
+            return b"standalone"
+
+        async def release(self):
+            self.released = True
+            return {"released": True}
+
+    lease = MemoryLease()
+    response = Response(
+        None, {"status": 200, "final_url": "http://fixture/"}, body=lease
+    )
+    assert await response.atext() == "standalone"
+    assert lease.released and response.is_closed
+
+
+def test_selected_runtime_is_actual_manifest_worker(tmp_path):
+    home, _ = make_runtime(tmp_path)
+    client = AsyncClient(firefox_version=155, runtime_home=home)
+    assert client.runtime_manifest.firefox_major == "155"
+    assert client.config.runtime_dir == home / "runtime"
+    assert client.max_channels_per_worker == 20
+
+
+def test_explicit_future_runtime_is_separate_not_a_published_claim(tmp_path):
+    # Fixture only: proves independent selection without claiming a 156 build.
+    a, _ = make_runtime(tmp_path, "155")
+    b, _ = make_runtime(tmp_path, "156")
+    assert (
+        resolve_runtime("155", runtime_home=a).network_worker
+        != resolve_runtime("156", runtime_home=b).network_worker
+    )
+    with pytest.raises(RuntimeCompatibilityError, match="requested Firefox"):
+        resolve_runtime("156", runtime_home=a)
+
+
+def test_unpublished_version_never_silently_falls_back(monkeypatch):
+    monkeypatch.delenv("WPR_RUNTIME_HOME", raising=False)
+    with pytest.raises(RuntimeCompatibilityError, match="no published runtime"):
+        AsyncClient(firefox_version=999)
+
+
+def test_registration_preserves_other_engines_and_exact_builds(tmp_path, monkeypatch):
+    from wpr_runtime_core.installer import _write_config, config_path
+
+    monkeypatch.setenv("LOCALAPPDATA", str(tmp_path / "appdata"))
+    monkeypatch.delenv("WPR_RUNTIME_HOME", raising=False)
+    a, _ = make_runtime(tmp_path, "155")
+    b, _ = make_runtime(tmp_path, "156")
+    _write_config(a, product="network")
+    _write_config(b, product="network")
+    settings = json.loads(config_path().read_text(encoding="utf-8"))
+    assert settings["network_runtimes"]["155"] == str(a)
+    assert settings["network_runtimes"]["156.0.6"] == str(b)
+    assert resolve_runtime("155").home == a
+    assert resolve_runtime("156").home == b
+
+
+@pytest.mark.parametrize("value", [True, "firefox155", "../155", "", 0])
+def test_invalid_engine_version(value):
+    with pytest.raises(RuntimeCompatibilityError):
+        resolve_runtime(value)
+
+
+def test_exact_build_pin(tmp_path):
+    home, _ = make_runtime(tmp_path)
+    with pytest.raises(RuntimeCompatibilityError, match="installed runtime"):
+        resolve_runtime("155.0.5", runtime_home=home)
+    assert resolve_runtime("155.0.6", runtime_home=home).runtime_version == "155.0.6"
+
+
+def test_catalog_selects_default_and_exact_build_without_fallback(monkeypatch):
+    from copy import deepcopy
+
+    from wpr_runtime_core import installer
+
+    catalog = deepcopy(installer.RUNTIME_CATALOG)
+    releases = catalog["engines"]["firefox155"]
+    older = deepcopy(releases["builds"]["155.0.6"])
+    older["version"] = "155.0.5"
+    releases["builds"]["155.0.5"] = older
+    monkeypatch.setattr(installer, "RUNTIME_CATALOG", catalog)
+    assert installer.select_release("155")["version"] == "155.0.6"
+    assert installer.select_release("155.0.5")["version"] == "155.0.5"
+    with pytest.raises(RuntimeCompatibilityError, match="no published runtime"):
+        installer.select_release("155.0.4")
+
+
+@pytest.mark.parametrize("kind", ["protocol", "abi", "hash", "escape"])
+def test_incompatible_runtime_is_rejected_before_launch(tmp_path, kind):
+    home, manifest = make_runtime(tmp_path)
+    if kind == "protocol":
+        manifest["components"]["network"]["protocol"] = "wpr-http-v2"
+    elif kind == "abi":
+        manifest["components"]["network"]["client_api"] = {"min": 2, "max": 2}
+    elif kind == "hash":
+        manifest["files"][manifest["network_worker"]]["sha256"] = "0" * 64
+    else:
+        manifest["components"]["network"]["worker"] = "../outside.exe"
+    (home / "manifest.json").write_text(json.dumps(manifest), encoding="utf-8")
+    with pytest.raises(RuntimeCompatibilityError):
+        RuntimeManifest.load(home, "155")
+
+
+def test_legacy_manifest_v1_is_supported(tmp_path):
+    home, manifest = make_runtime(tmp_path)
+    manifest.pop("components")
+    (home / "manifest.json").write_text(json.dumps(manifest), encoding="utf-8")
+    assert resolve_runtime("155", runtime_home=home).protocol == "wpr-http-v1"

wpr_http-0.2.0/tests/test_native_http.py

@@ -0,0 +1,124 @@
+"""Optional real-engine tests, independent of the browser client and public sites."""
+
+import asyncio
+import json
+import os
+import threading
+import time
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+import pytest
+from wpr_http import AsyncClient, WprHTTPStatusError, WprTimeoutError
+
+pytestmark = pytest.mark.skipif(
+    os.name != "nt" or not os.environ.get("WPR_TEST_RUNTIME_HOME"),
+    reason="requires an explicitly selected installed Windows network runtime",
+)
+
+
+class Api(ThreadingHTTPServer):
+    request_queue_size = 128
+    active = 0
+    peak = 0
+    lock = threading.Lock()
+
+    def handle_error(self, *_):
+        pass  # cancelled/timed-out requests intentionally close their sockets
+
+
+class Handler(BaseHTTPRequestHandler):
+    def log_message(self, *_):
+        pass
+
+    def do_GET(self):
+        with self.server.lock:
+            self.server.active += 1
+            self.server.peak = max(self.server.peak, self.server.active)
+        try:
+            if self.path.startswith("/slow"):
+                time.sleep(0.3)
+            if self.path.startswith("/parallel"):
+                time.sleep(0.1)
+            body = json.dumps(
+                {"path": self.path, "cookie": self.headers.get("Cookie")}
+            ).encode()
+            if self.path == "/large":
+                body = b"x" * (1024 * 1024)
+            status = (
+                418
+                if self.path == "/error"
+                else 302
+                if self.path == "/redirect"
+                else 200
+            )
+            self.send_response(status)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(body)))
+            if self.path == "/cookie":
+                self.send_header("Set-Cookie", "native=yes; Path=/")
+            if self.path == "/redirect":
+                self.send_header("Location", "/final")
+            self.end_headers()
+            self.wfile.write(body)
+        finally:
+            with self.server.lock:
+                self.server.active -= 1
+
+
+def test_native_sequential_parallel_cookie_redirect_timeout_body():
+    api = Api(("127.0.0.1", 0), Handler)
+    thread = threading.Thread(target=api.serve_forever, daemon=True)
+    thread.start()
+
+    async def run():
+        base = f"http://127.0.0.1:{api.server_port}"
+        async with AsyncClient(
+            firefox_version="155",
+            runtime_home=os.environ["WPR_TEST_RUNTIME_HOME"],
+            proxy="",
+            base_url=base,
+        ) as client:
+            for i in range(3):
+                response = await client.get(f"/serial/{i}")
+                assert (await response.ajson())["path"] == f"/serial/{i}"
+
+            async def one(i):
+                response = await client.get(f"/parallel/{i}")
+                return await response.ajson()
+
+            results = await asyncio.gather(*(one(i) for i in range(8)))
+            assert len(results) == 8 and api.peak >= 3
+            response = await client.get("/cookie")
+            await response.aread()
+            response = await client.get("/check")
+            assert "native=yes" in (await response.ajson())["cookie"]
+            response = await client.get("/redirect")
+            assert response.url.endswith("/final")
+            await response.aread()
+            response = await client.get("/error")
+            with pytest.raises(WprHTTPStatusError):
+                response.raise_for_status()
+            await response.aclose()
+            response = await client.get("/large")
+            assert len(await response.aread()) == 1024 * 1024
+            with pytest.raises(WprTimeoutError):
+                await client.get("/slow", timeout=0.04)
+            response = await client.get("/after-timeout")
+            assert response.status_code == 200
+            await response.aread()
+            task = asyncio.create_task(client.get("/slow-cancel"))
+            await asyncio.sleep(0.05)
+            task.cancel()
+            with pytest.raises(asyncio.CancelledError):
+                await task
+            response = await client.get("/after-cancel")
+            await response.aread()
+            await client.flush_releases()
+            assert client.transport_stats["pending_blob_count"] == 0
+
+    try:
+        asyncio.run(run())
+    finally:
+        api.shutdown()
+        api.server_close()
+        thread.join()

wpr_http-0.2.0/wpr_http/__init__.py

@@ -0,0 +1,60 @@
+"""Public network client API backed by Firefox Necko."""
+
+from wpr_runtime_core.registry import RuntimeCompatibilityError, RuntimeManifest
+
+from .client import AsyncWprHttpClient, WprHttpClient
+from .exceptions import (
+    WprConnectError,
+    WprHttpError,
+    WprHTTPStatusError,
+    WprPoolTimeoutError,
+    WprProxyError,
+    WprTimeoutError,
+    WprTransportError,
+)
+from .models import Headers, HttpRequest, HttpResponse, NetworkTiming, Request, Timeout
+
+__version__ = "0.2.0"
+
+
+class AsyncClient(AsyncWprHttpClient):
+    """Standalone client: select and validate an actual Firefox network runtime."""
+
+    def __init__(
+        self, *, firefox_version=None, runtime_home=None, config=None, **kwargs
+    ):
+        # Explicit config supports local development builds. Installed engines
+        # always go through manifest/version/hash validation.
+        if config is None and firefox_version is None:
+            firefox_version = "155"
+        super().__init__(
+            config=config,
+            firefox_version=firefox_version,
+            runtime_home=runtime_home,
+            **kwargs,
+        )
+
+
+Response = HttpResponse
+
+__all__ = [
+    "AsyncClient",
+    "AsyncWprHttpClient",
+    "Headers",
+    "HttpRequest",
+    "HttpResponse",
+    "NetworkTiming",
+    "Request",
+    "Response",
+    "RuntimeCompatibilityError",
+    "RuntimeManifest",
+    "Timeout",
+    "WprConnectError",
+    "WprHTTPStatusError",
+    "WprHttpClient",
+    "WprHttpError",
+    "WprPoolTimeoutError",
+    "WprProxyError",
+    "WprTimeoutError",
+    "WprTransportError",
+]

wpr_http-0.2.0/wpr_http/__main__.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import argparse
+import json
+
+from wpr_runtime_core.installer import RUNTIME_CATALOG, install_runtime
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(prog="python -m wpr_http")
+    commands = parser.add_subparsers(dest="command", required=True)
+    commands.add_parser(
+        "runtimes", help="list published engine versions in this client's catalog"
+    )
+    install = commands.add_parser("install-runtime")
+    install.add_argument("--version", default="155")
+    install.add_argument("--runtime-home")
+    install.add_argument("--force", action="store_true")
+    args = parser.parse_args()
+    if args.command == "runtimes":
+        print(json.dumps(RUNTIME_CATALOG, indent=2))
+    else:
+        print(install_runtime(args.version, args.runtime_home, force=args.force, product="network"))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

wpr_http-0.2.0/wpr_http/_urls.py

@@ -0,0 +1,31 @@
+"""URL helpers used in diagnostics; credential and query values stay private."""
+
+from urllib.parse import urlsplit, urlunsplit
+
+
+def safe_url(url: str) -> str:
+    try:
+        parsed = urlsplit(url)
+        host = parsed.hostname or ""
+        if ":" in host and not host.startswith("["):
+            host = f"[{host}]"
+        if parsed.port:
+            host = f"{host}:{parsed.port}"
+        return urlunsplit(
+            (parsed.scheme, host, parsed.path, "..." if parsed.query else "", "")
+        )
+    except ValueError:
+        return "<invalid URL>"
+
+
+def safe_proxy(proxy: str) -> str:
+    try:
+        parsed = urlsplit(proxy)
+        host = parsed.hostname or "<unknown>"
+        if ":" in host and not host.startswith("["):
+            host = f"[{host}]"
+        if parsed.port:
+            host = f"{host}:{parsed.port}"
+        return f"{parsed.scheme}://{host}"
+    except ValueError:
+        return "<configured proxy>"