UDP Traffic Inspector

Описание

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

Инспектор 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 выборки.
Разбор протоколов носит эвристический характер и не заменяет специализированные анализаторы.
В режиме разработчика правила аутентификации к инспектору могут отличаться от боевого режима; в продакшене требуется строгая аутентификация и настроенные лимиты.