browserwright 0.6.2__py3-none-any.whl

browserwright/daemon/backends/cloud.py

@@ -0,0 +1,222 @@
+"""cloud backend — v0.5 (spec §7 + §8.1.1).
+
+The cloud backend exists to cover what the v0.1 `env` backend couldn't:
+HTTP-header auth and mTLS for remote browser services (Browser Use,
+Browserless, Hyperbrowser, etc.). It still produces an upstream CDP ws
+URL (so `kind=UPSTREAM_WS`, not LOCAL_RELAY) — the difference is that
+the daemon's Mode B upstream-ws connect needs the auth provider's
+headers / ssl context to authenticate the handshake. Mode A is degraded
+but supported: for URL-embeddable auth styles (basic, URL-token), we
+fold credentials into the output URL; for header / mTLS auth, Mode A
+emits a warning that the resulting URL won't authenticate (the user
+needs Mode B serve to actually connect).
+
+Endpoint resolution:
+  - `wss://...` / `ws://...` → used as-is
+  - `https://...` / `http://...` → HTTP GET `{endpoint}/json/version`
+    and read `webSocketDebuggerUrl` (same shape as env backend's
+    BD_CDP_URL path). For Authorization-header auth, the discovery GET
+    also carries the header — otherwise some services 401 the GET.
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import httpx
+
+from ..auth import AuthProvider, build_auth_provider
+from ..config import Config
+from ..errors import Unavailable, UserError
+from .base import Backend, DoctorResult, ResolveResult
+
+logger = logging.getLogger(__name__)
+
+
+class CloudBackend(Backend):
+    name = "cloud"
+    kind = "UPSTREAM_WS"
+    recommended_mode: str = "B"  # header / mTLS auth needs Mode B to inject
+    ux_cost = "auth-required"  # v0.5 — new enum value, doctor contract
+
+    def __init__(self, cfg: Config):
+        self._cfg = cfg
+        self._cloud = cfg.backends.cloud
+
+    # ---- internal: build the AuthProvider (cached per-instance) ---------
+
+    _provider_cache: AuthProvider | None = None
+
+    def _provider(self) -> AuthProvider | None:
+        if self._provider_cache is not None:
+            return self._provider_cache
+        if not self._cloud.auth_kind:
+            return None
+        try:
+            p = build_auth_provider(self._cloud.auth_kind, self._cloud.auth)
+        except UserError:
+            raise
+        self._provider_cache = p
+        return p
+
+    # ---- probe ----------------------------------------------------------
+
+    def _extras(self, *, configured: bool) -> dict:
+        """Doctor JSON `extras` contract (v0.5) for cloud backend. Matches
+        skill-impl-2's `_extension_backend_available()` mirror pattern —
+        skill reads `entry["extras"]["configured"]` in install wizard.
+
+        Schema (stable, additions are minor backend bumps not schema-level):
+          provider:   str (browser-use | browserless | hyperbrowser | generic)
+          endpoint:   str | None  (configured ws / https URL, or None)
+          auth_kind:  str | None  (bearer | basic | mtls | oauth2 | None)
+          configured: bool  (True iff endpoint + auth_kind both present
+                             AND auth provider loads without raising)
+        """
+        return {
+            "provider": self._cloud.provider_hint or "generic",
+            "endpoint": self._cloud.endpoint,
+            "auth_kind": self._cloud.auth_kind,
+            "configured": configured,
+        }
+
+    async def probe(self) -> DoctorResult:
+        """Doctor probe — never opens a ws and **never** TCP-connects to the
+        cloud endpoint (spec §H3 / §5.2: zero side effects).
+
+        Contract (v0.5):
+          - `available=true` iff cloud config is complete AND auth provider
+            loads cleanly. We do NOT round-trip to the cloud server — that
+            would mean a TLS handshake (TCP connect + cert exchange) which
+            is a network side effect doctor must not have.
+          - `available=false + detail="not configured; ..."` when no endpoint
+            is configured.
+          - `available=false + detail="auth misconfigured: ..."` when auth
+            provider construction or eval fails (bad token_env, missing
+            cert file).
+          - `ux_cost="auth-required"` always (new enum value v0.5).
+          - `extras` carries `{provider, endpoint, auth_kind, configured}`.
+        """
+        ep = self._cloud.endpoint
+        if not ep:
+            return DoctorResult(
+                name=self.name,
+                available=False,
+                ws_url=None,
+                detail="not configured; configure under [backends.cloud] in config.toml",
+                needs_user_action=(
+                    "configure `[backends.cloud]` in config.toml — "
+                    "see README §cloud backend"),
+                ux_cost=self.ux_cost,
+                extras=self._extras(configured=False),
+            )
+        try:
+            provider = self._provider()
+        except UserError as e:
+            return DoctorResult(
+                name=self.name, available=False, ws_url=None,
+                detail=f"auth misconfigured: {e}",
+                needs_user_action="fix [backends.cloud.auth.*] in config.toml",
+                ux_cost=self.ux_cost,
+                extras=self._extras(configured=False),
+            )
+
+        # Validate the AuthProvider can produce headers / ssl context. This
+        # touches local config (env vars, cert files) but does NOT do any
+        # network I/O — preserves the zero-side-effect doctor contract.
+        try:
+            if provider is not None:
+                _ = await provider.headers()
+                # ssl_context() reads cert files; raises UserError on bad path.
+                _ = provider.ssl_context()
+        except UserError as e:
+            return DoctorResult(
+                name=self.name, available=False, ws_url=None,
+                detail=f"auth misconfigured: {e}",
+                needs_user_action="check env vars / cert files",
+                ux_cost=self.ux_cost,
+                extras=self._extras(configured=False),
+            )
+
+        auth_kind = self._cloud.auth_kind or "(none)"
+        hint = self._cloud.provider_hint or "generic"
+        return DoctorResult(
+            name=self.name,
+            available=True,
+            ws_url=None,
+            detail=f"provider={hint} (auth_kind={auth_kind}, endpoint={ep})",
+            ux_cost=self.ux_cost,
+            extras=self._extras(configured=True),
+        )
+
+    # ---- resolve --------------------------------------------------------
+
+    async def resolve(self, timeout: float) -> ResolveResult:
+        ep = self._cloud.endpoint
+        if not ep:
+            raise Unavailable(
+                "cloud backend has no endpoint configured",
+                attempts={self.name: "no endpoint"},
+            )
+        provider = self._provider()
+        # Pre-baked direct ws URL — just fold URL-embeddable auth in.
+        if ep.startswith(("ws://", "wss://")):
+            url = ep
+            if provider is not None:
+                url = await provider.url_with_auth(url)
+            extras: dict[str, Any] = {
+                "auth_kind": self._cloud.auth_kind or "none",
+                "provider": self._cloud.provider_hint or "generic",
+            }
+            if provider is not None and not provider.supports_websocket_auth():
+                # OAuth2 stub etc. — surface the limitation explicitly.
+                extras["warning"] = (
+                    f"auth_kind={self._cloud.auth_kind} doesn't support "
+                    "websocket auth in v0.5; Mode A URL will not "
+                    "authenticate by itself")
+            return ResolveResult(ws_url=url, backend=self.name, extras=extras)
+
+        # HTTP endpoint → discover via /json/version (matching env backend's
+        # BD_CDP_URL shape).
+        try:
+            headers = await provider.headers() if provider is not None else {}
+        except UserError as e:
+            raise Unavailable(
+                f"cloud backend auth headers unresolvable: {e}",
+                attempts={self.name: str(e)},
+            )
+        url = ep.rstrip("/") + "/json/version"
+        try:
+            async with httpx.AsyncClient(
+                    timeout=timeout, trust_env=False, mounts={}) as client:
+                resp = await client.get(url, headers=headers)
+        except (httpx.HTTPError, OSError) as e:
+            raise Unavailable(
+                f"cloud backend discovery failed: {e}",
+                attempts={self.name: f"{type(e).__name__}: {e}"},
+            )
+        if resp.status_code != 200:
+            raise Unavailable(
+                f"cloud backend discovery returned HTTP {resp.status_code}",
+                attempts={self.name: f"HTTP {resp.status_code} from {url}"},
+            )
+        try:
+            body = resp.json()
+        except ValueError:
+            body = {}
+        ws = body.get("webSocketDebuggerUrl") if isinstance(body, dict) else None
+        if not isinstance(ws, str) or not ws:
+            raise Unavailable(
+                f"cloud backend /json/version has no webSocketDebuggerUrl",
+                attempts={self.name: f"response body: {body!r}"},
+            )
+        if provider is not None:
+            ws = await provider.url_with_auth(ws)
+        return ResolveResult(
+            ws_url=ws,
+            backend=self.name,
+            extras={
+                "auth_kind": self._cloud.auth_kind or "none",
+                "provider": self._cloud.provider_hint or "generic",
+            },
+        )

browserwright/daemon/backends/env.py

@@ -0,0 +1,119 @@
+"""env backend — caller injects the ws URL out-of-band.
+
+Spec §8.1 + §8.1.1: BD_CDP_WS is trusted verbatim (no parsing, no rewriting —
+that's the whole point of the env path for cloud / fingerprint browsers with
+URL-embedded tokens). BD_CDP_URL goes through `/json/version` to pull the
+webSocketDebuggerUrl field, same as rdp but pointed at an arbitrary host.
+
+BU_CDP_WS / BU_CDP_URL are compat aliases honored at the Config layer
+(config.py records `cdp_ws_source`); doctor surfaces a "please migrate" hint
+when those fired.
+"""
+from __future__ import annotations
+
+import httpx
+
+from ..config import Config
+from ..errors import Unavailable
+from .base import Backend, DoctorResult, ResolveResult
+
+
+class EnvBackend(Backend):
+    name = "env"
+    kind = "UPSTREAM_WS"
+    recommended_mode: str = "A"
+    ux_cost = "none"
+
+    def __init__(self, cfg: Config):
+        self._cfg = cfg
+
+    # ------------------------------------------------------------------ probe
+
+    async def probe(self) -> DoctorResult:
+        cfg = self._cfg
+        if cfg.cdp_ws:
+            return DoctorResult(
+                name=self.name,
+                available=True,
+                ws_url=None,  # doctor never opens a ws — spec §5.2 contract
+                detail=self._origin_detail("BD_CDP_WS" if cfg.cdp_ws_source == "BD_CDP_WS"
+                                          else "BU_CDP_WS"),
+                ux_cost=self.ux_cost,
+            )
+        if cfg.cdp_url:
+            return DoctorResult(
+                name=self.name,
+                available=True,
+                ws_url=None,
+                detail=self._origin_detail("BD_CDP_URL" if cfg.cdp_url_source == "BD_CDP_URL"
+                                           else "BU_CDP_URL"),
+                ux_cost=self.ux_cost,
+            )
+        return DoctorResult(
+            name=self.name,
+            available=False,
+            ws_url=None,
+            detail="BD_CDP_WS not set, BD_CDP_URL not set",
+            ux_cost=self.ux_cost,
+        )
+
+    def _origin_detail(self, source: str) -> str:
+        if source.startswith("BU_"):
+            return f"{source} set (deprecated, please rename to BD_{source[3:]})"
+        return f"{source} set"
+
+    # ---------------------------------------------------------------- resolve
+
+    async def resolve(self, timeout: float) -> ResolveResult:
+        cfg = self._cfg
+        if cfg.cdp_ws:
+            return ResolveResult(ws_url=cfg.cdp_ws, backend=self.name, extras={})
+        if cfg.cdp_url:
+            ws = await _resolve_via_json_version(cfg.cdp_url, timeout)
+            return ResolveResult(
+                ws_url=ws,
+                backend=self.name,
+                extras={"discovery_url": cfg.cdp_url},
+            )
+        raise Unavailable(
+            "env backend: neither BD_CDP_WS nor BD_CDP_URL is set",
+            attempts={self.name: "BD_CDP_WS not set, BD_CDP_URL not set"},
+        )
+
+
+async def _resolve_via_json_version(base_url: str, timeout: float) -> str:
+    """HTTP GET {base_url}/json/version and return webSocketDebuggerUrl.
+
+    Spec §8.1: this is the standard CDP HTTP discovery shape that all real and
+    fingerprint browsers, plus most cloud providers, agree on. We keep this
+    function shared with `rdp`-style probes (re-imported there) so the two
+    paths can never diverge on edge handling (timeout / non-200 / missing key).
+    """
+    url = f"{base_url.rstrip('/')}/json/version"
+    try:
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            resp = await client.get(url)
+    except (httpx.HTTPError, OSError) as e:
+        raise Unavailable(
+            f"env backend: HTTP discovery failed for {url}: {e}",
+            attempts={"env": f"GET {url} -> {type(e).__name__}: {e}"},
+        ) from e
+    if resp.status_code != 200:
+        raise Unavailable(
+            f"env backend: {url} returned HTTP {resp.status_code}",
+            attempts={"env": f"GET {url} -> HTTP {resp.status_code}"},
+        )
+    try:
+        body = resp.json()
+    except ValueError as e:
+        raise Unavailable(
+            f"env backend: {url} returned non-JSON body: {e}",
+            attempts={"env": f"GET {url} -> non-JSON"},
+        ) from e
+    ws = body.get("webSocketDebuggerUrl") if isinstance(body, dict) else None
+    if not isinstance(ws, str) or not ws:
+        raise Unavailable(
+            f"env backend: {url} JSON has no webSocketDebuggerUrl field",
+            attempts={"env": f"GET {url} -> missing webSocketDebuggerUrl"},
+        )
+    return ws

browserwright/daemon/backends/extension.py

@@ -0,0 +1,185 @@
+"""extension backend — v0.4 real implementation (spec §8.4).
+
+Architecture: this backend doesn't return an upstream ws URL — Chrome's
+CDP isn't the upstream here. Instead, the daemon (Mode B `serve`) starts a
+local relay ws server (`server/relay.py`) on `127.0.0.1:19989`, and the
+user's Chrome extension connects TO us. The daemon then proxies standard
+CDP between Skill clients and the extension's `chrome.debugger` API.
+
+Implications:
+
+- `kind=LOCAL_RELAY` (spec §4.3): not a URL passthrough; the daemon
+  emulates the upstream side.
+- `resolve()` in Mode A still raises — Mode A `url` is meaningless when the
+  daemon IS the relay; Skill must drive Mode B.
+- `probe()` does a real check: GET `http://127.0.0.1:19989/__status__` and
+  inspect the response for a connected extension. If reachable + at least
+  one extension has sent `hello`, `available=true`.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from typing import Any
+
+import httpx
+
+from ..config import Config
+from ..errors import Unavailable
+from .base import Backend, DoctorResult, ResolveResult
+from ..server.relay import DEFAULT_RELAY_PORT
+from browserwright.version import EXTENSION_PROTOCOL_VERSION, package_version
+
+logger = logging.getLogger(__name__)
+
+
+class ExtensionBackend(Backend):
+    name = "extension"
+    kind = "LOCAL_RELAY"
+    recommended_mode: str = "B"
+    ux_cost = "extension-permission"
+
+    def __init__(self, cfg: Config):
+        self._cfg = cfg
+        # v0.5.3 F-5 / Task #24: single source of truth for host+port.
+        # Honors CLI --extension-port > BD_EXTENSION_PORT > toml port >
+        # toml relay_url > DEFAULT_RELAY_PORT.
+        self._host, self._port = cfg.backends.extension.resolved_host_port()
+
+    def caps(self) -> dict:
+        # Attaches to the user's existing Chrome; isolates sessions via tab
+        # groups, not browser contexts (P4).
+        return {"owns_browser": False, "supports_browser_context": False}
+
+    async def probe(self) -> DoctorResult:
+        """HTTP GET 127.0.0.1:19989/__status__.
+
+        Three outcomes:
+          1. connection refused → no daemon-serve running with extension
+             backend → available=false + needs_user_action
+          2. running but `extensions == 0` → relay up, user hasn't installed
+             / loaded the extension → available=false + needs_user_action
+          3. running with extensions → available=true
+        """
+        url = f"http://127.0.0.1:{self._port}/__status__"
+        # `trust_env=False` + explicit `mounts={}` makes httpx ignore the
+        # user's HTTPS_PROXY / SOCKS_PROXY / ALL_PROXY env vars. Loopback
+        # traffic must never go through a proxy — same trick the other
+        # backends use for their `/json/version` probes.
+        try:
+            async with httpx.AsyncClient(
+                timeout=2.0, trust_env=False, mounts={},
+            ) as client:
+                resp = await client.get(url)
+        except (httpx.ConnectError, httpx.ConnectTimeout):
+            return DoctorResult(
+                name=self.name,
+                available=False,
+                ws_url=None,
+                detail=(f"no extension relay listening on 127.0.0.1:{self._port} "
+                        f"— start `browserwright-daemon serve`"),
+                ux_warning=None,
+                needs_user_action=(
+                    "start the single global daemon, "
+                    "then load the Chrome extension from `chrome-extension/`"),
+                ux_cost=self.ux_cost,
+            )
+        except Exception as e:
+            return DoctorResult(
+                name=self.name,
+                available=False,
+                ws_url=None,
+                detail=f"relay status probe failed: {e!r}",
+                ux_warning=None,
+                needs_user_action="check daemon logs",
+                ux_cost=self.ux_cost,
+            )
+
+        if resp.status_code != 200:
+            return DoctorResult(
+                name=self.name,
+                available=False,
+                ws_url=None,
+                detail=f"relay /__status__ returned HTTP {resp.status_code}",
+                needs_user_action="restart daemon-serve",
+                ux_cost=self.ux_cost,
+            )
+        try:
+            status = resp.json()
+        except (ValueError, json.JSONDecodeError):
+            status = {}
+
+        ext_count = int(status.get("extensions", 0))
+        if ext_count == 0:
+            return DoctorResult(
+                name=self.name,
+                available=False,
+                ws_url=None,
+                detail=("extension relay is running but no Chrome extension "
+                        "has connected yet"),
+                needs_user_action=(
+                    "load `chrome-extension/` as an unpacked extension in "
+                    "Chrome (chrome://extensions/ → enable Developer mode "
+                    "→ Load unpacked)"),
+                ux_cost=self.ux_cost,
+            )
+
+        install_ids = status.get("install_ids") or []
+        details = status.get("extension_details") or []
+        incompatible = [
+            item for item in details
+            if item.get("compatible") is False
+        ]
+        version_mismatch = [
+            item for item in details
+            if item.get("browserwright_version")
+            and item.get("browserwright_version") != package_version()
+        ]
+        if incompatible:
+            return DoctorResult(
+                name=self.name,
+                available=False,
+                ws_url=None,
+                detail=(
+                    "extension relay connected, but protocol is incompatible "
+                    f"(daemon expects {EXTENSION_PROTOCOL_VERSION})"
+                ),
+                ux_warning="reload the unpacked extension from the matching release",
+                needs_user_action="reload `chrome-extension/` in Chrome",
+                ux_cost=self.ux_cost,
+            )
+        warning = None
+        if version_mismatch:
+            seen = sorted({
+                str(item.get("browserwright_version"))
+                for item in version_mismatch
+                if item.get("browserwright_version")
+            })
+            warning = (
+                f"extension version(s) {seen} do not match package "
+                f"{package_version()}; reload the unpacked extension"
+            )
+        tabs = int(status.get("tab_count", 0))
+        return DoctorResult(
+            name=self.name,
+            available=True,
+            ws_url=None,
+            detail=(f"{ext_count} extension(s) connected "
+                    f"(install_ids={install_ids}, attached tabs={tabs})"),
+            ux_warning=warning,
+            needs_user_action=None,
+            ux_cost=self.ux_cost,
+        )
+
+    async def resolve(self, timeout: float) -> ResolveResult:
+        """Mode A `url` isn't meaningful for LOCAL_RELAY: there's no
+        externally-connectable upstream ws — the daemon IS the relay. So we
+        raise Unavailable with a hint that points to Mode B.
+        """
+        raise Unavailable(
+            "extension backend is a LOCAL_RELAY — it cannot be used via "
+            "`browserwright-daemon url`. Run `browserwright-daemon serve` "
+            "instead and connect via the daemon's unix socket.",
+            attempts={self.name: "LOCAL_RELAY backend requires Mode B serve"},
+        )