netkit (s-netkit)

Сетевой слой китов. Всё, чем интеграция разговаривает с чужим сервером: транспорт, темп, живучесть, деградация. Ставится и работает без оркестратора — зависимости идут строго вниз: netkit → corekit.

     clikit        adapterkit        <- ветки-оболочки
          \           /
           librarykit                <- ОРКЕСТРАТОР (сессии, браузер, склад)
               |
            netkit                   <- СЕТЬ (этот пакет)
               |
            corekit                  <- ОСНОВАНИЕ (значения и правила)

Что внутри

Объявить транспорт декларативно

Один и тот же лимит и одна и та же политика повторов — на любом виде транспорта. Интеграция объявляет, а не пишет обвязку:

from netkit.declare import KIND_HTTP, KIND_WS, TransportSpec, declare
from netkit.limit import LimitPolicy, LimitScope
from netkit.retry import SimpleRetryPolicy

limit = LimitPolicy(rate=5, per=1.0)          # 5 обменов в секунду
retry = SimpleRetryPolicy(backoff=(0.0, 0.0))  # 2 повтора без пауз
scope = LimitScope(service="acme")

api = declare(TransportSpec(kind=KIND_HTTP, url="https://api.acme.io",
                            limit=limit, scope=scope, retry=retry))
live = declare(TransportSpec(kind=KIND_WS, channel=my_ws_channel,
                            limit=limit, scope=scope, retry=retry))

await api.call("GET", "/v1/items")   # ждёт квоту, повторяет 429/5xx и сбои
await live.call('{"op":"ping"}')     # ТОТ ЖЕ темп и ТЕ ЖЕ повторы — без своего кода

Свой вид (grpc, sse, …) добавляется register_kind(kind, builder) и сразу получает то же поведение.

Наряд: «чем мы выглядим» — в одном месте

Персона (corekit.persona.ClientPersona) описывает ОДНОГО посетителя: браузер, платформу, язык, часы, рукопожатие, выход. Превращается она в то, что нужно проводу, ровно один раз — дверью outfit_for, а исполнители получают ГОТОВОЕ:

from netkit.outfit import outfit_for

outfit = outfit_for(persona=persona, mode="page-request")
outfit.headers       # заголовки целиком, уже в браузерном ПОРЯДКЕ
outfit.http2         # версия протокола (персона о ней знает)
outfit.tls_target    # цель подражания — нужна только curl_cffi (считается лениво)

На практике этого не пишут вовсе: наряд собирают сами транспорты, choke-point'ы и permissive-рецепты — достаточно передать им persona=:

transport = HttpxTransport(persona=persona)                    # прямая ступень
transport = CurlCffiTransport(persona=persona)                 # ступень подражания
client = build_permissive_http_client(cookies=..., persona=persona)

Почему одна дверь. Пока сборка была скопирована по местам, персона доезжала до одних исполнителей и молча терялась у других — а видно это становилось не ошибкой, а отзывом сессии через несколько часов. Что дверь действительно одна, держит netkit.outfit_guard: он метит наряд на самой двери и ловит исполнителя, чей ушедший набор метки не несёт.

Кто главнее: вызывающий или умолчание кита

Вызывающий — поимённо. Кит говорит за него только там, где тот промолчал. Правило одно на весь кит (fingerprint.merged_headers) и действует на всех путях: прямая ступень, ступень подражания, per-call мердж choke-point'а и permissive-рецепты.

client = build_permissive_http_client(
    follow_redirects=True,
    headers={"accept-language": "de-DE"},   # уедет на провод именно de-DE
)

Назвавший свой User-Agent забирает ВСЁ заявление о себе — и UA, и client hints. Смешать чужой User-Agent с нашими sec-ch-ua значит собрать клиента, который в одном заголовке одна программа, а в другом Chrome: это ловится одним сравнением и хуже честного не-браузера.

Почему об этом отдельный раздел. У рецепта ДВА слоя набора — заголовки httpx-клиента и заголовки choke-point'а, — и до 0.0.18 они соревновались молча: названный язык принимался фабрикой и терялся на проводе, потому что per-request у httpx заменяет клиентский одноимённый. Хуже всего было именно это состояние: заголовок принят без возражений и потерян по дороге. Теперь оба слоя сводятся в один (transport.named_by_the_caller), а base_headers как слой, названный ближе к запросу, старше headers.

Платформа: персона → машина → названная константа

Персоны нет — платформа не берётся из константы, а выводится по машине (как и версия браузера). До этого она была зашита словом «Windows», и на Linux-ноде клиент заявлял Windows, показывая настоящую машину всем остальным.

from netkit.fingerprint import declared_platform

declared_platform().describe()          # 'Linux — x86/64 (откуда: машина)'
declared_platform(persona).describe()   # 'macOS 14.5 arm/64 (откуда: персона)'

Персона, называющая macOS с Linux-ноды, не врёт: заявленная платформа — это устройство аккаунта, а не нода, на которой крутится процесс, и узнавание устройства держится именно за неё. Лечится другое — платформа, которую никто не выбирал; поэтому у неё есть origin, и его печатают наряд (Outfit.platform) и проба (python -m netkit.fingerprint_probe). Написание платформы, её кусок в User-Agent и версия лежат ОДНОЙ строкой таблицы PLATFORMS — новая платформа добавляется строкой, а не ветвлением.

Кодировки: заявляем ровно то, что разожмём

Chrome шлёт Accept-Encoding: gzip, deflate, br, zstd — и кит шлёт то же самое. Списать эту строку дословно было нельзя: сервер верит и присылает br, а клиент без декодера пропускает сжатое тело наверх молча, и падает потом разбор JSON где-то в навыке. Поэтому строка собирается из двух фактов — что заявляет браузер и что умеет распаковать ТОТ, КТО понесёт запрос:

from netkit.fingerprint import DECODER_CURL, accept_encoding

accept_encoding()               # 'gzip, deflate, br, zstd' — распакует httpx
accept_encoding(DECODER_CURL)   # то же, но умения спрошены у сборки curl

Декодеры (brotli, zstandard) приезжают ОСНОВНОЙ зависимостью — через extra самого httpx, чтобы вилки версий объявлял он, а не мы. В окружении, где их всё-таки нет (--no-deps, замороженный requirements), набор сужается сам — заявляем меньше, а не врём больше. У ступени подражания распаковщик свой (кодеки, вкомпилированные в curl-impersonate), поэтому её строка не зависит от питоновских вендоров вовсе — и наоборот.

Держать соединение сутками, а не один обмен

netkit.stream умеет «открыть — послать — принять — закрыть». Каналу, который обязан быть на связи круглосуточно (входящее приходит пушем, курсора в протоколе нет), этого мало: кто-то должен держать сокет открытым и возвращаться после обрыва. Это netkit.hold.

from netkit.hold import ConnectionBudget, HoldPolicy, StreamHolder

holder = StreamHolder(
    connect=lambda: MyServiceConnection(session),   # порт `HeldConnection` — КАНАЛА
    on_frame=inbox.put,                            # СТОЙКАЯ очередь, не буфер в памяти
    policy=HoldPolicy(ping_every=30.0, ping_timeout=30.0),
    on_state=lambda state: log.info("канал: %s", state),
    on_revoked=notify_owner,                       # сессия мертва — нужен новый вход
    budget=ConnectionBudget(200),                  # сколько сокетов держим сразу
)
await holder.run()                                 # держит, пока не остановят
ответ = await holder.call({"op": "история"})       # запрос поверх ЖИВОГО соединения

Что делает держатель и почему именно так (каждое — из замера, а не из вкуса):

• возвращается после обрыва с нарастающей паузой, и сбрасывает лестницу после удачного входа: сутки работы и обрыв — это не «десятая неудачная попытка подряд». Пауза не вежливость: бурст соединений сервер режет на уровне TLS примерно на минуту, и при массовом обрыве десятки держателей не должны ломиться в такт;
• пингует и ЖДЁТ ответ, считая срок от ПЕРВОГО неотвеченного пинга. Считая от последнего, «сервер молчит» не наступало бы никогда: каждый следующий пинг сдвигал бы срок вперёд, и держатель бодро пинговал бы мёртвую сеть. Пассивное чтение об обрыве не узнаёт вовсе — мёртвая сеть выглядит как тишина;
• различает «оборвалось» и «нас разлогинили»: первое лечится возвратом (ConnectionLostError), второе не лечится ничем (SessionRevokedError) и обязано выйти наружу сигналом. Молчащий держатель по мёртвому токену выглядит рабочим, и сообщения теряются «без ошибок»;
• читает сокет ОДИН: call не читает сам, а ждёт кадр со своим номером из общего цикла. Два независимых читателя растащили бы кадры между собой;
• не буферизует: пришедшее уходит в on_frame, и лишь ПОСЛЕ этого канал подтверждает доставку серверу. Обратный порядок однажды означал бы «серверу сказали, что доставлено» при потерянном сообщении.

Кит не знает ни одного сервиса. Адрес, формат кадра, опкоды, порядок входа и код разлогина приносит КАНАЛ, реализуя узкий порт HeldConnection (открыть, войти, принять кадр, пингануть, опознать кадр FrameVerdict, закрыть). Держатель отвечает только за ВРЕМЯ.

Не всякий канал имеет смысл держать. PeriodicHolder — тот же движок, но заходами по расписанию: подключился, вычитал накопленное до тишины, отключился. Дешевле по памяти, дороже по задержке.

Сколько аккаунтов влезет на машину — вопрос не темпа, а числа открытых сокетов, и отвечает на него ConnectionBudget (netkit.limit считает обмены в единицу времени и этого не закрывает). Второй множитель — память: WS-транспорт по умолчанию берёт shared_ssl_context(), ОДИН контекст шифрования на процесс. Замер: вендор, создающий свой контекст на каждое соединение, стоит 2,18 МБ на сессию против 0,38–0,42 МБ с общим — впятеро, то есть 1,1 ГБ против 0,2 ГБ на 500 сессий.

Шкала ступеней: по стоимости, а не по «продвинутости»

1. прямой запрос (httpx);
2. прямой запрос с имитацией браузера (curl_cffi: подделка рукопожатия) — цель работы в том, чтобы оставаться на этих двух: ни окна, ни процесса браузера здесь нет;
3. настоящий браузер БЕЗ окна (headless): основной движок nodriver, camoufox — запасной НА ТОЙ ЖЕ ступени, когда nodriver палится;
4. настоящий браузер С ВИДИМЫМ ОКНОМ — только вход человека; лестница сюда не спускается вовсе.

Третья и четвёртая различаются ВИДИМОСТЬЮ ОКНА, а не стелсом. Шкала объявлена данными (netkit.ladder.LADDER_RUNGS), поэтому новая возможность обязана сказать, что при ней происходит и сколько это стоит.

Слоты: как netkit зовёт то, что живёт выше

Последняя ступень лестницы поднимает браузер, а браузер — чужой кит, который сам зависит от сети. Прямой импорт дал бы цикл, поэтому направление разворачивается: netkit объявляет слот, верхний слой заполняет его на своём импорте.

from netkit.providers import SLOT_BROWSER_MINT, register_provider
register_provider(SLOT_BROWSER_MINT, my_mint_session)

Слоты со своим дефолтом (json_store, file_lock, state_root, path_slug, transport_factory, diagnose, egress_proxy) никогда не роняют вызов — netkit умеет их сам, верхний слой лишь уточняет. Слоты без дефолта (браузерные) при обращении поднимают ProviderMissing с инструкцией: молчаливой деградации «ступень тихо ничего не сделала» здесь нет.

Если в окружении стоит librarykit, его импорт заполняет все слоты сам — отдельная регистрация не нужна.

Совместимость

librarykit остаётся фасадом: librarykit.transport, librarykit.ladder, librarykit.limit, librarykit.retry, librarykit.pagination, librarykit.upload, librarykit.forms, librarykit.rpc, librarykit.stream, librarykit.graphql, librarykit.errmap реэкспортируют ТЕ ЖЕ объекты (не копии) — isinstance / except / is работают через любой из путей.

Стоимость импорта

import netkit не исполняет ни одного подмодуля: ни httpx, ни stamina, ни asyncio. Имена резолвятся по PEP 562 при первом обращении — платит тот, кому нужно.

Установка

pip install s-netkit          # ядро: corekit + httpx + stamina
pip install s-netkit[ws]      # + websockets для WS-транспорта