Upload 13 files

README.md

@@ -1,45 +1,270 @@
-# colab-proxy
+# colab-tunnel
 
-Утилиты для получения публичных ссылок на локальные веб-интерфейсы в Google Colab
-через популярные reverse-proxy сервисы.
+Библиотека для публичного туннелирования локальных портов в Google Colab.
+Поддерживает в настоящий момент 15 провайдеров, работает молча — выдаёт ссылку без лишних действий со стороны пользователя.
+
+```python
+from colab_tunnel import get_share_link
+link = get_share_link('srvus', 7860)
+print(link)
+```
+
+---
 
 ## Установка
 
+```bash
+uv pip install colab-tunnel
+```
+
+```bash
+pip install colab-tunnel
+```
+
+```bash
+uv add colab-tunnel
+```
+
+---
+
+## Быстрый старт
+
+```python
+from colab_tunnel import get_share_link
+
+# Один провайдер
+link = get_share_link('gradio', 7860)
+
+# Все провайдеры параллельно
+links = get_share_link('all', 7860)
+```
+
+---
+
+## Провайдеры
+
+| Имя            | Старт | RTT    | Примечания                                 |
+|----------------|-------|--------|--------------------------------------------|
+| `srvus`        | ~0.4с | ~200мс | Один из быстрейших                         |
+| `bore`         | ~0.5с | ~150мс | Минимальная задержка                       |
+| `localt`       | ~0.3с | ~300мс |                                            |
+| `localhostrun` | ~0.7с | ~200мс |                                            |
+| `gradio`       | ~0.5с | ~200мс |                                            |
+| `tmole`        | ~1.5с | ~350мс |                                            |
+| `beeceptor`    | ~2с   | ~400мс |                                            |
+| `optimistix`   | ~1.5с | ~500мс |                                            |
+| `mmar`         | ~1с   | ~600мс |                                            |
+| `serveo`       | ~1.5с | ~700мс |                                            |
+| `boredigital`  | ~1.5с | ~900мс |                                            |
+| `cloudflared`  | ~4с   | ~400мс | Warmup ~15с после старта                   |
+| `tunnelite`    | ~4с   | ~300мс |                                            |
+| `native`       | ~2с   | —      | Только в Colab, требует Google-авторизации |
+| `tunwg`        | —     | —      | Отключён: сервис временно недоступен       |
+
+SSH-провайдеры (`srvus`, `serveo`, `localhostrun`, `optimistix`) используют стандартный SSH-ключ системы, при необходимости генерируется автоматически.
+
+---
+
+## API
+
+### `get_share_link(host, port)`
+
+Получить публичную ссылку через указанный провайдер.
+
 ```python
-!pip install -q git+https://github.com/ВАШ_ЮЗЕР/colab-proxy.git
+from colab_tunnel import get_share_link
+
+link = get_share_link('gradio', 7860)
+# host='all' — запустить всех параллельно, вернуть все ссылки
+links = get_share_link('all', 7860)
 ```
 
-## Использование
+---
+
+### `try_all(port)`
+
+Параллельно запускает всех активных провайдеров, возвращает все полученные ссылки.
 
 ```python
-from colab_proxy import get_share_link
+from colab_tunnel import try_all
 
-port = 7860  # порт вашего веб-интерфейса
+print(try_all(7860))
+# gradio: https://...gradio.live
+# bore: http://bore.pub:XXXXX/
+# srvus: https://...srv.us
+# ...
+```
 
-link = get_share_link('cloudflared', port)
-print(link)
+---
+
+### `benchmark(providers, timeout_per_provider, latency_timeout, print_report)`
+
+Последовательно тестирует провайдеров с замером времени старта и RTT.
+Требует бинарник `test_server` из папки проекта.
+
+```python
+from colab_tunnel import benchmark
+
+results = benchmark()
+# Бенчмарк: 14 провайдеров, порт XXXXX.
+# [srvus       ] OK (0.43с). Проверка... RTT 174мс
+# [bore        ] OK (0.81с). Проверка... RTT 125мс
+# ...
+# Итого: 14/14 провайдеров работают.
+# Минимальная задержка: bore (125мс)
+
+# Выборочно
+results = benchmark(providers=['cloudflared', 'bore', 'gradio'])
+
+# Результаты — список TunnelBenchmarkResult
+for r in results:
+    print(r.name, r.tunnel_time, r.latency, r.url)
+```
+
+Путь к `test_server` определяется ав��оматически:
+1. Переменная окружения `TEST_SERVER_PATH`
+2. `../test_server/test_server` относительно пакета
+3. `./test_server/test_server` относительно CWD
+
+---
+
+### Управление провайдерами
+
+```python
+from colab_tunnel import list_providers, disable_provider, enable_provider
+
+# Статус всех провайдеров
+list_providers()
+# {'tmole': True, 'tunwg': False, 'cloudflared': True, ...}
+
+# Отключить нерабочий
+disable_provider('tunwg')
+
+# Включить обратно
+enable_provider('tunwg')
 ```
 
-## Доступные провайдеры
+Отключённый провайдер не попадает в `get_share_link('all', ...)`, `try_all()` и `benchmark()`,
+но его функция (`get_tunwg_url`) остаётся доступна напрямую.
+
+---
+
+### Утилиты
+
+```python
+from colab_tunnel import download, run, WORK_FOLDER
+
+# Скачать файл с прогрессом
+path = download('https://example.com/file.tar.gz', save_path='/tmp')
+
+# Выполнить shell-команду
+result = run('echo hello', timeout=10)
+print(result['status_code'], result['output'])
+
+# Рабочая папка (по умолчанию /content/.config)
+print(WORK_FOLDER)
+```
 
-| Имя           | Описание                         |
-|---------------|----------------------------------|
-| `cloudflared` | Cloudflare Tunnel (рекомендуется)|
-| `gradio`      | Gradio share tunnel              |
-| `tmole`       | Tunnelmole                       |
-| `tunwg`       | tunwg                            |
-| `localt`      | localt (go_localt)               |
-| `native`      | Google Colab встроенный прокси   |
-| `all`         | Попробовать все сразу            |
+---
 
 ## Конфигурация
 
-По умолчанию бинарники туннелей скачиваются в `/content`.
-Для переопределения установите переменную окружения до импорта пакета:
+| Переменная окружения | По умолчанию       | Описание                           |
+|----------------------|--------------------|------------------------------------|
+| `TUNNEL_WORK_DIR`    | `/content/.config` | Папка для бинарников и кэша        |
+| `TEST_SERVER_PATH`   | —                  | Путь к бинарнику тестового сервера |
 
 ```python
 import os
-os.environ['COLAB_PROXY_WORK_DIR'] = '/tmp/proxy'
+os.environ['TUNNEL_WORK_DIR'] = '/tmp/tunnels'
+
+from colab_tunnel import get_share_link  # подхватит новый путь
+```
+
+> **Важно:** переменная `TUNNEL_WORK_DIR` должна быть установлена **до** первого импорта `colab_tunnel`.
+
+---
+
+## Добавление своего провайдера
+
+```python
+from colab_tunnel import tunnel_provider, get_share_link
+
+@tunnel_provider('myprovider')
+def get_myprovider_url(port: int) -> str:
+    # Запустить бинарник/SSH и вернуть публичный URL
+    return 'https://...'
+
+# Провайдер сразу доступен
+link = get_share_link('myprovider', 7860)
+```
+
+Для провайдеров на основе бинарных утилит удобно использовать `get_revproxy_url`:
+
+```python
+from colab_tunnel._tunnels import get_revproxy_url
+from colab_tunnel._config import WORK_FOLDER
+from colab_tunnel import tunnel_provider
+
+@tunnel_provider('myprovider')
+def get_myprovider_url(port: int) -> str:
+    return get_revproxy_url(
+        bin_url='https://example.com/mytunnel-linux-amd64',
+        need_unpack=False,
+        bin_path=WORK_FOLDER / 'mytunnel',
+        start_commands=[str(WORK_FOLDER / 'mytunnel'), str(port)],
+        read_from_stderr=False,
+        url_pattern=r'https://\S+\.mytunnel\.io',
+        timeout=20.0,
+    )
+```
+
+---
+
+## Разработка
+
+```bash
+git clone --depth 1 https://github.com/imbecility/colab-tunnel
+cd colab-tunnel
+pip install -e ".[dev]"
+
+# Запустить тесты (не требуют сети)
+pytest tests/
+
+# Тесты регулярных выражений провайдеров
+pytest tests/test_regex.py -v
+
+# Тесты утилит (требуют Unix)
+pytest tests/test_utils.py -v
+```
+
+### Структура проекта
+
+```
+colab_tunnel/
+├── __init__.py       # Публичный API
+├── _config.py        # Пути и HTTP-заголовки
+├── _logger.py        # Логгер (по умолчанию WARNING)
+├── _registry.py      # Реестр провайдеров (@tunnel_provider)
+├── _utils.py         # Утилиты: процессы, сеть, ар��ивы
+├── _tunnels.py       # Провайдеры на основе бинарников
+├── _ssh.py           # SSH-провайдеры
+└── _diagnostics.py   # Бенчмарк
+
+tests/
+├── test_regex.py     # Валидация regex-паттернов провайдеров
+└── test_utils.py     # Тесты утилитарных функций
+```
+
+### Детальный лог
+
+```python
+import logging
+logging.getLogger('colab_tunnel').setLevel(logging.DEBUG)
+```
+
+---
+
+## Лицензия
 
-from colab_proxy import get_share_link
-```
+MIT

colab_tunnel/__init__.py

@@ -0,0 +1,151 @@
+"""
+colab-tunnel — утилиты для туннелирования веб-интерфейсов в Google Colab.
+
+Быстрый старт:
+
+from colab_tunnel import get_share_link
+link = get_share_link('srvus', 7860)
+print(link)
+
+Запуск всех провайдеров параллельно:
+
+from colab_tunnel import try_all
+print(try_all(7860))
+
+Бенчмарк — найти лучший провайдер прямо сейчас:
+
+from colab_tunnel import benchmark
+results = benchmark()
+print(results)
+
+Добавить собственный провайдер:
+
+from colab_tunnel import tunnel_provider
+
+@tunnel_provider('myprovider')
+def get_myprovider_url(port: int) -> str:
+    ...
+"""
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+from ._config import WORK_FOLDER
+from ._logger import logger
+from ._registry import proxies_functions, tunnel_provider, list_providers, enable_provider, disable_provider
+from ._utils import run, download
+
+# Импорт модулей регистрирует провайдеров через @tunnel_provider
+from . import _tunnels  # noqa: F401
+from . import _ssh      # noqa: F401
+
+# Прямой доступ к функциям провайдеров (обратная совместимость)
+from ._tunnels import (
+    get_tmole_url,
+    get_tunwg_url,
+    get_cloudflared_url,
+    get_localt_url,
+    get_gradio_url,
+    get_native_url,
+    get_mmar_url,
+    get_tunnelite_url,
+    get_beeceptor_url,
+    get_bore_url,
+    get_boredigital_url,
+)
+from ._ssh import (
+    get_optimistix_url,
+    get_srvus_url,
+    get_serveo_url,
+    get_localhostrun_url,
+)
+from ._diagnostics import benchmark, TunnelBenchmarkResult
+
+__version__ = '1.1.0'
+
+__all__ = [
+    # Основной API
+    'get_share_link',
+    'try_all',
+    'benchmark',
+    'TunnelBenchmarkResult',
+    # Реестр (для расширения)
+    'disable_provider',
+    'enable_provider',
+    'list_providers',
+    'proxies_functions',
+    'tunnel_provider',
+    # Провайдеры (прямой доступ)
+    'get_tmole_url',
+    'get_tunwg_url',
+    'get_cloudflared_url',
+    'get_localt_url',
+    'get_gradio_url',
+    'get_native_url',
+    'get_mmar_url',
+    'get_tunnelite_url',
+    'get_beeceptor_url',
+    'get_bore_url',
+    'get_boredigital_url',
+    'get_optimistix_url',
+    'get_srvus_url',
+    'get_serveo_url',
+    'get_localhostrun_url',
+    # Утилиты
+    'download',
+    'run',
+    'WORK_FOLDER',
+    'logger',
+]
+
+
+def try_all(port: int) -> str:
+    """
+    Параллельно запускает все зарегистрированные провайдеры туннелей.
+
+    В отличие от benchmark(), не измеряет метрики точно, зато возвращает
+    все работающие ссылки в разы быстрее — за время самого медленного провайдера
+    вместо суммы времён всех провайдеров.
+
+    Args:
+        port: Локальный порт для туннелирования.
+
+    Returns:
+        Строка со всеми полученными ссылками в формате 'провайдер: URL'.
+    """
+    results: list[str] = []
+
+    with ThreadPoolExecutor(max_workers=len(proxies_functions)) as executor:
+        futures = {
+            executor.submit(func, port): name
+            for name, func in proxies_functions.items()
+        }
+        for future in as_completed(futures):
+            name = futures[future]
+            try:
+                url = future.result()
+                results.append(f'{name}: {url}')
+            except Exception as e:
+                logger.warning(f'[try_all] {name}: {e}')
+
+    return '\n'.join(results)
+
+
+def get_share_link(host: str, port: int) -> str:
+    """
+    Получает публичную ссылку на локальный порт через указанный туннель.
+
+    Args:
+        host: Имя провайдера или 'all' для параллельного запуска всех.
+              Доступные провайдеры: list(proxies_functions.keys()).
+        port: Локальный порт веб-интерфейса.
+
+    Returns:
+        Публичная URL-ссылка (или несколько строк при host='all').
+    """
+    if host in proxies_functions:
+        return proxies_functions[host](port)
+
+    if host == 'all':
+        return try_all(port)
+
+    available = ', '.join(proxies_functions.keys())
+    return f'Провайдер "{host}" не найден. Доступные: {available}'

colab_tunnel/_config.py

@@ -0,0 +1,55 @@
+from os import environ
+from pathlib import Path
+
+# Переопределяется переменной окружения TUNNEL_WORK_DIR
+WORK_FOLDER = Path(environ.get('TUNNEL_WORK_DIR', '/content/.config'))
+
+test_server_bin_url = 'https://github.com/imbecility/colab-tunnel/releases/download/test_server/test_server'
+
+test_server_bin  = WORK_FOLDER / 'test_server'
+cloudflare_bin   = WORK_FOLDER / 'cloudflared'
+tmole_bin        = WORK_FOLDER / 'tmole'
+tunwg_bin        = WORK_FOLDER / 'tunwg'
+go_localt_bin    = WORK_FOLDER / 'go_localt'
+gradio_bin       = WORK_FOLDER / 'frpc_linux_amd64'
+mmar_bin         = WORK_FOLDER / 'mmar'
+tunnelite_bin    = WORK_FOLDER / 'tunnelite'
+beeceptor_bin    = WORK_FOLDER / 'beeceptor-cli'
+bore_bin         = WORK_FOLDER / 'bore'
+boredigital_bin  = WORK_FOLDER / 'bore_digital'
+colab_native_url = WORK_FOLDER / 'colab_url.txt'
+links_file       = WORK_FOLDER / 'links.txt'
+
+HEADERS = {
+    'accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7',
+    'accept-language': 'ru-RU,ru;q=0.9,en-US;q=0.8,en;q=0.7',
+    'cache-control': 'no-cache',
+    'device-memory': '8',
+    'downlink': '10.0',
+    'dpr': '1.5',
+    'ect': '4g',
+    'origin': 'https://colab.research.google.com',
+    'pragma': 'no-cache',
+    'priority': 'u=0, i',
+    'referer': 'https://colab.research.google.com',
+    'rtt': '200',
+    'sec-ch-ua': '"Google Chrome";v="148", "Not?A)Brand";v="24", "Chromium";v="148"',
+    'sec-ch-ua-arch': '"x86"',
+    'sec-ch-ua-bitness': '"64"',
+    'sec-ch-ua-full-version': '"148.0.7778.168"',
+    'sec-ch-ua-full-version-list': '"Google Chrome";v="148.0.7778.168", "Not?A)Brand";v="24.0.0.0", "Chromium";v="148.0.7778.168"',
+    'sec-ch-ua-mobile': '?0',
+    'sec-ch-ua-model': '""',
+    'sec-ch-ua-platform': '"Windows"',
+    'sec-ch-ua-platform-version': '"19.0.0"',
+    'sec-ch-ua-wow64': '?0',
+    'sec-ch-viewport-height': '592',
+    'sec-ch-viewport-width': '1216',
+    'sec-fetch-dest': 'document',
+    'sec-fetch-mode': 'navigate',
+    'sec-fetch-site': 'same-origin',
+    'sec-fetch-user': '?1',
+    'upgrade-insecure-requests': '1',
+    'user-agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/148.0.7778.168 Safari/537.36',
+    'viewport-width': '1216'
+}

colab_tunnel/_diagnostics.py

@@ -0,0 +1,296 @@
+"""
+Диагностика и бенчмарк провайдеров туннелей.
+
+Использование:
+
+from colab_tunnel import benchmark
+results = benchmark()                   # все провайдеры
+results = benchmark(['serveo', 'bore']) # выборочно
+"""
+import os
+import socket
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+from requests import get as get_url
+
+from ._config import test_server_bin, test_server_bin_url
+from ._logger import logger
+from ._registry import proxies_functions
+from ._utils import run, kill_process_by_name, download
+
+
+@dataclass
+class TunnelBenchmarkResult:
+    """Результат тестирования одного провайдера."""
+    name: str
+    url: Optional[str]   = None
+    tunnel_time: float   = 0.0       # Время получения ссылки (сек)
+    latency: Optional[float] = None  # RTT до публичного URL (сек)
+    success: bool        = False
+    error: Optional[str] = None
+
+
+def find_free_port() -> int:
+    """Находит свободный TCP-порт в системе."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(('', 0))
+        s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        return s.getsockname()[1]
+
+
+def _find_test_server_bin() -> Path:
+    """
+    Ищет бинарник тестового сервера в следующем порядке:
+    1. Переменная окружения TEST_SERVER_PATH
+    2. ../test_server/test_server (рядом с пакетом)
+    3. ./test_server/test_server (текущая директория)
+    Если не нашел - скачивает.
+    """
+    candidates: list[Path] = []
+
+    env = os.environ.get('TEST_SERVER_PATH')
+    env_path = Path(env) if env else None
+    if env:
+        candidates.append(env_path)
+    if test_server_bin.exists():
+        candidates.append(test_server_bin)
+
+    candidates += [
+        Path(__file__).parent.parent / 'test_server' / 'test_server',
+        Path.cwd() / 'test_server' / 'test_server',
+    ]
+
+    bin_path = None
+    for path in candidates:
+        if path.exists() and path.is_file():
+            bin_path = path
+
+    if not bin_path:
+        downloaded = download(test_server_bin_url, save_path=test_server_bin.parent, progress=False)
+        if downloaded and downloaded.exists():
+            downloaded.chmod(0o755)
+            return downloaded
+
+    raise FileNotFoundError(
+        'Бинарник тестового сервера не найден. '
+        'Укажите путь через переменную окружения TEST_SERVER_PATH.'
+    )
+
+
+def _start_test_server(server_bin: Path, port: int) -> None:
+    """Запускает тестовый HTTP-сервер в daemon-режиме."""
+    server_bin.chmod(0o755)
+    run(f'"{server_bin}" -d -p {port}', timeout=10)
+    time.sleep(1.5)  # Даём серверу время на запуск
+    logger.debug(f'Тестовый сервер запущен на порту {port}.')
+
+
+def _stop_test_server(server_bin: Path) -> None:
+    """Останавливает тестовый HTTP-сервер."""
+    kill_process_by_name(server_bin.name)
+    logger.debug('Тестовый сервер остановлен.')
+
+
+def _check_url_latency(
+    url: str,
+    timeout: float = 10.0,
+    warmup_retries: int = 3,
+    warmup_delay: float = 5.0,
+) -> Optional[float]:
+    """
+    Проверяет доступность публичного URL и возвращает RTT.
+
+    Некоторые провайдеры (cloudflared, tunnelite) анонсируют URL раньше,
+    чем маршрут фактически распространяется по их сети. cloudflared
+    обычно требует 5–15 секунд после получения URL.
+    Делаем несколько попыток с паузой между ними.
+
+    Returns:
+        RTT в секундах, или None если URL недоступен после всех попыток.
+    """
+    # Убираем строку с IPv4-паролем, если провайдер вернул её второй строкой
+    clean_url = url.split('\n')[0].strip()
+
+    for attempt in range(warmup_retries):
+        if attempt > 0:
+            logger.debug(
+                f'Повтор проверки доступности {attempt + 1}/{warmup_retries}: {clean_url}'
+            )
+            time.sleep(warmup_delay)
+        try:
+            t = time.time()
+            resp = get_url(clean_url, timeout=timeout, allow_redirects=True)
+            elapsed = round(time.time() - t, 3)
+            if 200 <= resp.status_code < 400:
+                return elapsed
+            logger.debug(f'HTTP {resp.status_code} от {clean_url}')
+        except Exception as e:
+            logger.debug(f'Попытка {attempt + 1}: {e}')
+
+    return None
+
+
+def _print_report(results: list[TunnelBenchmarkResult]) -> None:
+    """Выводит форматированную таблицу результатов."""
+    W = {'name': 14, 'status': 10, 'tunnel': 14, 'latency': 12}
+    total_w = sum(W.values()) + 38  # 38 — ширина колонки URL
+    sep = '=' * total_w
+
+    print(f'\n{sep}')
+    print(f'{"БЕНЧМАРК ПРОВАЙДЕРОВ ТУННЕЛЕЙ":^{total_w}}')
+    print(sep)
+    print(
+        f'{"Провайдер":<{W["name"]}}'
+        f'{"Статус":<{W["status"]}}'
+        f'{"Туннель":<{W["tunnel"]}}'
+        f'{"Задержка":<{W["latency"]}}'
+        f'URL / Ошибка'
+    )
+    print('-' * total_w)
+
+    for r in results:
+        status  = '✓ OK  ' if r.success else '✗ FAIL'
+        t_str   = f'{r.tunnel_time:.2f}с'
+        lat_str = f'{r.latency * 1000:.0f}мс' if r.latency else '—'
+        detail  = (r.url or r.error or '').split('\n')[0]
+        if len(detail) > 38:
+            detail = detail[:35] + '…'
+        print(
+            f'{r.name:<{W["name"]}}'
+            f'{status:<{W["status"]}}'
+            f'{t_str:<{W["tunnel"]}}'
+            f'{lat_str:<{W["latency"]}}'
+            f'{detail}'
+        )
+
+    print(sep)
+    ok = [r for r in results if r.success]
+    print(f'Итого: {len(ok)}/{len(results)} провайдеров работают.')
+
+    if ok:
+        fastest = min(ok, key=lambda r: r.tunnel_time)
+        print(f'Быстрейший запуск  : {fastest.name} ({fastest.tunnel_time:.2f}с)')
+        with_lat = [r for r in ok if r.latency]
+        if with_lat:
+            lowest = min(with_lat, key=lambda r: r.latency)  # type: ignore[arg-type]
+            print(f'Минимальная задержка: {lowest.name} ({lowest.latency * 1000:.0f}мс)')  # type: ignore[operator]
+
+    # Пояснение для native — его URL требует сессионные куки Google Colab
+    native_result = next((r for r in results if r.name == 'native'), None)
+    if native_result and native_result.success and not native_result.latency:
+        print('\n  ℹ native: URL работает, но требует Google-авторизации —')
+        print('    внешняя проверка без куки браузера всегда будет недоступна.')
+    print()
+
+
+def benchmark(
+    providers: list[str] | None = None,
+    timeout_per_provider: float = 30.0,
+    latency_timeout: float = 10.0,
+    print_report: bool = True,
+) -> list[TunnelBenchmarkResult]:
+    """
+    Последовательно тестирует провайдеров туннелей и собирает метрики.
+
+    По умолчанию тестирует только активных провайдеров (из proxies_functions).
+    Передать список имён явно — включая отключённых — можно через параметр providers.
+
+    Схема работы:
+    1. Запускает тестовый HTTP-сервер.
+    2. Последовательно запускает каждого провайдера, измеряя время старта.
+    3. Сразу проверяет RTT полученного URL.
+    4. После всех провайдеров — второй проход RTT для тех, кто не ответил
+       с первого раза (cloudflared, tunnelite: маршрут распространяется 10–15с).
+    5. Останавливает тестовый сервер (блок finally).
+    6. Выводит форматированный отчёт.
+
+    Args:
+        providers:            Имена провайдеров. None — все активные.
+        timeout_per_provider: Таймаут ожидания ссылки от провайдера (сек).
+        latency_timeout:      Таймаут проверки RTT (сек).
+        print_report:         Вывести таблицу результатов.
+
+    Returns:
+        Список TunnelBenchmarkResult.
+    """
+    server_bin = _find_test_server_bin()
+    port       = find_free_port()
+
+    # Если провайдеры переданы явно — ищем в _all_providers (включая отключённых).
+    # Если нет — берём только активных из proxies_functions.
+    if providers is not None:
+        from ._registry import _all_providers
+        unknown = [n for n in providers if n not in _all_providers]
+        if unknown:
+            raise ValueError(
+                f'Неизвестные провайдеры: {unknown}. '
+                f'Все зарегистрированные: {list(_all_providers)}'
+            )
+        names = providers
+        func_map = _all_providers
+    else:
+        names    = list(proxies_functions.keys())
+        func_map = proxies_functions
+
+    print(f'Бенчмарк: {len(names)} провайдеров, порт {port}.')
+    _start_test_server(server_bin, port)
+    print('Тестовый сервер запущен.\n')
+
+    results: list[TunnelBenchmarkResult] = []
+
+    try:
+        # Основной проход: запуск + первая проверка RTT
+        for name in names:
+            func = func_map[name]
+            print(f'[{name:<12}] запуск...', end=' ', flush=True)
+            result = TunnelBenchmarkResult(name=name)
+            t_start = time.time()
+
+            try:
+                url = func(port)
+                result.tunnel_time = round(time.time() - t_start, 2)
+                result.url     = url
+                result.success = True
+                print(f'OK ({result.tunnel_time:.2f}с). Проверка...', end=' ', flush=True)
+
+                result.latency = _check_url_latency(url, timeout=latency_timeout)
+                if result.latency:
+                    print(f'RTT {result.latency * 1000:.0f}мс')
+                else:
+                    print('URL недоступен (туннель ещё поднимается?)')
+
+            except Exception as e:
+                result.tunnel_time = round(time.time() - t_start, 2)
+                result.error = str(e)
+                print(f'ОШИБКА: {str(e)[:100]}')
+                logger.debug(f'[{name}] детали:', exc_info=True)
+
+            results.append(result)
+
+        # Второй проход: RTT для провайдеров с warmup-задержкой
+        # К этому моменту прошло достаточно времени (пока тестировались
+        # остальные провайдеры), чтобы маршруты cloudflared/tunnelite
+        # успели распространиться по сети провайдера.
+        needs_recheck = [
+            r for r in results
+            if r.success and r.latency is None and r.name != 'native'
+        ]
+        if needs_recheck:
+            print(f'\nПовторная проверка RTT ({len(needs_recheck)} провайдеров)...')
+            for r in needs_recheck:
+                r.latency = _check_url_latency(r.url, timeout=latency_timeout)  # type: ignore[arg-type]
+                status = f'RTT {r.latency * 1000:.0f}мс' if r.latency else 'всё ещё недоступен'
+                print(f'  [{r.name:<12}] {status}')
+
+    finally:
+        print()
+        _stop_test_server(server_bin)
+        print('Тестовый сервер остановлен.')
+
+    if print_report:
+        _print_report(results)
+
+    return results

colab_tunnel/_logger.py

@@ -0,0 +1,17 @@
+"""
+Централизованный логгер для библиотеки colab_tunnel.
+
+Управление детализацией:
+
+import logging
+logging.getLogger('colab_tunnel').setLevel(logging.DEBUG)
+"""
+import logging
+
+logger = logging.getLogger('colab_tunnel')
+
+if not logger.handlers:
+    _handler = logging.StreamHandler()
+    _handler.setFormatter(logging.Formatter('[%(name)s] %(levelname)s: %(message)s'))
+    logger.addHandler(_handler)
+    logger.setLevel(logging.WARNING)

colab_tunnel/_registry.py

@@ -0,0 +1,91 @@
+"""
+Реестр провайдеров туннелей.
+
+Регистрация нового провайдера:
+
+@tunnel_provider('myprovider')
+def get_myprovider_url(port: int) -> str: ...
+
+Отключить провайдера (сервис временно недоступен):
+
+@tunnel_provider('tunwg', enabled=False)
+# или в рантайме:
+disable_provider('tunwg')
+
+Включить обратно:
+
+enable_provider('tunwg')
+
+Посмотреть статус всех:
+
+list_providers()
+"""
+from typing import Callable
+
+# Активные провайдеры — используются get_share_link(), try_all(), benchmark()
+proxies_functions: dict[str, Callable[[int], str]] = {}
+
+# Все зарегистрированные провайдеры (активные + отключённые)
+_all_providers: dict[str, Callable[[int], str]] = {}
+
+# Имена отключённых провайдеров
+_disabled_providers: set[str] = set()
+
+
+def tunnel_provider(name: str, *, enabled: bool = True) -> Callable:
+    """
+    Декоратор регистрации провайдера туннеля.
+
+    Args:
+        name:    Уникальное имя провайдера.
+        enabled: False — провайдер зарегистрирован, но не активен.
+                 Включить позднее через enable_provider(name).
+    """
+    def decorator(func: Callable[[int], str]) -> Callable[[int], str]:
+        _all_providers[name] = func
+        if enabled:
+            proxies_functions[name] = func
+        else:
+            _disabled_providers.add(name)
+        return func
+    return decorator
+
+
+def disable_provider(name: str) -> None:
+    """
+    Деактивирует провайдера: убирает из активного реестра.
+    Функция сохраняется — включить обратно через enable_provider().
+
+    Raises:
+        KeyError: Провайдер с таким именем не зарегистрирован.
+    """
+    if name not in _all_providers:
+        raise KeyError(f'Провайдер "{name}" не зарегистрирован. Доступные: {list(_all_providers)}')
+    proxies_functions.pop(name, None)
+    _disabled_providers.add(name)
+
+
+def enable_provider(name: str) -> None:
+    """
+    Активирует ранее отключённого провайдера.
+
+    Raises:
+        KeyError: Провайдер с таким именем не зарегистрирован.
+    """
+    if name not in _all_providers:
+        raise KeyError(f'Провайдер "{name}" не зарегистрирован. Доступные: {list(_all_providers)}')
+    _disabled_providers.discard(name)
+    proxies_functions[name] = _all_providers[name]
+
+
+def list_providers() -> dict[str, bool]:
+    """
+    Возвращает статус всех зарегистрированных провайдеров.
+
+    Returns:
+        Словарь {имя: активен}, в порядке регистрации.
+
+    Пример вывода:
+        {'cloudflared': True, 'tunwg': False, 'bore': True, ...}
+    """
+    return {name: (name not in _disabled_providers) for name in _all_providers}

colab_tunnel/_ssh.py

@@ -0,0 +1,159 @@
+"""
+Провайдеры туннелей на основе SSH.
+"""
+import subprocess
+from atexit import register as exit_register
+from pathlib import Path
+from subprocess import DEVNULL, PIPE, Popen, TimeoutExpired
+
+from ._logger import logger
+from ._registry import tunnel_provider
+from ._utils import kill_process_by_name, terminate_process, drain_process_output, read_until_pattern
+
+# Реестр активных SSH-туннелей: имя процесса → объект Popen
+# dict вместо list — предотвращает накопление мёртвых процессов при повторных вызовах
+_active_tunnels: dict[str, Popen] = {}
+
+_cmd = [
+    'ssh',
+    '-o', 'StrictHostKeyChecking=no',
+    '-o', 'UserKnownHostsFile=/dev/null',
+    '-o', 'ExitOnForwardFailure=yes',
+    '-o', 'ServerAliveInterval=10',
+    '-o', 'ServerAliveCountMax=3',
+]
+
+
+def _register_active_tunnel(name: str, process: Popen) -> None:
+    """Регистрирует туннель, корректно завершая предыдущий с тем же именем."""
+    if name in _active_tunnels:
+        old = _active_tunnels[name]
+        try:
+            old.terminate()
+            old.wait(timeout=3)
+        except TimeoutExpired:
+            old.kill()
+            old.wait()
+        except Exception:
+            pass
+    _active_tunnels[name] = process
+
+
+def ensure_ssh_key() -> None:
+    """Гарантирует наличие ed25519 SSH-ключа. Генерирует без пароля при отсутствии."""
+    ssh_dir = Path.home() / '.ssh'
+    ssh_dir.mkdir(mode=0o700, parents=True, exist_ok=True)
+    key_file = ssh_dir / 'id_ed25519'
+
+    if not key_file.exists():
+        subprocess.run(
+            ['ssh-keygen', '-t', 'ed25519', '-N', '', '-f', str(key_file)],
+            stdout=DEVNULL,
+            stderr=DEVNULL,
+        )
+        logger.debug('SSH-ключ ed25519 сгенерирован.')
+
+
+def get_ssh_tunnel_url(
+        start_commands: list[str],
+        process_name: str,
+        url_pattern: str,
+        timeout: float = 15.0,
+) -> str:
+    """
+    Запускает SSH-туннельный процесс и ждёт появления публичного URL.
+
+    stdin намеренно оставляется ОТКРЫТЫМ: SSH завершается при получении EOF,
+    что прервало бы туннель. Объект процесса сохраняется в _active_tunnels
+    для предотвращения сборки мусора.
+
+    Args:
+        start_commands: Полная команда SSH с флагами.
+        process_name:   Идентификатор процесса (часть адреса хоста).
+        url_pattern:    Regex для поиска URL в выводе.
+        timeout:        Таймаут ожидания URL в секундах.
+
+    Returns:
+        Публичный URL туннеля.
+    """
+    ensure_ssh_key()
+    kill_process_by_name(process_name)
+
+    process = Popen(start_commands, stdout=PIPE, stderr=PIPE, stdin=PIPE)
+
+    try:
+        url, _ = read_until_pattern(
+            process=process,
+            url_pattern=url_pattern,
+            timeout=timeout,
+            read_both_streams=True,  # SSH может писать URL в stdout или stderr
+        )
+    except RuntimeError:
+        process.terminate()
+        try:
+            process.wait(timeout=3)
+        except TimeoutExpired:
+            process.kill()
+            process.wait()
+        kill_process_by_name(process_name)
+        raise
+
+    drain_process_output(process)
+    _register_active_tunnel(process_name, process)
+    exit_register(terminate_process, process_name, process)
+
+    logger.debug(f'[{process_name}] SSH-туннель: {url}')
+    return url
+
+
+# ---------------------------------------------------------------------------
+# Провайдеры
+# ---------------------------------------------------------------------------
+
+@tunnel_provider('optimistix')
+def get_optimistix_url(port: int) -> str:
+    return get_ssh_tunnel_url(
+        start_commands=_cmd + [
+            '-p', '1122',
+            '-R', f'80:127.0.0.1:{port}',
+            'ssh.optimistixtunnel.com',
+        ],
+        process_name='ssh.optimistixtunnel.com',
+        url_pattern=r'https://\S+\.otnl\.link',
+    )
+
+
+@tunnel_provider('srvus')
+def get_srvus_url(port: int) -> str:
+    return get_ssh_tunnel_url(
+        start_commands=_cmd + [
+            '-R', f'1:127.0.0.1:{port}',
+            'srv.us',
+        ],
+        process_name='srv.us',
+        url_pattern=r'https://[a-z0-9]{10,}\.srv\.us/?',
+    )
+
+
+@tunnel_provider('serveo')
+def get_serveo_url(port: int) -> str:
+    return get_ssh_tunnel_url(
+        start_commands=_cmd + [
+            '-R', f'80:127.0.0.1:{port}',
+            'serveo.net',
+        ],
+        process_name='serveo.net',
+        url_pattern=r'https://\S+\.serveousercontent\.com',
+    )
+
+
+@tunnel_provider('localhostrun')
+def get_localhostrun_url(port: int) -> str:
+    return get_ssh_tunnel_url(
+        start_commands=_cmd + [
+            '-R', f'80:127.0.0.1:{port}',
+            'nokey@localhost.run',
+        ],
+        process_name='localhost.run',
+        url_pattern=r'https://(?!admin\b)[a-zA-Z0-9-]+\.(?:localhost\.run|lhr\.life)',
+    )

colab_tunnel/_tunnels.py

@@ -0,0 +1,370 @@
+"""
+Провайдеры туннелей на основе бинарных утилит.
+"""
+from atexit import register as exit_register
+from pathlib import Path
+from subprocess import PIPE, Popen
+from time import sleep
+
+from requests import get as get_url
+
+from ._config import (
+    WORK_FOLDER,
+    cloudflare_bin, tmole_bin, tunwg_bin,
+    go_localt_bin, gradio_bin, mmar_bin,
+    tunnelite_bin, beeceptor_bin, bore_bin,
+    boredigital_bin, colab_native_url, links_file,
+)
+from ._logger import logger
+from ._registry import tunnel_provider
+from ._utils import (
+    download, unpack_archive, run,
+    read_until_pattern, drain_process_output,
+    kill_process_by_name, terminate_process,
+    move_path, is_ipv4, _snapshot,
+    get_github_latest_release_url,
+)
+
+
+def get_revproxy_url(
+    bin_url: str,
+    need_unpack: bool,
+    bin_path: Path,
+    start_commands: list,
+    read_from_stderr: bool,
+    url_pattern: str = r'https://\S+',
+    timeout: float = 20.0,
+    write_link: bool = False,
+    stdin_input: str | None = None,
+    extra_env: dict[str, str] | None = None,
+    read_both_streams: bool = False,
+) -> str:
+    """
+    Универсальный запуск бинарного туннельного провайдера.
+
+    При первом вызове скачивает и устанавливает бинарник.
+    Использует неблокирующее чтение вывода для поиска URL.
+
+    Args:
+        bin_url:          URL скачивания бинарника (или архива).
+        need_unpack:      Нужно ли распаковывать архив.
+        bin_path:         Целевой путь бинарника на диске.
+        start_commands:   Команда запуска со всеми аргументами.
+        read_from_stderr: Искать URL в stderr (иначе в stdout).
+        url_pattern:      Regex для поиска публичного URL.
+        timeout:          Максимальное время ожидания URL (сек).
+        write_link:       Сохранять ли ссылку в links.txt.
+        stdin_input:      Строка для отправки в stdin процесса.
+        extra_env: Дополнительные переменные окружения для процесса.
+                   Накладываются поверх os.environ (не заменяют его).
+        read_both_streams: Читать ли оба потока.
+
+    Returns:
+        Публичный URL туннеля.
+    """
+    # ── Установка бинарника ──────────────────────────────────────────────
+    if not bin_path.exists():
+        WORK_FOLDER.mkdir(parents=True, exist_ok=True)
+        snapshot_before = _snapshot(WORK_FOLDER)
+
+        if need_unpack:
+            archive = download(bin_url, save_path=WORK_FOLDER, progress=False)
+            unpack_archive(archive, WORK_FOLDER, rm_archive=True)
+        else:
+            download(bin_url, save_path=bin_path.parent, progress=False)
+
+        new_files = list(_snapshot(WORK_FOLDER) - snapshot_before)
+
+        if not new_files:
+            raise RuntimeError(
+                f'В {WORK_FOLDER} не появилось новых файлов после загрузки {bin_url}'
+            )
+
+        if len(new_files) == 1:
+            move_path(new_files[0], bin_path)
+        else:
+            # Несколько файлов (например, архив с доп. файлами) — берём наибольший
+            largest = max(new_files, key=lambda f: f.stat().st_size)
+            move_path(largest, bin_path)
+            for f in new_files:
+                if f != largest and f.exists():
+                    f.unlink(missing_ok=True)
+
+        bin_path.chmod(0o755)
+        logger.debug(f'Установлен бинарник: {bin_path}')
+
+    # ── Завершение предыдущего экземпляра ───────────────────────────────
+    kill_process_by_name(bin_path.name)
+    # ── Подготовка окружения ─────────────────────────────────────────────
+    import os as _os
+    proc_env = _os.environ.copy()
+    if extra_env:
+        proc_env.update(extra_env)
+    # ── Запуск процесса ──────────────────────────────────────────────────
+    stdin_flag = PIPE if stdin_input is not None else None
+    process = Popen(
+        start_commands,
+        stdout=PIPE, stderr=PIPE, stdin=stdin_flag,
+        env=proc_env,  # ← передаём окружение
+    )
+    if stdin_input is not None and process.stdin:
+        try:
+            process.stdin.write(stdin_input.encode())
+            process.stdin.flush()
+        finally:
+            process.stdin.close()  # Сигнал EOF — многие утилиты ждут его перед стартом
+
+    # ── Чтение URL из вывода ─────────────────────────────────────────────
+    try:
+        url, full_output = read_until_pattern(
+            process=process,
+            url_pattern=url_pattern,
+            timeout=timeout,
+            read_from_stderr=read_from_stderr,
+            read_both_streams=read_both_streams,  # ← передаём дальше
+        )
+    except RuntimeError:
+        kill_process_by_name(bin_path.name)
+        try:
+            process.wait(timeout=3)
+        except Exception:
+            process.kill()
+            process.wait()
+        raise
+
+    # Слив вывода в фоне — предотвращает блокировку из-за переполнения пайпа
+    drain_process_output(process)
+
+    # Проверка наличия IPv4 в выводе (пароль/IP у некоторых провайдеров)
+    ipv4 = next(
+        (ln.strip() for ln in full_output.splitlines() if is_ipv4(ln.strip())),
+        None,
+    )
+
+    exit_register(terminate_process, bin_path.name, process)
+
+    if write_link:
+        try:
+            links_file.write_text(url)
+        except Exception as e:
+            logger.warning(f'Не удалось записать ссылку в {links_file}: {e}')
+
+    logger.debug(f'[{bin_path.name}] Туннель: {url}')
+    return f'{url}\n пароль(IP): {ipv4}' if ipv4 else url
+
+
+# ---------------------------------------------------------------------------
+# Провайдеры
+# ---------------------------------------------------------------------------
+
+@tunnel_provider('tmole')
+def get_tmole_url(port: int) -> str:
+    return get_revproxy_url(
+        bin_url='https://tunnelmole.com/downloads/tmole-linux.gz',
+        need_unpack=True,
+        bin_path=tmole_bin,
+        start_commands=[str(tmole_bin), str(port)],
+        read_from_stderr=False,
+        timeout=20.0,
+    )
+
+
+@tunnel_provider('tunwg', enabled=False)  # Сервис недоступен с 2026-06-16, включить: enable_provider('tunwg')
+def get_tunwg_url(port: int) -> str:
+    return get_revproxy_url(
+        bin_url='https://github.com/ntnj/tunwg/releases/latest/download/tunwg',
+        need_unpack=False,
+        bin_path=tunwg_bin,
+        start_commands=[str(tunwg_bin), f'--forward=http://127.0.0.1:{port}'],
+        read_from_stderr=True,
+        timeout=20.0,
+    )
+
+
+@tunnel_provider('cloudflared')
+def get_cloudflared_url(port: int) -> str:
+    return get_revproxy_url(
+        bin_url='https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64',
+        need_unpack=False,
+        bin_path=cloudflare_bin,
+        start_commands=[str(cloudflare_bin), 'tunnel', '--url', f'http://127.0.0.1:{port}'],
+        read_from_stderr=True,
+        url_pattern=r'(?P<url>https?://\S+\.trycloudflare\.com)',
+        timeout=25.0,
+    )
+
+
+@tunnel_provider('localt')
+def get_localt_url(port: int) -> str:
+    return get_revproxy_url(
+        bin_url='https://huggingface.co/prolapse/go_localt/resolve/main/go_localt',
+        need_unpack=False,
+        bin_path=go_localt_bin,
+        start_commands=[str(go_localt_bin), str(port)],
+        read_from_stderr=False,
+        timeout=20.0,
+    )
+
+
+@tunnel_provider('gradio')
+def get_gradio_url(port: int) -> str:
+    max_attempts = 3
+    last_error: Exception | None = None
+
+    for attempt in range(max_attempts):
+        try:
+            resp = get_url('https://api.gradio.app/v2/tunnel-request', timeout=10)
+            resp.raise_for_status()
+            info = resp.json()[0]
+            remote_host, remote_port = info['host'], int(info['port'])
+            cmd = [
+                str(gradio_bin), 'http', '-n', 'random',
+                '-l', str(port), '-i', '127.0.0.1',
+                '--uc', '--sd', 'random', '--ue',
+                '--server_addr', f'{remote_host}:{remote_port}',
+                '--disable_log_color',
+            ]
+            return get_revproxy_url(
+                bin_url='https://cdn-media.huggingface.co/frpc-gradio-0.1/frpc_linux_amd64',
+                need_unpack=False,
+                bin_path=gradio_bin,
+                start_commands=cmd,
+                read_from_stderr=False,
+                timeout=20.0,
+            )
+        except Exception as e:
+            last_error = e
+            if attempt < max_attempts - 1:
+                logger.warning(f'Попытка {attempt + 1} Gradio провалилась: {e}. Повтор через 5с...')
+                sleep(5)
+
+    raise RuntimeError(f'После {max_attempts} попыток Gradio-туннель не запущен: {last_error}')
+
+
+@tunnel_provider('native')
+def get_native_url(port: int) -> str:
+    """
+    Встроенный прокси Google Colab. Результат кэшируется по номеру порта.
+    """
+    try:
+        from google.colab.output import eval_js  # type: ignore[import]
+    except ImportError:
+        raise RuntimeError('get_native_url доступен только в среде Google Colab.')
+
+    cache_url_file  = colab_native_url
+    cache_port_file = colab_native_url.with_suffix('.port')
+
+    if cache_url_file.exists() and cache_port_file.exists():
+        try:
+            if int(cache_port_file.read_text().strip()) == port:
+                cached = cache_url_file.read_text().strip()
+                if cached:
+                    logger.debug(f'native URL из кэша (порт {port}): {cached}')
+                    return cached
+        except Exception:
+            pass
+
+    url = eval_js(f'google.colab.kernel.proxyPort({port})')
+
+    try:
+        WORK_FOLDER.mkdir(parents=True, exist_ok=True)
+        cache_url_file.write_text(url)
+        cache_port_file.write_text(str(port))
+    except Exception as e:
+        logger.warning(f'Не удалось кэшировать native URL: {e}')
+
+    return url
+
+
+@tunnel_provider('mmar')
+def get_mmar_url(port: int) -> str:
+    return get_revproxy_url(
+        bin_url='https://github.com/yusuf-musleh/mmar/releases/latest/download/mmar_Linux_x86_64.tar.gz',
+        need_unpack=True,
+        bin_path=mmar_bin,
+        start_commands=[str(mmar_bin), 'client', '--local-port', str(port)],
+        read_from_stderr=True,
+        url_pattern=r'(?P<url>https?://\S+\.mmar\.dev)',
+        timeout=20.0,
+    )
+
+
+@tunnel_provider('tunnelite')
+def get_tunnelite_url(port: int) -> str:
+    """
+    tunnelite — интерактивное TUI-приложение, которое проверяет isatty(stdout).
+    Без PTY оно выводит URL и сразу завершается, не поддерживая туннель → 404.
+    `script -q -c "..." /dev/null` выделяет pseudo-TTY для дочернего процесса,
+    tunnelite думает что работает в терминале и держит соединение.
+    script при этом транслирует весь вывод в свой stdout — читаем через обычный PIPE.
+    """
+    kill_process_by_name(tunnelite_bin.name)
+    return get_revproxy_url(
+        bin_url='https://github.com/hehepiska/tunnellite-linux/releases/download/latest/tunnelite',
+        need_unpack=False,
+        bin_path=tunnelite_bin,
+        start_commands=[
+            'script', '-q', '-c',
+            f'{tunnelite_bin} http://127.0.0.1:{port}',
+            '/dev/null',
+        ],
+        read_from_stderr=False,
+        url_pattern=r'(?P<url>https?://\S+\.tunnelite\.com)',
+        timeout=45.0,
+    )
+
+
+@tunnel_provider('beeceptor')
+def get_beeceptor_url(port: int) -> str:
+    return get_revproxy_url(
+        bin_url='https://cdn.beeceptor.com/downloads/cli/latest/beeceptor-cli-linux-x64.tar.gz',
+        need_unpack=True,
+        bin_path=beeceptor_bin,
+        start_commands=[str(beeceptor_bin), '-p', str(port), '-y'],
+        read_from_stderr=False,
+        url_pattern=r'(?P<url>https?://\S+\.beeceptor\.com)',
+        timeout=20.0,
+        stdin_input='\n',
+    )
+
+
+@tunnel_provider('bore')
+def get_bore_url(port: int) -> str:
+    bin_url = 'https://github.com/ekzhang/bore/releases/download/v0.6.0/bore-v0.6.0-x86_64-unknown-linux-musl.tar.gz'
+    if not bore_bin.exists():
+        try:
+            bin_url = get_github_latest_release_url(
+                'ekzhang/bore',
+                r'bore-v[\d.]+-x86_64-unknown-linux-musl\.tar\.gz',
+            )
+            logger.debug(f'Актуальный URL bore: {bin_url}')
+        except Exception as e:
+            logger.warning(f'GitHub API недоступен, используется закреплённая версия bore: {e}')
+
+    raw = get_revproxy_url(
+        bin_url=bin_url,
+        need_unpack=True,
+        bin_path=bore_bin,
+        start_commands=[str(bore_bin), 'local', str(port), '--to', 'bore.pub'],
+        # read_both_streams: bore пишет в stderr через tracing-subscriber,
+        # но читаем оба потока — на случай если конкретная сборка пишет в stdout
+        read_from_stderr=False,
+        read_both_streams=True,
+        url_pattern=r'bore\.pub:\d+',
+        timeout=20.0,
+    )
+    return f'http://{raw}/'
+
+
+
+@tunnel_provider('boredigital')
+def get_boredigital_url(port: int) -> str:
+    return get_revproxy_url(
+        bin_url='https://github.com/jkuri/bore/releases/latest/download/bore_linux_amd64',
+        need_unpack=False,
+        bin_path=boredigital_bin,
+        start_commands=[str(boredigital_bin), '-lp', str(port)],
+        read_from_stderr=False,
+        url_pattern=r'(?P<url>https://\S+\.bore\.digital)',
+        timeout=20.0,
+    )

colab_tunnel/_utils.py

@@ -0,0 +1,589 @@
+"""
+Вспомогательные утилиты: процессы, архивы, сеть, чтение потоков.
+"""
+import os
+import re
+import threading
+import time
+from os import name as os_name
+from pathlib import Path
+from shutil import move as shutil_move
+from subprocess import (
+    PIPE, Popen, STDOUT, TimeoutExpired,
+    check_output, CalledProcessError,
+)
+from sys import stdout as sys_stdout
+from typing import TypedDict
+from urllib.parse import unquote, urlparse
+
+from requests import get as get_url, head as get_head
+from requests.structures import CaseInsensitiveDict
+
+from ._config import WORK_FOLDER, HEADERS
+from ._logger import logger
+
+
+# ---------------------------------------------------------------------------
+# Типы
+# ---------------------------------------------------------------------------
+
+class RunResult(TypedDict):
+    status_code: int
+    output: str
+
+
+# ---------------------------------------------------------------------------
+# Процессы
+# ---------------------------------------------------------------------------
+
+def run(
+    command: str,
+    cwd: str | Path | None = None,
+    live_output: bool = False,
+    timeout: float | None = None,
+) -> RunResult:
+    """
+    Выполняет shell-команду, возвращает код выхода и вывод.
+
+    Args:
+        command:     Shell-команда.
+        cwd:         Рабочая директория (None — текущая).
+        live_output: Выводить прогресс в реальном времени.
+        timeout:     Таймаут в секундах (None — без ограничений).
+
+    Returns:
+        RunResult: {'status_code': int, 'output': str}.
+        При таймауте status_code == -1.
+    """
+    _encodings = ['utf-8', 'iso-8859-5', 'windows-1251', 'cp866', 'koi8-r', 'mac_cyrillic']
+    _progress_re = re.compile(r'\d+%|\d+/\d+')
+
+    def _decode(data: bytes) -> str:
+        for enc in _encodings:
+            try:
+                return data.decode(enc)
+            except UnicodeDecodeError:
+                continue
+        return data.decode('utf-8', errors='replace')
+
+    process = Popen(command, shell=True, cwd=cwd, stdout=PIPE, stderr=STDOUT)
+
+    # Режим без живого вывода: communicate() с поддержкой таймаута
+    if not live_output:
+        try:
+            stdout_data, _ = process.communicate(timeout=timeout)
+        except TimeoutExpired:
+            process.kill()
+            process.communicate()
+            msg = f'Таймаут ({timeout}с): {command}'
+            logger.warning(msg)
+            return RunResult(status_code=-1, output=msg)
+        lines = [ln.strip() for ln in _decode(stdout_data).splitlines() if ln.strip()]
+        return RunResult(status_code=process.returncode, output='\n'.join(lines))
+
+    # Режим живого вывода (для ручного использования, таймаут приблизительный)
+    final_output: list[str] = []
+    last_progress = ''
+    deadline = time.time() + timeout if timeout else None
+
+    for raw_line in iter(process.stdout.readline, b''):  # type: ignore[union-attr]
+        if deadline and time.time() > deadline:
+            process.kill()
+            process.wait()
+            final_output.append(f'[ТАЙМАУТ после {timeout}с]')
+            break
+        line = _decode(raw_line.strip())
+        if _progress_re.search(line):
+            last_progress = line
+            sys_stdout.write('\r' + line)
+            sys_stdout.flush()
+        else:
+            final_output.append(line)
+            sys_stdout.write(line + '\n')
+            sys_stdout.flush()
+
+    try:
+        process.wait(timeout=5)
+    except TimeoutExpired:
+        process.kill()
+        process.wait()
+
+    if last_progress:
+        final_output.append(last_progress)
+
+    return RunResult(status_code=process.returncode, output='\n'.join(final_output))
+
+
+def kill_process_by_name(name: str) -> None:
+    """
+    Завершает процессы текущего пользователя по подстроке имени.
+    Ограничение по UID предотвращает случайное завершение чужих процессов.
+    """
+    run(f'pkill -TERM -u "$(id -u)" -f "{name}" 2>/dev/null; true', timeout=5)
+
+
+def is_process_running(process_name: str | Path) -> bool:
+    try:
+        output = check_output(['pgrep', '-f', str(process_name)], text=True)
+        return bool(output.strip())
+    except CalledProcessError:
+        return False
+
+
+def terminate_process(process_name: str, process_obj: Popen) -> None:
+    """
+    Корректно завершает процесс туннеля.
+    Сначала SIGTERM + wait(5с), при зависании — SIGKILL.
+    """
+    for stream in (process_obj.stdout, process_obj.stderr, process_obj.stdin):
+        if stream:
+            try:
+                stream.close()
+            except Exception:
+                pass
+
+    try:
+        process_obj.terminate()
+        process_obj.wait(timeout=5)
+    except TimeoutExpired:
+        process_obj.kill()
+        process_obj.wait()
+    except Exception:
+        pass
+
+    kill_process_by_name(process_name)
+
+
+def _drain_raw(raw_stream: object) -> None:
+    """Сливает данные из сырого потока в никуда, предотвращая блокировку пайпа."""
+    try:
+        os.set_blocking(raw_stream.fileno(), True)  # type: ignore[attr-defined]
+    except Exception:
+        pass
+    try:
+        while True:
+            data = raw_stream.read(4096)  # type: ignore[attr-defined]
+            if not data:
+                break
+    except Exception:
+        pass
+
+
+def drain_process_output(process: Popen) -> None:
+    """
+    Запускает daemon-потоки для слива stdout/stderr долгоживущего процесса.
+
+    Без этого туннельный процесс заблокируется, когда системный буфер
+    пайпа (обычно 64 КБ) заполнится непрочитанными логами.
+    """
+    for stream in (process.stdout, process.stderr):
+        if stream:
+            raw = getattr(stream, 'raw', stream)
+            t = threading.Thread(target=_drain_raw, args=(raw,), daemon=True)
+            t.start()
+
+
+def read_until_pattern(
+    process: Popen,
+    url_pattern: str,
+    timeout: float = 20.0,
+    read_from_stderr: bool = False,
+    read_both_streams: bool = False,
+) -> tuple[str, str]:
+    """
+    Читает вывод процесса с таймаутом, ища URL-паттерн.
+
+    Использует блокирующие read() в daemon-потоках вместо select() +
+    неблокирующих read(). select()-подход даёт гонку при быстрых коротких
+    записях (< 1мс): select сигнализирует «readable», но к моменту вызова
+    read() данные ещё не попали в буфер пайпа — read возвращает пусто.
+    Блокирующий read в потоке этой гонки не имеет: он просто ждёт данных.
+
+    После нахождения URL потоки автоматически переходят в режим дренирования:
+    продолжают читать и отбрасывать данные, предотвращая переполнение
+    системного буфера пайпа (обычно 64 КБ) за время жизни туннеля.
+
+    Args:
+        process:           Запущенный Popen с открытыми потоками PIPE.
+        url_pattern:       Regex для поиска URL.
+        timeout:           Максимальное время ожидания (сек).
+        read_from_stderr:  Читать из stderr (иначе stdout).
+        read_both_streams: Читать из обоих потоков одновременно (для SSH).
+
+    Returns:
+        Кортеж (matched_url, full_output_so_far).
+
+    Raises:
+        RuntimeError: Паттерн не найден за timeout секунд.
+    """
+    import queue as _queue
+
+    if read_both_streams:
+        active = [s for s in (process.stdout, process.stderr) if s]
+    elif read_from_stderr:
+        active = [process.stderr] if process.stderr else []
+    else:
+        active = [process.stdout] if process.stdout else []
+
+    if not active:
+        raise RuntimeError('Потоки вывода процесса недоступны.')
+
+    q: _queue.Queue[bytes | None] = _queue.Queue()
+    drain_mode = threading.Event()
+
+    def _reader(stream) -> None:
+        """
+        Блокирующий читатель в daemon-потоке.
+        Пока URL не найден — пушит чанки в очередь.
+        После установки drain_mode — читает и отбрасывает (дренирование).
+        """
+        raw = getattr(stream, 'raw', stream)
+        try:
+            # Явно возвращаем в блокирующий режим на случай,
+            # если где-то раньше FD был переведён в неблокирующий
+            os.set_blocking(raw.fileno(), True)
+        except Exception:
+            pass
+        try:
+            while True:
+                chunk = raw.read(4096)
+                if not chunk:       # EOF — процесс закрыл поток
+                    break
+                if drain_mode.is_set():
+                    pass            # Дренирование: читаем и отбрасываем
+                else:
+                    q.put(chunk)    # Ищем URL: передаём в очередь
+        except Exception:
+            pass
+        finally:
+            # Сигнал EOF только если мы всё ещё ищем URL
+            if not drain_mode.is_set():
+                q.put(None)
+
+    for stream in active:
+        t = threading.Thread(target=_reader, args=(stream,), daemon=True)
+        t.start()
+
+    buffer = b''
+    deadline = time.time() + timeout
+    n_sentinels = 0
+
+    while time.time() < deadline:
+        remaining = max(0.01, deadline - time.time())
+        try:
+            item = q.get(timeout=min(remaining, 0.5))
+        except _queue.Empty:
+            if process.poll() is not None:
+                # Процесс завершился — дочитываем остатки из очереди
+                while True:
+                    try:
+                        item = q.get_nowait()
+                    except _queue.Empty:
+                        break
+                    if item is None:
+                        n_sentinels += 1
+                    else:
+                        buffer += item
+                break
+            continue
+
+        if item is None:
+            n_sentinels += 1
+            if n_sentinels >= len(active):
+                break       # Все читатели достигли EOF
+            continue
+
+        buffer += item
+        text = buffer.decode('utf-8', errors='ignore')
+        match = re.search(url_pattern, text)
+        if match:
+            drain_mode.set()    # Переключаем потоки в режим дренирования
+            return match.group(), text
+
+    raise RuntimeError(
+        f'URL не найден за {timeout} сек. Вывод процесса:\n'
+        + buffer.decode('utf-8', errors='ignore')
+    )
+
+
+
+def move_path(old_path: Path | str, new_path: Path | str) -> None:
+    old, new = Path(old_path), Path(new_path)
+    if not old.exists():
+        raise RuntimeError(f'Не найден исходный путь для перемещения: {old}')
+    try:
+        old.replace(new)
+    except Exception:
+        try:
+            shutil_move(str(old), str(new))
+        except Exception:
+            if os_name == 'posix':
+                run(f'mv "{old}" "{new}"')
+            else:
+                run(f'move "{old}" "{new}"')
+
+
+# ---------------------------------------------------------------------------
+# Файлы и архивы
+# ---------------------------------------------------------------------------
+
+def _snapshot(folder: Path) -> set[Path]:
+    """Рекурсивный снимок всех файлов в директории (включая вложенные папки)."""
+    if not folder.exists():
+        return set()
+    return {f for f in folder.rglob('*') if f.is_file()}
+
+
+def determine_archive_format(filepath: str | Path) -> str | None:
+    """Определяет формат архива по сигнатуре байт (magic bytes)."""
+    filepath = Path(filepath)
+    zip_sig = bytes([0x50, 0x4B, 0x03, 0x04])
+    seven_z = bytes([0x37, 0x7A, 0xBC, 0xAF, 0x27, 0x1C])
+    lzma_xz = bytes([0xFD, 0x37, 0x7A, 0x58, 0x5A])
+    tgz     = bytes([0x1F, 0x8B])
+    tbz     = bytes([0x42, 0x5A, 0x68])
+    ustar   = bytes([0x75, 0x73, 0x74, 0x61, 0x72])
+
+    with filepath.open('rb') as fh:
+        header = fh.read(262)
+
+    if header.startswith(zip_sig):   return 'zip'
+    if header.startswith(seven_z):   return '7z'
+    if header.startswith(lzma_xz):   return '7z'
+    if header.startswith(tgz):       return 'tar.gz'
+    if header.startswith(tbz):       return 'tar.bz2'
+    if header[0x101:0x101 + len(ustar)] == ustar: return 'tar'
+    return None
+
+
+def unpack_archive(
+    archive_path: str | Path,
+    dest_path: str | Path,
+    rm_archive: bool = True,
+) -> None:
+    """
+    Распаковывает архив в указанную директорию.
+
+    Поддерживает: tar, tar.gz, tar.bz2, tar.xz, gz (одиночный файл), zip, 7z.
+    При неудаче основного метода делает fallback к 7z.
+    Принимает URL — скачивает архив сам.
+    """
+    if str(archive_path).startswith(('https://', 'http://')):
+        archive_path = download(str(archive_path), save_path=WORK_FOLDER, progress=False)
+
+    archive_path = Path(archive_path)
+    dest_path    = Path(dest_path)
+
+    if not archive_path.exists():
+        raise RuntimeError(f'Архив не найден: {archive_path}')
+
+    fmt = determine_archive_format(archive_path)
+    dest_path.mkdir(parents=True, exist_ok=True)
+
+    def _rm() -> None:
+        if rm_archive:
+            archive_path.unlink(missing_ok=True)
+
+    def _try_7z() -> None:
+        result = run(
+            f'7z -bso0 -bd -mmt4 -slp -y x "{archive_path}" -o"{dest_path}"',
+            timeout=180,
+        )
+        if result['status_code'] != 0:
+            raise RuntimeError(
+                f'Не удалось распаковать {archive_path.name}.\n{result["output"]}'
+            )
+        _rm()
+
+    try:
+        if fmt == 'zip' or archive_path.suffix == '.zip':
+            r = run(f'unzip -o "{archive_path}" -d "{dest_path}"', timeout=180)
+            if r['status_code'] != 0:
+                raise RuntimeError(r['output'])
+            _rm()
+
+        elif fmt in ('7z',) or archive_path.suffix == '.7z':
+            r = run(
+                f'7z -bso0 -bd -slp -y x "{archive_path}" -o"{dest_path}"',
+                timeout=180,
+            )
+            if r['status_code'] != 0:
+                raise RuntimeError(r['output'])
+            _rm()
+
+        elif fmt in ('tar', 'tar.gz', 'tar.bz2') or archive_path.suffix in (
+            '.tar', '.tar.gz', '.tgz', '.tar.bz2', '.tar.xz', '.txz', '.gz',
+        ):
+            # GNU tar определяет формат сжатия автоматически через -xpf
+            r = run(f'tar -xpf "{archive_path}" -C "{dest_path}"', timeout=180)
+            if r['status_code'] != 0:
+                # Возможно, это одиночный gzip-файл без tar-обёртки (напр. tmole-linux.gz)
+                gz_r = run(f'gzip -df "{archive_path}"', timeout=60)
+                if gz_r['status_code'] != 0:
+                    raise RuntimeError(
+                        f'tar: {r["output"]}\ngzip: {gz_r["output"]}'
+                    )
+                # gzip -f уже удалил .gz и создал распакованный файл на месте
+                return
+            _rm()
+
+        else:
+            _try_7z()
+
+    except RuntimeError as e:
+        logger.debug(f'Основной метод распаковки не сработал ({e}), fallback к 7z.')
+        _try_7z()
+
+
+# ---------------------------------------------------------------------------
+# Сеть
+# ---------------------------------------------------------------------------
+
+def is_ipv4(address: str) -> bool:
+    pattern = re.compile(
+        r'^((25[0-5]|2[0-4]\d|[01]?\d\d?)\.){3}(25[0-5]|2[0-4]\d|[01]?\d\d?)$'
+    )
+    return bool(pattern.match(address))
+
+
+def is_valid_url(url: str, custom_headers: dict | None = None) -> bool:
+    """
+    Проверяет доступность URL (HEAD или GET запрос).
+
+    Returns:
+        True, если сервер вернул HTTP 2xx.
+    """
+    req_headers = HEADERS.copy()
+    if custom_headers:
+        req_headers.update(custom_headers)
+
+    for _ in range(2):
+        try:
+            with get_url(url, headers=req_headers, allow_redirects=True, stream=True, timeout=10) as resp:
+                if 200 <= resp.status_code < 300:
+                    return True
+        except Exception:
+            try:
+                resp = get_head(url, headers=req_headers, allow_redirects=True, timeout=10)
+                if 200 <= resp.status_code < 300:
+                    return True
+            except Exception:
+                pass
+        else:
+            break
+    return False
+
+
+def get_filename_from_headers(headers: CaseInsensitiveDict) -> str | None:
+    cd = headers.get('content-disposition')
+    if not cd:
+        return headers.get('filename')
+    for part in cd.split(';'):
+        part = part.strip()
+        if part.startswith('filename*='):
+            encoding, _, encoded = part[len('filename*='):].partition("''")
+            return unquote(encoded, encoding=encoding)
+        if part.startswith('filename='):
+            return part[len('filename='):].strip('"')
+    return None
+
+
+def download(
+    url: str,
+    filename: str | Path | None = None,
+    save_path: str | Path | None = None,
+    progress: bool = True,
+    extra_headers: dict[str, str] | None = None,
+) -> Path:
+    """
+    Скачивает файл по URL.
+
+    Args:
+        url:           URL файла.
+        filename:      Имя для сохранения (None — из заголовков или URL).
+        save_path:     Папка сохранения (None — текущая директория).
+        progress:      Показывать прогресс загрузки.
+        extra_headers: Дополнительные HTTP-заголовки.
+
+    Returns:
+        Path к скачанному файлу.
+
+    Raises:
+        RuntimeError: При ошибке сети или записи файла.
+    """
+    save_path = Path(save_path) if save_path else Path.cwd()
+    save_path.mkdir(parents=True, exist_ok=True)
+
+    req_headers = HEADERS.copy()
+    if extra_headers:
+        req_headers.update(extra_headers)
+
+    try:
+        resp = get_url(url, stream=True, allow_redirects=True, headers=req_headers, timeout=60)
+        resp.raise_for_status()
+    except Exception as e:
+        raise RuntimeError(f'Не удалось скачать файл по ссылке {url}:\n{e}')
+
+    file_size = int(resp.headers.get('content-length', 0))
+    raw_name = (
+        str(filename)
+        if filename
+        else (get_filename_from_headers(resp.headers) or Path(urlparse(resp.url).path).name)
+    )
+    file_name = Path(raw_name).name
+    file_path = save_path / file_name
+    chunk_size = max(4096, file_size // 2000) if file_size else 4096
+
+    downloaded = 0
+    start = time.time()
+    try:
+        with open(file_path, 'wb') as fp:
+            for chunk in resp.iter_content(chunk_size=chunk_size):
+                if chunk:
+                    fp.write(chunk)
+                    if progress and file_size:
+                        downloaded += len(chunk)
+                        elapsed = time.time() - start
+                        print(
+                            f'\rзагрузка {file_name}: '
+                            f'{downloaded / file_size * 100:.2f}% | {elapsed:.2f} сек.',
+                            end='',
+                        )
+    except Exception as e:
+        raise RuntimeError(f'Не удалось сохранить файл из {url}:\n{e}')
+
+    if progress and file_size:
+        print()
+
+    logger.debug(f'Скачан: {file_path} ({file_size} байт)')
+    return file_path
+
+
+def get_github_latest_release_url(repo: str, asset_pattern: str) -> str:
+    """
+    Возвращает URL загрузки актуального релизного ассета с GitHub.
+
+    Args:
+        repo:          Репозиторий в формате 'owner/repo'.
+        asset_pattern: Регулярное выражение для имени ассета.
+
+    Returns:
+        browser_download_url для найденного ассета.
+
+    Raises:
+        RuntimeError: Если ассет не найден или GitHub API недоступен.
+    """
+    api_url = f'https://api.github.com/repos/{repo}/releases/latest'
+    resp = get_url(api_url, timeout=10)
+    resp.raise_for_status()
+
+    assets = resp.json().get('assets', [])
+    for asset in assets:
+        if re.search(asset_pattern, asset['name']):
+            return asset['browser_download_url']
+
+    available = [a['name'] for a in assets]
+    raise RuntimeError(
+        f'Ассет "{asset_pattern}" не найден в {repo}. '
+        f'Доступные: {available}'
+    )

tests/test_regex.py

@@ -0,0 +1,105 @@
+"""
+Юнит-тесты для regex-паттернов поиска URL в выводе туннельных утилит.
+Тесты не требуют сети или реальных процессов.
+"""
+import re
+import pytest
+
+
+# Cloudflared───
+CF_PATTERN = r'(?P<url>https?://\S+\.trycloudflare\.com)'
+
+@pytest.mark.parametrize('text, expected', [
+    (
+        'Visit your tunnel at https://autumn-bread-1234.trycloudflare.com',
+        'https://autumn-bread-1234.trycloudflare.com',
+    ),
+    (
+        'https://my-test.trycloudflare.com is ready',
+        'https://my-test.trycloudflare.com',
+    ),
+])
+def test_cloudflared(text: str, expected: str) -> None:
+    m = re.search(CF_PATTERN, text)
+    assert m is not None, f'Паттерн не нашёл URL в: {text!r}'
+    assert m.group() == expected
+
+
+# Bore
+BORE_PATTERN = r'bore\.pub:\d+'
+
+@pytest.mark.parametrize('text, expected', [
+    ('INFO bore::client: listening at bore.pub:12345', 'bore.pub:12345'),
+    ('connected to bore.pub:54321 successfully',       'bore.pub:54321'),
+])
+def test_bore(text: str, expected: str) -> None:
+    m = re.search(BORE_PATTERN, text)
+    assert m is not None
+    assert m.group() == expected
+
+
+# MMAR
+@pytest.mark.parametrize('text, expected', [
+    ('Tunnel at https://abc123.mmar.dev',    'https://abc123.mmar.dev'),
+    ('http://test-tunnel.mmar.dev/ active',  'http://test-tunnel.mmar.dev/'),
+])
+def test_mmar(text: str, expected: str) -> None:
+    m = re.search(r'(?P<url>https?://\S+\.mmar\.dev)', text)
+    assert m is not None
+    assert m.group() == expected
+
+
+# Tunnelite
+def test_tunnelite() -> None:
+    text = 'Your public URL: https://random-words.tunnelite.com'
+    m = re.search(r'(?P<url>https?://\S+\.tunnelite\.com)', text)
+    assert m is not None
+    assert m.group() == 'https://random-words.tunnelite.com'
+
+
+# Beeceptor
+def test_beeceptor() -> None:
+    text = 'Tunnel running at https://my-endpoint.beeceptor.com'
+    m = re.search(r'(?P<url>https?://\S+\.beeceptor\.com)', text)
+    assert m is not None
+    assert m.group() == 'https://my-endpoint.beeceptor.com'
+
+
+# Bore Digital──
+def test_boredigital() -> None:
+    text = '| https://xyz123.bore.digital | active |'
+    m = re.search(r'(?P<url>https://\S+\.bore\.digital)', text)
+    assert m is not None
+    assert m.group() == 'https://xyz123.bore.digital'
+
+
+# SSH-провайдеры
+@pytest.mark.parametrize('pattern, text, should_match', [
+    # Optimistix
+    (r'https://\S+\.otnl\.link',
+     'Forwarding from https://tunnel-abc.otnl.link', True),
+
+    # srv.us — минимум 10 символов в субдомене
+    (r'https://[a-z0-9]{10,}\.srv\.us/?',
+     'https://abcdefghij.srv.us', True),
+    (r'https://[a-z0-9]{10,}\.srv\.us/?',
+     'https://short.srv.us', False),
+
+    # Serveo
+    (r'https://\S+\.serveousercontent\.com',
+     'Forwarding from https://mytunnel.serveousercontent.com', True),
+
+    # localhost.run — admin исключён
+    (r'https://(?!admin\b)[a-zA-Z0-9-]+\.(?:localhost\.run|lhr\.life)',
+     'https://abc123.localhost.run', True),
+    (r'https://(?!admin\b)[a-zA-Z0-9-]+\.(?:localhost\.run|lhr\.life)',
+     'https://admin.localhost.run', False),
+    (r'https://(?!admin\b)[a-zA-Z0-9-]+\.(?:localhost\.run|lhr\.life)',
+     'https://my-tunnel.lhr.life', True),
+])
+def test_ssh_patterns(pattern: str, text: str, should_match: bool) -> None:
+    m = re.search(pattern, text)
+    if should_match:
+        assert m is not None, f'{pattern!r} не нашёл совпадение в {text!r}'
+    else:
+        assert m is None, f'{pattern!r} не должен совпадать с {text!r}'

tests/test_utils.py

@@ -0,0 +1,133 @@
+"""
+Юнит-тесты для утилитарных функций colab_tunnel._utils.
+"""
+import sys
+import subprocess
+
+import pytest
+
+from colab_tunnel._utils import is_ipv4, run, read_until_pattern
+
+
+# is_ipv4
+
+@pytest.mark.parametrize('addr, expected', [
+    ('192.168.1.1',     True),
+    ('10.0.0.1',        True),
+    ('255.255.255.255',  True),
+    ('0.0.0.0',         True),
+    ('192.168.1.256',   False),
+    ('192.168.1',       False),
+    ('not-an-ip',       False),
+    ('',                False),
+    ('999.0.0.1',       False),
+    ('1.2.3.4.5',       False),
+])
+def test_is_ipv4(addr: str, expected: bool) -> None:
+    assert is_ipv4(addr) is expected
+
+
+# run()
+
+def test_run_captures_output() -> None:
+    result = run('echo hello_world')
+    assert result['status_code'] == 0
+    assert 'hello_world' in result['output']
+
+
+def test_run_nonzero_exit() -> None:
+    result = run('sh -c "exit 42"')
+    assert result['status_code'] == 42
+
+
+def test_run_captures_stderr() -> None:
+    result = run('sh -c "echo err_msg >&2"')
+    assert 'err_msg' in result['output']
+
+
+def test_run_timeout_returns_minus_one() -> None:
+    result = run('sleep 60', timeout=0.3)
+    assert result['status_code'] == -1
+    assert 'Таймаут' in result['output']
+
+
+# read_until_pattern()
+
+@pytest.mark.skipif(sys.platform == 'win32', reason='select() с пайпами не поддерживается на Windows')
+def test_read_until_pattern_found_in_stdout() -> None:
+    process = subprocess.Popen(
+        [sys.executable, '-c',
+         'import sys, time; print("https://example.com"); sys.stdout.flush(); time.sleep(60)'],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+    )
+    try:
+        url, output = read_until_pattern(process, r'https://\S+', timeout=5.0)
+        assert url == 'https://example.com'
+        assert 'https://example.com' in output
+    finally:
+        process.kill()
+        process.wait()
+
+
+@pytest.mark.skipif(sys.platform == 'win32', reason='select() с пайпами не поддерживается на Windows')
+def test_read_until_pattern_found_in_stderr() -> None:
+    process = subprocess.Popen(
+        [sys.executable, '-c',
+         'import sys, time; sys.stderr.write("https://stderr.example.com\\n"); sys.stderr.flush(); time.sleep(60)'],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+    )
+    try:
+        url, _ = read_until_pattern(
+            process, r'https://\S+', timeout=5.0, read_from_stderr=True
+        )
+        assert 'https://stderr.example.com' in url
+    finally:
+        process.kill()
+        process.wait()
+
+
+@pytest.mark.skipif(sys.platform == 'win32', reason='select() с пайпами не поддерживается на Windows')
+def test_read_until_pattern_raises_on_timeout() -> None:
+    process = subprocess.Popen(
+        [sys.executable, '-c', 'import time; time.sleep(60)'],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+    )
+    try:
+        with pytest.raises(RuntimeError, match='URL не найден'):
+            read_until_pattern(process, r'https://\S+', timeout=0.5)
+    finally:
+        process.kill()
+        process.wait()
+
+
+@pytest.mark.skipif(sys.platform == 'win32', reason='select() с пайпами не поддерживается на Windows')
+def test_read_until_pattern_raises_when_process_exits_without_url() -> None:
+    process = subprocess.Popen(
+        [sys.executable, '-c', 'print("no url here at all")'],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+    )
+    with pytest.raises(RuntimeError):
+        read_until_pattern(process, r'https://\S+', timeout=5.0)
+
+
+@pytest.mark.skipif(sys.platform == 'win32', reason='select() с пайпами не поддерживается на Windows')
+def test_read_both_streams_finds_url_in_either() -> None:
+    """URL в stderr должен находиться при read_both_streams=True."""
+    process = subprocess.Popen(
+        [sys.executable, '-c',
+         'import sys, time; sys.stderr.write("https://both.example.com\\n"); sys.stderr.flush(); time.sleep(60)'],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+    )
+    try:
+        url, _ = read_until_pattern(
+            process, r'https://\S+', timeout=5.0, read_both_streams=True
+        )
+        assert 'https://both.example.com' in url
+    finally:
+        process.kill()
+        process.wait()