funbrowser 0.1.0__py3-none-any.whl

funbrowser/__init__.py

@@ -0,0 +1,120 @@
+"""FunBrowser — undetect browser with built-in captcha solving via funsolver.com."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+
+from . import humanly as humanly_mod
+from . import tls as tls_mod
+from ._errors import (
+    BrowserLaunchError,
+    BrowserNotFoundError,
+    CDPConnectionClosed,
+    CDPError,
+    FunBrowserError,
+    TargetClosed,
+)
+from .browser import Browser
+from .context import BrowserContext
+from .context_pool import ContextPool
+from .element import ElementHandle
+from .fingerprint import Fingerprint, presets
+from .geo import GeoInfo, lookup_proxy_geo
+from .humanly import HumanBehavior
+from .pool import BrowserPool
+
+# Panel is optional — only available when aiohttp is installed.
+try:
+    from .panel import Panel
+except ImportError:
+    Panel = None  # type: ignore[assignment, misc]
+from .profile import Profile
+from .proxy import Proxy, ProxyParseError
+from .proxy import parse as parse_proxy
+from .solver import FunSolverClient, FunSolverError
+from .tab import Tab
+
+humanly = humanly_mod
+tls = tls_mod
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Browser",
+    "BrowserContext",
+    "BrowserLaunchError",
+    "BrowserNotFoundError",
+    "BrowserPool",
+    "CDPConnectionClosed",
+    "CDPError",
+    "ContextPool",
+    "ElementHandle",
+    "Fingerprint",
+    "FunBrowserError",
+    "FunSolverClient",
+    "FunSolverError",
+    "GeoInfo",
+    "HumanBehavior",
+    "Panel",
+    "Profile",
+    "Proxy",
+    "ProxyParseError",
+    "Tab",
+    "TargetClosed",
+    "__version__",
+    "humanly",
+    "lookup_proxy_geo",
+    "parse_proxy",
+    "presets",
+    "start",
+    "tls",
+]
+
+
+async def start(
+    *,
+    executable: str | Path | None = None,
+    user_data_dir: str | Path | None = None,
+    headless: bool = False,
+    stealth: bool = True,
+    fingerprint: Fingerprint | None = None,
+    proxy: str | Proxy | None = None,
+    geo_autoconfigure: bool = True,
+    humanly: bool | HumanBehavior = False,
+    mini: bool = False,
+    api_key: str | None = None,
+    auto_solve: bool = True,
+    solver_base_url: str | None = None,
+    args: Sequence[str] = (),
+) -> Browser:
+    """Launch Chrome and return a connected Browser.
+
+    ``proxy`` accepts any string format common in proxy lists — see
+    :mod:`funbrowser.proxy` for the full list — or a pre-built
+    :class:`Proxy`. HTTP/HTTPS auth is handled automatically via CDP;
+    SOCKS auth is not (front with a local HTTP proxy).
+
+    Pass ``fingerprint=`` (a :class:`Fingerprint` or a value from
+    :mod:`funbrowser.presets`) to override the JS-visible identity values
+    (UA, platform, languages, CPU cores, screen, WebGL strings, etc.).
+
+    If ``api_key`` is provided and ``auto_solve`` is true, captchas
+    detected on each tab will be sent to funsolver.com and solved
+    automatically.
+    """
+    return await Browser.start(
+        executable=executable,
+        user_data_dir=user_data_dir,
+        headless=headless,
+        stealth=stealth,
+        fingerprint=fingerprint,
+        proxy=proxy,
+        geo_autoconfigure=geo_autoconfigure,
+        humanly=humanly,
+        mini=mini,
+        api_key=api_key,
+        auto_solve=auto_solve,
+        solver_base_url=solver_base_url,
+        args=args,
+    )

funbrowser/_cdp.py

@@ -0,0 +1,181 @@
+"""Raw CDP transport over WebSocket.
+
+Spec: https://chromedevtools.github.io/devtools-protocol/
+
+The connection multiplexes:
+- request/response by sequential id (per the CDP spec)
+- event broadcasts dispatched to per-method listeners
+- flat session sub-targets — every outgoing message may carry a sessionId
+  obtained from Target.attachToTarget(flatten=True); incoming events with a
+  sessionId are routed to session-scoped listeners.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from websockets.asyncio.client import ClientConnection
+from websockets.asyncio.client import connect as ws_connect
+
+from ._errors import CDPConnectionClosed, CDPError
+
+logger = logging.getLogger(__name__)
+
+EventHandler = Callable[[dict[str, Any]], Awaitable[None] | None]
+Unsubscribe = Callable[[], None]
+
+
+class CDPConnection:
+    def __init__(self, ws_url: str) -> None:
+        self._ws_url = ws_url
+        self._next_id = 0
+        self._pending: dict[int, asyncio.Future[dict[str, Any]]] = {}
+        self._listeners: dict[str, list[EventHandler]] = {}
+        self._session_listeners: dict[tuple[str, str], list[EventHandler]] = {}
+        self._ws: ClientConnection | None = None
+        self._recv_task: asyncio.Task[None] | None = None
+        self._listener_tasks: set[asyncio.Task[None]] = set()
+        self._closed = asyncio.Event()
+        self._send_lock = asyncio.Lock()
+
+    @property
+    def closed(self) -> bool:
+        return self._closed.is_set()
+
+    async def connect(self) -> None:
+        self._ws = await ws_connect(self._ws_url, max_size=None, ping_interval=None)
+        self._recv_task = asyncio.create_task(self._receive_loop(), name="funbrowser-cdp-recv")
+
+    async def send(
+        self,
+        method: str,
+        params: dict[str, Any] | None = None,
+        *,
+        session_id: str | None = None,
+        timeout: float | None = 30.0,
+    ) -> dict[str, Any]:
+        if self._ws is None or self._closed.is_set():
+            raise CDPConnectionClosed("CDP connection is not open")
+        self._next_id += 1
+        msg_id = self._next_id
+        message: dict[str, Any] = {"id": msg_id, "method": method, "params": params or {}}
+        if session_id is not None:
+            message["sessionId"] = session_id
+
+        loop = asyncio.get_running_loop()
+        fut: asyncio.Future[dict[str, Any]] = loop.create_future()
+        self._pending[msg_id] = fut
+        try:
+            async with self._send_lock:
+                await self._ws.send(json.dumps(message))
+            if timeout is None:
+                return await fut
+            return await asyncio.wait_for(fut, timeout=timeout)
+        finally:
+            self._pending.pop(msg_id, None)
+
+    def on(
+        self,
+        method: str,
+        handler: EventHandler,
+        *,
+        session_id: str | None = None,
+    ) -> Unsubscribe:
+        """Subscribe to a CDP event. Returns an unsubscribe callable."""
+        if session_id is None:
+            lst = self._listeners.setdefault(method, [])
+        else:
+            lst = self._session_listeners.setdefault((session_id, method), [])
+        lst.append(handler)
+
+        def _unsub() -> None:
+            try:
+                lst.remove(handler)
+            except ValueError:
+                pass
+
+        return _unsub
+
+    async def _receive_loop(self) -> None:
+        assert self._ws is not None
+        try:
+            async for raw in self._ws:
+                try:
+                    msg = json.loads(raw)
+                except json.JSONDecodeError:
+                    logger.warning("CDP: failed to decode message")
+                    continue
+                self._dispatch(msg)
+        except Exception:
+            logger.debug("CDP: receive loop ended", exc_info=True)
+        finally:
+            self._closed.set()
+            for fut in self._pending.values():
+                if not fut.done():
+                    fut.set_exception(CDPConnectionClosed("CDP connection closed mid-request"))
+            self._pending.clear()
+
+    def _dispatch(self, msg: dict[str, Any]) -> None:
+        if "id" in msg:
+            fut = self._pending.pop(msg["id"], None)
+            if fut is None or fut.done():
+                return
+            if "error" in msg:
+                err = msg["error"]
+                fut.set_exception(
+                    CDPError(
+                        err.get("message", "CDP error"),
+                        code=err.get("code"),
+                        data=err.get("data"),
+                    )
+                )
+            else:
+                fut.set_result(msg.get("result", {}))
+            return
+
+        method = msg.get("method")
+        if not method:
+            return
+        session_id = msg.get("sessionId")
+        params = msg.get("params", {})
+        if session_id is not None:
+            for h in list(self._session_listeners.get((session_id, method), [])):
+                self._safe_invoke(h, params)
+        for h in list(self._listeners.get(method, [])):
+            self._safe_invoke(h, params)
+
+    def _safe_invoke(self, handler: EventHandler, params: dict[str, Any]) -> None:
+        try:
+            result = handler(params)
+        except Exception:
+            logger.exception("CDP listener raised")
+            return
+        if asyncio.iscoroutine(result):
+            task = asyncio.create_task(self._run_async(result))
+            self._listener_tasks.add(task)
+            task.add_done_callback(self._listener_tasks.discard)
+
+    async def _run_async(self, coro: Awaitable[None]) -> None:
+        try:
+            await coro
+        except Exception:
+            logger.exception("CDP async listener raised")
+
+    async def close(self) -> None:
+        if self._closed.is_set():
+            return
+        if self._ws is not None:
+            try:
+                await self._ws.close()
+            except Exception:
+                pass
+        if self._recv_task is not None:
+            try:
+                await asyncio.wait_for(self._recv_task, timeout=2.0)
+            except (TimeoutError, asyncio.CancelledError):
+                self._recv_task.cancel()
+        self._closed.set()

funbrowser/_errors.py

@@ -0,0 +1,32 @@
+"""Exceptions raised by funbrowser."""
+
+from __future__ import annotations
+
+
+class FunBrowserError(Exception):
+    """Base class for all funbrowser errors."""
+
+
+class BrowserNotFoundError(FunBrowserError):
+    """No Chrome / Chromium executable could be located."""
+
+
+class BrowserLaunchError(FunBrowserError):
+    """The browser process failed to start or expose a DevTools endpoint."""
+
+
+class CDPError(FunBrowserError):
+    """A CDP command returned an error response."""
+
+    def __init__(self, message: str, *, code: int | None = None, data: object = None) -> None:
+        super().__init__(message)
+        self.code = code
+        self.data = data
+
+
+class CDPConnectionClosed(FunBrowserError):
+    """The CDP WebSocket connection closed unexpectedly."""
+
+
+class TargetClosed(FunBrowserError):
+    """Operation attempted on a tab whose target has been destroyed."""

funbrowser/_flags.py

@@ -0,0 +1,89 @@
+"""Chrome launch flag presets and a merger that unions multi-value flags.
+
+Chrome accepts ``--disable-features=A,B`` once. Pass it twice and only the
+last wins. Stealth flags + mini flags + user-supplied flags can each carry
+their own ``--disable-features``, so we union all of them before launch.
+"""
+
+from __future__ import annotations
+
+
+def mini_flags() -> list[str]:
+    """Chrome flags that cut RAM / CPU / disk per browser.
+
+    Designed to be combined with :func:`funbrowser.stealth.stealth_flags`:
+    does **not** turn off the GPU (stealth needs the real-GPU WebGL
+    fingerprint), does **not** force ``--single-process`` (too crash-prone).
+    What it does turn off:
+
+    - site-per-process / IsolateOrigins → far fewer renderer processes
+    - background timers, occluded windows, renderer backgrounding
+    - extensions, sync, translate, breakpad, component-update
+    - audio output, metrics, domain reliability, hang monitor
+    - small disk / media caches, capped V8 heap per renderer
+
+    Typical effect on a 10-browser farm: ~50-60% lower RSS vs default
+    headless Chrome.
+    """
+    return [
+        "--mute-audio",
+        # Bundle all "feature off" toggles into a single --disable-features
+        # so merge_flags doesn't have to fight with stealth_flags.
+        "--disable-features="
+        "IsolateOrigins,site-per-process,"
+        "BackForwardCache,InterestFeedV2,"
+        "GlobalMediaControls,CalculateNativeWinOcclusion,"
+        "AudioServiceOutOfProcess",
+        "--disable-background-networking",
+        "--disable-background-timer-throttling",
+        "--disable-backgrounding-occluded-windows",
+        "--disable-renderer-backgrounding",
+        "--disable-breakpad",
+        "--disable-client-side-phishing-detection",
+        "--disable-component-update",
+        "--disable-domain-reliability",
+        "--disable-hang-monitor",
+        "--disable-ipc-flooding-protection",
+        "--disable-popup-blocking",
+        "--disable-prompt-on-repost",
+        "--disable-sync",
+        "--disable-translate",
+        "--disable-extensions",
+        "--disable-component-extensions-with-background-pages",
+        "--disk-cache-size=10485760",
+        "--media-cache-size=10485760",
+        "--js-flags=--max-old-space-size=192",
+        "--metrics-recording-only",
+    ]
+
+
+def merge_flags(*flag_lists: list[str]) -> list[str]:
+    """Combine flag lists, unioning multi-value flags and deduplicating others.
+
+    Chrome only honours the **last** ``--disable-features=`` argument on
+    the command line. Without this merger, stealth_flags + mini_flags
+    would silently drop one of their feature sets. We collect every
+    feature mentioned across all lists and emit a single
+    ``--disable-features=`` (same for ``--enable-features=``) at the end.
+    """
+    disabled: list[str] = []
+    enabled: list[str] = []
+    rest: list[str] = []
+    seen: set[str] = set()
+
+    for lst in flag_lists:
+        for f in lst:
+            if f.startswith("--disable-features="):
+                disabled.extend(p for p in f.removeprefix("--disable-features=").split(",") if p)
+            elif f.startswith("--enable-features="):
+                enabled.extend(p for p in f.removeprefix("--enable-features=").split(",") if p)
+            elif f not in seen:
+                seen.add(f)
+                rest.append(f)
+
+    out: list[str] = list(rest)
+    if disabled:
+        out.append("--disable-features=" + ",".join(sorted(set(disabled))))
+    if enabled:
+        out.append("--enable-features=" + ",".join(sorted(set(enabled))))
+    return out

funbrowser/_launcher.py

@@ -0,0 +1,153 @@
+"""Find and launch Chrome / Chromium with remote debugging enabled."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import re
+import shutil
+import sys
+import tempfile
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+from ._errors import BrowserLaunchError, BrowserNotFoundError
+
+DEVTOOLS_RE = re.compile(rb"DevTools listening on (ws://\S+)")
+
+
+@dataclass(frozen=True)
+class LaunchedBrowser:
+    process: asyncio.subprocess.Process
+    ws_url: str
+    user_data_dir: Path
+    user_data_dir_is_tmp: bool
+
+
+def _candidate_paths() -> list[Path]:
+    if sys.platform == "win32":
+        roots = [
+            os.environ.get("PROGRAMFILES", r"C:\Program Files"),
+            os.environ.get("PROGRAMFILES(X86)", r"C:\Program Files (x86)"),
+            os.environ.get("LOCALAPPDATA", str(Path.home() / "AppData" / "Local")),
+        ]
+        rels = [
+            r"Google\Chrome\Application\chrome.exe",
+            r"Chromium\Application\chrome.exe",
+            r"Google\Chrome Beta\Application\chrome.exe",
+            r"Google\Chrome Dev\Application\chrome.exe",
+            r"BraveSoftware\Brave-Browser\Application\brave.exe",
+            r"Microsoft\Edge\Application\msedge.exe",
+        ]
+        return [Path(r) / rel for r in roots if r for rel in rels]
+    if sys.platform == "darwin":
+        return [
+            Path("/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"),
+            Path("/Applications/Chromium.app/Contents/MacOS/Chromium"),
+            Path("/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"),
+            Path("/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"),
+        ]
+    return [
+        Path("/usr/bin/google-chrome"),
+        Path("/usr/bin/google-chrome-stable"),
+        Path("/usr/bin/chromium"),
+        Path("/usr/bin/chromium-browser"),
+        Path("/snap/bin/chromium"),
+    ]
+
+
+def find_chrome() -> Path | None:
+    """Return the first Chrome/Chromium-family binary found on this system."""
+    env = os.environ.get("FUNBROWSER_CHROME")
+    if env:
+        p = Path(env)
+        if p.is_file():
+            return p
+    for path in _candidate_paths():
+        if path.is_file():
+            return path
+    for name in (
+        "google-chrome",
+        "google-chrome-stable",
+        "chromium",
+        "chromium-browser",
+        "chrome",
+    ):
+        found = shutil.which(name)
+        if found:
+            return Path(found)
+    return None
+
+
+def _base_args(user_data_dir: Path, headless: bool, port: int) -> list[str]:
+    args = [
+        f"--remote-debugging-port={port}",
+        f"--user-data-dir={user_data_dir}",
+        "--no-first-run",
+        "--no-default-browser-check",
+        "--disable-blink-features=AutomationControlled",
+    ]
+    if headless:
+        args.append("--headless=new")
+    return args
+
+
+async def launch_chrome(
+    *,
+    executable: Path | None = None,
+    user_data_dir: Path | None = None,
+    headless: bool = False,
+    extra_args: Sequence[str] = (),
+    port: int = 0,
+    startup_timeout: float = 30.0,
+) -> LaunchedBrowser:
+    """Spawn Chrome with remote debugging and return its DevTools websocket URL."""
+    exe = executable or find_chrome()
+    if exe is None or not exe.is_file():
+        raise BrowserNotFoundError(
+            "No Chrome/Chromium binary located. Set the FUNBROWSER_CHROME env var "
+            "or pass executable= explicitly."
+        )
+
+    tmp_profile = False
+    if user_data_dir is None:
+        user_data_dir = Path(tempfile.mkdtemp(prefix="funbrowser-profile-"))
+        tmp_profile = True
+    else:
+        user_data_dir = Path(user_data_dir)
+        user_data_dir.mkdir(parents=True, exist_ok=True)
+
+    args = [str(exe), *_base_args(user_data_dir, headless, port), *extra_args]
+
+    proc = await asyncio.create_subprocess_exec(
+        *args,
+        stdout=asyncio.subprocess.DEVNULL,
+        stderr=asyncio.subprocess.PIPE,
+    )
+    ws_url = await _read_devtools_url(proc, startup_timeout)
+    return LaunchedBrowser(
+        process=proc,
+        ws_url=ws_url,
+        user_data_dir=user_data_dir,
+        user_data_dir_is_tmp=tmp_profile,
+    )
+
+
+async def _read_devtools_url(proc: asyncio.subprocess.Process, timeout: float) -> str:
+    assert proc.stderr is not None
+    try:
+        async with asyncio.timeout(timeout):
+            while True:
+                line = await proc.stderr.readline()
+                if not line:
+                    code = await proc.wait()
+                    raise BrowserLaunchError(
+                        f"Chrome exited (rc={code}) before printing DevTools URL"
+                    )
+                m = DEVTOOLS_RE.search(line)
+                if m:
+                    return m.group(1).decode("ascii")
+    except TimeoutError as exc:
+        proc.kill()
+        raise BrowserLaunchError("Timed out waiting for Chrome to print its DevTools URL") from exc