s-librarykit 0.1.0__py3-none-any.whl

librarykit/antibot.py

@@ -0,0 +1,467 @@
+"""Антибот-стратегия (КОРЕНЬ китов, W4) как ВЫБОР ТРАНСПОРТА, а не переписывание.
+
+Перенесено из `adapterkit.antibot` в жирный КОРЕНЬ `librarykit` (граф
+`librarykit <- adapterkit <- clikit`); `adapterkit.antibot` — тонкий реэкспорт.
+curl-cffi — ОПЦИОНАЛЬНЫЙ extra `[antibot]` (ленивый импорт внутри транспорта),
+librarykit-without-extras не падает на import пакета.
+
+Идея (spec §2, recipes/antibot reverse-factory): антибот — это не «headless vs
+residential proxy», а пять уровней архитектуры (Tier 0-4). Сервис «опт-инится» в
+нужный уровень, просто выбрав транспорт у эндпоинта (`Endpoint.transport`):
+
+- `TransportKind.HTTP`      → `HttpxTransport`  (Tier 0, обычный httpx) — другой модуль;
+- `TransportKind.CURL_CFFI` → `CurlCffiTransport` (Tier 1-3, JA3-имитация Chrome);
+- `TransportKind.BROWSER`   → `CdpTransport`    (Tier 0-1, реальный системный Edge/Chrome).
+
+Каждый из них реализует ОДИН И ТОТ ЖЕ контракт `librarykit.contract.Transport`
+(`async request(method, url, *, ...) -> httpx.Response`), поэтому вышестоящий код
+(`HttpClient`/`ErrorMapper`/адаптер) не различает транспорты — меняется только
+TLS-fingerprint и источник заголовков, но НЕ форма вызова. Маппинг кодов в
+доменные ошибки — НЕ здесь (это `HttpClient`/`ErrorMapper`); транспорт бросает
+`TransportError` только на сетевых сбоях и возвращает сырой `httpx.Response`.
+
+Опциональные зависимости (`curl_cffi`, `playwright`/`patchright`) импортируются
+ЛЕНИВО — модуль импортируется без них (graceful), а понятная ошибка о
+недостающем пакете возникает только при реальной попытке использовать транспорт.
+
+────────────────────────────────────────────────────────────────────────────────
+Tier 0-4 — какой транспорт выбрать под нагрузку и характер защиты
+────────────────────────────────────────────────────────────────────────────────
+Антибот эскалируется уровнями; не «беги за прокси первым», а подбирай по симптому.
+
+- **Tier 0** — видимый браузер (headed) / обычный httpx. RAM ~800 МБ. dev / debug /
+  первый bootstrap-логин. Здесь: `CdpTransport(headless=False)` / `HttpxTransport`.
+- **Tier 1** — headless реальный браузер (CDP→Edge `--headless=new`), ~700 мс,
+  500-800 МБ; prod 1-100 calls/day, антибот средний. Здесь: `CdpTransport(headless=True)`.
+  Вариант того же уровня — curl-cffi (JA3-имитация Chrome), ~10 МБ: JA3/TLS-детект
+  (Akamai, Google) БЕЗ signing. Здесь: `CurlCffiTransport`.
+- **Tier 2** — jsdom one-shot subprocess, 3-5 с, 30-50 МБ; init-флоу известен,
+  sign-only без рендера. Вне этого модуля.
+- **Tier 3** — jsdom persistent daemon (RPC), ~50 мс, ~80 МБ; prod sweet-spot
+  100-10K calls/day. Вне этого модуля.
+- **Tier 4** — pure native (Python/Go/Rust), ~1 мс, ~10 МБ; bundle pinned forever
+  + есть команда сопровождения. Вне этого модуля.
+
+Дерево решений:
+- read-only без подписи запроса → Tier 0/1 (или официальный REST, если есть);
+- мутирующий вызов с подписью (X-Sign/X-Bogus/_signature/msToken):
+  * bootstrap-логин → `CdpTransport` (реальный Edge ставит нативные
+    `sec-fetch-*` / Client-Hints / TLS — patchright их НЕ шлёт);
+  * массовая prod-нагрузка → Tier 3 jsdom-daemon (вне adapterkit), а Python-сторона
+    шлёт уже подписанный URL через `CurlCffiTransport` (JA3 совпадает).
+
+Симптом → направление (три ОРТОГОНАЛЬНЫХ оси, выбирай по симптому, не «по простоте»):
+- `403`/`Access denied` на любом IP, RU-регион заблокирован → IP/proxy (дорого, last resort);
+- видимый captcha-виджет (hCaptcha/Turnstile) → внешний solver (reCAPTCHA v3 — score-based,
+  solver НЕ работает, только реальный браузер `CdpTransport`);
+- `signatures don't match` / `isTTwidDecryptedFail` / «unusual activity» / нет
+  `sec-fetch-*` → архитектура: `CdpTransport` (реальный Edge);
+- `ECONNRESET` / другой контент на JA3-detection endpoint → архитектура: `CurlCffiTransport`.
+
+Железные правила (анти-паттерны):
+- версию Chrome НЕ пинить: захардкоженный `chrome131` через 4+ версии — сигнал «бот»
+  (`CurlCffiTransport` подбирает свежайший доступный профиль автоматически);
+- UA major == sec-ch-ua major == curl-cffi `impersonate` major — рассинхрон палится;
+- `CdpTransport` берёт версию браузера сам — держи системный Edge/Chrome обновлённым.
+"""
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Mapping
+from typing import Any, Protocol, runtime_checkable
+
+import httpx
+
+from librarykit.contract import Transport
+from librarykit.errors import TransportError
+
+# =========================================================================== #
+# Подбор impersonate-профиля curl-cffi (версию Chrome не пиним)                #
+# =========================================================================== #
+
+
+def pick_chrome_impersonate(target_major: int | None = None) -> str:
+    """Вернуть лучший доступный `impersonate` для Chrome из установленного curl-cffi.
+
+    - `target_major` — желаемый major (актуальная stable). `None` → самый свежий
+      `chromeNNN`, который знает текущий curl-cffi.
+
+    Если точного профиля нет — спускаемся к ближайшему МЕНЬШЕМУ; если target свежее
+    всего, что знает пакет, — берём максимум доступный (намёк: обновить curl-cffi).
+    Бросает `TransportError`, если curl-cffi не установлен или не знает ни одного
+    chrome-профиля (нечем имитировать JA3).
+    """
+    try:
+        from curl_cffi.requests.impersonate import BrowserType
+    except ImportError as exc:  # curl-cffi — опциональная зависимость (extra "antibot")
+        raise TransportError(
+            "curl_cffi не установлен — CurlCffiTransport недоступен. "
+            "Установите: uv sync --extra antibot (или uv add curl-cffi)."
+        ) from exc
+
+    chrome_versions: list[tuple[int, str]] = []
+    for b in BrowserType:
+        name = str(b.value)  # напр. "chrome148", "chrome120", "edge99", ...
+        suffix = name.removeprefix("chrome")
+        if name.startswith("chrome") and suffix.isdigit():
+            chrome_versions.append((int(suffix), name))
+    if not chrome_versions:
+        raise TransportError(
+            "curl_cffi не знает ни одного chrome-профиля — обновите пакет "
+            "(uv pip install -U curl-cffi)."
+        )
+
+    chrome_versions.sort()  # по возрастанию major
+    if target_major is None:
+        return chrome_versions[-1][1]  # самый свежий доступный
+    for major, name in chrome_versions:
+        if major == target_major:
+            return name
+    lower = [c for c in chrome_versions if c[0] < target_major]
+    if lower:
+        return lower[-1][1]  # ближайший меньший ≤ target
+    return chrome_versions[-1][1]  # target свежее пакета → максимум доступный
+
+
+# =========================================================================== #
+# Tier 1-3: curl-cffi транспорт (JA3-имитация реального Chrome)                #
+# =========================================================================== #
+
+
+@runtime_checkable
+class _CurlSessionLike(Protocol):
+    """Структурный минимум curl-cffi `AsyncSession` (для DI-фейков в тестах).
+
+    Реальный `curl_cffi.requests.AsyncSession` совпадает по форме; в тестах
+    подсовываем фейк той же формы, не таща сам curl-cffi.
+    """
+
+    async def request(self, method: str, url: str, **kwargs: Any) -> Any:
+        """Выполнить запрос; вернуть объект-ответ curl-cffi (см. `_to_httpx_response`)."""
+        ...
+
+    async def close(self) -> None:
+        """Закрыть нижележащую сессию/соединения."""
+        ...
+
+
+def _to_httpx_response(
+    raw: Any, *, request: httpx.Request, default_encoding: str = "utf-8"
+) -> httpx.Response:
+    """Сконвертировать ответ стороннего backend (curl-cffi) в `httpx.Response`.
+
+    Нормализует разнотипный ответ к единому контракту `Transport`: вышестоящий код
+    (`ErrorMapper`/адаптер) работает только с `httpx.Response`. Тянем status/headers/
+    тело и привязываем реконструированный `httpx.Request` (нужен для url в ошибках).
+    """
+    status = int(getattr(raw, "status_code", 0) or 0)
+    raw_headers = getattr(raw, "headers", None) or {}
+    headers = dict(raw_headers.items()) if hasattr(raw_headers, "items") else dict(raw_headers)
+    content = getattr(raw, "content", None)
+    if content is None:
+        text = getattr(raw, "text", "") or ""
+        content = text.encode(default_encoding)
+    elif isinstance(content, str):
+        content = content.encode(default_encoding)
+    return httpx.Response(
+        status,
+        headers=headers,
+        content=content,
+        request=request,
+        default_encoding=default_encoding,
+    )
+
+
+class CurlCffiTransport(Transport):
+    """Транспорт на `curl_cffi.AsyncSession` с JA3-имитацией Chrome (antibot Tier 1-3).
+
+    Обходит TLS/JA3-fingerprint-детект (Akamai, Google JA3-endpoint), где обычный
+    `httpx`/`requests` отбивается (`ECONNRESET` / подменённый контент): curl-cffi на
+    BoringSSL имитирует TLS-handshake и заголовки конкретной версии Chrome
+    (`impersonate=`). Реализует `librarykit.contract.Transport` — взаимозаменяем с
+    `HttpxTransport` для вышестоящего кода.
+
+    Параметры:
+    - `impersonate`  — явный профиль (``"chrome148"``); `None` → подбор по `target_major`;
+    - `target_major` — желаемый major Chrome (если `impersonate=None`);
+    - `headers`      — базовые заголовки (UA/sec-ch-ua держать СИНХРОННО с `impersonate`);
+    - `cookies`      — стартовые cookie (подставляет вызывающий код из своего storage);
+    - `timeout`      — таймаут запроса (сек);
+    - `proxy`        — явный прокси (``http(s)://``/``socks5://``);
+    - `session`      — внедрить готовую сессию (DI для тестов; минует импорт curl-cffi).
+
+    Версию Chrome НЕ пиним: при `impersonate=None` берётся свежайший доступный
+    профиль (`pick_chrome_impersonate`). UA/sec-ch-ua, переданные в `headers`,
+    обязаны совпадать major-в-major с `impersonate` (иначе рассинхрон палит бота).
+    """
+
+    def __init__(
+        self,
+        *,
+        impersonate: str | None = None,
+        target_major: int | None = None,
+        headers: Mapping[str, str] | None = None,
+        cookies: Mapping[str, str] | None = None,
+        timeout: float = 30.0,
+        proxy: str | None = None,
+        session: _CurlSessionLike | None = None,
+    ) -> None:
+        self._headers: dict[str, str] = dict(headers) if headers else {}
+        self._cookies: dict[str, str] = dict(cookies) if cookies else {}
+        self._timeout = timeout
+        self._proxy = proxy
+        # Профиль резолвим лениво (в _ensure_session), чтобы импорт модуля и
+        # конструктор работали БЕЗ установленного curl-cffi (graceful).
+        self._impersonate = impersonate
+        self._target_major = target_major
+        self._session: _CurlSessionLike | None = session
+
+    @property
+    def impersonate(self) -> str | None:
+        """Текущий выбранный impersonate-профиль (`None`, пока сессия не создана)."""
+        return self._impersonate
+
+    def _ensure_session(self) -> _CurlSessionLike:
+        """Лениво создать `AsyncSession` curl-cffi (или вернуть внедрённую DI-сессию).
+
+        Здесь происходит фактический импорт curl-cffi и резолв профиля — поэтому
+        отсутствие пакета бьёт понятным `TransportError` только при первом запросе.
+        """
+        if self._session is not None:
+            return self._session
+        try:
+            from curl_cffi.requests import AsyncSession
+        except ImportError as exc:
+            raise TransportError(
+                "curl_cffi не установлен — CurlCffiTransport недоступен. "
+                "Установите: uv sync --extra antibot (или uv add curl-cffi)."
+            ) from exc
+        if self._impersonate is None:
+            self._impersonate = pick_chrome_impersonate(self._target_major)
+        self._session = AsyncSession(  # type: ignore[assignment]
+            impersonate=self._impersonate,
+            timeout=self._timeout,
+            proxies={"http": self._proxy, "https": self._proxy} if self._proxy else None,
+        )
+        return self._session
+
+    async def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json: Any | None = None,
+        data: Any | None = None,
+        headers: Mapping[str, str] | None = None,
+        files: Any | None = None,
+        cookies: Mapping[str, str] | None = None,
+    ) -> httpx.Response:
+        """Выполнить запрос через curl-cffi и вернуть `httpx.Response`.
+
+        Заголовки/cookies запроса = базовые (конструктор) + переданные в вызов
+        (вызов перебивает). Сетевой сбой curl-cffi → `TransportError`. Маппинг
+        статусов в доменные ошибки делает вышестоящий `HttpClient`/`ErrorMapper`.
+        """
+        session = self._ensure_session()
+        merged_headers = {**self._headers, **(dict(headers) if headers else {})}
+        merged_cookies = {**self._cookies, **(dict(cookies) if cookies else {})}
+        # Реконструируем httpx.Request — нужен ответу (url в ошибках/логах ErrorMapper).
+        req = httpx.Request(
+            method,
+            url,
+            params=params,
+            headers=merged_headers or None,
+            cookies=merged_cookies or None,
+            json=json,
+            data=data,
+            files=files,
+        )
+        try:
+            raw = await session.request(
+                method,
+                url,
+                params=dict(params) if params else None,
+                json=json,
+                data=data,
+                headers=merged_headers or None,
+                cookies=merged_cookies or None,
+            )
+        except Exception as exc:
+            if isinstance(exc, TransportError):
+                raise
+            raise TransportError(f"curl_cffi: {type(exc).__name__}: {exc}") from exc
+        return _to_httpx_response(raw, request=req)
+
+    async def aclose(self) -> None:
+        """Закрыть нижележащую сессию curl-cffi (вызывать при завершении адаптера)."""
+        if self._session is not None:
+            close = getattr(self._session, "close", None)
+            if close is not None:
+                result = close()
+                if asyncio.iscoroutine(result):
+                    await result
+            self._session = None
+
+    async def __aenter__(self) -> CurlCffiTransport:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+
+# =========================================================================== #
+# Tier 0-1: CDP-транспорт (подключение к реальному системному Edge/Chrome)     #
+# =========================================================================== #
+
+
+@runtime_checkable
+class CdpBrowserBackend(Protocol):
+    """Контракт «движка реального браузера» под `CdpTransport` (точка DI).
+
+    Скрывает за собой запуск системного Edge/Chrome с `--remote-debugging-port`
+    и `connect_over_cdp` (см. recipes/antibot `cdp_real_browser.py`). Реализация —
+    в `librarykit.browser` (Playwright/patchright); здесь — только контракт, чтобы
+    `antibot` не тащил тяжёлый browser-стек и тестировался фейком той же формы.
+    """
+
+    async def fetch(
+        self,
+        method: str,
+        url: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json: Any | None = None,
+        data: Any | None = None,
+        headers: Mapping[str, str] | None = None,
+        cookies: Mapping[str, str] | None = None,
+    ) -> Any:
+        """Выполнить запрос внутри реального браузера; вернуть ответоподобный объект.
+
+        Объект нормализуется `_to_httpx_response` (нужны `status_code`/`headers`/
+        `content`|`text`). Браузер сам ставит нативные `sec-fetch-*` / Client-Hints
+        / TLS-fingerprint — ради чего CDP-транспорт и существует.
+        """
+        ...
+
+    async def aclose(self) -> None:
+        """Отключить CDP и завершить процесс браузера (idempotent)."""
+        ...
+
+
+class CdpTransport(Transport):
+    """Транспорт через РЕАЛЬНЫЙ системный Edge/Chrome по CDP (antibot Tier 0-1).
+
+    PRIMARY-путь для signing-heavy сервисов (TikTok / WB seller / Bitrix24-auth):
+    реальный браузер сам ставит нативный триплет `sec-fetch-{dest,mode,site}`,
+    корректные Client-Hints и TLS-fingerprint, которых нет у patchright (симптомы
+    `isTTwidDecryptedFail`, `signatures don't match`, «unusual activity»). `headless`
+    переключает Tier 0 (видимый, debug/bootstrap) ↔ Tier 1 (`--headless=new`, prod
+    1-100 calls/day).
+
+    Сам тяжёлый browser-движок инкапсулирован в `CdpBrowserBackend` (реализация —
+    `librarykit.browser`), который внедряется в конструктор. Так `antibot`:
+    1) не импортирует Playwright/patchright (опциональны → graceful);
+    2) реализует ровно `librarykit.contract.Transport` (взаимозаменяем с остальными);
+    3) детерминированно тестируется фейк-backend без реального браузера.
+
+    Параметры:
+    - `backend`  — реализация `CdpBrowserBackend` (composition root внедряет реальную);
+    - `headless` — Tier 1 (`True`) против Tier 0 (`False`); пробрасывается в реализацию;
+    - `prefer`   — предпочесть ``"edge"`` или ``"chrome"`` (Edge стабильнее на Windows);
+    - `headers`  — базовые заголовки, доливаемые к каждому запросу.
+
+    Если `backend=None` и реальный движок не сконфигурирован — первый `request`
+    бьёт понятным `TransportError` (а не падает при импорте модуля).
+    """
+
+    def __init__(
+        self,
+        *,
+        backend: CdpBrowserBackend | None = None,
+        headless: bool = True,
+        prefer: str = "edge",
+        headers: Mapping[str, str] | None = None,
+    ) -> None:
+        self._backend = backend
+        self.headless = headless
+        self.prefer = prefer
+        self._headers: dict[str, str] = dict(headers) if headers else {}
+
+    def _ensure_backend(self) -> CdpBrowserBackend:
+        """Вернуть browser-backend или объяснить, что реальный движок не подключён.
+
+        В spine `antibot` НЕ создаёт Playwright-backend сам (он живёт в
+        `librarykit.browser`); composition root внедряет его через конструктор.
+        """
+        if self._backend is None:
+            raise TransportError(
+                "CdpTransport требует CdpBrowserBackend (реальный Edge/Chrome через CDP). "
+                "Передайте backend=... из librarykit.browser или установите extra 'browser' "
+                "(uv sync --extra browser)."
+            )
+        return self._backend
+
+    async def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json: Any | None = None,
+        data: Any | None = None,
+        headers: Mapping[str, str] | None = None,
+        files: Any | None = None,
+        cookies: Mapping[str, str] | None = None,
+    ) -> httpx.Response:
+        """Выполнить запрос внутри реального браузера и вернуть `httpx.Response`.
+
+        `files` контрактом принимается, но в браузерном fetch не применяется
+        (multipart внутри страницы — отдельный сценарий); передаётся `None`. Сбой
+        браузера/CDP → `TransportError`. Маппинг статусов — выше по стеку.
+        """
+        backend = self._ensure_backend()
+        merged_headers = {**self._headers, **(dict(headers) if headers else {})}
+        req = httpx.Request(
+            method,
+            url,
+            params=params,
+            headers=merged_headers or None,
+            cookies=cookies,
+            json=json,
+            data=data,
+        )
+        try:
+            raw = await backend.fetch(
+                method,
+                url,
+                params=dict(params) if params else None,
+                json=json,
+                data=data,
+                headers=merged_headers or None,
+                cookies=dict(cookies) if cookies else None,
+            )
+        except Exception as exc:
+            if isinstance(exc, TransportError):
+                raise
+            raise TransportError(f"CDP: {type(exc).__name__}: {exc}") from exc
+        return _to_httpx_response(raw, request=req)
+
+    async def aclose(self) -> None:
+        """Закрыть browser-backend (отключить CDP, завершить процесс), если он есть."""
+        if self._backend is not None:
+            await self._backend.aclose()
+
+    async def __aenter__(self) -> CdpTransport:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+
+__all__ = [
+    "CurlCffiTransport",
+    "CdpTransport",
+    "CdpBrowserBackend",
+    "pick_chrome_impersonate",
+]