Описание

Общее описание функционала

CLI-клиент позволяет опубликовать локальный сервис по HTTP, HTTPS, TCP или UDP через туннель и получить для него URL туннеля. Он подходит для удалённого доступа, демонстраций, временного предоставления доступа к стенду и сценариев, где нужен быстрый запуск без веб-интерфейса. Клиент подключается к сервису ForTunnels на https://fortunnels.ru, работает с токеном или логином и паролем, а если на сервере доступен гостевой режим, может создать туннель и без учётной записи. Для соединения используются WebSocket, QUIC или DTLS в зависимости от настроек и условий сети.

Как пользователь может использовать

• Разработчик публикует локальный веб-сервер и получает URL туннеля для быстрого доступа извне.
• Пользователь открывает доступ к локальной базе, сервису или тестовому стенду без отдельного проброса портов.
• Пользователь выбирает WebSocket, если сеть пропускает только обычные HTTPS-соединения.
• Пользователь переключается на QUIC или DTLS, когда нужен альтернативный транспорт для ограниченной сети.
• Пользователь настраивает TCP- или UDP-туннель для сервисов, которые не работают как обычный веб-сайт.
• Пользователь включает режим ожидания stay, чтобы туннель оставался активным во время демонстрации или тестирования.
• Пользователь использует watch, когда нужно отслеживать изменения состояния туннеля без ручного перезапуска.
• Пользователь передаёт секреты через флаги, файлы, стандартный ввод или переменные окружения, чтобы не хранить их в командной строке.
• Явные параметры командной строки (в том числе -login и -pass) имеют приоритет над сохранённым в fortunnels.yml CLI-токеном.
• Пользователь скачивает готовый бинарник со страницы загрузок продукта или ставит клиент через поддерживаемый пакетный менеджер.

Как это реализовано в сервисе

Пользователь запускает CLI с адресом локального сервиса и параметрами подключения. Клиент проходит аутентификацию или использует гостевой режим, создаёт туннель в сервисе и получает URL туннеля. Затем он открывает выбранный канал передачи данных и направляет через него внешний трафик к локальному сервису. Если режим работы не даёт отдельного сигнала о завершении, клиент периодически проверяет состояние туннеля и завершает работу, когда доступ больше не нужен или туннель больше не действует. Ошибки подключения, ограничений и недоступного транспорта выводятся в консоли понятным для пользователя сообщением.

Справочник API

Создание туннеля (плоскость управления)

Клиент использует тот же REST API, что и дашборд: POST /api/tunnels с телом JSON (протокол, целевой адрес, опции авторизации туннеля и т.д.). Требуется заголовок Authorization: Bearer <token> или сессионная кука после входа — в зависимости от режима.

Гостевое создание (если включено на сервере): тот же маршрут без заголовка авторизации; в ответе — URL туннеля, срок жизни и лимиты.

Статус туннеля

GET /api/tunnels?id=<tunnel_id> — используется CLI для опроса жизненного цикла в режимах stay (HTTP/TCP expose-local/UDP), пока процесс удерживает туннель.

Удаление

DELETE /api/tunnels?id=<tunnel_id> — при поддержке сервером и политикой доступа.

Точные поля запроса и ответа совпадают с публичной справкой API сервера и типами в клиентском протоколе.

Транспорт данных

После создания туннеля клиент открывает WebSocket GET /ws (с параметрами режима и tunnel_id в строке запроса) или альтернативный транспорт (QUIC / DTLS) согласно флагам CLI и конфигурации сервера.

Ошибки

Ошибка аутентификации

Сообщение о неверном логине/пароле или просроченном токене; код выхода ненулевой. Нужно обновить учётные данные или получить новый токен.

Отказ в создании туннеля

Ответ API с телом JSON: поле error или message с человекочитаемым текстом (квота, запрещённый протокол, неверные параметры). Исправить параметры или тариф.

«Tunnel was removed. Exiting.»

Туннель удалён на сервере, истёк или доступ отозван; опрос GET /api/tunnels?id=... вернул признак отсутствия или 401. Запустить клиент заново и при необходимости создать новый туннель.

Ошибка сети / таймаут

Нет связи с сервисом ForTunnels. Проверить подключение к сети и DNS для fortunnels.ru.

Недостаточная длина PSK

При включённом шифровании потока PSK короче минимума — клиент завершится с ошибкой валидации до создания туннеля.

Ограничения

• CLI зависит от версии сервера: новые поля API могут требовать обновления клиента.
• Режим guest и лимиты гостевых туннелей задаются на сервере; пользователь не может продлить TTL или сбросить квоту из CLI.
• QUIC/DTLS могут быть недоступны, если сервер или сеть их блокирует; тогда используйте WebSocket.
• Опрос статуса в stay-режиме создаёт периодический трафик к API; при очень большом числе процессов учитывайте лимиты.
• Сообщения об ошибках в консоли не локализованы вне дашборда; язык зависит от версии клиента и ответов сервиса.