WebSocket

Руководство по публичному API DuckoNet 0.11.5 для Python 3.12 x64 на Windows и Linux. Для WebSocket используйте HttpClient или AsyncHttpClient; для HTTP/3 через прокси задайте MasqueProxy. Установите предоставленный wheel для вашей ОС обычным pip install <путь-к-wheel> с его зависимостями. API-ключ берите из своей конфигурации, конечные точки .example замените адресами ваших серверов.

WebSocket

Открывайте соединение через уже настроенный HttpClient или AsyncHttpClient. Используются API-ключ, выбранный браузерный профиль, каталог состояния, CA и cookie jar этого клиента. Требуются совместимые компоненты DuckoNet и закреплённая зависимость websockets==17.3 из поставки. Проверять возможности можно после входа в контекст клиента: client.capabilities.websocket.

import os
from duckonet import HttpClient

with HttpClient(api_key=os.environ["DUCKONET_API_KEY"], browser="chrome") as client:
    with client.websocket("wss://echo.example/ws", origin="https://app.example") as ws:
        ws.send("Привет")
        message = ws.recv()          # str для text, bytes для binary
        print(message)
        ws.send(b"\x00\x01")
        print(ws.recv())
        print(ws.selected_subprotocol)
        print(ws.handshake_response.status_code)  # 101

Адреса .example в примерах замените своими конечными точками. websocket() возвращает менеджер контекста; открытие происходит при входе в with / async with, выход закрывает соединение.

Все дополнительные аргументы websocket(url, ...) передаются по имени. У обоих клиентов одинаковые параметры и значения по умолчанию, приведённые в таблицах ниже. AsyncHttpClient.websocket() используется непосредственно с async with, без отдельного await перед вызовом.

import asyncio
import os
from duckonet import AsyncHttpClient

async def main():
    async with AsyncHttpClient(api_key=os.environ["DUCKONET_API_KEY"], browser="chrome") as client:
        async with client.websocket("wss://echo.example/ws", compression=True) as ws:
            await ws.send("Привет")
            print(await ws.recv())
            await ws.ping(b"probe")
            await ws.close(code=1000, reason="Готово")

asyncio.run(main())

Host, Connection, Upgrade, Sec-WebSocket-Key, Sec-WebSocket-Version, Sec-WebSocket-Extensions, Sec-WebSocket-Protocol и Origin управляются библиотекой: ручная передача этих полей, в том числе в общих headers клиента, отклоняется. Для Origin, subprotocols и compression используйте отдельные параметры. Proxy-Authorization задаётся через credentials маршрута. Нельзя сочетать raw Cookie с разовым cookies=; HTTP cookie-политика остаётся действующей.

При автоматически созданном контексте Referer для открытия WS не добавляется; явные пользовательские заголовки и расширенный контекст сохраняют свои правила.

Set-Cookie ответа открытия обрабатывается общим jar согласно настройкам клиента cookies_enabled и persist_cookies. Значения этих настроек по умолчанию — True. WS не имеет отдельного Python cookie-хранилища.

Сообщения, сроки и завершение

Для AsyncWebSocket те же операции выполняются с await. Синхронное соединение поддерживает for message in ws, асинхронное — async for message in ws. Итерация заканчивается без ошибки только при кодах закрытия 1000 или 1001; прямой вызов recv() после исчерпания сообщений поднимает WebSocketClosedError, в том числе при нормальном закрытии. Сообщения, полностью полученные до закрытия сервером, доступны для чтения; локальное close() / abort() отбрасывает ожидающие сообщения.

Доступны свойства closed, selected_subprotocol, handshake_response и generation_receipt. У handshake_response есть status_code, headers (Headers), url, subprotocol; это ответ открытия, без HTTP body. Заголовки могут содержать конфиденциальные значения: не выводите их целиком в общие журналы. generation_receipt относится к поколению runtime/profile, закреплённому для соединения.

В одном клиенте допускается до 32 открытых или открывающихся WS одновременно. Различные HTTP/proxy routes также ограничены общим лимитом HTTP API (8). Для handshake применяется предел заголовков до 64 KiB; меньший header_limit клиента ограничивает принятый ответ дополнительно. HTTP body_limit не задаёт размер WS-сообщений.

Разрешены один активный reader и один активный writer на соединение, в том числе одновременно друг с другом. Перекрывающиеся recv() либо send() / ping() поднимают WebSocketConcurrencyError. Обрабатывайте сообщения без накопления собственного неограниченного списка.

Истечение срока recv() или отправки завершает это соединение. Отмена async-операции также прерывает именно принадлежащее ей соединение и ожидает освобождения native ресурсов, после чего возвращает asyncio.CancelledError. Закрытие клиента завершает его WS. Автоматических reconnect и повторной отправки сообщений нет; успешный send() сам по себе не подтверждает обработку сообщения сервером. ОС, планировщик и освобождение native ресурсов могут добавить время сверх протокольного close window.

Ошибки WS

Публичные исключения импортируются из duckonet.

Все WS-исключения выше, кроме последних двух строк, наследуют WebSocketError. TLS, DNS и другие транспортные причины открытия могут быть сведены к безопасному WebSocketTransportError: отдельного публичного WS-класса для каждого TLS/proxy отказа нет. Redirect WS всегда отключён, opt-in параметр для него отсутствует.

Если сервер завершил соединение сразу после корректного ответа Upgrade, открытие может вернуть уже закрытый WS с сохранёнными handshake_response и generation_receipt. Чтение сообщает WebSocketClosedError (при EOF без Close — код 1006); полностью полученные сообщения сохраняют обычные правила чтения. Это отличается от отказа самого handshake: неверный статус или Accept по-прежнему дают WebSocketHandshakeError.

WS выполняется через HTTP/1.1 Upgrade. WebSocket-over-HTTP/2 и WebSocket-over-HTTP/3 не предоставляются. Использование профиля и компрессии само по себе не является обещанием полного совпадения трафика с браузером.

Профиль, cookies и полный прогон

WebSocket и MASQUE используют существующую установку, каталог state_dir, API-ключ и подписанные профили DuckoNet. Для обновления программы сохраняйте прежний state_dir: в нём находятся идентичность установки и история доверия. Cookies живут в памяти клиента; для сохранения после закрытия приложения используйте export_data() и import_data(). Выбор доступных версий браузера по ключу остаётся общим для HTTP и WS.

Когда используется version="last", клиент подготавливает новые доступные поколения в фоне. Обрамляйте весь связанный прогон client.run(): HTTP, открываемые в нём WS и потоки используют закреплённое поколение до завершения своих операций. Следующий внешний run() выбирает уже подготовленное поколение; вложенный run() наследует текущий. Обновление не переключает профиль внутри открытого WS. При явно выбранной версии профиль остаётся закреплённым.

import os
from duckonet import HttpClient

with HttpClient(
    api_key=os.environ["DUCKONET_API_KEY"], browser="chrome", version="last",
) as client:
    with client.run():
        response = client.get("https://app.example/session")
        response.raise_for_status()
        with client.websocket("wss://app.example/events", origin="https://app.example") as ws:
            ws.send("start")
            print(ws.recv())
        print(client.browser_profile)

В асинхронном коде используются async with client.run() и async with client.websocket(...). Закрывайте WS и потоки внутри своего run(); сам выход из run() не является командой немедленно прервать уже открытое соединение. Без явного run() автоматические операции используют исходное поколение клиента. client.profile_update_status показывает состояние подготовки профиля, а client.browser_profile — фактический профиль выбранного прогона. Поколение не даёт бессрочное право на сетевую работу: действуют обычные проверки срока действия, отзыва и доступа по ключу, в том числе при обмене по WS.

Cookies принадлежат клиенту и сохраняют штатные domain/path/secure/SameSite правила. Они доступны HTTP и WS в пределах того же владельца и переживают штатную смену поколения. Для общего cookie-состояния переиспользуйте один клиент; два независимых клиента не становятся одним cookie jar только из-за одинакового адреса сервера. cookies= — разовое наложение, а постоянными cookies управляйте через client.cookies.

Поддерживаемые маршруты

Внешнее соединение с прокси и соединение с сайтом имеют разные назначения. response.protocol относится к сайту. Настройки браузерного профиля применяются к соединению с целевым сайтом. TLS-соединение с прокси устанавливается отдельно. Библиотека не гарантирует полное совпадение всех сетевых признаков WebSocket и TLS прокси с браузером.

Текст страницы