s-clientkit 0.0.1__py3-none-any.whl

clientkit/__init__.py

@@ -0,0 +1,120 @@
+"""clientkit — КИТ-СБОРЩИК: готовый клиент сервиса собирается, а не пишется.
+
+ФОРМА ГРАФА::
+
+        clientkit                     <- СБОРЩИК (вы здесь)
+        /        \\
+    authkit-client  browserkit        <- доступ (кто ты) / чеканка (как войти)
+        \\        /
+          netkit                      <- сеть (чем ходить)
+             |
+          corekit                     <- основание (значения и чистые правила)
+
+ЗАЧЕМ. Интеграция с сервисом — это каждый раз одни и те же пять решений: куда
+ходить, чем представляться, как часто можно, какие операции есть и (если API
+скрытый) чем держать доступ. Пока эти решения — КОД, каждый новый сервис стоит
+файла на триста строк, который через месяц разъедется с соседним. Здесь они —
+ДАННЫЕ (:class:`~clientkit.declaration.ServiceDecl`, читается из TOML), а код
+один на всех.
+
+ОДИН ВЫЗОВ НА ОБА МИРА::
+
+    from clientkit import build_from_toml
+
+    white  = build_from_toml("examples/white_service.toml",  secrets=os.environ.get)
+    hidden = build_from_toml("examples/hidden_service.toml", session_store=store)
+
+    await white.call("me")      # белый REST с api-ключом
+    await hidden.call("me")     # скрытый API с сессией и лестницей деградации
+
+Потребитель зовёт ОДИНАКОВО и по поверхности клиента не может отличить один от
+другого. При этом белый путь НЕ поднимает ни сессий, ни чеканки, ни антибота и
+делает ровно один запрос — это проверяется тестом по ``sys.modules`` и по
+счётчику запросов, а не декларируется.
+
+ЧЕГО ЗДЕСЬ НЕТ. Своего HTTP: «чем ходить» приходит аргументом
+(:class:`~clientkit.ports.RequestPort`), умолчание резолвится лениво. Своего
+браузера: чеканка приходит через порт слоя доступа. Своей таксономии отказов:
+диагноз ставит `corekit.diagnosis.access` — та же функция, что у живой пробы и у
+реестра эндпоинтов.
+"""
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING
+
+__version__ = "0.0.1"
+
+if TYPE_CHECKING:  # pragma: no cover — для тайпчекера/IDE
+    from clientkit._base import ServiceClient
+    from clientkit.builder import build_client, build_from_toml
+    from clientkit.declaration import (
+        AccessRecipe,
+        AuthDecl,
+        AuthScheme,
+        EndpointDecl,
+        LimitDecl,
+        ServiceDecl,
+        ServiceKind,
+        decl_from_data,
+        decl_to_data,
+        load_toml,
+    )
+    from clientkit.errors import AccessUnavailable, ClientBuildError, OperationFailed
+    from clientkit.hidden import HiddenApiClient
+    from clientkit.ports import RequestPort, SecretLookup
+    from clientkit.white import WhiteApiClient
+
+#: имя -> модуль-владелец. `hidden` в этой таблице стоит РЯДОМ с `white`, но
+#: цена у них разная: обращение к `HiddenApiClient` подтягивает слой доступа, а
+#: к `WhiteApiClient` — нет. Ленивость здесь и защищает эту разницу.
+_LAZY_NAMES: dict[str, str] = {
+    "build_client": "clientkit.builder",
+    "build_from_toml": "clientkit.builder",
+    "ServiceClient": "clientkit._base",
+    # ИМЯ сервиса — тоже данные, и притом нужные тем, кто базы не держит:
+    # навыку назвать свою сессию, записи трафика — положить снимок.
+    "ServiceIdentity": "clientkit.identity",
+    "Instancing": "clientkit.identity",
+    "UnknownService": "clientkit.identity",
+    "CATALOG": "clientkit.identity",
+    "canonical": "clientkit.identity",
+    "resolve_service": "clientkit.identity",
+    "suggest_service": "clientkit.identity",
+    # декларация — данные
+    "ServiceDecl": "clientkit.declaration",
+    "ServiceKind": "clientkit.declaration",
+    "AuthDecl": "clientkit.declaration",
+    "AuthScheme": "clientkit.declaration",
+    "LimitDecl": "clientkit.declaration",
+    "EndpointDecl": "clientkit.declaration",
+    "AccessRecipe": "clientkit.declaration",
+    "decl_from_data": "clientkit.declaration",
+    "decl_to_data": "clientkit.declaration",
+    "load_toml": "clientkit.declaration",
+    # порты
+    "RequestPort": "clientkit.ports",
+    "SecretLookup": "clientkit.ports",
+    # клиенты (обычно не нужны напрямую — собирает build_client)
+    "WhiteApiClient": "clientkit.white",
+    "HiddenApiClient": "clientkit.hidden",
+    # ошибки
+    "ClientBuildError": "clientkit.errors",
+    "AccessUnavailable": "clientkit.errors",
+    "OperationFailed": "clientkit.errors",
+}
+
+__all__ = ["__version__", *sorted(_LAZY_NAMES)]
+
+
+def __getattr__(name: str):
+    module_name = _LAZY_NAMES.get(name)
+    if module_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    value = getattr(importlib.import_module(module_name), name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted({*globals(), *_LAZY_NAMES})

clientkit/_base.py

@@ -0,0 +1,160 @@
+"""Общая часть обоих клиентов: ОДИН вызов, одна сборка запроса, один разбор.
+
+Смысл файла — в том, чего в нём нет: ни одного ``if kind == HIDDEN``. Различие
+белого и скрытого путей вынесено в ДВЕ вещи, которые подклассы переопределяют,
+— заголовки (:meth:`ServiceClientBase._headers`) и адрес операции
+(:meth:`ServiceClientBase._address`). Всё остальное — подстановка параметров,
+лимит, отправка, разбор — общее, поэтому потребителю нечем отличить один путь от
+другого: он зовёт ``await client.call("me")`` и там, и там.
+"""
+from __future__ import annotations
+
+import inspect
+import re
+from typing import Any, Protocol, runtime_checkable
+
+from clientkit._limit import TokenBucket
+from clientkit.declaration import EndpointDecl, ServiceDecl
+from clientkit.ports import RequestPort
+
+__all__ = ["ServiceClient", "ServiceClientBase"]
+
+#: Потолок починок на один вызов: сессия могла умереть И адрес мог смениться,
+#: но третья попытка починить то же самое — уже круг.
+MAX_REPAIRS = 3
+
+#: ``{name}`` в пути операции — параметр, который уезжает В АДРЕС, а не в запрос.
+_PLACEHOLDER = re.compile(r"\{(\w+)\}")
+
+
+@runtime_checkable
+class ServiceClient(Protocol):
+    """ЕДИНЫЙ контракт готового клиента — то, ради чего собирался кит.
+
+    Ровно два имени. Потребитель, которому дали такой объект, НЕ МОЖЕТ узнать по
+    его поверхности, белый под ним API или скрытый: одна операция вызова и одно
+    свойство с именем сервиса.
+    """
+
+    name: str
+
+    async def call(self, operation: str, **params: Any) -> Any:
+        """Позвать операцию по ИМЕНИ и получить разобранный ответ."""
+        ...
+
+
+class ServiceClientBase:
+    """Скелет клиента: подстановка → лимит → запрос → разбор."""
+
+    def __init__(self, decl: ServiceDecl, transport: RequestPort) -> None:
+        self.decl = decl
+        self.name = decl.name
+        self._transport = transport
+        self._bucket = (
+            TokenBucket(decl.limits.rate, decl.limits.burst) if decl.limits.rate else None
+        )
+        #: счётчик отправленных запросов — улика для тестов и для отчёта о цене
+        #: вызова («белый путь = один запрос» проверяется числом, а не верой).
+        self.requests_sent = 0
+
+    # ------------------------------------------------------------------ #
+    # то, чем различаются белый и скрытый пути                            #
+    # ------------------------------------------------------------------ #
+    async def _headers(self) -> dict[str, str]:
+        """Заголовки авторизации. Белый — ключ/токен, скрытый — cookies сессии."""
+        return {}
+
+    async def _address(self, endpoint: EndpointDecl) -> str:
+        """Адрес операции (у скрытого — текущий живой кандидат)."""
+        return endpoint.path
+
+    async def _inspect(self, endpoint: EndpointDecl, response: Any) -> bool:
+        """Осмотреть ЛЮБОЙ ответ. ``True`` — починили, стоит повторить вызов.
+
+        Зовётся на каждом ответе, а не только на «похожем на ошибку», и это
+        принципиально: скрытый API хоронит метод статусом 200 с телом
+        ``unknown rpcid``. Гадать о виде отказа ЗДЕСЬ нельзя — таксономия одна на
+        экосистему (`corekit.diagnosis.access`), и подключает её тот клиент,
+        которому она нужна.
+
+        База не чинит ничего: у белого API отказ — это ответ сервиса, и глотать
+        его нельзя.
+        """
+        return False
+
+    # ------------------------------------------------------------------ #
+    # общий путь вызова                                                   #
+    # ------------------------------------------------------------------ #
+    async def call(self, operation: str, **params: Any) -> Any:
+        """Позвать операцию по имени. Одинаково для белого и скрытого сервиса."""
+        endpoint = self.decl.endpoint(operation)
+        attempts = 0
+        while True:
+            attempts += 1
+            address = await self._address(endpoint)
+            path, rest = _apply_placeholders(address, params)
+            headers = await self._headers()
+            if self._bucket is not None:
+                await self._bucket.acquire()
+            response = await self._send(endpoint.method, self._url(path), headers, rest)
+            self.requests_sent += 1
+            # Потолок повторов — страховка от бесконечного круга «починили →
+            # снова то же самое». Каждая починка ЧТО-ТО меняет (сессию либо
+            # адрес), поэтому исчерпание потолка означает, что чинить больше
+            # нечем; ответ уходит наверх как есть.
+            if attempts <= MAX_REPAIRS and await self._inspect(endpoint, response):
+                continue
+            return _parse(response)
+
+    def _url(self, path: str) -> str:
+        """Склейка базы и пути без двойных слэшей и без потери суффикса базы."""
+        if path.startswith(("http://", "https://")):
+            return path
+        return f"{self.decl.base_url.rstrip('/')}/{path.lstrip('/')}"
+
+    async def _send(
+        self, method: str, url: str, headers: dict[str, str], params: dict[str, Any]
+    ) -> Any:
+        """Отправить запрос через порт (sync-транспорт тоже годится)."""
+        kwargs: dict[str, Any] = {"headers": headers}
+        if method in {"GET", "HEAD", "DELETE"}:
+            kwargs["params"] = params
+        else:
+            kwargs["json"] = params
+        result = self._transport.request(method, url, **kwargs)
+        if inspect.isawaitable(result):
+            result = await result
+        return result
+
+
+def _apply_placeholders(path: str, params: dict[str, Any]) -> tuple[str, dict[str, Any]]:
+    """``/users/{id}`` + ``{"id": 7, "q": "x"}`` → ``/users/7`` + ``{"q": "x"}``.
+
+    Параметр, названный в адресе, в запрос НЕ уезжает — иначе ``id`` уходил бы и
+    в путь, и в query, и половина сервисов отвечала бы 400 на ровном месте.
+    """
+    used: list[str] = []
+
+    def _sub(match: re.Match[str]) -> str:
+        key = match.group(1)
+        if key not in params:
+            raise KeyError(f"адрес {path!r} требует параметр {key!r}, а его не передали")
+        used.append(key)
+        return str(params[key])
+
+    resolved = _PLACEHOLDER.sub(_sub, path)
+    return resolved, {k: v for k, v in params.items() if k not in used}
+
+
+
+
+def _parse(response: Any) -> Any:
+    """Разобрать ответ: ``.json()`` если умеет, иначе ``.text``, иначе как есть."""
+    parser = getattr(response, "json", None)
+    if callable(parser):
+        try:
+            return parser()
+        except Exception:
+            pass
+    text = getattr(response, "text", None)
+    return text if text is not None else response

clientkit/_candidates.py

@@ -0,0 +1,150 @@
+"""КНИГА АДРЕСОВ операции: кандидаты и их живость.
+
+Реальный инцидент (он же — причина, по которой adapterkit завёл
+`EndpointRegistry`): у Gemini операция «история беседы» годами звалась `rpcid`
+``EqPOKe``, а на свежей сессии он отдаёт ``null``. Пока адрес зашит в код, эта
+смерть выглядит как «история пустая» или «сессия протухла» — обе трактовки
+ложные, обе гонят человека делать бесполезный ручной вход.
+
+ДВА ИСТОЧНИКА, ОДНО ПОВЕДЕНИЕ. Если установлен `adapterkit`, книга — тонкая
+обёртка НАД ЕГО `EndpointRegistry` (тот же порядок кандидатов, та же семантика
+«мёртвый пропускается, непроверенный — нет»). Если нет — равнозначная реализация
+на 30 строк. Причина держать обе: adapterkit тянет за собой оркестратор целиком
+(`s-librarykit`, httpx), и заставлять белого потребителя ставить это ради
+кита-сборщика было бы ровно тем, от чего кит и уводит. Совпадение поведения
+проверяется тестом, который прогоняет ОДИН сценарий через обе ветки.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from clientkit.declaration import EndpointDecl, ServiceDecl
+from clientkit.errors import AccessUnavailable
+
+__all__ = ["CandidateBook"]
+
+
+class CandidateBook:
+    """Кандидаты операций сервиса + отметки «этот адрес доказано мёртв»."""
+
+    def __init__(self, decl: ServiceDecl, *, registry: Any | None = None) -> None:
+        self.decl = decl
+        self._registry = registry
+        self._dead: dict[str, set[str]] = {}
+
+    # ------------------------------------------------------------------ #
+    @classmethod
+    def for_service(cls, decl: ServiceDecl, *, prefer_adapterkit: bool = True) -> CandidateBook:
+        """Собрать книгу: поверх adapterkit, если он есть, иначе своя.
+
+        Импорт adapterkit ЛЕНИВЫЙ и только на скрытом пути — белый клиент за него
+        не платит (проверено тестом по ``sys.modules``).
+        """
+        if prefer_adapterkit:
+            registry = _adapterkit_registry(decl)
+            if registry is not None:
+                return cls(decl, registry=registry)
+        return cls(decl)
+
+    @property
+    def backend(self) -> str:
+        """Кто под книгой: ``"adapterkit"`` или ``"builtin"`` (улика для тестов)."""
+        return "adapterkit" if self._registry is not None else "builtin"
+
+    # ------------------------------------------------------------------ #
+    def candidates(self, endpoint: EndpointDecl) -> tuple[str, ...]:
+        """Все адреса операции по объявленному порядку (первым — основной путь)."""
+        return endpoint.candidates or ((endpoint.path,) if endpoint.path else ())
+
+    def active(self, endpoint: EndpointDecl) -> str:
+        """Адрес, которым звать операцию СЕЙЧАС. Все мертвы — `AccessUnavailable`."""
+        if self._registry is not None:
+            return self._registry_active(endpoint)
+        dead = self._dead.get(endpoint.name, set())
+        for candidate in self.candidates(endpoint):
+            if candidate not in dead:
+                return candidate
+        raise AccessUnavailable(_exhausted_message(self.decl.name, endpoint, sorted(dead)))
+
+    def bury(self, endpoint: EndpointDecl, *, why: str = "") -> bool:
+        """Пометить текущий адрес мёртвым. ``True``, если есть кем его заменить.
+
+        ``False`` (а не исключение) намеренно: решение «сдаться или отдать ответ
+        как есть» принимает вызывающий, а книга лишь отвечает, осталось ли чем
+        звонить.
+        """
+        current = self.active(endpoint)
+        if self._registry is not None:
+            return self._registry_bury(endpoint, current, why)
+        self._dead.setdefault(endpoint.name, set()).add(current)
+        remaining = [c for c in self.candidates(endpoint) if c not in self._dead[endpoint.name]]
+        return bool(remaining)
+
+    # ------------------------------------------------------------------ #
+    # ветка adapterkit                                                    #
+    # ------------------------------------------------------------------ #
+    def _registry_active(self, endpoint: EndpointDecl) -> str:
+        from adapterkit.endpoints import EndpointsExhausted
+
+        try:
+            return self._registry.resolve(endpoint.name).id
+        except EndpointsExhausted as exc:
+            raise AccessUnavailable(str(exc)) from exc
+
+    def _registry_bury(self, endpoint: EndpointDecl, current: str, why: str) -> bool:
+        from adapterkit.endpoints import EndpointProbe, EndpointsExhausted
+
+        self._registry.record_probe(
+            EndpointProbe(
+                endpoint=endpoint.name,
+                candidate=current,
+                state=_endpoint_dead_state(),
+                why=why or "адрес не отвечает по существу",
+            )
+        )
+        try:
+            self._registry.resolve(endpoint.name)
+        except EndpointsExhausted:
+            return False
+        return True
+
+
+def _endpoint_dead_state():
+    from corekit.diagnosis.access import AccessState
+
+    return AccessState.ENDPOINT_DEAD
+
+
+def _adapterkit_registry(decl: ServiceDecl):
+    """Построить `EndpointRegistry` из ДЕКЛАРАЦИИ. ``None``, если adapterkit нет."""
+    try:
+        from adapterkit.endpoints import EndpointRegistry, endpoint_from_data
+    except Exception:
+        return None
+    endpoints = []
+    for ep in decl.endpoints:
+        ids = ep.candidates or ((ep.path,) if ep.path else ())
+        endpoints.append(
+            endpoint_from_data(
+                {
+                    "name": ep.name,
+                    "method": ep.method,
+                    "path": ep.path,
+                    "surface": "hidden",
+                    # Приоритет ПО ПОРЯДКУ ОБЪЯВЛЕНИЯ: декларация читается сверху
+                    # вниз, и первый кандидат обязан пойти первым.
+                    "candidates": [
+                        {"id": cid, "priority": 10 * (i + 1)} for i, cid in enumerate(ids)
+                    ],
+                }
+            )
+        )
+    return EndpointRegistry(endpoints, service=decl.name)
+
+
+def _exhausted_message(service: str, endpoint: EndpointDecl, dead: list[str]) -> str:
+    return (
+        f"сервис {service!r}, операция {endpoint.name!r}: живых адресов не осталось "
+        f"(мертвы: {', '.join(dead) or '—'}). Нужен актуальный адрес метода — "
+        "перевход не поможет."
+    )

clientkit/_limit.py

@@ -0,0 +1,55 @@
+"""Гейт лимита: token bucket на монотонных часах.
+
+Крошечный намеренно. Настоящая политика лимитов (percent-остаток аккаунта,
+балансировка пула, health) живёт выше — здесь ровно то, что объявлено В
+ДЕКЛАРАЦИИ сервиса: «не чаще N в секунду». Если ``rate == 0``, гейт не строится
+вовсе — платить блокировкой за необъявленное никто не обязан.
+"""
+from __future__ import annotations
+
+import asyncio
+import time
+
+__all__ = ["TokenBucket"]
+
+
+class TokenBucket:
+    """``rate`` пополнений в секунду, ёмкость ``burst``.
+
+    Часы — ``time.monotonic`` (перевод системного времени не открывает шлюз и не
+    вешает вызов навсегда). Инъекция часов/сна — для тестов: настоящий ``sleep``
+    в прогоне лимитов означал бы тест, который либо врёт, либо идёт минуту.
+    """
+
+    def __init__(
+        self,
+        rate: float,
+        burst: int = 1,
+        *,
+        clock=time.monotonic,
+        sleep=asyncio.sleep,
+    ) -> None:
+        if rate <= 0:
+            raise ValueError("rate обязан быть положительным (0 = гейт не нужен вовсе)")
+        self.rate = rate
+        self.burst = max(1, burst)
+        self._clock = clock
+        self._sleep = sleep
+        self._tokens = float(self.burst)
+        self._updated = clock()
+        self._lock = asyncio.Lock()
+
+    async def acquire(self) -> float:
+        """Дождаться права на вызов. Возвращает, сколько СЕКУНД пришлось ждать."""
+        async with self._lock:
+            now = self._clock()
+            self._tokens = min(self.burst, self._tokens + (now - self._updated) * self.rate)
+            self._updated = now
+            if self._tokens >= 1.0:
+                self._tokens -= 1.0
+                return 0.0
+            wait = (1.0 - self._tokens) / self.rate
+            await self._sleep(wait)
+            self._updated = self._clock()
+            self._tokens = 0.0
+            return wait

clientkit/builder.py

@@ -0,0 +1,65 @@
+"""СБОРЩИК: декларация → готовый клиент. Здесь и происходит выбор слоёв.
+
+Ровно одна развилка на весь кит, и она смотрит на ДАННЫЕ (``decl.kind``), а не на
+имя сервиса, не на env и не на «если это гугл, то…». За развилкой — два клиента с
+ОДИНАКОВОЙ поверхностью (:class:`~clientkit._base.ServiceClient`), поэтому дальше
+по коду потребителя различия нет.
+
+ГЛАВНОЕ СВОЙСТВО: белая ветка не импортирует ни сессий, ни чеканки, ни антибота.
+Импорт :mod:`clientkit.hidden` живёт ВНУТРИ ветки ``HIDDEN`` — не для красоты, а
+потому что импорт на уровне модуля стоил бы каждому белому клиенту всего слоя
+удержания доступа. Проверяется по ``sys.modules``, а не чтением.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from clientkit._base import ServiceClient
+from clientkit.declaration import ServiceDecl, ServiceKind, load_toml
+from clientkit.ports import RequestPort, resolve_transport
+
+__all__ = ["build_client", "build_from_toml"]
+
+
+def build_client(
+    decl: ServiceDecl,
+    *,
+    transport: RequestPort | None = None,
+    **options: Any,
+) -> ServiceClient:
+    """Собрать готовый клиент по декларации.
+
+    ``transport`` — «чем ходить». Не передали → умолчание резолвится ЛЕНИВО
+    (netkit → httpx): кит не тянет сетевое колесо на импорте.
+
+    ``options`` уходят выбранному клиенту как есть:
+
+    * белый  — ``secrets`` (``(name) -> str | None``), ``tokens``,
+      ``oauth_refresher``;
+    * скрытый — ``session_store``, ``profile``, ``account_id``, ``mint``.
+
+    Декларация ВАЛИДИРУЕТСЯ здесь: белый сервис с рецептом доступа или скрытый
+    без чеканщика — опечатка, и узнать о ней надо при сборке.
+    """
+    decl.validate()
+    port = transport if transport is not None else resolve_transport()
+    if decl.kind is ServiceKind.WHITE:
+        from clientkit.white import WhiteApiClient
+
+        return WhiteApiClient(decl, port, **options)
+
+    # Скрытый путь — и только он — поднимает слой удержания доступа.
+    from clientkit.hidden import HiddenApiClient
+
+    return HiddenApiClient(decl, port, **options)
+
+
+def build_from_toml(
+    path: str | Path,
+    *,
+    transport: RequestPort | None = None,
+    **options: Any,
+) -> ServiceClient:
+    """Прочитать декларацию из TOML и собрать клиент (самая короткая форма)."""
+    return build_client(load_toml(path), transport=transport, **options)