README.md

# colab-tunnel

Библиотека для публичного туннелирования локальных портов в Google Colab.
Поддерживает в настоящий момент 15 провайдеров, работает молча — выдаёт ссылку без лишних действий со стороны пользователя.

![example](https://github.com/user-attachments/assets/20c8b870-2295-49d1-bd78-1f68b274df6e)

```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
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_tunnel import try_all

print(try_all(7860))
# gradio: https://...gradio.live
# bore: http://bore.pub:XXXXX/
# srvus: https://...srv.us
# ...
```

---

### `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)
```

---

## Конфигурация

| Переменная окружения | По умолчанию       | Описание                           |
|----------------------|--------------------|------------------------------------|
| `TUNNEL_WORK_DIR`    | `/content/.config` | Папка для бинарников и кэша        |
| `TEST_SERVER_PATH`   | —                  | Путь к бинарнику тестового сервера |

```python
import os
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)
```

---

## Лицензия

MIT