s-corekit 0.0.1__py3-none-any.whl

corekit/__init__.py

@@ -0,0 +1,168 @@
+"""corekit — ОСНОВАНИЕ экосистемы китов. Ноль зависимостей, дешёвый импорт.
+
+ФОРМА ГРАФА::
+
+        clikit          adapterkit          <- ветки-оболочки
+             \\             /
+              \\           /
+               librarykit                   <- ОРКЕСТРАТОР (сеть, сессии, браузер)
+                    |
+                 corekit                    <- ОСНОВАНИЕ (значения и правила)
+
+Что попало в основание и по какому признаку. Ровно одно: **сущность не тянет
+реализацию**. Здесь живут ЗНАЧЕНИЯ и ЧИСТЫЕ ПРАВИЛА — то, что нужно и тому, кто
+поднимает браузер, и тому, кто просто читает конфиг:
+
+* :mod:`corekit.context` — `ExecutionContext`: чей вызов, где его состояние,
+  куда он ходит в сеть. ОДИН на экосистему, с синонимами имён обеих школ
+  (``tenant``/``tenant_id``, ``profile``/``profile_name``);
+* :mod:`corekit.dto` — `SessionRef` / `Creds` / `RequestBody`;
+* :mod:`corekit.limits` — `QuotaScope` / `QuotaInfo` / `LimitSpec`;
+* :mod:`corekit.enums` — `PaginationMode` / `AuthMode` / `TransportKind`;
+* :mod:`corekit.errors` — ЕДИНАЯ иерархия исключений (`CliError` и потомки);
+* :mod:`corekit.redaction` — маскировка секретов в тексте/заголовках/теле;
+* :mod:`corekit.diagnosis` — таксономия причин (`Reason`) и состояние доступа
+  (`AccessState`/`AccessVerdict`) — классификация по УЛИКЕ, без сети.
+
+ЧЕГО ЗДЕСЬ НЕТ И НЕ БУДЕТ: httpx, pydantic, cryptography, keyring, playwright —
+никаких зависимостей вообще (``dependencies = []`` в pyproject, проверено
+тестом). Это не аскеза, а условие: основание ставится туда, где чужие колёса
+поставить нельзя.
+
+ЦЕНА ИМПОРТА (замер, а не обещание; Python 3.14, Windows, холодный
+интерпретатор, 3 прогона). Пол stdlib, который основание тянет законно
+(``dataclasses``/``pathlib``/``enum``/``re``/``json``/``datetime``) — 77-85 мс на
+этой машине. СОБСТВЕННАЯ цена ``import corekit`` поверх этого пола — 24-30 мс;
+для сравнения ``import librarykit`` поверх того же пола — 151-162 мс. Полный
+импорт: corekit ~105 мс против librarykit ~246 мс. Порог зафиксирован тестом
+``tests/test_stdlib_only.py`` и меряется ИМЕННО над полом — абсолютное число
+здесь описывает машину, а не код.
+
+СОВМЕСТИМОСТЬ. Ни одно имя отсюда не «переехало» для потребителя:
+`librarykit.contract`, `librarykit.errors`, `librarykit.redaction` и
+`librarykit.diagnosis.*` реэкспортируют ТЕ ЖЕ объекты (не копии), поэтому
+``isinstance``/``except``/``is``-сравнения работают через любой из путей.
+"""
+from __future__ import annotations
+
+from corekit.context import DEFAULT_TENANT, ExecutionContext
+from corekit.diagnosis import (
+    ACCESS_STATE_MESSAGES,
+    REASON_MESSAGES,
+    REASON_ORDER,
+    REASON_RANK,
+    AccessState,
+    AccessVerdict,
+    Reason,
+    Verdict,
+    classify_access,
+    classify_failure,
+    describe_egress,
+    is_egress_failure,
+    is_launch_failure,
+    resolve,
+    state_from_reason,
+    stronger,
+    verdict_from_error,
+)
+from corekit.dto import Creds, RequestBody, SessionRef
+from corekit.enums import AuthMode, PaginationMode, RequestExecutionMode, TransportKind
+from corekit.errors import (
+    RETRYABLE,
+    AdapterError,
+    ApiError,
+    AuthRequired,
+    Blocked,
+    CliError,
+    GraphQLError,
+    NotFound,
+    NotFoundError,
+    NotImplementedYet,
+    ProcessError,
+    ProfileBroken,
+    RateLimited,
+    ServerError,
+    SessionEgressMismatch,
+    SessionExpired,
+    TransportError,
+    ValidationError,
+)
+from corekit.limits import LimitSpec, QuotaInfo, QuotaScope
+from corekit.redaction import (
+    BODY_FIELD_PATTERNS,
+    HEADER_BLACKLIST,
+    SECRET_MASK,
+    excerpt_response_body,
+    sanitize_body,
+    sanitize_headers,
+    scrub_credentials,
+    truncate_body,
+)
+
+__version__ = "0.0.1"
+
+__all__ = [
+    "__version__",
+    # контекст исполнения
+    "ExecutionContext",
+    "DEFAULT_TENANT",
+    # базовые DTO
+    "SessionRef",
+    "Creds",
+    "RequestBody",
+    # квоты / лимиты
+    "QuotaScope",
+    "QuotaInfo",
+    "LimitSpec",
+    # перечисления «талии»
+    "PaginationMode",
+    "AuthMode",
+    "TransportKind",
+    "RequestExecutionMode",
+    # единая иерархия ошибок
+    "CliError",
+    "ApiError",
+    "AuthRequired",
+    "SessionExpired",
+    "SessionEgressMismatch",
+    "ProfileBroken",
+    "RateLimited",
+    "ValidationError",
+    "NotImplementedYet",
+    "ProcessError",
+    "AdapterError",
+    "TransportError",
+    "NotFound",
+    "NotFoundError",
+    "Blocked",
+    "ServerError",
+    "GraphQLError",
+    "RETRYABLE",
+    # диагностика: причина захода + состояние доступа
+    "Reason",
+    "Verdict",
+    "REASON_ORDER",
+    "REASON_RANK",
+    "REASON_MESSAGES",
+    "resolve",
+    "stronger",
+    "AccessState",
+    "AccessVerdict",
+    "ACCESS_STATE_MESSAGES",
+    "classify_access",
+    "state_from_reason",
+    "classify_failure",
+    "describe_egress",
+    "is_egress_failure",
+    "is_launch_failure",
+    "verdict_from_error",
+    # редакция секретов
+    "SECRET_MASK",
+    "HEADER_BLACKLIST",
+    "BODY_FIELD_PATTERNS",
+    "sanitize_headers",
+    "sanitize_body",
+    "truncate_body",
+    "excerpt_response_body",
+    "scrub_credentials",
+]

corekit/context.py

@@ -0,0 +1,268 @@
+"""ExecutionContext — ЕДИНЫЙ контекст одного вызова (ОСНОВАНИЕ экосистемы).
+
+Здесь живёт КАНОН контекста всей экосистемы китов. Модуль намеренно НИЧЕГО не
+знает про носитель (`contextvars`), про
+HTTP-клиент и про пути: он даёт ЗНАЧЕНИЕ. Носитель и резолверы ресурсов остаются
+слоем выше (`librarykit.context`) — иначе основание потянуло бы за собой сеть и
+файловую систему.
+
+ТОЛЬКО stdlib: ``dataclasses`` + ``pathlib`` + ``typing``. Ни httpx, ни pydantic,
+ни platformdirs.
+"""
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import FrozenInstanceError, dataclass, field, replace
+from pathlib import Path
+from typing import Any
+
+__all__ = [
+    "DEFAULT_TENANT",
+    "ExecutionContext",
+]
+
+#: Идентификатор ЕДИНСТВЕННОГО тенанта в локальном (CLI) режиме. Дефолт всех
+#: контекстов и `SessionRef`: пока он не изменён, раскладка путей и индекс
+#: байт-в-байт совпадают с тем, что было до введения мультитенантности.
+DEFAULT_TENANT = "local"
+
+
+#: Сентинел «аргумент не передан» для `ExecutionContext.__init__`: отличает
+#: «поле оставили по умолчанию» от «поле передали, и значение совпало с дефолтом».
+#: Без него нельзя решить конфликт синонимов (`tenant` vs `tenant_id`) честно.
+_UNSET: Any = object()
+
+
+def _pick_alias(
+    canonical_name: str, canonical: Any, alias_name: str, alias: Any, default: Any
+) -> Any:
+    """Значение поля, заданного одним из двух синонимичных имён.
+
+    Правило простое и без «победителей»: задано одно — берём его; задано оба и
+    они РАЗНЫЕ — `TypeError`. Молчаливый выбор одного из двух — ровно та ошибка,
+    из-за которой мост clikit↔librarykit терял тенанта (см. `ExecutionContext`).
+    """
+    has_canonical = canonical is not _UNSET
+    has_alias = alias is not None
+    if has_canonical and has_alias and canonical != alias:
+        raise TypeError(
+            f"ExecutionContext: {canonical_name}={canonical!r} и {alias_name}={alias!r} — "
+            f"это одно и то же поле под двумя именами, но значения разные. "
+            f"Передай что-то одно."
+        )
+    if has_canonical:
+        return canonical
+    if has_alias:
+        return alias
+    return default
+
+
+@dataclass(frozen=True, slots=True, init=False)
+class ExecutionContext:
+    """Контекст ОДНОГО вызова: чей он, где его состояние, куда он ходит в сеть.
+
+    Ядро мультитенантности (Этап 2). До него всё это текло через ``os.environ`` и
+    модульные global'ы — а значит, было ПРОЦЕССНЫМ: два тенанта в одном хосте
+    (или две корутины) переписывали друг другу профиль, ``{BRAND}_HOME``,
+    ``ALL_PROXY`` и флаг раскрытия секретов. `ExecutionContext` делает эти
+    величины ЯВНЫМИ, а скоупит их по `contextvars` слой выше (носитель —
+    :mod:`librarykit.context`), а не по процессу.
+
+    Поля:
+
+    - ``tenant_id``      — владелец вызова; в CLI ровно один — ``"local"``
+      (`DEFAULT_TENANT`), и тогда все раскладки/пути совпадают с досегодняшними;
+    - ``profile_name``   — профиль (набор сессий) внутри тенанта;
+    - ``home_dir``       — КОРЕНЬ состояния тенанта (вместо чтения ``{BRAND}_HOME``
+      в глубине кода);
+    - ``proxy``          — egress ИМЕННО ЭТОГО вызова (вместо ``ALL_PROXY`` /
+      ``install_opener`` на весь процесс); передаётся аргументом в транспорт;
+    - ``output_mode``    — режим вывода (``"json"``/``"text"``) для CLI-границы;
+    - ``reveal_secrets`` — раскрывать ли секреты в выводе (вместо global ``_REVEAL``);
+    - ``deadline``       — абсолютный дедлайн вызова, ``time.monotonic()``-шкала
+      (вместо global ``_DEADLINE``); ``None`` = без дедлайна;
+    - ``trace_id``       — сквозной идентификатор вызова для логов/трейсинга;
+    - ``brand``          — имя продукта/CLI, под которым контекст собран: по нему
+      потребитель понимает, «его» ли это контекст (``clikit.context.context_for``),
+      и не подхватывает чужой профиль. ``""`` = нейтральный, ничей;
+    - ``redactor``       — функция редакции данных вывода (``None`` — не
+      редактировать). РЕСУРС-исключение: живёт в контексте, потому что решение
+      «маскировать ли» принимается на границе вывода, а не в глубине;
+    - ``extra``          — произвольные поля потребителя, ядром не
+      интерпретируются.
+
+    **ЕДИНСТВЕННОСТЬ.** Это ОДИН на экосистему `ExecutionContext`.
+    Раньше их было два — свой у `clikit` (``brand``/``tenant``/``profile``/
+    ``redactor``/``extra``) плюс мост, который переносил значения по таблице
+    синонимов и молча терял ровно то, ради чего существовал. Здесь тот и другой
+    набор полей сведены в один тип, а ИМЕНА обеих школ поддержаны как синонимы:
+
+    ==================  ==================  ===============================
+    канон (corekit)     синоним (clikit)    где принимается
+    ==================  ==================  ===============================
+    ``tenant_id``       ``tenant``          конструктор, `evolve`, чтение
+    ``profile_name``    ``profile``         конструктор, `evolve`, чтение
+    ==================  ==================  ===============================
+
+    Синоним — не второе поле, а другое ИМЯ того же (``ctx.tenant is
+    ctx.tenant_id``). Передать оба разом можно, только если значения совпадают:
+    иначе `TypeError` — тихо выбирать «победителя» тут нельзя, это и была
+    исходная болезнь моста.
+
+    ``profile_name`` по умолчанию — ПУСТАЯ строка, а не ``"default"``: пустое
+    значит «профиль не выбран», и потребитель волен подставить свой дефолт
+    (`clikit.config.active_profile` по пустому уходит в общий конфиг-каталог, а
+    не в ``profiles/default/``). Свойство ``profile`` отдаёт такое значение как
+    ``None`` — форма, к которой привык clikit.
+
+    ``frozen=True, slots=True`` — как `SessionRef`/`Endpoint`: объект неизменяем,
+    поэтому его безопасно шарить между потоками и задачами (Этап 1), а «изменение»
+    делается порождением потомка (``dataclasses.replace`` →
+    :func:`librarykit.context.derive_context`).
+
+    .. note:: **Почему тут НЕТ поля ``http_client``.**
+
+       DTO ядра — ЗНАЧЕНИЕ: неизменяемое, хешируемое, дешёвое для копирования,
+       безопасное для логов и для передачи между потоками. HTTP-клиент — РЕСУРС с
+       жизненным циклом (пул соединений, привязка к event loop, обязательный
+       ``aclose``). Положив его полем, мы бы: (1) сделали ``replace()`` источником
+       утечки сокетов (клон разделяет пул, но никто не владеет закрытием);
+       (2) привязали контекст к конкретному event loop, хотя контекст живёт и в
+       потоках; (3) сломали дешёвое копирование и сериализацию контекста.
+       Поэтому клиент РЕЗОЛВИТСЯ ПО контексту, а не хранится В нём: см.
+       :func:`librarykit.context.http_client_for_context` (реестр «ключ контекста
+       → клиент» с явным :func:`librarykit.context.aclose_context_clients`) и
+       :func:`librarykit.context.transport_kwargs`.
+    """
+
+    tenant_id: str = DEFAULT_TENANT
+    profile_name: str = ""
+    home_dir: Path | None = field(default_factory=Path.home)
+    proxy: str | None = None
+    output_mode: str = "json"
+    reveal_secrets: bool = False
+    deadline: float | None = None
+    trace_id: str = ""
+    brand: str = ""
+    redactor: Callable[[Any], Any] | None = None
+    extra: Mapping[str, Any] = field(default_factory=dict)
+
+    def __init__(
+        self,
+        tenant_id: str = _UNSET,
+        profile_name: str = _UNSET,
+        home_dir: Path | None = _UNSET,
+        proxy: str | None = None,
+        output_mode: str = "json",
+        reveal_secrets: bool = False,
+        deadline: float | None = None,
+        trace_id: str = "",
+        brand: str = "",
+        redactor: Callable[[Any], Any] | None = None,
+        extra: Mapping[str, Any] | None = None,
+        *,
+        tenant: str | None = None,
+        profile: str | None = None,
+    ) -> None:
+        """Собрать контекст; ``tenant``/``profile`` — синонимы канонических имён.
+
+        Порядок ПОЗИЦИОННЫХ параметров исторический, а новые поля
+        (``brand``/``redactor``/``extra``) добавлены В КОНЕЦ — поэтому и
+        ``ExecutionContext("acme", "main")``, и любой прежний вызов по именам
+        продолжают значить ровно то же самое.
+        """
+        object.__setattr__(
+            self, "tenant_id", _pick_alias("tenant_id", tenant_id, "tenant", tenant, DEFAULT_TENANT)
+        )
+        object.__setattr__(
+            self, "profile_name", _pick_alias("profile_name", profile_name, "profile", profile, "")
+        )
+        object.__setattr__(
+            self, "home_dir", Path.home() if home_dir is _UNSET else home_dir
+        )
+        object.__setattr__(self, "proxy", proxy)
+        object.__setattr__(self, "output_mode", output_mode)
+        object.__setattr__(self, "reveal_secrets", reveal_secrets)
+        object.__setattr__(self, "deadline", deadline)
+        object.__setattr__(self, "trace_id", trace_id)
+        object.__setattr__(self, "brand", brand)
+        object.__setattr__(self, "redactor", redactor)
+        object.__setattr__(self, "extra", {} if extra is None else extra)
+
+    # --- синонимы имён (clikit-школа): ЧТЕНИЕ того же поля, не второе поле --- #
+    @property
+    def tenant(self) -> str:
+        """Синоним `tenant_id` (имя из clikit)."""
+        return self.tenant_id
+
+    @property
+    def profile(self) -> str | None:
+        """Синоним `profile_name`; пустое значение отдаётся как ``None``."""
+        return self.profile_name or None
+
+    def evolve(self, **changes: Any) -> ExecutionContext:
+        """Потомок с изменёнными полями (принимает и синонимы ``tenant``/``profile``).
+
+        То же, что `dataclasses.replace`, но понимает clikit-имена: ``replace``
+        работает строго по именам полей и на ``profile=`` упал бы.
+        """
+        for alias, canonical in (("tenant", "tenant_id"), ("profile", "profile_name")):
+            if alias in changes:
+                value = changes.pop(alias)
+                changes[canonical] = "" if value is None and canonical == "profile_name" else value
+        return replace(self, **changes)
+
+    def __hash__(self) -> int:
+        """Хеш по ЗНАЧИМЫМ координатам вызова (без ``redactor``/``extra``).
+
+        Сгенерированный dataclass-хеш взял бы ВСЕ поля и падал бы на ``extra``
+        (обычный ``dict`` не хешируется), а `ExecutionContext` обязан оставаться
+        хешируемым: он ложится в ключи реестров (см.
+        `librarykit.context.http_client_for_context`) и в множества в тестах.
+        Опущены ровно два поля-«довеска»: функция редакции и мешок потребителя —
+        они не меняют, ЧЕЙ это вызов и куда он ходит.
+        """
+        return hash(
+            (
+                self.tenant_id,
+                self.profile_name,
+                self.home_dir,
+                self.proxy,
+                self.output_mode,
+                self.reveal_secrets,
+                self.deadline,
+                self.trace_id,
+                self.brand,
+            )
+        )
+
+
+def _seal_frozen(cls: type) -> type:
+    """Сделать «заморозку» полной: присвоение ЛЮБОГО имени → `FrozenInstanceError`.
+
+    Ловушка CPython (проверено на 3.14): у ``@dataclass(frozen=True, slots=True)``
+    сгенерированный ``__setattr__`` замыкается на ИСХОДНЫЙ класс, а ``slots=True``
+    затем создаёт НОВЫЙ. Поэтому ветка «не поле — отдай родителю» уходит в
+    ``super(старый_класс, self)`` и вылетает
+    ``TypeError: super(type, obj): obj is not an instance…`` вместо внятного
+    отказа. Присвоение полю (``ctx.tenant_id = …``) отрабатывает верно — падает
+    только присвоение ИМЕНИ ВНЕ полей, а у `ExecutionContext` такие имена
+    появились: синонимы-свойства ``tenant``/``profile``.
+
+    Ставим свои ``__setattr__``/``__delattr__``: единый внятный отказ для всего.
+    Инициализация от этого не страдает — она идёт через `object.__setattr__`
+    (см. ``__init__``), а не через класс.
+    """
+
+    def _no_setattr(self: Any, name: str, value: Any) -> None:
+        raise FrozenInstanceError(f"cannot assign to field {name!r}")
+
+    def _no_delattr(self: Any, name: str) -> None:
+        raise FrozenInstanceError(f"cannot delete field {name!r}")
+
+    cls.__setattr__ = _no_setattr  # type: ignore[method-assign, assignment]
+    cls.__delattr__ = _no_delattr  # type: ignore[method-assign, assignment]
+    return cls
+
+
+_seal_frozen(ExecutionContext)

corekit/diagnosis/__init__.py

@@ -0,0 +1,103 @@
+"""ЧИСТАЯ диагностика доступа: таксономия причин + классификация по УЛИКАМ.
+
+Что здесь есть и почему это ОСНОВАНИЕ, а не «утиль»:
+
+* :mod:`corekit.diagnosis.verdict` — таксономия причин (`Reason`/`Verdict`) и
+  ПОРЯДОК их разбора как ДАННЫЕ (``REASON_ORDER``), а не как проза в комментариях;
+* :mod:`corekit.diagnosis.egress` — разбор ТЕКСТА ошибки: «лёг выход» против
+  «сервер спрашивает, кто ты» против «браузер не поднялся»;
+* :mod:`corekit.diagnosis.access` — состояние ДОСТУПА (`AccessState`/
+  `AccessVerdict`): что именно мертво — сессия, эндпоинт или инфраструктура.
+
+Ни один из трёх не ходит в сеть, не поднимает браузер и не читает файлы: на вход
+им дают статус/тело/URL/текст исключения, на выход они дают вердикт С УЛИКОЙ.
+Именно поэтому они годятся в основание — их можно позвать откуда угодно, включая
+процесс, где нет ни httpx, ни playwright.
+
+.. note:: Ссылки вида ``librarykit.diagnosis.geo`` / ``librarykit.diagnosis.landing``
+   в докстрингах ниже — указатели на слои ВЫШЕ (кто этими примитивами
+   пользуется и что достраивает). Импортов туда нет и быть не может: контракт
+   ``0a`` в `import-linter` роняет прогон на первой же такой строке.
+"""
+from __future__ import annotations
+
+from corekit.diagnosis.access import (
+    ACCESS_STATE_MESSAGES,
+    ENDPOINT_DEAD_MARKERS,
+    LOGIN_HOST_MARKERS,
+    SESSION_DEAD_MARKERS,
+    TOKEN_EXPIRED_MARKERS,
+    AccessState,
+    AccessVerdict,
+    classify_access,
+    state_from_reason,
+)
+from corekit.diagnosis.egress import (
+    AUTH_MARKERS,
+    AUTH_STATUS_CODES,
+    AUTH_TIMEOUT_PHRASES,
+    EGRESS_MARKERS,
+    EGRESS_STATUS_CODES,
+    KIND_AUTH,
+    KIND_EGRESS,
+    KIND_UNKNOWN,
+    LAUNCH_FAILURE_MARKERS,
+    LAYER_NAME_MARKERS,
+    PROXY_AUTH_PHRASES,
+    WEAK_EGRESS_MARKERS,
+    classify_failure,
+    describe_egress,
+    is_egress_failure,
+    is_launch_failure,
+    probe_egress_alive,
+    verdict_from_error,
+)
+from corekit.diagnosis.verdict import (
+    REASON_MESSAGES,
+    REASON_ORDER,
+    REASON_RANK,
+    Reason,
+    Verdict,
+    resolve,
+    stronger,
+)
+
+__all__ = [
+    # taxonomy: причины, порядок, вердикт
+    "Reason",
+    "Verdict",
+    "REASON_ORDER",
+    "REASON_RANK",
+    "REASON_MESSAGES",
+    "resolve",
+    "stronger",
+    # access: ЧТО мертво — сессия / эндпоинт / инфраструктура
+    "AccessState",
+    "AccessVerdict",
+    "ACCESS_STATE_MESSAGES",
+    "ENDPOINT_DEAD_MARKERS",
+    "LOGIN_HOST_MARKERS",
+    "SESSION_DEAD_MARKERS",
+    "TOKEN_EXPIRED_MARKERS",
+    "classify_access",
+    "state_from_reason",
+    # egress: транспорт vs авторизация vs «движок не поднялся»
+    "KIND_AUTH",
+    "KIND_EGRESS",
+    "KIND_UNKNOWN",
+    "AUTH_MARKERS",
+    "AUTH_STATUS_CODES",
+    "AUTH_TIMEOUT_PHRASES",
+    "EGRESS_MARKERS",
+    "EGRESS_STATUS_CODES",
+    "LAUNCH_FAILURE_MARKERS",
+    "LAYER_NAME_MARKERS",
+    "PROXY_AUTH_PHRASES",
+    "WEAK_EGRESS_MARKERS",
+    "classify_failure",
+    "describe_egress",
+    "is_egress_failure",
+    "is_launch_failure",
+    "probe_egress_alive",
+    "verdict_from_error",
+]