grewbrowser 0.1.0__py3-none-any.whl

grewbrowser/__init__.py

@@ -0,0 +1,101 @@
+"""grewbrowser — a stealth Playwright launcher for Chromium."""
+
+from __future__ import annotations
+
+from .behavior.config import HumanConfig, resolve_config
+from .behavior.human import humanize_context, humanize_context_async, install
+from .core.binary_manager import ChromiumBinary, binary_info, resolve_binary
+from .core.download import (
+    InstalledBuild,
+    ensure_chromium,
+    installed_builds,
+    cache_dir as browser_cache_dir,
+)
+from .diagnostics import Check, evaluate_checks, observe, run_checks
+from .core.flags import IGNORE_DEFAULT_ARGS, build_args, build_stealth_args
+from .core.profile import BrowserProfile, ScreenProfile, random_seed
+from .exceptions import (
+    ActionabilityError,
+    BinaryNotFoundError,
+    FingerprintError,
+    GeoIPError,
+    GrewBrowserError,
+    IsolatedWorldError,
+    LaunchError,
+    PoolClosedError,
+    ProxyConfigError,
+    RelayError,
+)
+from .fingerprint.scripts import build_fingerprint_script
+from .launcher import (
+    AsyncBrowserSession,
+    BrowserSession,
+    launch,
+    launch_async,
+    launch_persistent_context,
+    launch_persistent_context_async,
+)
+from .network.geoip import GeoIdentity, resolve_exit_ip, resolve_geo
+from .network.proxy import ProxyConfig, parse_proxy
+from .network.relay import AuthRelay, RelayHandle, start_relay, start_relay_async
+from .session.pool import BrowserPool, SyncBrowserPool
+from .session.teardown import TeardownGuard, global_guard, guard
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "launch",
+    "launch_async",
+    "launch_persistent_context",
+    "launch_persistent_context_async",
+    "BrowserSession",
+    "AsyncBrowserSession",
+    "BrowserProfile",
+    "ScreenProfile",
+    "random_seed",
+    "build_stealth_args",
+    "build_args",
+    "IGNORE_DEFAULT_ARGS",
+    "build_fingerprint_script",
+    "ChromiumBinary",
+    "resolve_binary",
+    "binary_info",
+    "ensure_chromium",
+    "installed_builds",
+    "InstalledBuild",
+    "browser_cache_dir",
+    "run_checks",
+    "evaluate_checks",
+    "observe",
+    "Check",
+    "HumanConfig",
+    "resolve_config",
+    "humanize_context",
+    "humanize_context_async",
+    "install",
+    "ProxyConfig",
+    "parse_proxy",
+    "GeoIdentity",
+    "resolve_geo",
+    "resolve_exit_ip",
+    "AuthRelay",
+    "RelayHandle",
+    "start_relay",
+    "start_relay_async",
+    "BrowserPool",
+    "SyncBrowserPool",
+    "TeardownGuard",
+    "guard",
+    "global_guard",
+    "GrewBrowserError",
+    "BinaryNotFoundError",
+    "LaunchError",
+    "ProxyConfigError",
+    "RelayError",
+    "GeoIPError",
+    "FingerprintError",
+    "IsolatedWorldError",
+    "ActionabilityError",
+    "PoolClosedError",
+    "__version__",
+]

grewbrowser/__main__.py

@@ -0,0 +1,248 @@
+"""Command line interface: ``python -m grewbrowser <command>``."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+import sys
+from typing import Any
+
+from .core.binary_manager import binary_info, clear_cache
+from .core.download import (
+    cache_dir,
+    clear_downloads,
+    ensure_chromium,
+    installed_builds,
+    platform_tag,
+    remove_build,
+    verify_build,
+)
+from .exceptions import GrewBrowserError
+
+
+def _install(args: argparse.Namespace) -> int:
+    """Download grewbrowser's own browser build."""
+    build = ensure_chromium(args.version, source=args.source, force=args.force)
+    print(f"installed {build.version} ({build.source})")
+    print(f"  executable: {build.executable}")
+    print(f"  sha256    : {build.archive_sha256}")
+    print("\nIt is now the default for channel='auto', so launch() needs no arguments.")
+    return 0
+
+
+def _list(args: argparse.Namespace) -> int:
+    """List cached builds."""
+    builds = installed_builds()
+    print(f"cache: {cache_dir()}  (platform {platform_tag()})")
+    if not builds:
+        print("  no builds yet -- run 'python -m grewbrowser install'")
+        return 0
+    for build in builds:
+        state = "ok" if verify_build(build) else "BROKEN"
+        print(f"  {build.version:<20} {state:<7} {build.source:<20} {build.executable}")
+    return 0
+
+
+def _info(args: argparse.Namespace) -> int:
+    """Report which browser a launch would resolve to."""
+    clear_cache()
+    for key, value in binary_info(channel=args.channel).items():
+        print(f"{key:9} {value}")
+    return 0
+
+
+def _open(args: argparse.Namespace) -> int:
+    """Open a URL in a real window, to eyeball the result."""
+    from . import launch
+
+    with launch(headless=args.headless, channel=args.channel, geoip=False) as session:
+        print(f"browser : {session.binary.channel} {session.binary.version}")
+        print(
+            f"identity: seed={session.seed} {session.profile.os_family} "
+            f"{session.profile.locale} {session.profile.timezone_id}"
+        )
+        page = session.new_page()
+        page.goto(args.url, wait_until="domcontentloaded")
+        print(f"title   : {page.title()}")
+        if not args.headless:
+            input("Press Enter to close...")
+    return 0
+
+
+def _check(args: argparse.Namespace) -> int:
+    """Run the self-checks and compare headless against headful."""
+    from .diagnostics import run_checks
+
+    modes = {"both": (True, False), "headless": (True,), "headful": (False,)}[args.mode]
+    results: dict[bool, list] = {}
+    for headless in modes:
+        label = "headless" if headless else "headful"
+        print(f"running {label} ...", flush=True)
+        profile, checks = run_checks(
+            headless=headless,
+            url=args.url,
+            channel=args.channel,
+            seed=args.seed,
+            include_behaviour=not args.fast,
+        )
+        results[headless] = checks
+        print(
+            f"  identity: seed={profile.seed} {profile.os_family} "
+            f"Chrome/{profile.chrome_major} {profile.screen.width}x{profile.screen.height}\n"
+        )
+
+    width = max(len(check.name) for checks in results.values() for check in checks)
+    header = f"{'check'.ljust(width)}  " + "  ".join(
+        ("headless" if headless else "headful ") for headless in modes
+    )
+    print(header)
+    print("-" * len(header))
+
+    core_failures = 0
+    env_failures = 0
+    differences = 0
+    annotations: list[str] = []
+    by_name: dict[str, dict[bool, Any]] = {}
+    order: list[str] = []
+    for headless, checks in results.items():
+        for check in checks:
+            if check.name not in by_name:
+                order.append(check.name)
+            by_name.setdefault(check.name, {})[headless] = check
+
+    def render(tier: str) -> None:
+        nonlocal core_failures, env_failures, differences
+        printed = False
+        for name in order:
+            per_mode = by_name[name]
+            sample = next(iter(per_mode.values()))
+            if sample.tier != tier:
+                continue
+            if not printed:
+                heading = "coherence" if tier == "core" else "this machine"
+                print(f"\n[{heading}]")
+                printed = True
+            cells = []
+            verdicts = set()
+            for headless in modes:
+                check = per_mode.get(headless)
+                if check is None:
+                    cells.append("   --   ")
+                    continue
+                verdicts.add(check.ok)
+                if not check.ok:
+                    if tier == "core":
+                        core_failures += 1
+                    else:
+                        env_failures += 1
+                cells.append(
+                    "  pass  " if check.ok else ("  FAIL  " if tier == "core" else "  n/a   ")
+                )
+            differing = len(verdicts) > 1
+            differences += 1 if differing else 0
+            marker = "  <- differs" if differing else ""
+            print(f"{name.ljust(width)}  " + "  ".join(cells) + marker)
+            if not all(verdicts):
+                for headless in modes:
+                    check = per_mode.get(headless)
+                    if check is not None and not check.ok:
+                        label = "headless" if headless else "headful"
+                        print(f"{' '.ljust(width)}    {label}: {check.detail}")
+                        if tier == "core":
+                            annotations.append(f"{name} [{label}]: {check.detail}")
+
+    render("core")
+    render("environment")
+
+    total = sum(len(checks) for checks in results.values())
+    passed = total - core_failures - env_failures
+    print(f"\n{passed}/{total} checks passed")
+    if env_failures:
+        print(
+            f"{env_failures} depend on the host, not on grewbrowser "
+            "(no GPU, missing fonts, no speech voices on a CI box)"
+        )
+    if len(modes) > 1:
+        print(
+            f"{differences} check(s) differ between headless and headful"
+            if differences
+            else "headless and headful agree on every check"
+        )
+
+    if annotations and os.environ.get("GITHUB_ACTIONS") == "true":
+        for line in annotations:
+            print(f"::error title=grewbrowser check::{line}")
+
+    return 1 if core_failures else 0
+
+
+def _clean(args: argparse.Namespace) -> int:
+    """Delete cached builds."""
+    if args.version:
+        removed = remove_build(args.version)
+        print(f"removed {args.version}" if removed else f"no cached build {args.version}")
+        return 0 if removed else 1
+    count = clear_downloads()
+    print(f"removed {count} build(s) from {cache_dir()}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Parse arguments and run the chosen command."""
+    parser = argparse.ArgumentParser(prog="python -m grewbrowser")
+    parser.add_argument("-q", "--quiet", action="store_true", help="suppress progress logs")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    install = commands.add_parser("install", help="download grewbrowser's own Chromium")
+    install.add_argument("--version", default=None, help="exact version or snapshot revision")
+    install.add_argument(
+        "--source",
+        default="chrome-for-testing",
+        choices=("chrome-for-testing", "chromium-snapshots"),
+    )
+    install.add_argument("--force", action="store_true", help="re-download even if cached")
+    install.set_defaults(handler=_install)
+
+    listing = commands.add_parser("list", help="list cached builds")
+    listing.set_defaults(handler=_list)
+
+    info = commands.add_parser("info", help="show which browser a launch would use")
+    info.add_argument("--channel", default="auto")
+    info.set_defaults(handler=_info)
+
+    opener = commands.add_parser("open", help="open a URL in a real window")
+    opener.add_argument("url", nargs="?", default="https://example.com")
+    opener.add_argument("--channel", default="auto")
+    opener.add_argument("--headless", action="store_true")
+    opener.set_defaults(handler=_open)
+
+    check = commands.add_parser("check", help="self-check, headless vs headful")
+    check.add_argument("--mode", default="both", choices=("both", "headless", "headful"))
+    check.add_argument("--url", default=None, help="run the probes on this page")
+    check.add_argument("--channel", default="auto")
+    check.add_argument("--seed", type=int, default=None, help="pin the identity")
+    check.add_argument("--fast", action="store_true", help="skip the input-behaviour probes")
+    check.set_defaults(handler=_check)
+
+    clean = commands.add_parser("clean", help="delete cached builds")
+    clean.add_argument("--version", default=None, help="delete only this version")
+    clean.set_defaults(handler=_clean)
+
+    args = parser.parse_args(argv)
+    logging.basicConfig(
+        level=logging.WARNING if args.quiet else logging.INFO,
+        format="%(message)s",
+    )
+    try:
+        return int(args.handler(args))
+    except GrewBrowserError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        print("\ninterrupted", file=sys.stderr)
+        return 130
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

grewbrowser/_driver.py

@@ -0,0 +1,61 @@
+"""Shared Playwright drivers, reference counted per thread."""
+
+from __future__ import annotations
+
+import logging
+import threading
+from dataclasses import dataclass
+from typing import Any
+
+__all__ = ["acquire_sync", "release_sync", "active_sync_drivers"]
+
+logger = logging.getLogger("grewbrowser")
+
+_local = threading.local()
+_counter_lock = threading.Lock()
+_live = 0
+
+
+@dataclass
+class _Driver:
+    playwright: Any
+    refcount: int = 0
+
+
+def acquire_sync() -> Any:
+    """Return this thread's Playwright driver, starting it on first use."""
+    global _live
+    driver = getattr(_local, "driver", None)
+    if driver is None:
+        from playwright.sync_api import sync_playwright
+
+        driver = _Driver(sync_playwright().start())
+        _local.driver = driver
+        with _counter_lock:
+            _live += 1
+    driver.refcount += 1
+    return driver.playwright
+
+
+def release_sync() -> None:
+    """Give back a driver reference, stopping it when the last one goes."""
+    global _live
+    driver = getattr(_local, "driver", None)
+    if driver is None:
+        return
+    driver.refcount -= 1
+    if driver.refcount > 0:
+        return
+    _local.driver = None
+    with _counter_lock:
+        _live -= 1
+    try:
+        driver.playwright.stop()
+    except Exception as exc:
+        logger.debug("Stopping the Playwright driver failed: %s", exc)
+
+
+def active_sync_drivers() -> int:
+    """How many threads currently hold a started driver."""
+    with _counter_lock:
+        return _live

grewbrowser/behavior/__init__.py

@@ -0,0 +1,43 @@
+"""Human-like interaction primitives that replace Playwright's own."""
+
+from __future__ import annotations
+
+from .config import HumanConfig, Preset, Range, resolve_config
+from .curves import MoveStep, Point, WheelStep, plan_move, plan_stroke, plan_wheel
+from .human import (
+    AsyncHumanEngine,
+    HumanEngine,
+    engine_for,
+    humanize_context,
+    humanize_context_async,
+    humanize_page,
+    humanize_page_async,
+    install,
+)
+from .keyboard import KeyEvent, plan_typing
+from .world import AsyncIsolatedWorld, IsolatedWorld
+
+__all__ = [
+    "HumanConfig",
+    "Preset",
+    "Range",
+    "resolve_config",
+    "Point",
+    "MoveStep",
+    "WheelStep",
+    "plan_move",
+    "plan_stroke",
+    "plan_wheel",
+    "KeyEvent",
+    "plan_typing",
+    "HumanEngine",
+    "AsyncHumanEngine",
+    "humanize_page",
+    "humanize_page_async",
+    "humanize_context",
+    "humanize_context_async",
+    "engine_for",
+    "install",
+    "IsolatedWorld",
+    "AsyncIsolatedWorld",
+]

grewbrowser/behavior/config.py

@@ -0,0 +1,197 @@
+"""Tunable parameters for the human-behaviour layer."""
+
+from __future__ import annotations
+
+import math
+import random
+import time
+from dataclasses import dataclass, fields, replace
+from typing import Final, Literal
+
+__all__ = [
+    "Range",
+    "HumanConfig",
+    "Preset",
+    "resolve_config",
+    "rand",
+    "rand_range",
+    "rand_int_range",
+    "rand_lognormal",
+    "sleep_ms",
+]
+
+Range = tuple[float, float]
+
+Preset = Literal["default", "careful", "brisk"]
+
+FRAME_MS: Final[float] = 1000.0 / 60.0
+
+
+@dataclass(frozen=True, slots=True)
+class HumanConfig:
+    """Every timing knob of the behaviour layer.
+    All durations are milliseconds. ``Range`` values are sampled log-normally
+    between roughly the 5th and 95th percentile, so the occasional long pause
+    appears without the mean drifting.
+    """
+
+    typing_delay: float = 150.0
+    typing_delay_spread: float = 70.0
+    key_hold: Range = (60.0, 175.0)
+    word_pause_chance: float = 0.15
+    word_pause: Range = (300.0, 1000.0)
+    shift_down_delay: Range = (60.0, 220.0)
+    shift_up_delay: Range = (-60.0, 30.0)
+    mistype_chance: float = 0.04
+    mistype_notice_delay: Range = (100.0, 300.0)
+    mistype_correct_delay: Range = (50.0, 150.0)
+    field_switch_delay: Range = (800.0, 1500.0)
+
+    move_time_base: float = 160.0
+    move_time_per_bit: float = 75.0
+    move_time_spread: float = 0.3
+    move_min_steps: int = 2
+    move_max_steps: int = 200
+    wobble_max: float = 1.5
+    overshoot_chance: float = 0.35
+    overshoot_px: Range = (2.0, 6.0)
+
+    aim_delay_input: Range = (60.0, 140.0)
+    aim_delay_button: Range = (80.0, 200.0)
+    hold_input: Range = (40.0, 100.0)
+    hold_button: Range = (60.0, 150.0)
+    input_x_fraction: Range = (0.05, 0.30)
+
+    notch_px: float = 0.0
+    notch_pause_fast: Range = (30.0, 80.0)
+    notch_pause_slow: Range = (80.0, 200.0)
+    accel_notches: Range = (2, 3)
+    decel_notches: Range = (2, 3)
+    scroll_overshoot_chance: float = 0.10
+    scroll_overshoot_px: Range = (50.0, 150.0)
+    scroll_settle_delay: Range = (300.0, 600.0)
+
+    idle_drift_px: float = 3.0
+    idle_pause: Range = (300.0, 1000.0)
+    idle_between_actions: bool = False
+    idle_between_duration: Range = (0.3, 0.8)
+
+    action_timeout: float = 30_000.0
+    poll_interval: float = 50.0
+    stability_epsilon: float = 1.0
+
+    initial_cursor_x: Range = (400.0, 700.0)
+    initial_cursor_y: Range = (45.0, 60.0)
+
+    def merged(self, **overrides: object) -> HumanConfig:
+        """Return a copy with *overrides* applied.
+        Raises:
+            TypeError: If an override does not name a configuration field.
+        """
+        known = {f.name for f in fields(self)}
+        unknown = set(overrides) - known
+        if unknown:
+            raise TypeError(f"Unknown HumanConfig field(s): {', '.join(sorted(unknown))}")
+        return replace(self, **overrides)
+
+
+_CAREFUL = HumanConfig(
+    typing_delay=210.0,
+    typing_delay_spread=95.0,
+    word_pause_chance=0.25,
+    word_pause=(400.0, 1600.0),
+    mistype_chance=0.06,
+    move_time_base=220.0,
+    move_time_per_bit=95.0,
+    overshoot_chance=0.45,
+    aim_delay_input=(90.0, 220.0),
+    aim_delay_button=(120.0, 300.0),
+    idle_between_actions=True,
+)
+
+_BRISK = HumanConfig(
+    typing_delay=105.0,
+    typing_delay_spread=45.0,
+    word_pause_chance=0.08,
+    mistype_chance=0.02,
+    move_time_base=120.0,
+    move_time_per_bit=55.0,
+    overshoot_chance=0.25,
+)
+
+_PRESETS: Final[dict[str, HumanConfig]] = {
+    "default": HumanConfig(),
+    "careful": _CAREFUL,
+    "brisk": _BRISK,
+}
+
+
+def resolve_config(
+    humanize: bool | str | HumanConfig | dict[str, object] | None,
+) -> HumanConfig | None:
+    """Normalise the ``humanize=`` argument of the launcher.
+    Args:
+        humanize: ``True``/``None`` for the default preset, ``False`` to
+            disable the layer, a preset name, a ready
+            :class:`HumanConfig`, or a mapping of field overrides applied on
+            top of the default preset.
+    Returns:
+        The resolved configuration, or ``None`` when the layer is disabled.
+    Raises:
+        ValueError: If a preset name is unknown.
+        TypeError: If the value is of an unsupported type, or a mapping names
+            an unknown field.
+    """
+    if humanize is False:
+        return None
+    if humanize is None or humanize is True:
+        return _PRESETS["default"]
+    if isinstance(humanize, HumanConfig):
+        return humanize
+    if isinstance(humanize, str):
+        try:
+            return _PRESETS[humanize]
+        except KeyError:
+            raise ValueError(
+                f"Unknown humanize preset {humanize!r}; "
+                f"choose from {', '.join(sorted(_PRESETS))}"
+            ) from None
+    if isinstance(humanize, dict):
+        return _PRESETS["default"].merged(**humanize)
+    raise TypeError(f"Unsupported humanize value of type {type(humanize).__name__}")
+
+
+def rand(low: float, high: float) -> float:
+    """Uniform sample in ``[low, high]``."""
+    return random.uniform(low, high)
+
+
+def rand_range(span: Range) -> float:
+    """Log-normal sample whose 5th/95th percentiles are roughly *span*.
+    A uniform sample over a human delay range produces a flat distribution no
+    person generates; the log-normal shape gives the characteristic long tail.
+    Ranges that cross zero (such as ``shift_up_delay``) fall back to uniform.
+    """
+    low, high = span
+    if low <= 0 or high <= low:
+        return random.uniform(low, high)
+    median = math.sqrt(low * high)
+    sigma = math.log(high / low) / 3.29
+    return min(high * 1.5, median * math.exp(random.gauss(0.0, sigma)))
+
+
+def rand_int_range(span: Range) -> int:
+    """Integer sample in ``[low, high]``, inclusive."""
+    low, high = span
+    return random.randint(int(low), int(high))
+
+
+def rand_lognormal(median: float, sigma: float) -> float:
+    """Log-normal sample around *median*."""
+    return median * math.exp(random.gauss(0.0, sigma))
+
+
+def sleep_ms(milliseconds: float) -> None:
+    """Block for *milliseconds*, ignoring non-positive values."""
+    if milliseconds > 0:
+        time.sleep(milliseconds / 1000.0)