From c0935aba6c7491919a9f2bdcf3dce5448ff382d7 Mon Sep 17 00:00:00 2001 From: Evgeny Date: Mon, 13 Jul 2026 15:21:30 +0300 Subject: [PATCH] docs: update AGENTS.md and etcp_arch.md --- AGENTS.md | 85 ++++++++++++++++++++++++++++++++++++++---------- doc/etcp_arch.md | 2 +- 2 files changed, 69 insertions(+), 18 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 887988e9..d9832f1d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -194,11 +194,12 @@ sc_obfuscate_pubkey(salt, peer_pubkey_bin, my_pubkey_bin, obfuscated_output); ### Debug Levels (по возрастанию) `none < error < warn < info < debug < trace` -### Debug Categories (21 категория) +### Debug Categories (25 категорий) ``` NONE=0, UASYNC=1, LL_QUEUE=2, CONNECTION=3, ETCP=4, CRYPTO=5, MEMORY=6, TIMING=7, CONFIG=8, TUN=9, ROUTING=10, TIMERS=11, NORMALIZER=12, BGP=13, -SOCKET=14, CONTROL=15, DUMP=16, TRAFFIC=17, DEBUG=18, GENERAL=19, NAT=20 +SOCKET=14, CONTROL=15, DUMP=16, TRAFFIC=17, DEBUG=18, GENERAL=19, NAT=20, +KEEPALIVE=21, ETCPROUTE=22, BBR=23, ETCP_DUMP=24 ``` ### Настройка отладки @@ -215,9 +216,9 @@ SOCKET=14, CONTROL=15, DUMP=16, TRAFFIC=17, DEBUG=18, GENERAL=19, NAT=20 ### Directory Structure ``` -├── lib/ # Core libraries (13 .c + 14 .h) -├── src/ # Main source code (28 .c + 23 .h) -├── tests/ # 31+ test programs +├── lib/ # Core libraries (17 .c + 17 .h) +├── src/ # Main source code (42 .c + 44 .h root + 17 в поддиректориях) +├── tests/ # 65 .c файлов, 55 в check_PROGRAMS ├── doc/ # Technical Specifications ├── tools/ # Auxiliary tools │ ├── etcpmon/ # GUI монитор ETCP @@ -245,17 +246,34 @@ SOCKET=14, CONTROL=15, DUMP=16, TRAFFIC=17, DEBUG=18, GENERAL=19, NAT=20 - `etcp_connections.c/h` - Socket and link management, INIT handshake, keepalive, PING/PONG - `etcp_loadbalancer.c/h` - Multi-link load balancing with traffic shaper - `etcp_debug.c/h` - ETCP packet dump/formatting +- `etcp_router.c/h` - ETCP router/multiplexer (мультиплексирование каналов) +- `etcp_connect.c/h` - ETCP outbound connections +- `etcp_dump.c/h` - ETCP дамп/декодирование пакетов +- `etcp_bbr.c/h` - BBR congestion control for ETCP - `pkt_normalizer.c/h` - Packet fragmentation/reassembly (packer/unpacker) - `packet_dump.c/h` - Packet hex dump utility - `firewall.c/h` - Firewall rules (per-interface filtering) - `dummynet.c/h` - Network emulator integrated into utun (for testing) -**Routing (src/)** -- `routing.c/h` - Routing table management (local routes) -- `route_lib.c/h` - Routing library utilities -- `route_bgp.c/h` - BGP-style route exchange between peers +**BBR (src/BBR/)** +- `bbr_v3.c` - BBR congestion control algorithm v3 + +**STCP (src/)** +- `stcp.c/h` - STCP протокол (Secure TCP) +- `stcp_server.c/h` - STCP сервер +- `stcp_client.c/h` - STCP клиент +- `stcp_link.c/h` - STCP линк-уровень + +**Топология / Маршрутизация (src/)** +- `routing.c/h` - Таблица маршрутов (локальные) +- `route_lib.c/h` - Библиотека маршрутизации +- `route6_lib.c/h` - IPv6 маршрутизация - `route_ping.c/h` - Route ping probing (NAT check, liveness) -- `route_node.c/h` - Route node (peer) management +- `route_connectivity.c/h` - Проверка связности маршрутов +- `topo_group.c/h` - BGP-подобный обмен маршрутами между узлами +- `topo_node.c/h` - Управление узлами (peer management) +- `topo_node_lmdb.c/h` - LMDB-персистентность узлов +- `conn_mgr.c/h` - Менеджер соединений **Crypto (src/)** - `secure_channel.c/h` - AES-CCM encryption with X25519 key exchange, pubkey obfuscation @@ -272,6 +290,23 @@ SOCKET=14, CONTROL=15, DUMP=16, TRAFFIC=17, DEBUG=18, GENERAL=19, NAT=20 **Control (src/)** - `control_server.c/h` - Control/monitoring server (etcpmon backend API) +**Транспорт сообщений (src/)** +- `msg_transport.c/h` - Транспорт сообщений (чат, команды) +- `db_sync.c/h` - Синхронизация БД между узлами + +**Прокси (src/proxy/)** +- `socks_proxy.c/h` - SOCKS5 прокси +- `udp_proxy.c/h` - UDP прокси +- `icmp_proxy.c/h` - ICMP прокси +- `tcp_proxy_server.c/h` - TCP прокси (серверная сторона) +- `tcp_proxy_client.c/h` - TCP прокси (клиентская сторона) + +**lwIP TCP (src/lwip_tcp/)** +- `lwip_tcp.c/h` - lwIP TCP стек +- `lwip_tcp_out.c` / `lwip_tcp_in.c` - Исходящий/входящий трафик +- `lwip_pbuf.c/h` - Пакетные буферы lwIP +- `lwip_tcp_priv.h`, `lwip_tcp_opts.h` - Внутренние настройки lwIP + **Libraries (lib/)** - `u_async.c/h` - Async event loop (epoll/poll/select, timers via timeout_heap) - `ll_queue.c/h` - Lock-free linked list queue with callbacks, hash index, threshold waiter @@ -286,6 +321,9 @@ SOCKET=14, CONTROL=15, DUMP=16, TRAFFIC=17, DEBUG=18, GENERAL=19, NAT=20 - `myip.c` - My IP helper (no header) - `socket_compat.c/h` - Cross-platform socket compatibility (Linux/FreeBSD/Windows) - `platform_compat.c/h` - Cross-platform compatibility layer (byte order, time, random) +- `radix.c/h` - Radix tree for IP routing lookups +- `tcp_io.c/h` - TCP I/O abstraction (Windows IOCP, Linux epoll) +- `wintun.h` - Wintun API header for Windows TUN driver **Memory Pools in UTUN_INSTANCE:** - `data_pool` — для данных пакетов (payload), используется input_queue/output_queue фрагментами @@ -308,7 +346,8 @@ SOCKET=14, CONTROL=15, DUMP=16, TRAFFIC=17, DEBUG=18, GENERAL=19, NAT=20 ### Запись в очередь - Очереди забивать нельзя. Добавляй следующий элемент только когда очередь стала пустой. -- Используй `queue_wait_threshold` для ожидания освобождения очереди до заданного порога. +- Порог задаётся через `queue_set_threshold(q, max_packets, max_bytes)`. +- Используй `queue_waiter_wait` для ожидания освобождения очереди до заданного порога. ### Чтение из очереди - Используй `queue_set_callback`: при вызове callback обработай один или несколько элементов, потом вызови `queue_resume_callback`. @@ -379,13 +418,13 @@ SOCKET=14, CONTROL=15, DUMP=16, TRAFFIC=17, DEBUG=18, GENERAL=19, NAT=20 ## chatgui (GUI Chat Client) -Chatgui — десктопный GUI-чат на Qt 5, отдельный проект внутри репозитория. Не связан с autotools-сборкой utun. +Chatgui — десктопный GUI-чат на Qt 6 (Qt 5 fallback), отдельный проект внутри репозитория. Не связан с autotools-сборкой utun. В chat gui интегрированы библиотеки utun. Чат и библиотеки работают в разных потоках. Поэтому нужно использовать семафоры, сокеты или другие механизмы синхронизации (uasync_post, uasync_memsync, uasync_get_wakeup_fd) ### Технологии -- **Язык:** C++17 -- **Фреймворк:** Qt 5.15+ (Widgets + Network) +- **Язык:** C++20 +- **Фреймворк:** Qt 6 (предпочитаемый) или Qt 5.15+ (Widgets + Network) - **Сборка:** CMake 3.16+ - **БД:** SQLite3 (WAL mode, встроенный `db/sqlite3.c` amalgamation) - **Анимации:** rlottie (C API) + zlib (gzip-декомпрессия TGS) @@ -393,7 +432,8 @@ Chatgui — десктопный GUI-чат на Qt 5, отдельный про ### Сборка ```bash # Установка зависимостей -sudo apt install librlottie-dev zlib1g-dev qtbase5-dev +sudo apt install librlottie-dev zlib1g-dev qt6-base-dev +# или qtbase5-dev для Qt 5 fallback # Сборка cd tools/chatgui && mkdir -p build && cd build @@ -405,6 +445,7 @@ cmake .. && make -j4 | Файл | Назначение | |------|-----------| +| `main.cpp` | Точка входа, инициализация QApplication | | `mainwindow.h/cpp` | Главное окно, QSplitter (ChannelList \| MessageList \| AccountList), трей | | `chatview.h/cpp` | QListView с фоновым изображением, hover-сигнал, drag-to-select | | `messagelist.h/cpp` | QStandardItemModel, stub-данные, инициализация анимаций, hover→activate | @@ -417,10 +458,18 @@ cmake .. && make -j4 | `animtimer.h/cpp` | Синглтон-таймер 30fps, refcount activate/deactivate, сигнал ticked | | `channellist.h/cpp` `channeldelegate.h/cpp` | Список каналов с аватарами и превью | | `accountlist.h/cpp` | Список аккаунтов/пользователей | +| `joindialog.h/cpp` | Диалог присоединения к группе/каналу | +| `invitedialog.h/cpp` | Диалог приглашения пользователя | +| `invite_link.h/cpp` | Логика invite-ссылок | +| `settingsdialog.h/cpp` | Окно настроек | +| `creategroupdialog.h/cpp` | Диалог создания группы | +| `networksettingspage.h/cpp` | Страница сетевых настроек | +| `qrcode_utils.h/cpp` | Утилиты для QR-кодов | +| `debug_ui.h` | Отладочный UI | ### Другие поддиректории -- `db/` — SQLite3 amalgamation (`sqlite3.c/h`), `db_manager.h/cpp` (схема: nodes, channels, messages, keys, addresses) -- `transport/` — TCP-клиент для связи с uTun (`msg_client.h/cpp`, бинарный протокол `[size:2][type:1][id:8][options:1][data...]`) +- `db/` — SQLite3 amalgamation (`sqlite3.c/h`), `db_manager.h/cpp` (схема: nodes, node_addresses, channels, msg_, peers_, local_identity, accounts, ui_state) +- `transport/` — интеграция с uTun: `gui_bridge.h/gui_bridge_impl.cpp` (Qt signal-based обмен), `chat_core.h/c` (управление), `chat_sync.h/c` (синхронизация), `db_sync_stub.c` (заглушка БД), `node_config.h/cpp`, `config_updater.h/cpp`, `utun_node.h/cpp`, `topo_node_sqlite.h/c` - `resources/` — `bg.jpg`, `chatgui.qrc` (встраивает 5 TGS в бинарник), `animations/*.tgs` ### Система анимированных эмодзи @@ -518,7 +567,9 @@ void lottie_animation_destroy(Lottie_Animation *anim); - `/doc/etcp_protocol.txt` - ETCP протокол (формат кодограмм, ACK, handshake, keepalive) - `/doc/etcp_arch.md` - ETCP архитектура - `/doc/etcp_config.txt` - Конфигурация ETCP +- `/doc/etcp_router_arch.md` - ETCP роутер архитектура - `/doc/route_p2pconn.txt` - Route peer-to-peer соединения +- `/src/route_bgp.txt` - BGP обмен маршрутами (дизайн-документ) ## Runtime - Запуск utun от root (для tun): `/home/vnc1/proj/utun3/utun_start.sh` diff --git a/doc/etcp_arch.md b/doc/etcp_arch.md index 8017f7ff..37b4e2a7 100644 --- a/doc/etcp_arch.md +++ b/doc/etcp_arch.md @@ -80,6 +80,6 @@ utun поддерживает встроенный ipv4 роутинг, може Тесты: # Правила работы с очередями в тестах: -- для добавления в очередь надо использовать queue_wait_threshold(q,0,0,arg) и добавлять по одному пакету, каждый раз дожидаясь когда очередь станет пустой. +- для добавления в очередь надо использовать queue_waiter_wait и queue_set_threshold, добавлять по одному пакету, каждый раз дожидаясь когда очередь станет пустой. - для получения надо использовать queue_set_callback + queue_resume_callback