Описание

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

CLI-клиент — программа командной строки для создания туннелей к локальным сервисам HTTP, HTTPS, TCP и UDP и удержания плоскости данных (WebSocket, QUIC или DTLS в зависимости от настроек). На плоскости управления клиент проходит аутентификацию (токен или логин/пароль) и создаёт туннель через API, выводит пользователю публичный адрес и удерживает соединение, пока нужен доступ. Встроены проверки безопасности (в том числе ограничение незащищённого HTTP к нелокальным целям без явного подтверждения) и работа с секретами через флаги, файлы, stdin и переменные окружения.

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

• Разработчик публикует локальный веб-сервер: ./bin/client с целевым портом или адресом и нужным протоколом, без регистрации (гостевой режим) или с входом в аккаунт.
• Пользователь передаёт токен или логин/пароль для создания именованных туннелей с лимитами тарифа.
• Пользователь выбирает транспорт данных (например WebSocket по умолчанию или QUIC/DTLS) для обхода ограничений сети.
• Пользователь задаёт PSK или другие параметры шифрования потока, когда политика организации требует дополнительного слоя.
• Пользователь запускает TCP или UDP туннель к локальному порту для удалённого доступа к базе, DNS или произвольному протоколу.
• Пользователь использует режим expose-local (внешний порт на сервере), когда внешний мир подключается к выделенному порту на сервере, а клиент пробрасывает трафик на локальный сервис.
• Пользователь оставляет процесс в режиме ожидания (stay), пока демонстрирует стенд; опционально включает watch для подписки на обновления через WebSocket.
• Пользователь перенаправляет секреты из файла или stdin, чтобы пароли не светились в списке процессов.
• Пользователь скачивает бинарник со страницы загрузок продукта, устанавливает клиент через поддерживаемый пакетный менеджер (Homebrew, Chocolatey, WinGet) или собирает клиент из исходников по инструкции на сайте.

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

Клиент разбирает аргументы и приводит адрес назначения к единому виду (протокол, адрес, порт), затем устанавливает аутентифицированный или анонимный сеанс с сервером туннелей и отправляет запрос создания туннеля. Сервер возвращает идентификатор и публичные адреса; клиент поднимает транспорт плоскости данных и сопоставляет входящий и исходящий трафик с локальным сервисом. Для режимов без явного канала завершения клиент периодически опрашивает API туннеля: если туннель удалён или сессия недействительна, процесс завершается с понятным сообщением. Ошибки сети и квот отображаются в консоли; при логине через сессию опрос и изменяющие запросы используют те же механизмы, что и браузерный дашборд.

Справочник API

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

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

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

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

GET /api/tunnels?id=<tunnel_id> — используется CLI для опроса жизненного цикла в режимах stay (HTTP/TCP listen/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. Запустить клиент заново и при необходимости создать новый туннель.

Небезопасный HTTP к нелокальной цели

Клиент отказывается подключаться по http:// к адресу вне локальных диапазонов без явного флага подтверждения (формулировка в stderr зависит от версии). Использовать https://, локальный адрес или разрешённый флаг.

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

Нет связи с -server URL. Проверить сеть, DNS и значение флага -server.

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

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

Ограничения

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

Описание

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

CLI-токен — персональный токен для подключения CLI-клиента ForTunnels к аккаунту пользователя. Он позволяет один раз настроить клиент на рабочей машине и дальше запускать туннели командами вроде fortunnels http 8080 без ручной передачи токена в каждом запуске.

CLI-токен создаётся в дашборде аккаунта на платном тарифе (функция CLI-токен в каталоге), показывается пользователю один раз и сохраняется локально в конфигурационный файл CLI. На бесплатном тарифе управление CLI-токенами в интерфейсе недоступно, а API отклоняет запросы с понятным кодом ограничения тарифа. Пользователь может видеть список активных CLI-токенов и отзывать те, которые больше не нужны.

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

• Разработчик создаёт CLI-токен на своём ноутбуке и настраивает CLI один раз, чтобы быстро запускать HTTP-туннели к локальному приложению.
• Инженер использует отдельные CLI-токены для разных рабочих машин, чтобы при потере доступа к одной машине отозвать только её токен.
• Пользователь копирует готовую команду fortunnels config add-authtoken ... из дашборда и не редактирует YAML вручную.
• Пользователь проверяет локальный файл конфигурации командой fortunnels config check, прежде чем запускать туннель.
• Пользователь удаляет старый CLI-токен из дашборда, когда меняет устройство или больше не использует CLI на конкретной машине.
• Пользователь на бесплатном тарифе видит, что создание CLI-токена недоступно, и может перейти к смене тарифа из подсказки в интерфейсе.
• Пользователь на Pro или Enterprise создаёт и отзывает CLI-токены как обычно.
• Команда поддержки или администратор может попросить пользователя отозвать CLI-токен, если есть подозрение, что он был скомпрометирован.
• Пользователь хранит CLI-токен в стандартном для своей ОС месте: Linux, macOS и Windows используют разные пути, но CLI выбирает их автоматически.

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

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

Локальная команда конфигурации записывает CLI-токен в файл на машине пользователя. При запуске туннеля CLI читает этот файл, если токен не был передан более явным способом через флаг, файл секрета, stdin или переменную окружения.

Справочник API

Дашборд: управление токенами

Пользователь управляет CLI-токенами из дашборда. Эти маршруты требуют активной браузерной сессии. Для небезопасных методов используется защита CSRF, как и для других действий дашборда.

Получить список токенов

GET /api/me/authtokens

На бесплатном тарифе без возможности CLI-токен в плане: HTTP 403, JSON code: feature_disabled, feature_id: authtoken.

Успешный ответ:

{
  "authtokens": [
    {
      "id": 1,
      "name": "Laptop",
      "prefix": "ft_abc123",
      "created_at": "2026-05-31T21:00:00Z",
      "last_used_at": "2026-05-31T21:10:00Z",
      "expires_at": null
    }
  ]
}

Полное значение токена в списке не возвращается.

Создать токен

POST /api/me/authtokens

На бесплатном тарифе без возможности CLI-токен в плане: HTTP 403, JSON code: feature_disabled, feature_id: authtoken, текст authtoken requires a paid plan.

Тело запроса:

{
  "name": "Laptop",
  "expires_at": "2026-12-31T00:00:00Z"
}

Поля name и expires_at необязательны.

Успешный ответ:

{
  "id": 1,
  "name": "Laptop",
  "prefix": "ft_abc123",
  "authtoken": "ft_..."
}

Поле authtoken показывается только один раз — в ответе на создание.

Отозвать токен

DELETE /api/me/authtokens/{id}

Успешный ответ: 204 No Content.

CLI: локальная конфигурация

CLI поддерживает команды:

fortunnels config add-authtoken YOUR_FORTUNNELS_TOKEN
fortunnels config check

config add-authtoken записывает токен в конфигурационный файл. config check проверяет наличие файла, корректность YAML, версию схемы и наличие agent.authtoken. Команда не обращается к серверу.

Формат файла:

version: 3

agent:
  authtoken: YOUR_FORTUNNELS_TOKEN

Пути по умолчанию:

• Linux: ~/.config/fortunnels/fortunnels.yml
• macOS: ~/Library/Application Support/fortunnels/fortunnels.yml
• Windows: %LOCALAPPDATA%\fortunnels\fortunnels.yml

Переменная FORTUNNELS_CONFIG задаёт пользовательский путь к конфигурационному файлу.

CLI: запуск туннеля

После настройки CLI использует CLI-токен из конфигурации при командах:

fortunnels http 8080

Более явные источники токена имеют приоритет над конфигурацией: флаг, файл секрета, stdin и переменная окружения.

Ошибки

Ошибки дашборда

• HTTP 401: пользователь не вошёл в аккаунт или сессия истекла. Нужно войти в дашборд заново.
• HTTP 400: запрос на создание токена некорректен, например указан неверный формат expires_at. Нужно исправить данные и повторить действие.
• HTTP 403: действие заблокировано политикой доступа, CSRF-проверкой или ограничением тарифа. При code: feature_disabled и feature_id: authtoken сообщение указывает, что CLI-токен недоступен на текущем плане (authtoken requires a paid plan); нужно сменить тариф или обратиться к администратору.
• HTTP 404: пользователь пытается отозвать несуществующий токен или токен, который ему не принадлежит. Нужно обновить список токенов.
• HTTP 409: достигнут лимит активных токенов. Нужно отозвать старый токен и создать новый.
• HTTP 500: внутренняя ошибка сервиса. Нужно повторить позже или обратиться в поддержку.

Ошибки CLI-конфигурации

• No configuration file at ...: файл конфигурации не найден. Нужно создать его вручную или выполнить fortunnels config add-authtoken <token>.
• config version must be 3: версия схемы в YAML не поддерживается. Нужно указать version: 3.
• agent.authtoken is required: в конфигурации нет токена. Нужно добавить agent.authtoken.
• Ошибка парсинга YAML: файл имеет некорректный синтаксис. Нужно исправить отступы и структуру YAML.
• LOCALAPPDATA is not set на Windows: CLI не смог определить стандартный путь. Нужно задать LOCALAPPDATA или FORTUNNELS_CONFIG.

Ошибки запуска туннеля с CLI-токеном

• HTTP 401 при создании туннеля: токен неверный, отозван, истёк или не принят сервером. Нужно создать новый токен в дашборде и обновить локальную конфигурацию.
• HTTP 403 при создании туннеля: аккаунт заблокирован или действие запрещено тарифом/политикой доступа. Нужно проверить статус аккаунта и ограничения тарифа.
• Сообщение о недоступном сервере: CLI не смог подключиться к серверу ForTunnels. Нужно проверить сеть и значение --server, если оно переопределено.

Ограничения

Одноразовый показ токена

Полное значение CLI-токена показывается только сразу после создания. Если пользователь закрыл окно или не сохранил токен, нужно создать новый токен и отозвать старый.

Локальная проверка конфигурации

fortunnels config check проверяет только локальный файл: путь, YAML, версию схемы и наличие agent.authtoken. Команда не подтверждает, что токен действителен на сервере.

Ручная защита локального файла

CLI записывает конфигурационный файл с ограниченными правами, но пользователь отвечает за безопасность своей машины, резервных копий и синхронизаций домашней директории.

Лимит активных токенов

У аккаунта есть ограничение на количество активных токенов. Если лимит достигнут, нужно отозвать неиспользуемые токены.

Тарифный план

Функция CLI-токен доступна только когда она включена в активный тариф пользователя (по умолчанию — платные планы Pro и Enterprise). На Free дашборд не загружает список токенов и блокирует создание и отзыв; прямые запросы к API управления токенами возвращают отказ с кодом feature_disabled.

Приоритет источников токена

Если пользователь одновременно указал токен через флаг, переменную окружения и конфигурационный файл, CLI выберет более явный источник. Это может выглядеть так, будто конфигурационный файл игнорируется.

Отзыв не завершает уже запущенный процесс мгновенно

Отзыв токена запрещает будущую аутентификацию этим токеном. Уже созданный туннель может завершиться по обычным правилам жизненного цикла соединения и серверных проверок.

Описание

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

Функциональность отвечает за публичный доступ к вашим HTTP- и HTTPS-приложениям через туннель: внешний клиент обращается к адресу сервиса, а запрос перенаправляется на целевой хост и порт, который вы указали при создании туннеля. Поддерживается доступ по пути вида /t/{идентификатор_туннеля}/… и по имени хоста (поддомен публичного URL туннеля на домене сервиса). Для одноуровневого поддомена публичного URL на домене сервиса (например label.fortunnels.ru) для туннелей зарегистрированных пользователей действуют те же правила, что и для /t/{id}/…: нужен владелец, администратор или гостевой туннель; сессия или токен должны позволять сервису определить пользователя (cookie сессии на родительском домене или Authorization: Bearer). Для привязанного пользовательского домена по-прежнему допускается публичный доступ по знанию имени хоста — без проверки владения сессией, как «ссылка-возможность»; после этого по-прежнему применяются списки доступа по IP, лимиты и тариф. Для захода по пути /t/{id}/… проверка владельца, гостевого режима и администратора выполняется до списков доступа по IP и лимитов. Сервис проверяет, существует ли туннель и разрешён ли запрос в соответствии с выбранным режимом маршрутизации. Дополнительно могут применяться ограничения по IP, частоте запросов и условиям тарифа (квоты и включённые возможности). При недоступности целевого приложения или срабатывании ограничений клиент получает понятный по смыслу ответ об ошибке вместо успешного ответа от вашего приложения.

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

• Разработчик поднимает API или веб-интерфейс локально и открывает его коллегам или тестовой среде по выданному публичному URL, не выставляя машину в интернет напрямую.
• Интегратор проверяет вебхуки или OAuth-редиректы: внешний сервис шлёт запросы на публичный адрес туннеля, а трафик доходит до локального стенда.
• Владелец туннеля делится ссылкой с префиксом /t/… там, где удобнее явный путь, или использует «короткий» URL на поддомене, когда важна привычная форма адреса в браузере.
• Для приложений на Next.js и похожих SPA путь /t/… обычно работает прозрачно для типовых запросов, включая загрузку _next-ресурсов, fetch, WebSocket, EventSource и sendBeacon, но для максимальной предсказуемости всё равно полезно включать собственную конфигурацию под подпуть (basePath, assetPrefix и аналоги).
• Пользователь с гостевым туннелем (доступный всем) демонстрирует прототип заказчикам без входа в аккаунт у них; при этом приватные туннели остаются доступны только владельцу и уполномоченным ролям.
• Администратор или сопровождение проверяет доступ к туннелю другого пользователя при расследовании инцидента, в рамках полномочий, выданных продуктом.
• Клиент API или скрипт автоматизации дергает те же публичные URL, что и браузер, для проверки поведения за прокси (заголовки, редиректы, тело ответа).
• Пользователь сталкивается с временной приостановкой туннеля и видит, что сервис недоступен до возобновления, вместо «тихого» ответа от старого кэша.
• Владелец плана с лимитами отслеживает, что при исчерпании квоты или отключённой возможности запросы к туннелю отклоняются с явным сигналом, а не проксируются «в никуда».
• Пользователь с ограничениями по IP или частоте запросов понимает по ответу сервиса, что доступ временно или постоянно ограничён политикой безопасности или защитой от злоупотреблений.
• Посетитель основного сайта сервиса и посетитель URL туннеля получают согласованное поведение по протоколу (например, ожидаемые редиректы на HTTPS там, где это задумано продуктом).
• Поддерживаются долгоживущие соединения WebSocket через тот же обратный прокси, при условии корректных таймаутов на публичном входе.
• Если приложение критически зависит от service worker, офлайн-кэша или фонового перехвата запросов, более надёжный вариант для пользователя — хостовый публичный URL, а не путь /t/{id}/….
• Нужны формализованные истории уровня продукта — см. user-stories.md.

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

Входящий HTTP-запрос сначала попадает на публичную точку входа домена сервиса: часть запросов обслуживает сам продукт (например, лендинг), а трафик туннелей направляется в компонент маршрутизации. По фрагменту пути или по заголовку Host определяется, к какому туннелю относится запрос; затем проверяется, что туннель существует и находится в состоянии, допускающем обработку. Для маршрута по пути /t/{id}/ проверка владельца/гостя/администратора выполняется до списков доступа по IP. Для маршрута по хосту одноуровневого поддомена на домене сервиса (публичный URL вида label.<домен_сервиса>) для туннелей с владельцем применяется та же проверка доступа, что и для /t/{id}/. Для хоста, привязанного как пользовательский домен (отдельная привязка в хранилище), публичный доступ по знанию имени хоста сохраняется; затем по-прежнему применяются списки доступа по IP, лимиты и тарифные проверки владельца. При локальной разработке поддомены *.localhost не считаются продакшен-вайлдкардом и ведут себя как публичный доступ по имени хоста. В API списков и чтения туннелей для гостей по-прежнему может использоваться скрытие факта существования чужих туннелей (404), что не отменяет описанную модель прокси. После этого могут учитываться сетевые списки доступа, ограничение интенсивности запросов и условия тарифа владельца. Если все проверки пройдены, запрос пересылается на целевой адрес туннеля как обратный прокси: сохраняется метод, тело и заголовки в допустимых пределах, устанавливается соединение с пулом повторного использования соединений к цели. Ответ целевого приложения возвращается клиенту; при ошибках на любом этапе (не найден туннель, отказ в доступе, перегрузка лимитами, недоступность цели, тайм-аут) формируется ответ об ошибке на стороне сервиса до завершения или вместо проксирования.

Справочник API

Публичное проксирование

• GET /t/{tunnel_id}/* — проксирование HTTP-запросов к целевому туннелю по пути
• GET /{custom_domain}/* — маршрутизация по хосту

Поддерживаются все HTTP-методы (GET, POST, PUT, DELETE и др.). Заголовки, тело и параметры запроса сохраняются при пересылке.

Управление туннелями (API)

• POST /api/tunnels — создание туннеля с протоколом HTTP/HTTPS
• GET /api/tunnels/{id} — получение информации о туннеле
• PATCH /api/tunnels/{id} — обновление конфигурации туннеля (пауза, транспорт, TLS, регенерация URL, редиректы и т.д.)
• DELETE /api/tunnels/{id} — удаление туннеля

Для HTTP/HTTPS-туннелей поддерживается действие set_public_subdomain: в теле JSON указываются id, action: "set_public_subdomain" и поле public_subdomain (метка поддомена). Ограничения: валидация метки, уникальность хоста, зарезервированные имена, при включённых тарифах — возможность custom-public-subdomain, отдельный лимит частоты смены метки, максимальный размер тела PATCH. Коды ответов: см. раздел Ошибки возможности «Свой поддомен публичного URL» в документации.

Для зарегистрированных пользователей с тарифными планами при создании туннеля возможны ответы 403 с JSON-кодами: user_suspended (аккаунт заблокирован) или quota_exceeded с полем quota: max_concurrent_tunnels (превышен лимит одновременных туннелей). Поле expires_at в ответе может отражать ограничение срока жизни туннеля по плану.

Запрос создания туннеля

{
  "protocol": "http",
  "target_addr": "127.0.0.1:8000",
  "user_id": "user123"
}

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

{
  "id": "a1b2c3d4e5f6g7h8",
  "protocol": "http",
  "target_addr": "127.0.0.1:8000",
  "public_url": "http://xyz789.fortunnels.ru",
  "created_at": "2024-01-01T12:00:00Z",
  "expires_at": "2024-01-01T14:00:00Z"
}

Поддомен public_url генерируется независимо от id туннеля для повышения безопасности.

Список и детали туннеля (GET /api/tunnels, GET /api/tunnels?id=<id>)

Ответ списка и одиночного туннеля включает поля created_at, expires_at, bytes_used, traffic_limit_bytes и объект limit_indicators — компактные индикаторы лимитов для интерфейса (без отдельного запроса на строку).

limit_indicators

| Поле | Описание |

|------|----------|

| as_of | Момент расчёта на сервере (RFC3339) |

| lifetime | Оставшееся время жизни туннеля из created_at / expires_at |

| traffic | Per-tunnel трафик из bytes_used / traffic_limit_bytes (для гостевых туннелей); для зарегистрированных владельцев — unavailable (месячный egress аккаунта не показывается как per-tunnel cap) |

| http_rpm | Оставшаяся ёмкость HTTP-запросов в минуту по плану в текущем окне |

Состояния каждого индикатора: limited, unlimited, unavailable, zero_limit, exhausted, expired.

Снимок http_rpm носит информационный характер и не расходует лимит запросов при чтении; фактическое ограничение применяется при обработке HTTP-запросов к туннелю.

Для не-админов поля user_id и owner_login по-прежнему опускаются в теле туннеля; limit_indicators не содержит owner/account/plan идентификаторов.

Пример фрагмента:

{
  "limit_indicators": {
    "as_of": "2026-06-05T12:00:00Z",
    "lifetime": {
      "state": "limited",
      "used_seconds": 120,
      "remaining_seconds": 480,
      "total_seconds": 600,
      "reset_at": "2026-06-05T14:00:00Z"
    },
    "traffic": {
      "state": "limited",
      "used_bytes": 256,
      "remaining_bytes": 768,
      "total_bytes": 1024
    },
    "http_rpm": {
      "state": "limited",
      "used_requests": 3,
      "remaining_requests": 7,
      "total_requests": 10,
      "reset_at": "2026-06-05T12:01:00Z"
    }
  }
}

Поле remaining_requests в http_rpm — оставшаяся ёмкость HTTP requests/min в текущем окне (не current_http_requests_per_minute).

Ошибки

413 Payload Too Large

Когда возникает: Тело запроса PATCH /api/tunnels/{id} превышает лимит размера (внутренний порог для JSON-действий с туннелем).

Что делать: Уменьшить тело запроса; для set_public_subdomain достаточно компактного JSON с полями id, action, public_subdomain.

400 Bad Request

Когда возникает: Невалидный формат ID туннеля, некорректный запрос, попытки path traversal (../ в путях), невалидная метка public_subdomain, зарезервированное имя поддомена, действие только для HTTP/HTTPS.

Что делать: Проверить корректность URL и ID туннеля. Убедиться, что путь не содержит недопустимых последовательностей.

403 Forbidden

Когда возникает: ACL запретил доступ, требуется аутентификация, пользователь обращается к чужому туннелю.

Что делать: Проверить права доступа и настройки ACL туннеля. Убедиться, что аутентификация валидна и пользователь имеет право доступа к туннелю.

404 Not Found

Когда возникает: Туннель не найден, невалидный путь или ID туннеля.

Что делать: Проверить корректность ID туннеля и URL. Убедиться, что туннель существует и не истёк.

429 Too Many Requests

Когда возникает: Превышен лимит запросов (глобальный, на пользователя или на туннель).

Что делать: Снизить частоту запросов. Заголовок Retry-After указывает, когда можно повторить запрос.

502 Bad Gateway

Когда возникает: Целевой сервис недоступен, подключение не удалось (connection refused, timeout).

Что делать: Убедиться, что локальный сервис запущен и доступен по адресу, указанному при создании туннеля. Повторить запрос после восстановления сервиса.

503 Service Unavailable

Когда возникает: Туннель приостановлен; туннель возобновлён в панели, но клиент ещё не переподключился («Туннель возобновляется»); или временные проблемы на стороне сервера.

Что делать: Проверить статус туннеля через API. Если туннель возобновлён — подождать несколько секунд (клиент переподключается после паузы). Возобновить туннель при необходимости.

504 Gateway Timeout

Когда возникает: Превышен таймаут запроса к целевому сервису.

Что делать: Проверить доступность и нагрузку локального сервиса. Увеличить таймаут в конфигурации туннеля при необходимости.

Описание

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

Инспектор TCP-трафика даёт владельцу TCP-туннеля просматривать историю TCP-соединений, проходящих через туннель: адреса клиента и цели, длительность, объём трафика, состояние завершения и при необходимости укороченный захват потока в текстовом или шестнадцатеричном виде. Данные доступны в дашборде на странице инспектора туннеля (вкладка TCP) и через API с поддержкой потоковой подписки (SSE) для живых обновлений.

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

• Разработчик отлаивает нестабильное TCP-приложение: открывает инспектор, сортирует соединения по времени, находит обрывы и ошибки.
• Пользователь проверяет, что внешний клиент действительно доходит до указанного целевого адреса, сверяя IP и порты в списке.
• Пользователь переключает отображение текст/hex для просмотра коротких текстовых протоколов поверх TCP.
• Пользователь фильтрует соединения по состоянию (активные, закрытые, ошибка) для фокуса на проблемных сессиях.
• Администратор при поддержке пользователя просматривает те же метаданные в рамках полномочий продукта.
• Инженер подписывается на SSE-поток, чтобы видеть новые соединения в реальном времени во время теста.

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

При установке и закрытии TCP-соединения через туннель сервис фиксирует событие и сохраняет его в базе вместе с ограниченным объёмом перехваченных байт. Запросы из интерфейса дашборда или API проходят проверку владельца туннеля (или права администратора), затем возвращают страницу списка или одну запись. Поток событий рассылает новые записи подписчикам; частота опроса ограничивается лимитами сервера. В публичном развёртывании инспектор доступен только при корректной аутентификации и настройке режима работы, отличного от небезопасной отладочной конфигурации.

Справочник API

Список соединений

GET /api/v1/inspector/tcp/connections

Параметры:

• tunnel_id (обязательный) — ID туннеля
• from — начало периода (RFC3339)
• to — конец периода (RFC3339)
• state — фильтр по состоянию: active, closed, error
• limit — лимит (по умолчанию 50)
• offset — смещение

Ответ: { "connections": [...], "pagination": { "limit", "offset", "count", "has_more" } }

Получение соединения

GET /api/v1/inspector/tcp/connections/:id

Параметры:

• format — text | hex (опционально, для формата stream_capture)

Ответ: объект TCPConnectionEvent с полями id, tunnel_id, client_ip, client_port, target_addr, started_at, ended_at, duration_ms, bytes_in, bytes_out, state, error_msg, stream_capture / stream_capture_text / stream_capture_hex

SSE-поток

GET /api/v1/inspector/tcp/connections/stream?tunnel_id=...

События: { "type": "tcp_connection", "data": TCPConnectionEvent }

Ошибки

Справочник ошибок

| Код | Сообщение | Условие |

|-----|-----------|---------|

| 401 | Unauthorized | Отсутствует или недействительна авторизация |

| 403 | Forbidden | Пользователь не имеет доступа к туннелю |

| 404 | TCP connection not found | Соединение не найдено |

| 503 | Service Unavailable | Сервис инспектора недоступен |

Ограничения

Известные ограничения

• Захват потока ограничен (по умолчанию 32 КБ на соединение)
• Guest-пользователи не имеют доступа к TCP-инспектору
• Клиентский IP в dataplane-пути может быть недоступен (отображается как «dataplane»)
• Отображение потока в текстовом формате может содержать замены для невалидного UTF-8

Риски конфигурации

• tls_insecure_skip_verify: При создании/изменении HTTPS-туннелей можно отключить проверку TLS-сертификата бэкенда. Это делает трафик уязвимым к MITM. Использовать только для доверенных внутренних целей (localhost, dev-сертификаты). Никогда не включать для ненадёжных или публичных бэкендов.

Описание

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

TCP-туннелирование открывает локальный TCP-сервис (SSH, база данных, произвольный бинарный протокол) для доступа с интернета через инфраструктуру туннеля. Трафик передаётся как поток байт с мультиплексированием по надёжному транспорту между клиентом и сервером; поддерживаются режим публичного порта на стороне сервиса и сценарий expose-local (внешний порт на сервере), когда внешние клиенты подключаются к выделенному порту, а агент пробрасывает соединение на локальную машину. Для протоколов с TLS на стороне приложения платформа не расшифровывает полезную нагрузку на границе (в отличие от HTTP(S)-туннеля с терминацией TLS на входе).

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

• Разработчик открывает SSH к домашней машине для удалённой отладки.
• Команда подключается к общей базе данных на стенде разработчика через выданный host:port.
• Пользователь поднимает туннель к промышленному устройству или SCADA по TCP.
• Пользователь использует режим expose-local (внешний порт на сервере), чтобы внешний партнёр подключился к порту на сервере туннелей, а трафик ушёл на 127.0.0.1 у владельца.
• Пользователь полагается на автоматические повторы при кратковременных обрывах транспорта между CLI и сервером.
• Администратор ограничивает доступ списками IP на уровне туннеля.
• Пользователь сравнивает с HTTP(S)-туннелем: для «короткой ссылки в браузере» чаще подходит HTTP-маршрут; для сквозного TLS приложения — TCP-туннель (см. user-stories.md).
• На macOS пользователь может сочетать expose-local TCP с локальным слушателем на 127.0.0.1 (например nc или опционально socat) для интерактивной TCP-сессии поддержки и отладки (см. US-12 и раздел Ограничения).

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

Клиент регистрирует туннель на плоскости управления и получает публичный адрес:порт или инструкции для режима expose-local. Плоскость данных устанавливает защищённый канал между сервером и CLI, через который байты копируются между сокетом в интернете и локальным приложением. Сервер выделяет порты из настроенного диапазона, применяет лимиты на соединения и уважает паузу туннеля. Контроль доступа и тарифные ограничения применяются на этапе установления соединения и при создании туннеля так же, как для других протоколов.

Справочник API

Создание туннеля

POST /api/tunnels

Пример тела:

{
  "protocol": "tcp",
  "target_addr": "127.0.0.1:22"
}

Ответ содержит id, public_addr (или эквивалент host:port) и метаданные создания.

Требуется аутентификация, если на сервере не разрешён только гостевой режим.

Чтение и удаление

• GET /api/tunnels/{id} или GET /api/tunnels?id={id} — в зависимости от версии API вашего сервера.
• DELETE с тем же идентификатором — удалить туннель.

Публичный вход

Внешний клиент открывает TCP на выданный public host:port; сервер сопоставляет поток с туннелем и клиентским агентом.

CLI

См. справку ./bin/client для режима tcp и expose-local; глобальные флаги сервера, аутентификации и транспорта (-dp ws/quic/dtls) общие с другими протоколами.

Ошибки

Отказ в подключении

Целевой localhost порт закрыт — внешний клиент или CLI получают обрыв или сообщение об ошибке прокси в зависимости от стадии.

Превышен лимит одновременных соединений

Новые подключения к туннелю отклоняются или ожидают освобождения слота согласно политике сервера и тарифа.

ACL

Подключение с заблокированного IP отклоняется на входе туннеля.

Квоты и тариф

Создание или использование туннеля может быть отклонено с JSON 403 (квота, функция недоступна) по тем же правилам, что и HTTP-туннели.

Аутентификация

401 при обращении к API без учётных данных там, где они обязательны.

Ограничения

• Дополнительная задержка и джиттер по сравнению с прямым TCP неизбежны из-за туннелирования.
• Пул публичных портов ограничен настройками сервиса; исчерпание диапазона блокирует новые TCP-туннели.
• При паузе туннеля публичные соединения не обслуживаются до возобновления и переподключения клиента.
• Режим expose-local зависит от поддержки в CLI и на сервере; сетевой путь отличается от классического «публичный порт на сервере → локальный сервис».
• Не гарантируется сохранение долгих idle-соединений при агрессивных таймаутах NAT и прокси на пути.
• На macOS поведение интерактивной TCP-сессии зависит от выбранных утилит (BSD nc vs GNU netcat, опционально socat): это не SSH; полноценный TTY и сигналы не гарантируются. Рекомендуется слушать только 127.0.0.1, а не 0.0.0.0. Типовой порядок: (1) запустить локальный слушатель, например nc -l 127.0.0.1 7777; (2) поднять TCP-туннель на этот порт; (3) удалённый клиент подключается к выданному публичному host:port.

Описание

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

Инспектор HTTP-трафика сохраняет события HTTP/HTTPS-запросов, прошедших через туннель: метод, путь, код ответа, задержку и выборочные заголовки/тело в пределах политики приватности и размера. Владелец туннеля просматривает журнал в дашборде на странице инспектора и может повторить отдельный запрос в безопасном режиме с ограничениями на подмену пути и заголовков.

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

• Разработчик отлаивает API: находит неудачный запрос в списке, открывает детали и сравнивает с ответом бэкенда.
• Пользователь фильтрует события по туннелю, времени и пагинации, чтобы не загружать весь журнал.
• Пользователь подписывается на поток событий (SSE) для живого просмотра во время ручного теста.
• Пользователь запускает повтор запроса события в режиме «через облако» или «локально» с допустимыми правками тела/метода в рамках ограничений сервера.
• Администратор при поддержке просматривает те же события в рамках полномочий.

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

При проксировании HTTP-запроса сервис записывает нормализованное событие в хранилище инспектора (при включённой функции и настройках захвата). Запросы к API списка и детали проходят аутентификацию и проверку владения туннелем. Повтор запроса выполняется в изолированном контуре с валидацией переопределений (запрет опасных заголовков и абсолютных URL в пути, лимит размера тела), чтобы снизить риск злоупотреблений. В боевом режиме доступ к инспектору не должен быть открыт без входа; в отладочном режиме правила могут отличаться — это задача оператора развёртывания.

Справочник API

Список событий

GET /api/v1/inspector/events

Параметры (имена уточняйте по ответу сервера): tunnel_id, фильтры времени, пагинация limit / offset или курсор.

Ответ: JSON со списком событий и метаданными пагинации.

Одно событие

GET /api/v1/inspector/events/{id}

id должен быть URL-encoded в клиенте.

Поток SSE

GET /api/v1/inspector/events/stream?tunnel_id=...

Подписка на новые события; tunnel_id в query также передавать в закодированном виде при необходимости.

Повтор запроса

POST /api/v1/inspector/events/{eventId}/replay

Тело JSON: { "mode": "cloud" | "local", "overrides": { ... опционально } }.

Поля overrides (правки метода, пути, заголовков и тела) ограничены сервером: нельзя подставить абсолютный URL в path, запрещённые заголовки и слишком большое тело (лимит порядка десятков килобайт).

Ошибки

401 Unauthorized

Нет сессии или токена для инспектора (в боевом режиме).

403 Forbidden

Нет доступа к туннелю события.

400 Bad Request

Некорректные параметры списка или недопустимые правки запроса при повторе (путь, заголовки, размер тела).

404 Not Found

Событие не найдено или недоступно.

503 Service Unavailable

Инспектор отключён или хранилище недоступно.

Ограничения

• Захват может не включать полное тело запроса/ответа или маскировать чувствительные поля по политике сервера.
• Повтор запроса не гарантирует идентичный побочный эффект на бэкенде; использовать только на тестовых стендах с осторожностью.
• Большие журналы требуют фильтрации по времени и туннелю.
• В dev-режиме сервера правила аутентификации к инспектору могут быть слабее, чем в продакшене.

Описание

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

Инспектор UDP-трафика позволяет владельцу UDP-туннеля просматривать проходящие датаграммы: направление (к клиенту или к бэкенду), адреса, размер полезной нагрузки, время и при необходимости укороченное содержимое пакета с текстовой/шестнадцатеричной подсказкой и эвристическим разбором известных протоколов. Данные накапливаются на стороне сервиса и доступны через API и вкладку инспектора у туннеля. Гостевой режим не имеет доступа к UDP-инспектору.

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

• Разработчик отлаивает DNS, игровой UDP или кастомный протокол: открывает инспектор туннеля, вкладку UDP, фильтрует по времени и направлению, смотрит цепочку запрос/ответ между клиентом и локальным сервисом.
• Пользователь ищет конкретный поток по flow_key или подстроке адреса, чтобы отделить один клиент от другого.
• Администратор при расследовании инцидента запрашивает датаграммы пользователя по user_id (через админские параметры API), не смешивая чужие туннели без полномочий.
• Инженер подписывается на поток событий (SSE) для живого мониторинга во время нагрузочного теста.
• Пользователь открывает карточку датаграммы по идентификатору, чтобы увидеть полные метаданные и анализ полезной нагрузки, если она сохранена и не обрезана политикой размера.
• Сопровождение сверяет, что после изменения конфигурации туннеля трафик действительно доходит до бэкенда, сравнивая метки времени и направления в списке.

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

Трафик UDP-туннеля проходит через серверный прокси датаплана: при обмене датаграммами сервис фиксирует метаданные и ограниченный фрагмент содержимого и сохраняет запись в хранилище инспектора. Запросы из дашборда или внешнего клиента API проходят аутентификацию и проверку доступа к туннелю (владелец или администратор). Список поддерживает фильтры и постраничность; отдельный запрос отдаёт одну запись с дополнительным разбором полезной нагрузки; поток событий доставляет новые записи по подписке. Частота запросов может ограничиваться лимитами, чтобы защитить сервер от злоупотреблений.

Справочник API

Список датаграмм

GET /api/v1/inspector/udp/datagrams

Основные параметры запроса:

• tunnel_id — фильтр по туннелю (для не-админа обычно обязателен для осмысленной выборки и проверки доступа)
• from, to — границы времени (RFC3339)
• direction — направление потока
• flow_key — ключ потока
• addr_contains — подстрока в адресе
• search, search_payload, field_contains — расширенный поиск (при поиске по полезной нагрузке действуют более строгие лимиты выборки)
• limit, offset — пагинация

Ответ: JSON с массивом datagrams и объектом pagination (лимит, смещение, признак наличия следующих страниц).

Для администратора допускается параметр user_id для выборки в разрезе другого пользователя (см. поведение сервера в продакшене).

Одна датаграмма

GET /api/v1/inspector/udp/datagrams/{id}

id — UUID записи.

Ответ: метаданные записи; при наличии сохранённой полезной нагрузки — поля вроде payload, hex_dump, utf8_preview, analysis, а также parsed_summary / metrics, если заполнялись.

Поток SSE

GET /api/v1/inspector/udp/datagrams/stream

Опционально tunnel_id для фильтрации событий.

События с типом, соответствующим UDP-датаграммам (например udp_datagram), с телом в формате JSON.

Ошибки

401 Unauthorized

Пользователь не аутентифицирован или используется гостевой доступ — для UDP-инспектора он не допускается.

403 Forbidden

Аутентифицированный пользователь не имеет права на указанный туннель (чужой туннель без роли администратора).

400 Bad Request

Некорректные параметры фильтра (например, невалидный JSON в field_contains) или отсутствует идентификатор датаграммы в пути там, где он обязателен.

404 Not Found

Запись с указанным UUID не найдена или недоступна текущему пользователю.

429 Too Many Requests

Сработали лимиты частоты для API инспектора UDP.

503 Service Unavailable

Сервис инспектора отключён или хранилище недоступно.

500 Internal Server Error

Внутренняя ошибка при чтении или кодировании ответа. Повторить позже.

Ограничения

• Полезная нагрузка датаграммы обрезается на уровне сервера: длинные пакеты в списке и в деталях могут отображаться не полностью; точный предел задаётся конфигурацией сервера.
• Поиск, включающий содержимое полезной нагрузки, дороже обычного списка; сервер может снижать максимальный limit выборки.
• Разбор протоколов носит эвристический характер и не заменяет специализированные анализаторы.
• В режиме разработчика правила аутентификации к инспектору могут отличаться от боевого режима; в продакшене требуется строгая аутентификация и настроенные лимиты.

Описание

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

UDP-туннелирование пересылает датаграммы между локальным UDP-сервисом и клиентами в интернете через инфраструктуру туннеля. Подходит для DNS, syslog, игровых протоколов и других сценариев, где важна низкая задержка и модель «без установления соединения», с пониманием, что потери и порядок остаются на совести UDP. Сервер выделяет публичный UDP-порт в заданном диапазоне и сопоставляет потоки по правилам сессий и ключей потока.

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

• Разработчик публикует локальный DNS-резолвер или тестовый UDP-сервис для команды.
• Администратор собирает syslog или метрики с удалённых хостов на локальный коллектор.
• Пользователь подключается к игровому или стриминговому UDP-сервису за NAT.
• Пользователь задаёт в CLI локальный UDP listen и целевой адрес на стороне сервера согласно документации.
• Пользователь учитывает таймаут неактивности и максимальный размер датаграммы, настроенные оператором.

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

Клиент создаёт туннель с протоколом udp и поднимает транспорт плоскости данных; в параметрах запуска или сопутствующих сообщениях задаётся соответствие локального порта и удалённого назначения. Сервер слушает UDP на выделенном порту из диапазона конфигурации, классифицирует пакеты по туннелю и потоку и пересылает их через защищённый канал к агенту, который отправляет датаграммы локальному приложению. Неактивные потоки могут очищаться по таймеру; превышение размера датаграммы отсекается. Тарифы и списки доступа по IP применяются там, где продукт их подключает для UDP.

Справочник API

Создание туннеля

POST /api/tunnels

Пример:

{
  "protocol": "udp",
  "target_addr": "127.0.0.1:5353"
}

Ответ: идентификатор туннеля и публичный UDP-адрес (схема udp://host:port или поля host/port — как возвращает ваш сервер).

Статус и удаление

GET / DELETE по контракту API туннелей с идентификатором (см. актуальные пути в справочнике сервера).

CLI

./bin/client в режиме udp с флагами локального прослушивания и удалённого назначения (см. --udp-listen, --udp-dst в справке клиента).

Инспектор UDP

Просмотр записанных датаграмм: GET /api/v1/inspector/udp/datagrams (отдельная возможность продукта; требует прав зарегистрированного пользователя, не гостя).

Ошибки

Датаграмма слишком большая

Пакет превышает udp_max_payload_bytes сервера — отбрасывается или не пересылается (наблюдаемо как отсутствие ответа на стороне UDP).

Нет свободного порта

Не удаётся выделить порт из udp_port_range — создание туннеля завершается ошибкой API.

Таймаут неактивности

Поток UDP закрыт после простоя; следующая датаграмма может инициализировать новый поток или быть потеряна в зависимости от клиента.

401 / 403 на API

Создание или управление без прав или при запрете протокола политикой.

Ограничения

• UDP не гарантирует доставку и порядок; приложение должно это учитывать.
• NAT и файрволы могут ограничивать входящий UDP к клиенту агента.
• Диапазон публичных портов и лимиты размера задаются конфигурацией; нет отдельного глобального «выключателя UDP» в современной модели — доступ контролируется диапазоном, ACL и протоколом туннеля.
• Устаревшие флаги вроде -udp-enabled у сервера не используются; их наличие в скриптах приведёт к ошибке запуска.

Описание

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

Гостевой доступ позволяет создать туннель без регистрации и входа: пользователь сразу получает публичный URL к локальному сервису. Это снижает порог для демонстраций, быстрых вебхуков и разовых задач. Гостевой туннель живёт ограниченное время, имеет лимит объёма трафика и не даёт полноценного управления в дашборде; зарегистрированные пользователи получают расширенные возможности и контроль.

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

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

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

Запрос на создание туннеля без учётных данных обрабатывается плоскостью управления как особый тип учётной записи: выдаются короткоживущие параметры (срок жизни, потолок трафика), туннель появляется в той же подсистеме маршрутизации, что и именованные туннели. Публичный вход проксирует HTTP(S) или другие протоколы по правилам продукта; гость не видит инспектор и административные разделы. После истечения срока или лимита туннель перестаёт принимать трафик; управление «списком гостевых туннелей» в интерфейсе не предусмотрено — идентификация идёт по выданному URL.

Справочник API

Создание гостевого туннеля

POST /api/tunnels

Тело JSON: те же поля, что и для обычного создания (protocol, целевой адрес и т.д.), см. общую справку по API туннелей.

Без заголовка Authorization и без сессионной куки — если гостевой режим разрешён на сервере.

Ответ: данные туннеля с public_url (или эквивалент), время истечения, сведения о лимите трафика — в форме, которую возвращает ваш экземпляр сервера.

Доступ посетителя к URL

GET / POST / другие методы на публичный URL туннеля (путь /t/{id}/… или хост поддомена) — без входа на платформу; поведение определяется типом туннеля и локальным сервисом.

Ограничения для гостя

Эндпоинты дашборда, инспектора трафика и админки требуют зарегистрированного пользователя; гостевой токен URL не заменяет сессию для этих API.

Ошибки

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

Сервер отключил гостевой режим или превышена внутренняя квота — 4xx/5xx с телом JSON или текстом по политике развёртывания.

Туннель истёк или исчерпан трафик

Запросы к публичному URL возвращают страницу или JSON с сообщением о недоступности; нужно создать новый гостевой туннель.

401 на защищённых API

Попытка вызвать пользовательский API дашборда без регистрации — ожидаемое поведение для гостя.

Ограничения

• Ограниченный срок жизни туннеля (типично до 24 часов).
• Ограниченный объём трафика на туннель; при исчерпании туннель останавливается до срока.
• Нет списка гостевых туннелей в личном кабинете; сохраняйте выданный URL самостоятельно.
• Нельзя приостанавливать, удалять или настраивать гостевой туннель через дашборд тем же способом, что у зарегистрированного пользователя.
• Инспектор трафика и расширенная аналитика недоступны гостю.
• Протоколы и лимиты гостя задаются конфигурацией сервера и могут отличаться между развёртываниями.

Описание

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

Раздел «Настройки» в дашборде позволяет просматривать и менять параметры интерфейса, транспорта и связанных возможностей, а также при необходимости экспортировать и импортировать конфигурацию в JSON. Часть действий привязана к платным возможностям тарифа: на бесплатном плане соответствующие элементы отображаются неактивными с подсказкой о смене тарифа, а сервер дополнительно проверяет права при сохранении.

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

• Открыть Настройки в дашборде (/dashboard/settings) после входа в аккаунт.
• Изменить параметры интерфейса (заголовок, цвета и др.), если это разрешено тарифом и ролью.
• Настроить параметры UDP и QUIC/DTLS, когда соответствующие возможности доступны в продукте и на тарифе.
• Включить или отключить опции, связанные с аудитом, если функция доступна.
• Экспортировать текущую конфигурацию в JSON для резервного копирования или переноса на другую среду.
• Импортировать ранее сохранённый JSON через форму в разделе настроек.
• Увидеть заблокированные разделы на бесплатном тарифе и перейти к смене плана из подсказки в интерфейсе.
• Администратор сохраняет глобальные параметры, влияющие на отображение и поведение панели, через те же экраны и API настроек.

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

Пользователь работает в дашборде: форма отправляет изменения на сервер, который проверяет сессию, роль и права по тарифу, затем применяет допустимые параметры к конфигурации интерфейса и транспорта. Экспорт отдаёт снимок текущих настроек; импорт разбирает JSON и обновляет только разрешённые поля. Изменения вступают в силу без перезапуска клиента туннеля; для части параметров может потребоваться обновление страницы или повторный вход.

Справочник API

Публичные маршруты настроек дашборда. Для изменяющих запросов требуется активная сессия; в текущей версии сохранение глобальных параметров доступно администратору.

Сохранение настроек

POST /ui/settings

• Назначение: обновить параметры интерфейса, транспорта и связанных опций из формы дашборда.
• Авторизация: сессия; без прав администратора — 403 Forbidden.
• Успех: перенаправление обратно на страницу настроек.

Экспорт

GET /ui/settings/export

• Назначение: скачать JSON с текущей конфигурацией.
• Авторизация: сессия администратора.
• Успех: файл ui-config.json (или аналогичное имя, заданное клиентом).

Импорт

POST /ui/settings/import

• Назначение: загрузить JSON конфигурации (форма multipart или тело с полезной нагрузкой по контракту интерфейса).
• Авторизация: сессия администратора.
• Успех: перенаправление на страницу настроек с применёнными полями.

Описание

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

Раздел «Оплата» и связанные API позволяют пользователю оформить подписку Pro через платёжного провайдера ЮKassa (при включённой конфигурации магазина и хранилища планов). Сервис создаёт платёж, перенаправляет пользователя на страницу оплаты, принимает вебхуки от провайдера и после проверки состояния платежа назначает тариф Pro или откатывает на Free при отмене продления или ошибке списания. Пользователь видит статус подписки, дату следующего списания и может отвязать сохранённый способ оплаты в рамках описанных в продукте правил (без мгновенной отмены уже оплаченного периода).

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

• Войти в дашборд и открыть раздел «Оплата», чтобы перейти к оплате подписки Pro и увидеть состояние после возврата с сайта провайдера.
• Оформить оплату картой или другим доступным в ЮKassa способом; после успешного платежа получить тариф Pro без ручного ввода кода активации.
• Просмотреть, привязан ли способ оплаты для автопродления и когда ожидается следующее списание.
• Отвязать способ оплаты, если не нужны автоматические продления, с учётом того, что текущий оплаченный период Pro сохраняется до окончания срока, если иное не описано в ограничениях продукта.
• Администратор при необходимости отменяет подписку пользователя через админ-инструменты (немедленный переход на Free), если это разрешено политикой развёртывания.

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

Пользователь обращается к публичным HTTPS API личного кабинета; сервер проверяет сессию и блокировку аккаунта, затем обращается к модулю биллинга, который взаимодействует с API ЮKassa и записывает состояние в хранилище. Уведомления провайдера приходят на отдельный вебхук-эндпоинт; обработчик подтверждает фактический статус платежа через API провайдера и только после этого обновляет назначение тарифа через общий с админкой модуль планов, чтобы лимиты и возможности применились сразу для туннелей и дашборда.

Справочник API

Публичные контракты для страницы «Оплата» и сервер-серверного вебхука. Пути ниже регистрируются только при включённом биллинге ЮKassa и поддерживаемой конфигурации планов (иначе маршруты могут отсутствовать — 404).

Текущий пользователь

POST /api/me/billing/yookassa/checkout

• Назначение: создать платёж и получить confirmation_url для перенаправления браузера.
• Авторизация: сессия или Bearer; без авторизации — 401. Заблокированный аккаунт — 403, JSON с code: "user_suspended" и сообщением на русском.
• Успех: 200, тело: { "confirmation_url": "<url>" }.
• Конфликт: тариф Enterprise — 409, error: "enterprise_plan".
• Ошибка создания: 400, checkout_failed.

GET /api/me/billing/yookassa/status

• Назначение: код плана, статус подписки, payment_method_linked, auto_renew_enabled, при наличии next_renewal_at (RFC3339 UTC).
• Авторизация: как у checkout. Внутренняя ошибка хранилища — 500, internal_error.

DELETE /api/me/billing/yookassa/payment-method

• Назначение: отвязать сохранённый способ оплаты в данных сервиса.
• Успех: 204.
• Конфликт: нечего отвязывать — 409, error: "no_payment_method".

Вебхук провайдера

POST /api/billing/yookassa/webhook

• Назначение: приём уведомлений ЮKassa; не вызывается из браузера пользователя.
• Ответы: 200 при успехе или заведомо некорректном теле; 503 при временных сбоях (повтор доставки провайдером). Подробнее — раздел Ограничения и Ошибки в документации по оплате.

Администратор

POST /api/admin/billing/yookassa/cancel-user

• Назначение: отмена подписки и перевод пользователя на Free (только role: admin).
• Тело: { "user_id": <number> }.

Ошибки

Сообщения и коды, которые пользователь или интегратор может наблюдать при работе с оплатой.

HTTP 401 Unauthorized

• Нет сессии или Bearer-токена на /api/me/billing/yookassa/*.
• Действие: выполнить вход в дашборд или передать валидный токен.

HTTP 403 Forbidden

• code: "user_suspended" — учётная запись заблокирована; оплата и просмотр статуса недоступны до разблокировки.
• Действие: обратиться к администратору или в поддержку.

HTTP 409 Conflict

• enterprise_plan при checkout — для текущего тарифа не предусмотрена оплата через этот поток.
• no_payment_method при DELETE отвязки — сохранённого способа оплаты нет.

HTTP 400 Bad Request

• checkout_failed / unlink_failed — не удалось завершить операцию; тело может содержать message с пояснением (UTF-8).

Вебхук (оператор инфраструктуры)

• 503 от обработчика вебхука означает временную ошибку; ЮKassa повторит доставку. Устранить причину (БД, доступность API ЮKassa, назначение плана).

Ограничения

• Раздел «Оплата» и API ЮKassa доступны только когда на сервере включена и корректно настроена оплата; иначе соответствующие пути возвращают 404.
• Отвязка способа оплаты не удаляет карту в личном кабинете ЮKassa; прекращает использование сохранённого способа для автосписаний в сервисе. Текущий оплаченный период Pro сохраняется до next_renewal_at.
• После успешной оплаты или отвязки статус в дашборде может обновиться с небольшой задержкой, пока сервис обработает уведомление провайдера.

Описание

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

Раздел администрирования «Пользователи» предназначен для управления зарегистрированными учётными записями дашборда: просмотр списка и карточки пользователя, назначение и история тарифных планов, просмотр и правка эффективных лимитов, временная блокировка (suspension) и полное удаление учётной записи. Доступ есть только у роли администратор; обычные пользователи этот раздел не видят.

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

• Администратор открывает Пользователи в админ-части дашборда и просматривает таблицу: логин, роль, активный тариф, статус (в т.ч. заблокирован), дата создания.
• Администратор обновляет список кнопкой обновления после изменений в другой вкладке или у другого оператора.
• Администратор открывает действия по строке пользователя: назначить или сменить тарифный план с указанием периода действия, просмотреть историю назначений и при необходимости скорректировать окна действия.
• Администратор просматривает детальную информацию по пользователю: активное назначение плана, эффективные лимиты, использование в текущем календарном месяце (UTC), чтобы понять, почему сработали ограничения.
• Администратор вручную корректирует эффективные лимиты пользователя (override), когда нужна разовая компенсация или тест без смены каталога планов.
• Администратор блокирует пользователя — тот не может пользоваться сервисом до разблокировки; активные туннели при необходимости завершаются со стороны сервера.
• Администратор разблокирует пользователя после проверки инцидента.
• Администратор удаляет учётную запись, когда аккаунт нужно полностью убрать из системы; связанные данные обрабатываются согласно политике хранения и каскадным правилам БД.
• Интегратор или сопровождение вызывает те же операции через админ HTTP API (сессия или токен администратора) для автоматизации или скриптов.

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

Запросы администратора попадают в защищённый контур админ-API: сервер проверяет подлинность и роль администратора, затем обращается к хранилищу пользователей и модулю тарифов. Список и детали строятся из актуальных записей о пользователе, назначенном плане и накопленном использовании за месяц. Операции изменения состояния (блокировка, смена плана, лимиты, удаление) последовательно обновляют базу, сбрасывают кэш прав пользователя и при необходимости завершают сессии и туннели, чтобы ограничения вступили в силу сразу. Пользовательский интерфейс в дашборде отображает те же данные, что отдаёт API, и направляет действия на соответствующие методы без отдельного бизнес-контура.

Справочник API

Базовый префикс

Все пути ниже относительно /api/admin. Требуется аутентификация и роль администратора. Мутирующие запросы из браузера могут требовать CSRF-токен при включённой защите.

Пользователи

Список

GET /api/admin/users

Ответ: 200, JSON-массив сводок по пользователям (логин, роль, признаки активного плана, статус и т.д. по фактической схеме ответа).

Деталь

GET /api/admin/users/{id}

Ответ: 200, объект детали (пользователь, активное назначение плана, эффективные лимиты, использование за текущий месяц UTC). 404, если пользователь не найден.

Удаление

DELETE /api/admin/users/{id}

Успех: 204 без тела. Ошибки: пользователь не найден, системные ограничения на удаление — по телу JSON с полем error.

Блокировка и разблокировка

POST /api/admin/users/{id}/suspend

POST /api/admin/users/{id}/unsuspend

Успех: 204 без тела.

Назначение плана

POST /api/admin/users/{id}/plan-assignment

Тело JSON: plan_id (число), опционально valid_from, valid_to в формате RFC3339 (UTC).

Успех: 201 с идентификатором назначения.

История назначений

GET /api/admin/users/{id}/plan-assignments — список назначений.

PATCH /api/admin/users/{id}/plan-assignments/{assignment_id} — правка окна действия (тело по контракту API).

Эффективные лимиты

GET /api/admin/users/{id}/effective-limits — чтение override.

PATCH /api/admin/users/{id}/effective-limits — частичное обновление лимитов, успех 204.

Ошибки

401 Unauthorized

Нет сессии или недействительный токен. Пользователь должен войти в дашборд (или передать валидный Bearer для API).

403 Forbidden

Учётная запись не является администратором. Раздел и админ-API недоступны.

404 Not Found

Запрошенный id пользователя не существует в каталоге зарегистрированных пользователей.

405 Method Not Allowed

Неподдерживаемый HTTP-метод для данного пути.

503 Service Unavailable

Администрирование пользователей временно недоступно (например, не подключён каталог пользователей). В JSON может быть поле error со значением вроде users_admin_unavailable.

500 Internal Server Error

Внутренняя ошибка при обращении к хранилищу. Повторить запрос позже; если повторяется — обратиться к сопровождению.

Ошибки домена (4xx, JSON)

Удаление или изменение системной учётной записи, конфликт бизнес-правил: тело ответа JSON с полем error и понятным для оператора смыслом (точные коды см. в ответе сервера).

Ограничения

• В списке пользователей отображаются зарегистрированные учётные записи дашборда; гостевые или служебные идентичности могут не попадать в этот каталог в зависимости от реализации каталога.
• Время использования квот и «текущего месяца» в деталях пользователя привязано к UTC, что может отличаться от локального календаря оператора.
• Удаление пользователя необратимо с точки зрения доступа к аккаунту; восстановление возможно только созданием новой учётной записи, если продукт это допускает.
• Назначение планов и лимитов требует согласованности с каталогом тарифов; несуществующий или отключённый план должен отклоняться API с ошибкой валидации.