Skip to content

https://arxiv.org/abs/2606.28344. The end of web parsing. The beginning of scalable pixel-native search. link: https://pixelrag.ai/

10.7 KB
Raw Blame
"""Chrome binary management for pixelshot.

Downloads and manages a patched headless Chrome binary with rawFilePath
support. Similar to `playwright install chromium`.

Usage:
    pixelshot install-chrome     # download patched headless_shell
    pixelshot which-chrome       # print path to active binary

Programmatic:
    from pixelrag_render.chrome import find_chrome, install_chrome
    path = find_chrome()             # auto-detect best available
    path = install_chrome()          # download if needed
"""

import json
import logging
import os
import platform
import re
import subprocess
import sys
import tarfile
import tempfile
import urllib.request
from pathlib import Path

INSTALL_DIR = Path.home() / ".cache" / "pixelrag" / "chrome"
VERSION_FILE = "version.json"
logger = logging.getLogger(__name__)

_SANDBOX_WARNING_EMITTED = False

# Update these when releasing a new build
CHROME_VERSION = "150.0.7844.0"
RELEASE_URL_TEMPLATE = (
    "https://github.com/StarTrail-org/PixelRAG/releases/download/"
    "chrome-{version}/headless_shell-linux-x64.tar.zst"
)


def sandbox_args() -> list[str]:
    """Return Chrome sandbox arguments, adding ``--no-sandbox`` only when needed."""

    global _SANDBOX_WARNING_EMITTED

    args: list[str] = []
    force_no_sandbox = os.environ.get("PIXELSHOT_NO_SANDBOX") == "1"
    running_as_root = (
        platform.system() == "Linux" and hasattr(os, "getuid") and os.getuid() == 0
    )

    if force_no_sandbox or running_as_root:
        args.append("--no-sandbox")
        if running_as_root and not _SANDBOX_WARNING_EMITTED:
            logger.warning(
                "Running Chrome as root on Linux; adding --no-sandbox to avoid crashes. "
                "Set PIXELSHOT_NO_SANDBOX=1 to force this behavior."
            )
            _SANDBOX_WARNING_EMITTED = True

    return args


def _playwright_revision(path: str) -> int:
    """Integer Playwright Chromium revision embedded in ``path``.

    Playwright caches browsers under ``chromium-<revision>`` with a plain
    monotonically-increasing integer revision. Paths without a recognizable
    revision sort last (``-1``) rather than raising.
    """
    m = re.search(r"chromium-(\d+)", path)
    return int(m.group(1)) if m else -1


def _candidate_chrome_paths(system: str | None = None) -> list[str]:
    """Ordered Chrome binary candidates for the given OS (default: this OS).

    Order: CHROME_PATH env → pixelrag-installed patched headless_shell →
    Playwright's Chromium (newest version first) → system Chrome/Chromium.
    Playwright and system locations are OS-specific so the skill works on
    macOS and Windows, not only Linux.
    """
    import glob

    system = system or platform.system()
    home = Path.home()
    paths: list[str] = []

    env = os.environ.get("CHROME_PATH", "")
    if env:
        paths.append(env)
    # Bundled patched headless_shell (only installed on linux-x64, harmless elsewhere).
    paths.append(str(INSTALL_DIR / "headless_shell"))

    def add_playwright(cache_dir: Path, rel_glob: str) -> None:
        # Newest chromium-NNNN first. Sort by integer revision, not lexically:
        # a string sort ranks "chromium-999" above "chromium-1187" once the
        # revision crosses the 3→4 digit boundary, picking an older browser.
        matches = glob.glob(str(cache_dir / rel_glob))
        paths.extend(sorted(matches, key=_playwright_revision, reverse=True))

    if system == "Darwin":
        add_playwright(
            home / "Library" / "Caches" / "ms-playwright",
            "chromium-*/chrome-mac/Chromium.app/Contents/MacOS/Chromium",
        )
        paths += [
            "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
            "/Applications/Chromium.app/Contents/MacOS/Chromium",
        ]
    elif system == "Windows":
        localappdata = os.environ.get("LOCALAPPDATA", "")
        if localappdata:
            add_playwright(
                Path(localappdata) / "ms-playwright",
                "chromium-*/chrome-win*/chrome.exe",
            )
        for base in (
            os.environ.get("PROGRAMFILES", r"C:\Program Files"),
            os.environ.get("PROGRAMFILES(X86)", r"C:\Program Files (x86)"),
            localappdata,
        ):
            if base:
                paths.append(str(Path(base) / "Google/Chrome/Application/chrome.exe"))
    else:  # Linux / other
        add_playwright(
            home / ".cache" / "ms-playwright", "chromium-*/chrome-linux*/chrome"
        )
        paths += [
            "/usr/bin/google-chrome",
            "/usr/bin/google-chrome-stable",
            "/usr/bin/chromium-browser",
            "/usr/bin/chromium",
        ]
    return paths


def find_chrome(auto_install: bool = True) -> str:
    """Find the best available Chrome binary. Auto-installs on linux-x64 if none found.

    Search order (per OS): CHROME_PATH → pixelrag-installed headless_shell →
    Playwright's Chromium → system Chrome/Chromium → (linux-x64) auto-install.

    Returns:
        Path to Chrome binary.

    Raises:
        FileNotFoundError: No Chrome binary found (and auto-install unavailable).
    """
    for path in _candidate_chrome_paths():
        if path and os.path.isfile(path) and os.access(path, os.X_OK):
            return path

    # The prebuilt (turbo) headless_shell is published only for linux-x64.
    if auto_install and platform.system() == "Linux" and platform.machine() == "x86_64":
        print("No Chrome found. Installing headless_shell...", flush=True)
        return str(install_chrome())

    raise FileNotFoundError(
        "No Chrome binary found. Install Google Chrome or Chromium, or set CHROME_PATH "
        "to its executable. (The bundled headless_shell auto-installs on linux-x64 only.)"
    )


def get_installed_version() -> str | None:
    """Return version string of installed headless_shell, or None."""
    version_path = INSTALL_DIR / VERSION_FILE
    if version_path.exists():
        try:
            data = json.loads(version_path.read_text())
            return data.get("version")
        except Exception:
            pass
    return None


def is_turbo_capable(chrome_path: str) -> bool:
    """Whether ``chrome_path`` is the pixelrag-installed patched headless_shell,
    which supports the turbo capture extensions (rawFilePath/directClip/skipRedraw).

    Deterministic by provenance — the patched binary lives only at the install path
    (with its version.json marker). No runtime probe, so a stock Chrome is never
    mistaken for a turbo-capable one (and a turbo run is never tried on a binary
    that would hang on the unknown CDP params).
    """
    try:
        installed = (INSTALL_DIR / "headless_shell").resolve()
        return (
            Path(chrome_path).resolve() == installed
            and (INSTALL_DIR / VERSION_FILE).exists()
        )
    except Exception:
        return False


def install_chrome(version: str | None = None, force: bool = False) -> Path:
    """Download and install the patched headless_shell binary.

    Args:
        version: Chrome version to install. Defaults to CHROME_VERSION.
        force: Re-download even if already installed.

    Returns:
        Path to the installed headless_shell binary.
    """
    version = version or CHROME_VERSION
    binary_path = INSTALL_DIR / "headless_shell"

    if binary_path.exists() and not force:
        installed = get_installed_version()
        if installed == version:
            print(f"Already installed: headless_shell {version}")
            return binary_path

    if platform.system() != "Linux" or platform.machine() != "x86_64":
        raise RuntimeError(
            f"Pre-built headless_shell only available for linux-x64, "
            f"got {platform.system()}-{platform.machine()}"
        )

    url = RELEASE_URL_TEMPLATE.format(version=version)
    print(f"Downloading headless_shell {version}...")
    print(f"  URL: {url}")

    INSTALL_DIR.mkdir(parents=True, exist_ok=True)

    with tempfile.NamedTemporaryFile(suffix=".tar.zst", delete=False) as tmp:
        tmp_path = tmp.name

    try:
        urllib.request.urlretrieve(url, tmp_path, _progress_hook)
        print()

        # Decompress: zstd → tar → extract
        print("Extracting...")
        # Try zstd decompression
        decomp_path = tmp_path + ".tar"
        try:
            subprocess.run(
                ["zstd", "-d", tmp_path, "-o", decomp_path],
                check=True,
                capture_output=True,
            )
        except (FileNotFoundError, subprocess.CalledProcessError):
            # Fallback: try python zstandard
            try:
                import zstandard

                with open(tmp_path, "rb") as f_in, open(decomp_path, "wb") as f_out:
                    dctx = zstandard.ZstdDecompressor()
                    dctx.copy_stream(f_in, f_out)
            except ImportError:
                raise RuntimeError(
                    "zstd not found. Install with: apt install zstd (or pip install zstandard)"
                )

        with tarfile.open(decomp_path) as tar:
            tar.extractall(INSTALL_DIR)
        os.unlink(decomp_path)

        # Set executable permission
        binary_path.chmod(0o755)

        # Write version file
        version_data = {"version": version, "binary": str(binary_path)}
        (INSTALL_DIR / VERSION_FILE).write_text(json.dumps(version_data))

        print(
            f"Installed: {binary_path} ({binary_path.stat().st_size / 1024 / 1024:.0f}MB)"
        )
        return binary_path

    finally:
        if os.path.exists(tmp_path):
            os.unlink(tmp_path)


def _progress_hook(block_num, block_size, total_size):
    downloaded = block_num * block_size
    if total_size > 0:
        pct = min(100, downloaded * 100 // total_size)
        mb = downloaded / 1024 / 1024
        total_mb = total_size / 1024 / 1024
        print(f"\r  {mb:.0f}/{total_mb:.0f} MB ({pct}%)", end="", flush=True)


def main():
    """CLI entry point for chrome management."""
    import argparse

    parser = argparse.ArgumentParser(description="Manage Chrome for pixelshot")
    sub = parser.add_subparsers(dest="command")

    sub.add_parser("install", help="Download patched headless_shell")
    sub.add_parser("which", help="Print path to active Chrome binary")
    sub.add_parser("version", help="Print installed version")

    args = parser.parse_args()

    if args.command == "install":
        install_chrome()
    elif args.command == "which":
        try:
            print(find_chrome())
        except FileNotFoundError as e:
            print(str(e), file=sys.stderr)
            sys.exit(1)
    elif args.command == "version":
        v = get_installed_version()
        if v:
            print(v)
        else:
            print("Not installed", file=sys.stderr)
            sys.exit(1)
    else:
        parser.print_help()


if __name__ == "__main__":
    main()