utun2/src/control_server_doc.md

Control Server (control_server)

1. Назначение

TCP-сервер для мониторинга ETCP-соединений. Принимает подключения от GUI-клиента etcpmon, отдаёт по запросу метрики соединений/каналов/TUN/роутера, список узлов BGP-топологии, позволяет менять уровни отладки на лету. Уведомляет подписанных клиентов об изменениях узлов через control_server_notify_node_change().

2. Как пользоваться

1. Вызвать control_server_init() — создаёт слушающий TCP-сокет на адресе из конфига control_sock, регистрирует accept-колбэк в uasync.
2. Периодически вызывать control_server_process_updates() для обработки накопившихся данных клиентов.
3. При изменении/удалении узла BGP-топологии вызывать control_server_notify_node_change() / control_server_notify_node_removed() — сервер сам разошлёт уведомления подписанным клиентам.
4. При остановке вызвать control_server_shutdown().

Нюансы:

• Доступ разрешён только IPv4-клиентам по control_allow в конфиге; без правил доступ запрещён. IPv6-клиенты отклоняются.
• Клиенты отключаются по idle-таймауту (30 секунд без команд). Каждая обработанная команда перезапускает таймер.
• Лог пишется в control_server.log: дампы содержат первые 256 байт каждого чтения RX и некоторых ответов TX.
• control_server_process_updates() разбирает команды; метрики отправляются только по CMD_GET_METRICS.
• Очередь отправки владеет исходными буферами до полной отправки или отключения; частичная отправка хранит отдельное смещение.
• Если список сокетов превышает предел сообщения (32 768 байт; сейчас помещается 230 записей), возвращается RSP_ERROR с кодом SERVER_BUSY. Список не усекается; сокеты probe_only не учитываются.
• SET_DEBUG_CONFIG требует ровно 2 + category_count байт, не более 64 категорий. Несоответствие длины закрывает соединение без применения настроек.

3. API

Структуры

Структура	Назначение
struct control_server	Состояние сервера: listen_fd, связный список clients, uasync-контекст, счётчик клиентов.
struct control_client	Состояние клиента: fd, буфер приёма (recv_buffer), output_queue для асинхронной отправки, selected_peer_id, флаг подписки на узлы.

Функции

Функция	Назначение
control_server_init(server, ua, instance, bind_addr, max_clients)	Создать слушающий сокет, зарегистрировать в uasync. Возвращает 0 / -1.
control_server_shutdown(server)	Закрыть всех клиентов, освободить слушающий сокет, закрыть лог-файл.
control_server_process_updates(server)	Обработать накопившиеся данные всех клиентов (вызывать периодически).
control_server_get_client_count(server)	Вернуть количество подключённых клиентов.
control_server_notify_node_change(server, node)	Разослать подписанным клиентам сериализованную информацию об узле.
control_server_notify_node_removed(server, node_id)	Разослать подписанным клиентам уведомление об удалении узла.

Поддерживаемые команды ETCPMON

Команда	Ответ	Описание
CMD_LIST_CONN	RSP_CONN_LIST	Список активных ETCP-соединений.
CMD_SELECT_CONN	—	Выбрать соединение по peer_node_id для метрик.
CMD_GET_METRICS	RSP_METRICS	Полные метрики: ETCP, TUN, router, все каналы с BBR.
CMD_LIST_SOCKETS	RSP_SOCKET_LIST	Список локальных сокетов с NAT-типом и NAT-адресом.
CMD_ACTION	Для "nodes" — RSP_ACTION_RESULT; для "nat" — без ответа	"nat" — запрос NAT-проверки; "nodes" — дамп BGP-узлов текстом.
CMD_GET_DEBUG_CONFIG	RSP_DEBUG_CONFIG	Текущие уровни отладки (глобальный + по категориям).
CMD_SET_DEBUG_CONFIG	—	Установить уровни отладки.
CMD_SUBSCRIBE_NODES	RSP_NODE_INFO (список) + RSP_NODE_INFO_END	Подписка на изменения узлов + текущий список.
CMD_DISCONNECT	—	Отключение клиента.