Собственный поддомен

Описание

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

Функция «Свой поддомен» позволяет владельцу HTTP/HTTPS-туннеля задать стабильную метку в адресе вида https://{метка}.{домен_сервиса}/… вместо случайного поддомена, чтобы делиться одной и той же ссылкой с командой и интеграциями. Метка должна быть корректной DNS-меткой, не входить в зарезервированный список и быть уникальной в системе. На тарифах без этой возможности панель и API возвращают отказ с указанием функции; администраторы при управлении чужими туннелями ограничения тарифа обычно не испытывают.

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

• Разработчик после создания туннеля в дашборде задаёт свой поддомен в карточке туннеля или через API PATCH с действием set_public_subdomain.
• Пользователь делится коротким брендированным URL с заказчиком на поддомене домена сервиса. Каноническая ссылка для HTTP/HTTPS — URL туннеля вида https://{метка}.{домен_сервиса}/….
• Интегратор настраивает OAuth redirect URI на постоянный хост туннеля.
• Владелец переименовывает поддомен в пределах правил уникальности (старое имя освобождается для других после успешного перехода).
• Пользователь на бесплатном плане пытается включить метку и получает понятный отказ с предложением сменить тариф.
• Администратор правит поддомен для туннеля пользователя при операционной необходимости.

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

Запрос на смену метки приходит на плоскость управления вместе с идентификатором туннеля. Сервер проверяет владельца (или администратора), правила тарифа для обычных пользователей, формат метки, уникальность и частоту смены (защита от злоупотреблений). После успеха обновляется запись туннеля с новым URL туннеля и обновляется соответствие имя хоста → туннель, чтобы входящие запросы по новому имени сразу попадали в тот же туннель. Дальнейшая обработка запроса совпадает с обычной HTTP-маршрутизацией: проверки доступа, лимиты и обратный прокси к локальному сервису.

Справочник API

Смена своего поддомена

PATCH /api/tunnels (тот же маршрут, что и для других действий над туннелем).

Тело JSON (поля уточняйте по актуальному контракту API создания/изменения туннеля):

• id — идентификатор туннеля (должен совпадать с объектом изменения).
• action: set_public_subdomain
• public_subdomain: строка — метка поддомена (только допустимые символы DNS-метки, без точек).

Успех: туннель возвращается с обновлённым URL туннеля (в ответе API — поле public_url) и полями хоста (как в ответе вашего API PATCH).

Ошибки: 400 (неверная метка, зарезервировано, не HTTP(S) туннель), 403 (нет функции в тарифе для не-админа), 409 (метка занята), 429 (слишком частые переименования), 413 (слишком большое тело запроса).

Авторизация

Требуется вход в дашборд или Bearer-токен. Не-владелец (кроме администратора) не может менять чужой туннель.

Ошибки

400 Bad Request

Недопустимая метка (длина, символы, дефисы), метка в зарезервированном списке, или туннель не HTTP/HTTPS — в теле JSON указано сообщение об ошибке.

401 Unauthorized

Пользователь не аутентифицирован.

403 Forbidden

Нет прав на изменение туннеля или у пользователя нет функции custom-public-subdomain в тарифе (код вроде feature_disabled в JSON).

409 Conflict

Такой поддомен уже используется другим туннелем.

413 Payload Too Large

Тело PATCH превышает лимит сервера.

429 Too Many Requests

Превышен лимит частоты переименований поддомена для пользователя.

Ограничения

• Доступно только для туннелей с протоколом HTTP или HTTPS.
• Метка — одна DNS-метка без точек; полноценный произвольный домен — отдельная возможность продукта (кастомные домены).
• Смена поддомена ограничена по частоте на пользователя.
• Уникальность проверяется глобально в пределах окружения: занятая метка недоступна другому туннелю, пока не освобождена.