browserwright 0.6.2__py3-none-any.whl

browserwright/daemon/platforms.py

@@ -0,0 +1,234 @@
+"""Platform-specific Chrome / Chromium-family profile locations.
+
+This table is sourced verbatim from browser-harness `daemon.py:36-65` — the spec
+(§8.3) is explicit: "this table is fought for, do not reinvent it." Any addition
+should match a real installed browser and ship with a smoke test.
+
+Covers macOS, Linux, Linux Flatpak, Windows × Chrome (Stable/Canary) / Chromium
+/ Edge (Stable/Beta/Dev/Canary) / Brave / Arc / Dia / Comet.
+"""
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+import subprocess
+from pathlib import Path
+
+
+def proc_start_time(pid: int) -> str | None:
+    """Best-effort process start-time fingerprint, used to detect PID reuse
+    before signalling a daemon (see ``cli._cmd_stop``).
+
+    Returns an opaque but *stable* string identifying when the process started,
+    or ``None`` when the platform can't answer (no such pid, or unsupported) —
+    callers must treat ``None`` as "can't verify" and fall back, never as a
+    match.
+
+    - Linux: field 22 (``starttime``, in clock ticks since boot) of
+      ``/proc/<pid>/stat``.
+    - macOS / BSD: ``ps -o lstart= -p <pid>`` (a stable wall-clock string).
+    """
+    # Linux fast path — no subprocess.
+    try:
+        stat = Path(f"/proc/{pid}/stat")
+        if stat.exists():
+            data = stat.read_text()
+            # comm (field 2) is parenthesised and may contain spaces/parens;
+            # split after the final ')' so positional fields stay aligned.
+            rparen = data.rfind(")")
+            if rparen != -1:
+                # After "pid (comm) " the remaining fields start at state
+                # (field 3). starttime is field 22 → index 22 - 3 = 19.
+                fields = data[rparen + 2:].split()
+                if len(fields) > 19:
+                    return fields[19]
+    except (OSError, ValueError, IndexError):
+        pass
+    # macOS / BSD — ask ps for the start timestamp.
+    try:
+        out = subprocess.run(
+            ["ps", "-o", "lstart=", "-p", str(pid)],
+            capture_output=True, text=True, timeout=3.0)
+        if out.returncode == 0:
+            s = out.stdout.strip()
+            return s or None
+    except (OSError, subprocess.SubprocessError):
+        pass
+    return None
+
+
+def profile_paths() -> list[Path]:
+    """The full cross-platform profile list. Order is significant only as
+    documentation — callers should always tie-break by mtime, never by order.
+    """
+    home = Path.home()
+    return [
+        # macOS
+        home / "Library/Application Support/Google/Chrome",
+        home / "Library/Application Support/Google/Chrome Canary",
+        home / "Library/Application Support/Comet",
+        home / "Library/Application Support/Arc/User Data",
+        home / "Library/Application Support/Dia/User Data",
+        home / "Library/Application Support/Microsoft Edge",
+        home / "Library/Application Support/Microsoft Edge Beta",
+        home / "Library/Application Support/Microsoft Edge Dev",
+        home / "Library/Application Support/Microsoft Edge Canary",
+        home / "Library/Application Support/BraveSoftware/Brave-Browser",
+        # Linux (native)
+        home / ".config/google-chrome",
+        home / ".config/chromium",
+        home / ".config/chromium-browser",
+        home / ".config/microsoft-edge",
+        home / ".config/microsoft-edge-beta",
+        home / ".config/microsoft-edge-dev",
+        # Linux (Flatpak)
+        home / ".var/app/org.chromium.Chromium/config/chromium",
+        home / ".var/app/com.google.Chrome/config/google-chrome",
+        home / ".var/app/com.brave.Browser/config/BraveSoftware/Brave-Browser",
+        home / ".var/app/com.microsoft.Edge/config/microsoft-edge",
+        # Windows
+        home / "AppData/Local/Google/Chrome/User Data",
+        home / "AppData/Local/Google/Chrome SxS/User Data",
+        home / "AppData/Local/Chromium/User Data",
+        home / "AppData/Local/Microsoft/Edge/User Data",
+        home / "AppData/Local/Microsoft/Edge Beta/User Data",
+        home / "AppData/Local/Microsoft/Edge Dev/User Data",
+        home / "AppData/Local/Microsoft/Edge SxS/User Data",
+        home / "AppData/Local/BraveSoftware/Brave-Browser/User Data",
+    ]
+
+
+# Likely-binary paths for `launch-chrome` (§5.5 step 1 fallback). PATH lookup is
+# tried first; this list is only consulted if PATH yields nothing.
+def chrome_binary_candidates() -> list[Path]:
+    system = platform.system()
+    if system == "Darwin":
+        return [
+            Path("/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"),
+            Path("/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary"),
+            Path("/Applications/Chromium.app/Contents/MacOS/Chromium"),
+            Path("/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"),
+            Path("/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"),
+        ]
+    if system == "Windows":
+        pf = os.environ.get("PROGRAMFILES", r"C:\Program Files")
+        pfx86 = os.environ.get("PROGRAMFILES(X86)", r"C:\Program Files (x86)")
+        local = os.environ.get("LOCALAPPDATA", str(Path.home() / "AppData/Local"))
+        return [
+            Path(pf) / "Google/Chrome/Application/chrome.exe",
+            Path(pfx86) / "Google/Chrome/Application/chrome.exe",
+            Path(local) / "Google/Chrome/Application/chrome.exe",
+            Path(pf) / "Microsoft/Edge/Application/msedge.exe",
+            Path(pfx86) / "Microsoft/Edge/Application/msedge.exe",
+        ]
+    # Linux + everything else
+    return [
+        Path("/usr/bin/google-chrome"),
+        Path("/usr/bin/google-chrome-stable"),
+        Path("/usr/bin/chromium"),
+        Path("/usr/bin/chromium-browser"),
+        Path("/usr/bin/microsoft-edge"),
+        Path("/usr/bin/brave-browser"),
+        Path("/snap/bin/chromium"),
+    ]
+
+
+def _binary_is_runnable(path: Path, timeout: float = 3.0) -> bool:
+    """Validate a Chrome candidate by `<binary> --version` returning exit 0.
+
+    Task #12: macOS Homebrew installs of `chromium` sometimes leave a wrapper
+    shell script at `/opt/homebrew/bin/chromium` that exec's a non-existent
+    `.app` and exits 126. PATH-lookup `shutil.which("chromium")` happily
+    picks that up and `launch_chrome` falls into the now-fixed Bug #2 poll
+    race symptom WITHOUT the underlying poll-race actually being present.
+
+    Cheap (`--version` returns < 50ms in steady state) + side-effect-free
+    (no `--user-data-dir` involved). On a healthy install, all browser
+    binaries respond to `--version`. We don't parse the output — just check
+    the exit code.
+    """
+    import subprocess
+    try:
+        result = subprocess.run(
+            [str(path), "--version"],
+            capture_output=True,
+            timeout=timeout,
+        )
+    except (FileNotFoundError, PermissionError, subprocess.TimeoutExpired):
+        return False
+    except OSError:
+        return False
+    return result.returncode == 0
+
+
+def discover_chrome_binary(explicit: str | None = None) -> Path | None:
+    """Implements §5.5 step 1: --chrome-binary > BD_CHROME_BINARY (caller passes
+    in via `explicit`) > platform default `.app` list (macOS) > $PATH walk
+    with `--version` validation.
+
+    Returns the resolved absolute Path or None when nothing matches. Caller
+    decides whether to raise ChromeBinaryNotFound — keeping the policy out here
+    lets unit tests assert on (binary_path is None) without depending on $HOME.
+
+    Order rationale (Task #12 fix):
+    - macOS, prefer the real `.app` bundle paths from
+      `chrome_binary_candidates()` BEFORE `shutil.which` PATH lookup.
+      Reason: Homebrew leaves stale wrapper scripts on PATH that exit 126
+      (= Bug #2 symptom without the actual poll race).
+    - Linux + Windows, PATH is the canonical install signal; check it first
+      but still validate via `--version` so partial / broken installs fail
+      fast with a clean error.
+    """
+    if explicit:
+        p = Path(explicit).expanduser()
+        return p if p.exists() and _binary_is_runnable(p) else None
+
+    candidates: list[Path] = []
+    if platform.system() == "Darwin":
+        # macOS: real .app paths first, then PATH fallback.
+        candidates.extend(chrome_binary_candidates())
+        for name in ("google-chrome", "google-chrome-stable", "chromium",
+                     "chromium-browser", "microsoft-edge", "brave-browser"):
+            if (which := shutil.which(name)):
+                candidates.append(Path(which))
+    else:
+        # Linux + Windows: PATH first, then platform defaults.
+        for name in ("google-chrome", "google-chrome-stable", "chromium",
+                     "chromium-browser", "microsoft-edge", "brave-browser"):
+            if (which := shutil.which(name)):
+                candidates.append(Path(which))
+        candidates.extend(chrome_binary_candidates())
+
+    seen: set[Path] = set()
+    for p in candidates:
+        if p in seen:
+            continue
+        seen.add(p)
+        if not p.exists():
+            continue
+        if _binary_is_runnable(p):
+            return p
+    return None
+
+
+def runtime_dir() -> Path:
+    """Where pid / sock files live. Spec §5.5 step 7 + §6.7.
+
+    Mirrors browser-harness _ipc.py logic — XDG_RUNTIME_DIR on POSIX, %TEMP% on
+    Windows, /tmp fallback (gettempdir() returns long /var/folders on macOS which
+    is unsafe for AF_UNIX sun_path's 104-byte budget).
+    """
+    if (xdg := os.environ.get("XDG_RUNTIME_DIR")):
+        return Path(xdg)
+    if platform.system() == "Windows":
+        import tempfile
+        return Path(tempfile.gettempdir())
+    return Path("/tmp")
+
+
+def cache_dir() -> Path:
+    """Where persistent launch-chrome profiles live (§5.5 step 2)."""
+    if (xdg := os.environ.get("XDG_CACHE_HOME")):
+        return Path(xdg) / "browserwright-daemon"
+    return Path.home() / ".cache" / "browserwright-daemon"

browserwright/daemon/resolver.py

@@ -0,0 +1,72 @@
+"""Mode A URL resolver.
+
+Spec §5.1: walk the backend chain, return the first that yields a ResolveResult,
+otherwise aggregate per-backend failure reasons and raise Unavailable. When
+--backend is explicit, only that one backend runs (no fallback) — that's H10.
+
+Importantly: resolve() never opens a ws. It only does HTTP discovery and
+filesystem reads. The Skill opens the ws downstream. (§2.3 banner sync.)
+
+The `caller_context` ContextVar communicates to backends whether the resolve
+is happening on the Mode A short-conn path or inside the Mode B long-running
+daemon. Reserved for future backends that need to diverge per call site.
+Async-safe by virtue of contextvars.
+"""
+from __future__ import annotations
+
+import contextvars
+
+from .backends import all_backends, get_backend
+from .config import Config
+from .errors import Unavailable
+
+
+# Values: "mode_a" (default — Mode A CLI invocation) or "mode_b_serve"
+# (called from inside `browserwright-daemon serve`). Extend with care; backends
+# read this and may diverge behavior.
+caller_context: contextvars.ContextVar[str] = contextvars.ContextVar(
+    "bd_caller", default="mode_a"
+)
+
+
+async def resolve(cfg: Config):
+    """Return a ResolveResult for the first backend that succeeds.
+
+    cfg.backend pinning behavior:
+    - None  -> try every backend in registry order (env > rdp), then bail.
+              `extension` and `cloud` are deliberately excluded from the
+              auto-fallback (see _CHAIN_OPT_OUT below).
+    - str   -> try only that one
+    """
+    if cfg.backend is not None:
+        backend = get_backend(cfg.backend, cfg)
+        try:
+            return await backend.resolve(cfg.timeout)
+        except Unavailable:
+            raise  # explicit backend: surface attempts as-is
+    # Auto chain. Two backends are explicitly NOT in the auto-fallback:
+    #   `extension` — LOCAL_RELAY kind, requires daemon-serve to be the
+    #       ws server; `resolve()` is meaningless for Mode A.
+    #   `cloud`     — requires explicit endpoint + auth_kind config; we
+    #       don't want a stale `[backends.cloud]` row to silently surface
+    #       in `browserwright-daemon url` and confuse users who expected local
+    #       Chrome to be reachable.
+    # Both still work when `--backend cloud` / `--backend extension` is
+    # explicit (the branch above), they're just absent from auto-fallback.
+    attempts: dict[str, str] = {}
+    _CHAIN_OPT_OUT = {"extension", "cloud"}
+    for backend in all_backends(cfg):
+        if backend.name in _CHAIN_OPT_OUT:
+            continue
+        try:
+            return await backend.resolve(cfg.timeout)
+        except Unavailable as e:
+            # Preserve each backend's specific reason
+            if e.attempts:
+                attempts.update(e.attempts)
+            else:
+                attempts[backend.name] = str(e)
+    raise Unavailable(
+        "no backend could resolve a CDP WebSocket URL",
+        attempts=attempts,
+    )

browserwright/daemon/server/__init__.py

@@ -0,0 +1,6 @@
+"""Mode B (v0.2) — long-running daemon process.
+
+This package is loaded only by `browserwright-daemon serve` and friends. v0.1 Mode A
+subcommands never import from here, keeping the import graph + cold-start cost
+of the CLI minimal.
+"""

browserwright/daemon/server/daemon.py

@@ -0,0 +1,229 @@
+"""Single global daemon: multi-upstream, session-keyed routing.
+
+`docs/refactor-single-daemon.md` §"Key insight: the engine already exists":
+`Router` + `DaemonState` + `_UpstreamHolder` are already a complete
+single-upstream / multi-client engine — they only touch `self.state.*` and one
+`self._upstream_send`. So this module does NOT rewrite any routing/translation
+logic. It:
+
+  - bundles one `(state, router, holder)` triple per upstream into an
+    `UpstreamContext` (the per-upstream unit of `docs §Decomposition`), and
+  - adds the thin global `Daemon` that owns the shared (extension/real-browser)
+    context plus one lazily-created context per rdp session, and dispatches a
+    connecting client to the right context by reading the session's *immutable*
+    backend from the ledger.
+
+Cross-talk is structurally impossible: a client is bound to exactly one context
+for its whole connection, so each context's `Router._broadcast` only ever
+reaches that context's own clients (browser-level events stay scoped to the
+upstream that produced them).
+
+Phase boundaries (this file is Phase 2):
+  - The actual per-session rdp Chrome *launch* is Phase 3. Here we only create
+    the context object + its `(state, router, holder)` triple, wiring the
+    holder with a cfg whose rdp port comes from the session's workspace; the
+    holder's existing resolve/connect path is left untouched.
+"""
+from __future__ import annotations
+
+import dataclasses
+import itertools
+import logging
+
+from ... import session_registry
+from ..config import Config
+from .state import DaemonState
+from .proxy import Router
+
+logger = logging.getLogger(__name__)
+
+
+class UnknownSessionError(KeyError):
+    """Raised when an explicit session-bound client names no ledger session."""
+
+
+# ---- per-upstream context --------------------------------------------------
+
+
+class UpstreamContext:
+    """One live upstream: its `(state, router, holder)` triple.
+
+    Mirrors exactly what `run_serve` used to build for the single upstream —
+    just bundled so the `Daemon` can hold N of them. The holder is created by
+    `make_context` (it lives in listener.py to avoid an import cycle), so this
+    class is a passive bundle: it owns no construction logic, only the handle
+    each dispatch path needs (`router` to register a client, `state` to release
+    it, `holder` for lifecycle).
+    """
+
+    def __init__(self, *, backend: str, state: DaemonState, router: Router,
+                 holder: object, session_id: str | None = None):
+        self.backend = backend
+        self.state = state
+        self.router = router
+        # Typed as object to keep this module free of a listener import cycle
+        # (_UpstreamHolder lives in listener.py and imports nothing from here).
+        self.holder = holder
+        # None for the shared context; the rdp session id otherwise.
+        self.session_id = session_id
+
+
+# ---- the thin global daemon ------------------------------------------------
+
+
+class Daemon:
+    """Global daemon: one shared context + one context per rdp session.
+
+    `shared_context` is the always-on, real-browser upstream (backend ==
+    `cfg.backend`, default `extension`); for the extension backend its holder
+    owns the always-on `RelayServer` started eagerly in `run_serve`. Every
+    extension/env/cloud session routes here.
+
+    `contexts` holds one `UpstreamContext` per rdp session, created lazily on
+    first reference (Phase 3 makes the holder actually launch the per-session
+    Chrome — here it is only wired with a port-pinned cfg).
+    """
+
+    def __init__(self, *, cfg: Config, shared_context: UpstreamContext,
+                 make_context):
+        self.cfg = cfg
+        self.shared_context = shared_context
+        self.contexts: dict[str, UpstreamContext] = {}
+        # Phase B: per-session persistent executor subprocesses, keyed by
+        # session id (mirrors `contexts`). Lazily spawned by the
+        # `ensureExecutor` verb (PR1). Supervised by the daemon (PR2): idle/crash
+        # reap via the idle-watchdog, endSession kill in the endSession handler,
+        # kill-all on graceful shutdown, orphan-sweep on startup.
+        from .executor_registry import ExecutorRegistry
+        self.executors = ExecutorRegistry()
+        # Injected factory `(backend, cfg, session_id) -> UpstreamContext`.
+        # Lives in listener.py (it builds the _UpstreamHolder); injected to
+        # avoid an import cycle.
+        self._make_context = make_context
+        # Global, unique-across-contexts client id source — purely for
+        # log-friendliness so two contexts never print the same client #.
+        self._next_client_id: "itertools.count[int]" = itertools.count(1)
+        # Back-reference set on each context's router so RPC handlers
+        # (ensureSession / endSession) can reach the daemon to create/drop
+        # an rdp context.
+        shared_context.router.daemon = self  # type: ignore[attr-defined]
+
+    def all_contexts(self) -> list[UpstreamContext]:
+        """Shared context first, then every rdp context — used by shutdown /
+        idle / signal paths that must iterate every live upstream."""
+        return [self.shared_context, *self.contexts.values()]
+
+    def context_for(self, session_id: str | None, *, require_known: bool = False) -> UpstreamContext:
+        """Resolve the `UpstreamContext` that should serve `session_id`.
+
+        - None / empty session       → the shared (real-browser) context.
+        - ledger backend == "rdp"     → a per-session context (created lazily).
+        - extension/env/cloud         → the shared context.
+        - unknown explicit session    → raises when `require_known=True`.
+
+        The backend is the ledger's immutable `backend` field — never a client
+        param (docs §RPCs). Sessionless clients keep the historical shared
+        context; explicit session-bound clients can require the ledger record so
+        a typo or stale id never silently falls into the extension backend.
+        """
+        if not session_id:
+            return self.shared_context
+        record = session_registry.get(session_id)
+        if record is None:
+            if require_known:
+                raise UnknownSessionError(session_id)
+            return self.shared_context
+        backend = record.get("backend")
+        if backend == "rdp":
+            return self._ensure_rdp_context(session_id, record)
+        # extension / env / cloud → shared upstream.
+        return self.shared_context
+
+    def context_for_required(self, session_id: str) -> UpstreamContext:
+        """Resolve an explicitly session-bound context, failing closed."""
+        return self.context_for(session_id, require_known=True)
+
+    def _ensure_rdp_context(self, session_id: str, record: dict) -> UpstreamContext:
+        """Get or create the per-session rdp context.
+
+        Phase 2 scope: build the context object (its own state/router/holder)
+        and wire the holder with a cfg whose rdp port comes from the session's
+        `workspace["port"]` when present (else the existing resolve path is
+        left intact). The actual Chrome *launch* is Phase 3 — the holder's
+        lazy-open will then resolve+connect to that port.
+        """
+        ctx = self.contexts.get(session_id)
+        if ctx is not None:
+            return ctx
+        cfg = self._rdp_cfg_for(record)
+        ctx = self._make_context(backend="rdp", cfg=cfg, session_id=session_id)
+        # Preserve ownership semantics past the ledger→context boundary:
+        # create-owned sessions launch/kill daemon-owned Chrome; attach
+        # sessions only connect to the caller-provided port.
+        try:
+            ctx.holder.rdp_owns_browser = record.get("owner") == "create"  # type: ignore[attr-defined]
+        except Exception:
+            pass
+        # Same daemon back-reference the shared context got, so the rdp
+        # context's RPC handlers can drop themselves on endSession.
+        ctx.router.daemon = self  # type: ignore[attr-defined]
+        self.contexts[session_id] = ctx
+        logger.info("created rdp upstream context for session %s (port=%s)",
+                    session_id, cfg.backends.rdp.port)
+        return ctx
+
+    def _rdp_cfg_for(self, record: dict) -> Config:
+        """Derive a per-session rdp Config from the ledger record.
+
+        Pins `backend="rdp"` and, when the session's workspace carries a port,
+        `backends.rdp.port` so the holder's resolve path targets the right
+        per-session Chrome. Leaves the resolve path otherwise unchanged.
+        """
+        workspace = record.get("workspace")
+        port = None
+        if isinstance(workspace, dict):
+            raw = workspace.get("port")
+            if isinstance(raw, int):
+                port = raw
+        cfg = dataclasses.replace(self.cfg, backend="rdp")
+        if port is not None:
+            # `replace` shares the nested BackendsConfig instance; copy the rdp
+            # sub-config so per-session port pinning never mutates the shared
+            # cfg (or another session's context).
+            cfg.backends = dataclasses.replace(
+                cfg.backends,
+                rdp=dataclasses.replace(cfg.backends.rdp, port=port),
+            )
+        return cfg
+
+    def drop_rdp_context(self, session_id: str) -> UpstreamContext | None:
+        """Remove an rdp context from the registry. Returns the dropped
+        context, or None if absent.
+
+        This only de-registers the context (sync, callable from `_on_upstream_
+        closed` after teardown already ran). To also close the upstream + kill
+        the owned Chrome, use the async `teardown_rdp_context` instead — it runs
+        the holder's `trigger_close` (which SIGTERMs the Chrome) before
+        dropping."""
+        return self.contexts.pop(session_id, None)
+
+    async def teardown_rdp_context(self, session_id: str) -> bool:
+        """Phase 3 endSession teardown: close the per-session upstream, kill the
+        daemon-owned Chrome (the holder's `trigger_close` SIGTERMs `rdp_pid`),
+        and drop the context. Returns True if a context was found + torn down.
+
+        Idempotent-ish: a missing context returns False so the caller can still
+        answer the wire RPC with a uniform success shape."""
+        ctx = self.contexts.get(session_id)
+        if ctx is None:
+            return False
+        try:
+            # "skill_disconnect" is the closest honest CloseReason — the client
+            # explicitly asked to end this session (vs chrome_exit / idle).
+            await ctx.holder.trigger_close("skill_disconnect")  # type: ignore[attr-defined]
+        except Exception as e:
+            logger.warning("teardown rdp context %s close failed: %r",
+                           session_id, e)
+        self.contexts.pop(session_id, None)
+        logger.info("tore down rdp context for session %s", session_id)
+        return True