diff --git a/tools/etcpmon/IMPLEMENTATION.md b/tools/etcpmon/IMPLEMENTATION.md index 2204178f..09b27266 100644 --- a/tools/etcpmon/IMPLEMENTATION.md +++ b/tools/etcpmon/IMPLEMENTATION.md @@ -1,171 +1,27 @@ -# ETCP Monitor - Implementation Summary +# Устройство etcpmon -## Overview -ETCP Monitor is a Windows GUI utility for real-time monitoring of ETCP connections in uTun. +Действующие контракты и использование описаны в [etcpmon_doc.md](etcpmon_doc.md), +API — в `etcpmon_client.h`, `etcpmon_gui.h`, `etcpmon_graph.h` и `etcpmon_protocol.h`. +Серверная реализация: `src/control_server.c/h` и +[control_server_doc.md](../../src/control_server_doc.md). -## Architecture +`WinMain` создаёт `etcpmon_app`, инициализирует Winsock/классы окон, создаёт окно и запускает +message loop. Таймер GUI вызывает неблокирующий `etcpmon_client_process()`; фонового сетевого +потока нет. Client завершает connect, разбирает TCP-кадры, обновляет кеши и вызывает GUI callbacks. +Сэмпл истории добавляет только парсер ответа метрик; GUI отображает уже сохранённую историю. -### Protocol (Binary) -- **Format**: `[2 bytes: size] [1 byte: type] [payload...]` -- **Period**: 100ms updates -- **Transport**: TCP socket +Все команды клиента проходят через один TX FIFO с лимитом 64 КиБ/256 кадров и смещением досылки. +Pending с ненулевым seq регистрируется вместе с кадром, но срок ответа начинается после полной отправки. +Тип и payload ответа проверяются до снятия pending и вызова callback. -### Message Types -**Client → Server:** -- `0x01` - Request connection list -- `0x02` - Select connection by peer_node_id -- `0x03` - Request metrics -- `0x04` - Disconnect +Сервер использует `ll_queue` с одним кадром до 32 КиБ и отдельным смещением частичной отправки. +Чтение/разбор команд ждут пустой очереди через отменяемый deferred waiter. Начальная подписка +хранит ID узлов и сериализует актуальную запись при освобождении TX; live-изменения объединяются +в ограниченном наборе из 256 ID. Переполнение отключает подписчика с диагностикой. +Перед освобождением клиента отменяются таймер и waiter, затем освобождаются снимок и очередь. +Метрики выдаются по запросу, а сообщения об узлах UTUN — только после явной подписки другого клиента; +сам GUI etcpmon подписку не использует. -**Server → Client:** -- `0x81` - Connection list response -- `0x82` - Metrics response (ETCP + TUN + Links) -- `0xFF` - Error response - -## Files Created - -### Protocol (Shared) -- `tools/etcpmon/etcpmon_protocol.h` - Protocol definitions and structures - -### Server (uTun) -- `src/control_server.h` - Control server interface -- `src/control_server.c` - TCP server implementation -- Modified `src/utun_instance.c` - Integration with uTun lifecycle -- Modified `src/Makefile.am` - Added control_server.c to build -- Modified `lib/debug_config.h` - Added DEBUG_CATEGORY_CONTROL - -### Client (Windows GUI) -- `tools/etcpmon/etcpmon_client.h/c` - Network layer (Winsock) -- `tools/etcpmon/etcpmon_gui.h/c` - WinAPI GUI implementation -- `tools/etcpmon/etcpmon_main.c` - Entry point -- `tools/etcpmon/Makefile.mingw` - MinGW build -- `tools/etcpmon/build.bat` - Windows build script -- `tools/etcpmon/build.sh` - Unix build script -- `tools/etcpmon/clean.bat` - Clean script -- `tools/etcpmon/README.md` - Documentation - -### Test -- `tests/test_control_server.c` - Integration test for control server protocol - -### Library Fix -- `lib/u_async.c` - Modified to use select() on Windows instead of WSAPoll - -## Build Instructions - -### Windows (Recommended) -```cmd -cd tools\etcpmon -build.bat -``` - -### Unix/MinGW -```bash -cd tools/etcpmon -bash build.sh -``` - -## Usage - -### 1. Configure uTun -Add to `utun.conf`: -```ini -control_ip=127.0.0.1 -control_port=9090 -``` - -### 2. Start uTun -```bash -./utun -``` - -### 3. Start ETCP Monitor -```cmd -etcpmon.exe -``` - -### 4. Connect -- Enter server IP:port (default: 127.0.0.1:9090) -- Click "Connect" -- Select connection from list -- View real-time metrics - -## Metrics Displayed - -### ETCP Connection -- RTT (last, avg 10, avg 100) -- Jitter -- Bytes sent total -- Retransmission count -- ACK count -- Unacked bytes -- Links count - -### TUN Interface -- Bytes read/written -- Packets read/written -- Read/write errors - -### Links (per link) -- Status (UP/DOWN) -- Encrypt/decrypt errors -- Send/receive errors -- Total encrypted/decrypted bytes -- Bandwidth (Kbps) -- NAT changes count - -## Technical Details - -### Windows select() Implementation -On Windows, the uasync library now uses `select()` instead of `WSAPoll()` for socket monitoring. This resolves issues with accepted TCP sockets that caused WSAPoll to fail with error 10022 (WSAEINVAL). - -**Changes in `lib/u_async.c`:** -- Added Windows-specific code path using `select()` -- Maintains compatibility with Linux (uses `poll()`) -- Properly handles both regular FDs and socket_t types - -### Binary Protocol -The protocol uses fixed-size binary structures for efficient communication: -- Header: 3 bytes (2 size + 1 type) -- Connection list item: 40 bytes (8 peer_id + 32 name) -- ETCP metrics: 40 bytes -- Link metrics: 32 bytes per link -- TUN metrics: 24 bytes - -## Testing - -### Unit Test -```bash -cd tests -./test_control_server -``` - -Expected output: -``` -================================ -Control Server Protocol Test -================================ - -[TEST] Setting up mock data... -[TEST] Mock data ready (1 conn, 2 links) -[TEST] Starting control server on port 19090... -[TEST] Control server started ✓ -[TEST] Starting client thread... -[TEST] Running event loop... - -[CLIENT] Connecting to 127.0.0.1:19090... -[CLIENT] Connected -[CLIENT] Sending CMD_LIST_CONN... -[CLIENT] Waiting for response... -[CLIENT] Received connection list: 1 connection(s) -[CLIENT] Connection verified: peer_id=0x1234567890ABCDEF ✓ -[CLIENT] All tests passed ✓ - -[TEST] Cleaning up... - -================================ -[PASS] All tests passed! -================================ -``` - -## License -See main project LICENSE file. +Проверки клиента: `make -C tools/etcpmon CC=x86_64-w64-mingw32-gcc TEST_RUNNER=wine check`. +Проверки серверных очередей/cleanup/метрик: цель `test_control_server` из `tests/Makefile.am`. +Они проверяют разные стороны протокола и не заменяют интеграционный запуск клиента с сервером. diff --git a/tools/etcpmon/README.md b/tools/etcpmon/README.md index 7711a318..88795b16 100644 --- a/tools/etcpmon/README.md +++ b/tools/etcpmon/README.md @@ -1,137 +1,65 @@ # ETCP Monitor -Windows GUI утилита для мониторинга ETCP подключений uTun в реальном времени. +WinAPI-монитор соединений uTun. Работает под Windows и Wine, подключается по IPv4 TCP +к `control_server`. Метрики выбранного соединения запрашиваются раз в 100 мс, +списки соединений и сокетов — раз в секунду. Сеть обрабатывается в GUI-потоке. -## Описание +Полное описание протокола, интерфейса, владения ресурсами и текущих ограничений: +[etcpmon_doc.md](etcpmon_doc.md). Серверная часть: [control_server_doc.md](../../src/control_server_doc.md). -ETCP Monitor - это Windows GUI приложение, которое подключается к работающему экземпляру uTun и отображает статистику ETCP подключений в реальном времени с периодом обновления 100мс. +## Сборка и запуск -## Архитектура - -### Протокол управления (бинарный) - -Формат сообщения: `[2 байта: размер] [1 байт: тип] [payload...]` - -**Команды клиента:** -- `0x01` - запрос списка подключений -- `0x02` - выбор подключения по `peer_node_id` -- `0x03` - запрос метрик выбранного подключения -- `0x04` - отключение - -**Ответы сервера:** -- `0x81` - список подключений -- `0x82` - метрики ETCP + линки + TUN -- `0xFF` - ошибка - -### Файлы - -**Общие (протокол):** -- `etcpmon_protocol.h` - определения структур и констант протокола - -**Сервер (utun):** -- `src/control_server.h` - интерфейс control server -- `src/control_server.c` - реализация TCP сервера - -**Клиент (Windows GUI):** -- `etcpmon_client.h/c` - сетевая часть (Winsock) -- `etcpmon_gui.h/c` - GUI (WinAPI) -- `etcpmon_main.c` - точка входа - -## Сборка - -### Клиент (Windows) - Рекомендуемый способ - -**Используя MSYS2 UCRT64 (рекомендуется):** +Windows/MSYS2 UCRT64: ```cmd cd tools\etcpmon build.bat +etcpmon.exe ``` -Это автоматически запустит MSYS2 UCRT64 shell и выполнит сборку. +`build.bat` использует `C:\msys64`, либо `MSYS2_ROOT`/`MSYS2`. Внутри MSYS2 можно выполнить `bash build.sh`. -Требования: -- Установленный MSYS2 (обычно в `C:\msys64`) -- Или переменная окружения `MSYS2_ROOT` с путем к MSYS2 - -**Альтернативные способы:** +Linux с установленными MinGW и Wine, из корня проекта: ```bash -# Через MSYS2 напрямую -cd tools/etcpmon -bash build.sh - -# Через Makefile (если установлен make для Windows) -make -f Makefile.mingw +make -C tools/etcpmon CC=x86_64-w64-mingw32-gcc +wine tools/etcpmon/etcpmon.exe +make -C tools/etcpmon CC=x86_64-w64-mingw32-gcc TEST_RUNNER=wine check ``` -**Очистка:** -```cmd -clean.bat -``` +Для запуска GUI и WinAPI-тестов нужен дисплей; без рабочего стола можно использовать `xvfb-run -a`. -### Сервер (utun) +## Подключение -Control server интегрирован в utun. Сборка стандартная: - -```bash -./configure -make -``` - -## Настройка - -### Конфигурация uTun - -Добавьте в `utun.conf`: +В конфиге uTun: ```ini -control_ip=127.0.0.1 -control_port=9090 +[control] +ip=127.0.0.1 +port=9090 +allow=127.0.0.1/32 ``` -### Использование +Без `allow` все подключения отклоняются. Транспорт управления не шифруется и не аутентифицирует +ключи ETCP: используйте loopback или доверенный защищённый канал. -1. Запустите uTun с настроенным control socket -2. Запустите etcpmon.exe -3. Введите IP и порт control сервера -4. Нажмите "Connect" -5. Выберите подключение из списка для просмотра метрик +При открытии окна etcpmon автоматически начинает connect к `192.168.40.1:9091`. +Нажмите Disconnect, задайте числовой IPv4/порт своего сервера и нажмите Connect. +Первое соединение выбирается автоматически. Enter в адресе/порту подключает, Escape отключает. -## Отображаемые метрики +## Состав -### ETCP Connection: -- RTT Last/Avg10/Avg100 (микросекунды) -- Jitter (микросекунды) -- Bytes Sent (всего) -- Retransmissions (число) -- ACK received (число) -- Unacked bytes (текущие) -- Links count (число линков) +- `etcpmon_client.c/h`: неблокирующий Winsock-клиент, разбор кадров, pending ответов, кеши и история. +- `etcpmon_gui.c/h`: окно, контролы, опрос списков, обработка событий и Action Result. +- `etcpmon_graph.c/h`: график восьми метрик первого линка и выбор сэмпла курсором. +- `etcpmon_protocol.h`: общий с сервером wire-layout: `[size:2][type:1][seq_id:1][payload]`. +- `test_etcpmon.c`: регрессии клиента/GUI с локальным TCP-сервером; запускаются через `make check`. -### TUN Interface: -- Bytes Read/Written -- Packets Read/Written -- Read/Write Errors +Команда Action `nodes` возвращает текст узлов, `nat` подтверждает запуск NAT/STUN-проверки. +Неизвестная команда или недоступная служба возвращает ошибку с сохранением TCP-соединения. -### Links: -- Status (UP/DOWN) -- Encrypt/Decrypt Errors -- Send/Receive Errors -- Total Encrypted/Decrypted Bytes -- Bandwidth (Kbps) -- NAT Changes Count +Клиент досылает частичные кадры через ограниченный TX (64 КиБ/256 кадров). Сервер формирует +один кадр до 32 КиБ, приостанавливая чтение до его отправки; список узлов передаётся порциями. +Таймауты и ограничения подписки описаны в [etcpmon_doc.md](etcpmon_doc.md). -## Период обновления - -100 мс (10 обновлений в секунду) - -## Безопасность - -- Поддержка нескольких одновременных клиентов -- Отдельный TCP сокет (не путать с ETCP UDP) -- Рекомендуется использовать localhost (127.0.0.1) для локального мониторинга - -## Лицензия - -См. основной LICENSE файл проекта uTun. +Клиент пишет `etcpmon.log`, сервер — `control_server.log` в текущем рабочем каталоге каждого процесса.