telethon-webproxy 0.1.0__tar.gz

telethon_webproxy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fiksofficial
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

telethon_webproxy-0.1.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: telethon-webproxy
+Version: 0.1.0
+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
+
+# telethon-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 telethon-webproxy
+```
+
+Или с указанием версии Telethon:
+
+```bash
+pip install "telethon-webproxy[telethon-v1]"   # Telethon 1.x
+pip install "telethon-webproxy[telethon-v2]"   # Telethon 2.x
+```
+
+## Быстрый старт
+
+### Telethon v1
+
+```python
+from telethon import TelegramClient
+from telethon_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 telethon_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 telethon_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 telethon_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

telethon_webproxy-0.1.0/README.md

@@ -0,0 +1,136 @@
+# telethon-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 telethon-webproxy
+```
+
+Или с указанием версии Telethon:
+
+```bash
+pip install "telethon-webproxy[telethon-v1]"   # Telethon 1.x
+pip install "telethon-webproxy[telethon-v2]"   # Telethon 2.x
+```
+
+## Быстрый старт
+
+### Telethon v1
+
+```python
+from telethon import TelegramClient
+from telethon_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 telethon_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 telethon_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 telethon_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

telethon_webproxy-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "telethon-webproxy"
+version = "0.1.0"
+authors = [{name = "fiksofficial"}]
+description = "Telegram WEB Proxy connector for Telethon (v1 & v2)"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+keywords = ["telegram", "telethon", "proxy", "mtproto", "web-proxy"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Communications :: Chat",
+    "Topic :: Internet",
+]
+dependencies = [
+    "websockets>=12.0",
+    "aiohttp>=3.9",
+    "cryptography>=39.0",
+]
+
+[project.optional-dependencies]
+telethon-v1 = ["telethon>=1.28"]
+telethon-v2 = ["telethon>=2.0"]
+dev = ["pytest", "pytest-asyncio"]
+
+[project.urls]
+Homepage = "https://github.com/fiksofficial/telethon-webproxy"
+Issues = "https://github.com/fiksofficial/telethon-webproxy/issues"
+
+[tool.setuptools.packages.find]
+include = ["telethon_webproxy*"]

telethon_webproxy-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

telethon_webproxy-0.1.0/telethon_webproxy/__init__.py

@@ -0,0 +1,78 @@
+"""
+telethon-webproxy — Telegram WEB Proxy connector for Telethon.
+
+Supports all four carrier modes:
+  • ``websocket``       — single multiplexed WebSocket (default)
+  • ``websocket-lanes`` — one WebSocket per stream (best isolation)
+  • ``https``           — HTTP long-polling (widest compatibility)
+  • ``https-lanes``     — per-stream HTTP long-polling
+
+Auto-reconnect is available via :class:`ReconnectingCarrier`.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.2.0"
+
+# ── Protocol core ─────────────────────────────────────────────────────────────
+from .protocol import (
+    FrameType,
+    Frame,
+    compute_capability,
+    compute_capability_from_hex,
+    encode_frame,
+    encode_hello,
+    parse_frames,
+)
+
+# ── Carrier base ──────────────────────────────────────────────────────────────
+from .carrier_base import (
+    BaseCarrier,
+    CarrierError,
+    HandshakeError,
+    StreamClosedError,
+    RelayByeError,
+)
+
+# ── Carrier implementations ──────────────────────────────────────────────────
+from .carrier import WebSocketCarrier
+from .carrier_https import HTTPSCarrier
+from .carrier_lanes import WebSocketLanesCarrier
+from .reconnect import ReconnectingCarrier
+
+# ── Telethon connectors ──────────────────────────────────────────────────────
+from .connector_v1 import ConnectionWebProxy
+from .connector_v2 import make_web_proxy_connector, WebProxyStream
+
+# ── Version auto-detect ──────────────────────────────────────────────────────
+_telethon_major: int | None = None
+
+try:
+    import importlib.metadata as _meta
+    _tv = _meta.version("telethon")
+    _telethon_major = int(_tv.split(".")[0])
+except Exception:
+    pass
+
+if _telethon_major is not None and _telethon_major >= 2:
+    WebProxyConnector = make_web_proxy_connector
+else:
+    WebProxyConnector = ConnectionWebProxy
+
+__all__ = [
+    # Protocol
+    "FrameType", "Frame",
+    "compute_capability", "compute_capability_from_hex",
+    "encode_frame", "encode_hello", "parse_frames",
+    # Carrier base
+    "BaseCarrier", "CarrierError", "HandshakeError",
+    "StreamClosedError", "RelayByeError",
+    # Carriers
+    "WebSocketCarrier", "HTTPSCarrier",
+    "WebSocketLanesCarrier", "ReconnectingCarrier",
+    # Telethon connectors
+    "ConnectionWebProxy", "make_web_proxy_connector",
+    "WebProxyStream", "WebProxyConnector",
+    # Meta
+    "__version__",
+]

telethon_webproxy-0.1.0/telethon_webproxy/carrier.py

@@ -0,0 +1,141 @@
+"""
+Multiplexed WebSocket carrier (``websocket`` carrier mode).
+
+Reference: PROTOCOL.md §Multiplexed WebSocket
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import ssl
+from typing import Optional
+
+import aiohttp
+
+from .carrier_base import BaseCarrier, StreamClosedError
+from .protocol import (
+    DATA_CHUNK,
+    WS_SUBPROTOCOL_PREFIX,
+    WS_UPGRADE_PATH,
+    FrameType,
+    encode_frame,
+    parse_frames,
+)
+
+log = logging.getLogger(__name__)
+
+
+class WebSocketCarrier(BaseCarrier):
+    """Single multiplexed WebSocket carrier.
+
+    All streams share one WSS connection. A WebSocket loss closes the
+    entire relay session (per the spec).
+    """
+
+    def __init__(
+        self,
+        host: str,
+        secret_hex: str,
+        *,
+        ssl_context: Optional[ssl.SSLContext] = None,
+    ) -> None:
+        super().__init__(host, secret_hex, ssl_context=ssl_context)
+        self._ws: Optional[aiohttp.ClientWebSocketResponse] = None
+        self._reader_task: Optional[asyncio.Task] = None
+
+    # ── Transport lifecycle ───────────────────────────────────────────────
+
+    async def _start_transport(self) -> None:
+        si = self._session_info
+        subprotocol = WS_SUBPROTOCOL_PREFIX + si.token
+        self._ws = await self._http.ws_connect(
+            f"wss://{si.host}{WS_UPGRADE_PATH}",
+            protocols=[subprotocol],
+            ssl=self._ssl,
+            max_msg_size=4 * 1024 * 1024,
+            origin=f"https://{si.host}",
+        )
+        self._reader_task = asyncio.get_event_loop().create_task(
+            self._reader_loop()
+        )
+        log.info("WebSocket carrier connected to %s", si.host)
+
+    async def _stop_transport(self) -> None:
+        if self._reader_task:
+            self._reader_task.cancel()
+            try:
+                await self._reader_task
+            except (asyncio.CancelledError, Exception):
+                pass
+            self._reader_task = None
+        if self._ws and not self._ws.closed:
+            await self._ws.close()
+        self._ws = None
+
+    # ── Stream operations ─────────────────────────────────────────────────
+
+    async def open_stream(self) -> int:
+        sid = self._alloc_stream()
+        await self._ws_send(encode_frame(FrameType.OPEN, sid))
+        return sid
+
+    async def close_stream(self, stream_id: int) -> None:
+        if stream_id in self._open_streams:
+            self._open_streams.discard(stream_id)
+            await self._ws_send(encode_frame(FrameType.CLOSE, stream_id))
+
+    async def send_data(self, stream_id: int, data: bytes) -> None:
+        offset = 0
+        while offset < len(data):
+            chunk_size = min(DATA_CHUNK, len(data) - offset)
+            await self._wait_send_window(stream_id, chunk_size)
+            chunk = data[offset : offset + chunk_size]
+            self._send_windows[stream_id] -= len(chunk)
+            await self._ws_send(encode_frame(FrameType.DATA, stream_id, chunk))
+            offset += chunk_size
+
+    async def _send_control(self, frame_bytes: bytes) -> None:
+        await self._ws_send(frame_bytes)
+
+    # ── Internals ─────────────────────────────────────────────────────────
+
+    async def _ws_send(self, data: bytes) -> None:
+        if self._ws and not self._ws.closed:
+            await self._ws.send_bytes(data)
+
+    async def _reader_loop(self) -> None:
+        try:
+            async for msg in self._ws:
+                if msg.type == aiohttp.WSMsgType.BINARY:
+                    await self._on_batch(msg.data)
+                elif msg.type == aiohttp.WSMsgType.PING:
+                    await self._ws.pong(msg.data)
+                elif msg.type in (
+                    aiohttp.WSMsgType.CLOSE,
+                    aiohttp.WSMsgType.CLOSING,
+                    aiohttp.WSMsgType.CLOSED,
+                    aiohttp.WSMsgType.ERROR,
+                ):
+                    break
+        except asyncio.CancelledError:
+            return
+        except Exception as exc:
+            log.warning("WebSocket reader error: %s", exc)
+        finally:
+            if self._connected:
+                await self.disconnect()
+
+    async def _on_batch(self, data: bytes) -> None:
+        try:
+            frames = parse_frames(data)
+        except ValueError as exc:
+            log.warning("Malformed relay batch: %s", exc)
+            return
+        for frame in frames:
+            pong = self._dispatch_frame(frame.type, frame.stream_id, frame.payload)
+            if pong:
+                await self._ws_send(pong)
+            if frame.type == FrameType.BYE:
+                await self.disconnect()
+                return