Metadata-Version: 2.4
Name: herokutl-webproxy
Version: 0.1.1
Summary: Telegram WEB Proxy connector for Telethon (v1 & v2)
Author: fiksofficial
License: MIT
Project-URL: Homepage, https://github.com/fiksofficial/telethon-webproxy
Project-URL: Issues, https://github.com/fiksofficial/telethon-webproxy/issues
Keywords: telegram,telethon,proxy,mtproto,web-proxy
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.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Internet
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: websockets>=12.0
Requires-Dist: aiohttp>=3.9
Requires-Dist: cryptography>=39.0
Provides-Extra: telethon-v1
Requires-Dist: telethon>=1.28; extra == "telethon-v1"
Provides-Extra: telethon-v2
Requires-Dist: telethon>=2.0; extra == "telethon-v2"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Dynamic: license-file

# herokutl-webproxy

**Telegram WEB Proxy connector for Telethon (v1 & v2).**

Позволяет подключать [Telethon](https://codeberg.org/Lonami/Telethon) к Telegram через новый тип прокси — **WEB Proxy** (`tdesktop-web-proxy-bridge-v1`), появившийся в Telegram Desktop 7.1.

> [!IMPORTANT]
> Библиотека общается с relay-сервером напрямую по WebSocket.
> **Браузер не нужен.** Потребление памяти — несколько сотен КБ на соединение.

## Установка

```bash
pip install herokutl-webproxy
```

Или с указанием версии Telethon:

```bash
pip install "herokutl-webproxy[herokutl-v1]"   # Telethon 1.x
pip install "herokutl-webproxy[herokutl-v2]"   # Telethon 2.x
```

## Быстрый старт

### Telethon v1

```python
from telethon import TelegramClient
from herokutl_webproxy import ConnectionWebProxy

client = TelegramClient(
    "session",
    api_id,
    api_hash,
    connection=ConnectionWebProxy,
    # Третий элемент кортежа — словарь с опциями (опционально)
    proxy=("proxy.example.com", "dd00...", {"mode": "websocket-lanes", "reconnect": True}),
)

async def main():
    await client.start()
    me = await client.get_me()
    print(me.first_name)

import asyncio
asyncio.run(main())
```

### Telethon v2

```python
from telethon import Client
from herokutl_webproxy import make_web_proxy_connector

connector = make_web_proxy_connector(
    host="proxy.example.com",
    secret_hex="dd00...",
    mode="websocket-lanes",
    reconnect=True,
)

client = Client("session", api_id, api_hash, connector=connector)
```

### Автоопределение версии

```python
from herokutl_webproxy import WebProxyConnector

# WebProxyConnector — это ConnectionWebProxy для Telethon v1
# или make_web_proxy_connector для Telethon v2.
# Определяется автоматически при импорте.
```

## Как это работает

```
┌──────────────┐         WSS / HTTPS  ┌───────────────┐        TCP        ┌──────────────┐
│  Ваш скрипт  │ ◄──────────────────► │  tproxy-server│ ◄───────────────► │   Telegram   │
│  (Telethon)  │   Фреймы протокола   │  (relay)      │   MTProto         │   DC         │
└──────────────┘    WEB Proxy v1      └───────────────┘                   └──────────────┘
```

1. Библиотека вычисляет `capability` — HMAC-SHA256 от секрета и домена.
2. Запрашивает bridge-страницу (`GET /?bridge=<cap>`) и извлекает bootstrap-токен.
3. Создает сессию (`POST /api/v1/session`) и получает session-токен.
4. Открывает выбранный транспорт (WSS мультиплекс, WSS на каждый поток, или HTTP long-polling).
5. Мультиплексирует MTProto-потоки через фреймы OPEN/DATA/CLOSE/WINDOW.

## Параметры прокси

| Параметр | Описание |
|:---------|:---------|
| `host` | Доменное имя WEB-прокси сервера (например `proxy.example.com`) |
| `secret_hex` | Hex-строка секрета MTProxy. Если не начинается с `dd`, библиотека добавит его. |
| `mode` | Режим работы: `websocket` (по умолч.), `websocket-lanes`, `https`. |
| `reconnect`| Автоматическое переподключение при обрыве сети (по умолч. `True`). |

## Низкоуровневый API

Если вам не нужна интеграция с Telethon, используйте `WebSocketCarrier` напрямую:

```python
import asyncio
from herokutl_webproxy import WebSocketCarrier

async def main():
    carrier = WebSocketCarrier("proxy.example.com", "dd00…")
    await carrier.connect()

    stream_id = await carrier.open_stream()
    await carrier.send_data(stream_id, b"\\x00\\x00\\x00\\x00...")  # raw MTProto
    response = await carrier.recv_data(stream_id)

    await carrier.close_stream(stream_id)
    await carrier.disconnect()

asyncio.run(main())
```

## Поддерживаемые серверы

- [telegramdesktop/tproxy-server](https://github.com/telegramdesktop/tproxy-server) — эталонная реализация на Go (от команды Telegram)
- [sleep3r/mtproto.zig](https://github.com/sleep3r/mtproto.zig) — высокопроизводительная реализация на Zig

## Тестирование

```bash
pip install -e ".[dev]"
pytest tests/
```

## Лицензия

MIT
