s-browserkit 0.0.1__tar.gz

s_browserkit-0.0.1/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/

s_browserkit-0.0.1/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog — s-browserkit
+
+Формат: [Keep a Changelog](https://keepachangelog.com/ru/1.1.0/), версии — SemVer.
+
+## [0.0.1] — 2026-08-03
+
+Выделение браузерного слоя из `s-librarykit`. Кода не написано
+заново — он ПЕРЕЕХАЛ; по старым путям остались алиасы на те же модули.
+
+### Добавлено
+
+* **Фасад возможностей** `browserkit.capabilities` — потребитель просит ЦЕЛЬ
+  (`Capability.STEALTH_SESSION` / `VISIBLE_LOGIN` / `PERSISTENT_WORK` /
+  `STEALTH_REQUEST` / `IN_PAGE_REQUEST` / `TRAFFIC_CAPTURE`), а не движок.
+  Соответствие «цель → движок» живёт в одной таблице `_DEFAULT_PLAN` внутри кита;
+  выбор — лестница кандидатов (первый установленный выигрывает), отсутствие всех
+  → `CapabilityUnavailable` с рецептом установки.
+* `browserkit.ports` — `Transport` / `SyncTransport` / `BrowserEngineRole`:
+  контракты, которые киту нужны снаружи. Структурно совпадают с контрактами
+  сетевого слоя (проверено тестом), поэтому транспорты взаимозаменяемы.
+* Ленивый корень (PEP 562): `import browserkit` не тянет ни подпакеты-реализации,
+  ни движки — можно спрашивать «умеешь ли ты стелс?», не платя импортом.
+
+### Переехало из librarykit (без изменения поведения)
+
+* `browser/` — `_engine`, `geometry`, `launchers`, `persistent`, `camoufox`,
+  `nodriver`, `capture_tap`, `state`, `_cdp_state`;
+* `antibot/` — `curl_cffi`, `cdp`, `page_evaluate`, `warmup_minter`, `_helpers`;
+* `profile_health.py` — предстартовая проверка профиля и карантин;
+* `proc.py` — запуск подпроцессов без всплывающих консолей.
+
+### Известный долг
+
+* `browserkit/proc.py` — ДУБЛЬ `librarykit/proc.py`. Настоящий дом слоя — основание
+  (`corekit`), перенос отложен, чтобы не драться за файл с параллельным выделением
+  `netkit`/`authkit-client`. Дрейф копий ловится тестом
+  `tests/test_layering.py::test_proc_layer_has_not_drifted_from_the_orchestrator`.
+* `browserkit/ports.py` — своя копия Protocol'ов транспорта; станет реэкспортом из
+  `netkit.contract`, когда сетевой кит будет опубликован.
+* `librarykit/ephemeral.py` (минт без дискового профиля) ОСТАЛСЯ в оркестраторе:
+  он тянет `librarykit.session_fingerprint` (инвариант «один egress + один
+  профиль»), чей дом — session-слой, а не браузерный. Браузер он поднимает лениво,
+  через этот кит, поэтому слои не нарушены.

s_browserkit-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dmitry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

s_browserkit-0.0.1/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: s-browserkit
+Version: 0.0.1
+Summary: Браузерный слой для Python-автоматизации: стелс-сессии, антибот-запросы и capture трафика через единый фасад возможностей, а не имя движка.
+Author: Dmitry
+License: MIT
+License-File: LICENSE
+Keywords: antibot,automation,browser,cdp,http,playwright,stealth
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: s-corekit>=0.0.1
+Provides-Extra: antibot
+Requires-Dist: curl-cffi>=0.7; extra == 'antibot'
+Provides-Extra: browser
+Requires-Dist: playwright>=1.40; extra == 'browser'
+Provides-Extra: camoufox
+Requires-Dist: camoufox>=0.4; extra == 'camoufox'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Provides-Extra: nodriver
+Requires-Dist: nodriver>=0.50; extra == 'nodriver'
+Description-Content-Type: text/markdown
+
+# s-browserkit — браузерный слой китов
+
+Живой браузер, антибот и стелс — одним китом, который ставится **отдельно**.
+Чистой API-интеграции (белый REST/GraphQL) он не нужен и больше не навязывается:
+`librarykit` без `browserkit` полностью работоспособен.
+
+```
+        clikit          adapterkit          ветки-оболочки
+             \             /
+              \           /
+               librarykit                   ОРКЕСТРАТОР (сессии, лимиты, фабрики)
+                /        \
+        browserkit        …                 СЛОЙ-КИТ (браузер и антибот)
+                \        /
+                 corekit                    ОСНОВАНИЕ (значения и чистые правила)
+```
+
+## Главное: просят ВОЗМОЖНОСТЬ, а не движок
+
+```python
+import browserkit
+
+backend = browserkit.open_browser(
+    browserkit.Capability.STEALTH_SESSION,   # ЦЕЛЬ, а не «camoufox»
+    profile_dir=profile,
+)
+http = browserkit.make_requester(browserkit.Capability.STEALTH_REQUEST)
+```
+
+Соответствие «цель → движок» живёт ровно в одной таблице внутри кита
+(`browserkit/capabilities.py`). Anti-detect движок начал палиться — правится одна
+строка, **ни один навык не меняется**, потому что ни один навык движок не назвал.
+
+Возможности:
+
+| Capability | Что нужно потребителю |
+|---|---|
+| `STEALTH_SESSION` | поднять браузер там, где обычный палится antibot'ом |
+| `VISIBLE_LOGIN`   | видимое окно: пароль/2FA человек вводит руками |
+| `PERSISTENT_WORK` | обычная автоматизация в персистентном профиле |
+| `STEALTH_REQUEST` | один HTTP-запрос с браузерным TLS-отпечатком, БЕЗ браузера |
+| `IN_PAGE_REQUEST` | запрос изнутри живой страницы (её cookies/TLS/заголовки) |
+| `TRAFFIC_CAPTURE` | нормализованный сетевой трафик страницы (реверс скрытого API) |
+
+Диагностика — «чем закрыта каждая цель прямо сейчас»:
+
+Сразу после `pip install s-browserkit` (без единого extra) все цели пусты — это и
+есть нормальный ответ, а не поломка:
+
+```python
+>>> import browserkit
+>>> browserkit.describe_capabilities()
+{'stealth_session': None, 'visible_login': None, 'persistent_work': None,
+ 'stealth_request': None, 'in_page_request': None, 'traffic_capture': None}
+```
+
+`None` означает «не установлен ни один исполнитель». Попытка воспользоваться такой
+целью даёт внятную ошибку с рецептом установки, а не голый `ModuleNotFoundError`:
+
+```python
+>>> browserkit.make_requester(browserkit.Capability.STEALTH_REQUEST)
+Traceback (most recent call last):
+  ...
+browserkit.CapabilityUnavailable: Возможность 'stealth_request' недоступна:
+ни один исполнитель не установлен. Поставь один из: `pip install 's-browserkit[antibot]'`.
+```
+
+После `pip install 's-browserkit[antibot]'` та же строка вернёт готовый
+исполнитель (`CurlCffiTransport`), а `describe_capabilities()['stealth_request']`
+станет `'tls_impersonate'` — имя ИСПОЛНИТЕЛЯ цели, не пакета. Какие исполнители
+стоят в очереди за каждой целью, видно заранее:
+
+```python
+>>> browserkit.capability_plan(browserkit.Capability.STEALTH_SESSION)
+('camoufox', 'nodriver', 'cdp')
+```
+
+Побеждает первый установленный; порядок переопределяется `set_capability_plan()`.
+
+## Состав
+
+* `browserkit.browser` — лаунчеры (системный Chromium по CDP, персистентный
+  контекст), anti-detect / undetected бэкенды, `capture_tap` (нормализованный
+  event-tap над любым движком), `state` (storage-state, тёплый вход, детекторы
+  протухания), геометрия окна, брони портов;
+* `browserkit.antibot` — исполнители HTTP-запроса, ходящие «как браузер»;
+* `browserkit.profile_health` — предстартовая проверка профиля и карантин;
+* `browserkit.proc` — запуск подпроцессов без всплывающих консолей;
+* `browserkit.ports` — Protocol'ы, которых киту не хватает снаружи.
+
+## Установка
+
+```bash
+pip install s-browserkit                 # без движков: фасад, антибот-контракты, здоровье профиля
+pip install 's-browserkit[browser]'      # + Playwright (CDP-attach, персистентный контекст)
+pip install 's-browserkit[camoufox]'     # + anti-detect Firefox   (затем `camoufox fetch`)
+pip install 's-browserkit[nodriver]'     # + undetected Chromium
+pip install 's-browserkit[antibot]'      # + TLS/JA3-импersonate без браузера
+```
+
+`import browserkit` не поднимает браузер и не импортирует ни одного движка:
+подпакеты резолвятся лениво (PEP 562), вендоры — ещё позже, внутри бэкендов.
+
+## Совместимость
+
+Прежние пути (`librarykit.browser.*`, `librarykit.antibot.*`,
+`librarykit.profile_health`) продолжают работать: там оставлены **алиасы на те же
+модули** (`sys.modules`), а не копии. Поэтому `monkeypatch`, `isinstance` и
+`is`-сравнения ведут себя ровно как до переноса.
+
+## Тесты
+
+```bash
+uv run --no-sync pytest -q          # либо .venv\Scripts\python.exe -m pytest -q
+```

s_browserkit-0.0.1/README.md

@@ -0,0 +1,115 @@
+# s-browserkit — браузерный слой китов
+
+Живой браузер, антибот и стелс — одним китом, который ставится **отдельно**.
+Чистой API-интеграции (белый REST/GraphQL) он не нужен и больше не навязывается:
+`librarykit` без `browserkit` полностью работоспособен.
+
+```
+        clikit          adapterkit          ветки-оболочки
+             \             /
+              \           /
+               librarykit                   ОРКЕСТРАТОР (сессии, лимиты, фабрики)
+                /        \
+        browserkit        …                 СЛОЙ-КИТ (браузер и антибот)
+                \        /
+                 corekit                    ОСНОВАНИЕ (значения и чистые правила)
+```
+
+## Главное: просят ВОЗМОЖНОСТЬ, а не движок
+
+```python
+import browserkit
+
+backend = browserkit.open_browser(
+    browserkit.Capability.STEALTH_SESSION,   # ЦЕЛЬ, а не «camoufox»
+    profile_dir=profile,
+)
+http = browserkit.make_requester(browserkit.Capability.STEALTH_REQUEST)
+```
+
+Соответствие «цель → движок» живёт ровно в одной таблице внутри кита
+(`browserkit/capabilities.py`). Anti-detect движок начал палиться — правится одна
+строка, **ни один навык не меняется**, потому что ни один навык движок не назвал.
+
+Возможности:
+
+| Capability | Что нужно потребителю |
+|---|---|
+| `STEALTH_SESSION` | поднять браузер там, где обычный палится antibot'ом |
+| `VISIBLE_LOGIN`   | видимое окно: пароль/2FA человек вводит руками |
+| `PERSISTENT_WORK` | обычная автоматизация в персистентном профиле |
+| `STEALTH_REQUEST` | один HTTP-запрос с браузерным TLS-отпечатком, БЕЗ браузера |
+| `IN_PAGE_REQUEST` | запрос изнутри живой страницы (её cookies/TLS/заголовки) |
+| `TRAFFIC_CAPTURE` | нормализованный сетевой трафик страницы (реверс скрытого API) |
+
+Диагностика — «чем закрыта каждая цель прямо сейчас»:
+
+Сразу после `pip install s-browserkit` (без единого extra) все цели пусты — это и
+есть нормальный ответ, а не поломка:
+
+```python
+>>> import browserkit
+>>> browserkit.describe_capabilities()
+{'stealth_session': None, 'visible_login': None, 'persistent_work': None,
+ 'stealth_request': None, 'in_page_request': None, 'traffic_capture': None}
+```
+
+`None` означает «не установлен ни один исполнитель». Попытка воспользоваться такой
+целью даёт внятную ошибку с рецептом установки, а не голый `ModuleNotFoundError`:
+
+```python
+>>> browserkit.make_requester(browserkit.Capability.STEALTH_REQUEST)
+Traceback (most recent call last):
+  ...
+browserkit.CapabilityUnavailable: Возможность 'stealth_request' недоступна:
+ни один исполнитель не установлен. Поставь один из: `pip install 's-browserkit[antibot]'`.
+```
+
+После `pip install 's-browserkit[antibot]'` та же строка вернёт готовый
+исполнитель (`CurlCffiTransport`), а `describe_capabilities()['stealth_request']`
+станет `'tls_impersonate'` — имя ИСПОЛНИТЕЛЯ цели, не пакета. Какие исполнители
+стоят в очереди за каждой целью, видно заранее:
+
+```python
+>>> browserkit.capability_plan(browserkit.Capability.STEALTH_SESSION)
+('camoufox', 'nodriver', 'cdp')
+```
+
+Побеждает первый установленный; порядок переопределяется `set_capability_plan()`.
+
+## Состав
+
+* `browserkit.browser` — лаунчеры (системный Chromium по CDP, персистентный
+  контекст), anti-detect / undetected бэкенды, `capture_tap` (нормализованный
+  event-tap над любым движком), `state` (storage-state, тёплый вход, детекторы
+  протухания), геометрия окна, брони портов;
+* `browserkit.antibot` — исполнители HTTP-запроса, ходящие «как браузер»;
+* `browserkit.profile_health` — предстартовая проверка профиля и карантин;
+* `browserkit.proc` — запуск подпроцессов без всплывающих консолей;
+* `browserkit.ports` — Protocol'ы, которых киту не хватает снаружи.
+
+## Установка
+
+```bash
+pip install s-browserkit                 # без движков: фасад, антибот-контракты, здоровье профиля
+pip install 's-browserkit[browser]'      # + Playwright (CDP-attach, персистентный контекст)
+pip install 's-browserkit[camoufox]'     # + anti-detect Firefox   (затем `camoufox fetch`)
+pip install 's-browserkit[nodriver]'     # + undetected Chromium
+pip install 's-browserkit[antibot]'      # + TLS/JA3-импersonate без браузера
+```
+
+`import browserkit` не поднимает браузер и не импортирует ни одного движка:
+подпакеты резолвятся лениво (PEP 562), вендоры — ещё позже, внутри бэкендов.
+
+## Совместимость
+
+Прежние пути (`librarykit.browser.*`, `librarykit.antibot.*`,
+`librarykit.profile_health`) продолжают работать: там оставлены **алиасы на те же
+модули** (`sys.modules`), а не копии. Поэтому `monkeypatch`, `isinstance` и
+`is`-сравнения ведут себя ровно как до переноса.
+
+## Тесты
+
+```bash
+uv run --no-sync pytest -q          # либо .venv\Scripts\python.exe -m pytest -q
+```

s_browserkit-0.0.1/browserkit/__init__.py

@@ -0,0 +1,185 @@
+"""browserkit — БРАУЗЕРНЫЙ СЛОЙ экосистемы китов: живой браузер, антибот, стелс.
+
+ФОРМА ГРАФА::
+
+        clikit          adapterkit          <- ветки-оболочки
+             \\             /
+              \\           /
+               librarykit                   <- ОРКЕСТРАТОР (сессии, лимиты, фабрики)
+                /        \\
+        browserkit        …                 <- СЛОЙ-КИТ (браузер и антибот)
+                \\        /
+                 corekit                    <- ОСНОВАНИЕ (значения и чистые правила)
+
+Что сюда переехало из `librarykit` (реальный код, не копия):
+
+* :mod:`browserkit.browser` — лаунчеры (системный Chromium по CDP, персистентный
+  контекст), anti-detect и undetected-бэкенды, `capture_tap` (нормализованный
+  event-tap над любым движком), `state` (storage-state, тёплый вход, детекторы
+  протухания), геометрия окна и брони портов;
+* :mod:`browserkit.antibot` — исполнители запроса, которые ходят «как браузер»:
+  TLS/JA3-импersonate без браузера, запрос через CDP-бэкенд, in-page fetch,
+  warmup-минтер одноразовых токенов;
+* :mod:`browserkit.profile_health` — предстартовая проверка браузерного профиля
+  (битые Cookies/Preferences, распухший кэш) и карантин;
+* :mod:`browserkit.proc` — запуск подпроцессов без всплывающих консолей;
+* :mod:`browserkit.ports` — Protocol'ы, которых киту не хватает снаружи.
+
+★ ГЛАВНОЕ — ФАСАД ВОЗМОЖНОСТЕЙ (:mod:`browserkit.capabilities`). Потребитель
+просит ЦЕЛЬ, а не движок::
+
+    import browserkit
+    backend = browserkit.open_browser(browserkit.Capability.STEALTH_SESSION,
+                                      profile_dir=profile)
+    http = browserkit.make_requester(browserkit.Capability.STEALTH_REQUEST)
+
+Замена движка (anti-detect Firefox начал палиться) — правка ОДНОЙ таблицы внутри
+кита; ни один навык не меняется, потому что ни один навык не назвал движок.
+
+ЛЕНИВОСТЬ. `import browserkit` НЕ поднимает браузер и НЕ импортирует ни одного
+тяжёлого движка: `browser`/`antibot` — реальные подпакеты, но резолвятся через
+PEP 562 по факту обращения; сами вендоры (playwright/camoufox/nodriver/curl_cffi)
+тянутся ещё позже — внутри бэкендов, где уже бросается внятное
+`BrowserUnavailable` с инструкцией по установке.
+
+СОВМЕСТИМОСТЬ. Прежние пути импорта (`librarykit.browser.*`,
+`librarykit.antibot.*`, `librarykit.profile_health`) продолжают работать: там
+оставлены АЛИАСЫ НА ТЕ ЖЕ модули (`sys.modules`), а не копии, поэтому
+monkeypatch, `isinstance` и `is`-сравнения ведут себя как до переноса.
+"""
+from __future__ import annotations
+
+from importlib import import_module as _import_module
+from importlib.util import find_spec as _find_spec
+from typing import TYPE_CHECKING
+
+from browserkit.capabilities import (
+    Capability,
+    CapabilityUnavailable,
+    capability_plan,
+    describe_capabilities,
+    is_capability_available,
+    make_requester,
+    open_browser,
+    set_capability_plan,
+)
+from browserkit.ports import (
+    BrowserEngineRole,
+    HttpRequestExecutor,
+    SyncHttpRequestExecutor,
+    SyncTransport,
+    Transport,
+)
+
+__version__ = "0.0.1"
+
+if TYPE_CHECKING:  # pragma: no cover - только статическая видимость для IDE/mypy
+    from typing import Any
+
+    from browserkit.antibot import (
+        CurlCffiTransport as CurlCffiTransport,
+    )
+    from browserkit.antibot import (
+        TokenHarvest as TokenHarvest,
+    )
+    from browserkit.antibot import (
+        WarmupTokenMinter as WarmupTokenMinter,
+    )
+    from browserkit.browser import (
+        BrowserUnavailable as BrowserUnavailable,
+    )
+    from browserkit.profile_health import (
+        ProfileHealth as ProfileHealth,
+    )
+    from browserkit.profile_health import (
+        check_profile as check_profile,
+    )
+    from browserkit.profile_health import (
+        ensure_healthy_profile as ensure_healthy_profile,
+    )
+
+#: Ленивые ИМЕНА корня: имя → модуль-источник. Держим их ленивыми по той же
+#: причине, что и в `librarykit`: `import browserkit` обязан стоить дёшево, чтобы
+#: фасад возможностей можно было спрашивать («умеешь ли ты стелс?»), не поднимая
+#: ни одного движка.
+_LAZY_NAMES: dict[str, str] = {
+    # browser
+    "BrowserUnavailable": "browserkit.browser",
+    "build_capture_backend": "browserkit.browser",
+    "attach_capture_tap": "browserkit.browser",
+    "camoufox_available": "browserkit.browser",
+    "nodriver_available": "browserkit.browser",
+    "playwright_available": "browserkit.browser",
+    # antibot
+    "CurlCffiTransport": "browserkit.antibot",
+    "TokenHarvest": "browserkit.antibot",
+    "WarmupTokenMinter": "browserkit.antibot",
+    "page_fetch": "browserkit.antibot",
+    # profile_health
+    "ProfileHealth": "browserkit.profile_health",
+    "ProfileProblem": "browserkit.profile_health",
+    "check_profile": "browserkit.profile_health",
+    "ensure_healthy_profile": "browserkit.profile_health",
+    "quarantine_profile": "browserkit.profile_health",
+    # proc
+    "ProcResult": "browserkit.proc",
+}
+
+__all__ = [
+    # ★ фасад возможностей — рекомендуемый вход
+    "Capability",
+    "CapabilityUnavailable",
+    "open_browser",
+    "make_requester",
+    "is_capability_available",
+    "describe_capabilities",
+    "capability_plan",
+    "set_capability_plan",
+    # порты (контракты)
+    "Transport",
+    "SyncTransport",
+    "HttpRequestExecutor",
+    "SyncHttpRequestExecutor",
+    "BrowserEngineRole",
+    # ленивые имена реализаций (совместимость с прежним корнем librarykit)
+    "BrowserUnavailable",
+    "build_capture_backend",
+    "attach_capture_tap",
+    "camoufox_available",
+    "nodriver_available",
+    "playwright_available",
+    "CurlCffiTransport",
+    "TokenHarvest",
+    "WarmupTokenMinter",
+    "page_fetch",
+    "ProfileHealth",
+    "ProfileProblem",
+    "check_profile",
+    "ensure_healthy_profile",
+    "quarantine_profile",
+    "ProcResult",
+]
+
+
+def __getattr__(name: str) -> Any:  # `Any` — только под TYPE_CHECKING
+    """Ленивый резолв (PEP 562): сперва карта имён, затем РЕАЛЬНЫЙ подмодуль."""
+    target = _LAZY_NAMES.get(name)
+    if target is None:
+        if not name.startswith("_"):
+            try:
+                found = _find_spec(f"{__name__}.{name}") is not None
+            except (ImportError, ValueError):
+                found = False
+            if found:
+                module = _import_module(f"{__name__}.{name}")
+                globals()[name] = module
+                return module
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    value = getattr(_import_module(target), name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    """Полная поверхность корня: жадные атрибуты + `__all__` + ленивые имена."""
+    return sorted(set(globals()) | set(__all__) | set(_LAZY_NAMES))

s_browserkit-0.0.1/browserkit/antibot/__init__.py

@@ -0,0 +1,131 @@
+"""Антибот-стратегия как ВЫБОР ТРАНСПОРТА, а не переписывание кода вызова.
+
+ДОМ ПАКЕТА — БРАУЗЕРНЫЙ КИТ. Раньше код жил в `librarykit`
+(а до того в `adapterkit.antibot`); по обоим старым путям остались АЛИАСЫ на эти
+же модули. curl-cffi — ОПЦИОНАЛЬНЫЙ extra `[antibot]` (ленивый импорт внутри
+транспорта), кит без extras не падает на import пакета.
+
+Идея: антибот — это не «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).
+
+Каждый из них реализует ОДИН И ТОТ ЖЕ контракт `ports.Transport`
+(`async request(method, url, *, ...) -> httpx.Response`), поэтому вышестоящий код
+(`HttpClient`/`ErrorMapper`/адаптер) не различает транспорты — меняется только
+TLS-fingerprint и источник заголовков, но НЕ форма вызова. Маппинг кодов в
+доменные ошибки — НЕ здесь (это `HttpClient`/`ErrorMapper`); транспорт бросает
+`TransportError` только на сетевых сбоях и возвращает сырой `httpx.Response`.
+
+Этот пакет — ТОНКИЙ ФАСАД: механически разнесён по ответственности на подмодули
+(`._helpers` — обёртка ошибок + нормализация ответа; `.curl_cffi` —
+`CurlCffiTransport`/`pick_chrome_impersonate`; `.cdp` — `CdpTransport`/
+`SyncCdpTransport` + backend-контракты; `.page_evaluate` — `PageEvaluateTransport`/
+`page_fetch`/`_build_fetch_spec`). Публичный API прежний — все прежние имена
+реэкспортированы.
+
+Опциональные зависимости (`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
+
+from ._helpers import (  # noqa: F401  # seam: тесты/потребители импортируют приватные
+    _as_transport_error,
+    _to_httpx_response,
+)
+from .cdp import (
+    CdpBrowserBackend,
+    CdpTransport,
+    SyncCdpBrowserBackend,
+    SyncCdpTransport,
+)
+from .curl_cffi import CurlCffiTransport, pick_chrome_impersonate
+from .page_evaluate import (
+    PageEvaluateTransport,
+    PageFetchResult,
+    _build_fetch_spec,  # noqa: F401  # seam: browser+тесты импортируют
+    page_fetch,
+    sync_page_fetch,
+)
+from .warmup_minter import TokenHarvest, WarmupTokenMinter
+
+# Первичные ролевые имена исполнителей запроса (роль снаружи, вендор — внутри):
+#   ImpersonatedHttpExecutor  — TLS/JA3-impersonate (curl-cffi) [было CurlCffiTransport];
+#   BrowserRequestExecutor    — запрос «руками браузера» по CDP/CamouFox [было CdpTransport];
+#   BorrowedPageRequestExecutor — запрос в ЗАИМСТВОВАННОЙ странице [было PageEvaluateTransport];
+#   BrowserRequester          — роль «умеет выполнить запрос в браузере» ПОВЕРХ живой
+#                               contract.BrowserSession (fetch, не ЖЦ) [было CdpBrowserBackend].
+# Старые имена остаются deprecated-псевдонимами (ничего не удалено).
+ImpersonatedHttpExecutor = CurlCffiTransport
+BrowserRequestExecutor = CdpTransport
+SyncBrowserRequestExecutor = SyncCdpTransport
+BorrowedPageRequestExecutor = PageEvaluateTransport
+BrowserRequester = CdpBrowserBackend
+SyncBrowserRequester = SyncCdpBrowserBackend
+
+__all__ = [
+    "CurlCffiTransport",
+    "CdpTransport",
+    "CdpBrowserBackend",
+    "SyncCdpTransport",
+    "SyncCdpBrowserBackend",
+    "PageEvaluateTransport",
+    "PageFetchResult",
+    "page_fetch",
+    "sync_page_fetch",
+    "pick_chrome_impersonate",
+    # warmup-минт одноразовых токенов тёплой страницей (генерик chatgpt-паттерна)
+    "WarmupTokenMinter",
+    "TokenHarvest",
+    # первичные ролевые имена (псевдонимы вендор-классов выше)
+    "ImpersonatedHttpExecutor",
+    "BrowserRequestExecutor",
+    "SyncBrowserRequestExecutor",
+    "BorrowedPageRequestExecutor",
+    "BrowserRequester",
+    "SyncBrowserRequester",
+]