From 14d1673f06ef89bb2a92dcc19665253a8e766e68 Mon Sep 17 00:00:00 2001 From: evgeny Date: Sun, 2 Aug 2026 12:16:25 +0300 Subject: [PATCH] AGENTS.md: update structure to reflect actual codebase layout MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Debug categories: 25→27, add CONNECTIVITY and DB_SYNC - Directory structure: reflect real subdirs (transport_layer, routing_layer, chat, proxy, lwip_tcp, media_delivery, media_async) - File overview: reorganize by actual subdirectories, fix paths - BBR: src/BBR/ → src/transport_layer/BBR/ - topo_node_lmdb → topo_node_sqlite - Remove sha256.c/h (deleted), add missing lib/ modules (sqlite3, opus_codec, audio_compressor, json_flat) - Add missing modules: ntp_time, ntp_node_time, media_delivery, media_async, nat_detection, topo_recovery, topo_group_connect, node_conn_direct, socket_monitor - Add chatgui-android to tools/ --- AGENTS.md | 97 ++++++++++++++++++++++++++++++++----------------------- 1 file changed, 57 insertions(+), 40 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 2b60d22a..60fa2a78 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -203,12 +203,12 @@ debug - всё что нужно для понимание сути происх info - сообщения для пользователя о работе. мы должны видеть в читаемом виде понятные и осмысленные сообщения о каких-либо значимых действиях с точки зрения логики работы модуля или приложения warn / error - ошибки и предупреждения (аномалии). должны быть во всех ошибочных ветках. Молча вываливаться с ошибкой нельзя, все ошибки и предупреждения должны логироваться. -### Debug Categories (25 категорий) +### Debug Categories (27 категорий) ``` 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, -KEEPALIVE=21, ETCPROUTE=22, BBR=23, ETCP_DUMP=24 +KEEPALIVE=21, ETCPROUTE=22, BBR=23, ETCP_DUMP=24, CONNECTIVITY=25, DB_SYNC=26 ``` ### Настройка отладки @@ -225,13 +225,22 @@ KEEPALIVE=21, ETCPROUTE=22, BBR=23, ETCP_DUMP=24 ### Directory Structure ``` -├── lib/ # Core libraries (17 .c + 17 .h) -├── src/ # Main source code (42 .c + 44 .h root + 17 в поддиректориях) -├── tests/ # 65 .c файлов, 55 в check_PROGRAMS +├── lib/ # Core libraries (18 .c + 20 .h + libopus/liblmdb) +├── src/ # Main source code +│ ├── transport_layer/ # ETCP stack, crypto, STCP, normalizer, BBR (~30 файлов) +│ ├── routing_layer/ # Routing, BGP, conn_mgr, etcp_router, NAT detection (~20 файлов) +│ ├── chat/ # P2P чат, db_sync, merkle_sync, member_sync (17 файлов) +│ ├── proxy/ # SOCKS5, TCP/UDP/ICMP прокси (10 файлов) +│ ├── lwip_tcp/ # Встроенный lwIP TCP стек (7 файлов) +│ ├── media_delivery/ # Доставка медиафайлов (6 файлов) +│ ├── media_async/ # Асинхронный движок медиа (2 файла) +│ └── *.c/h # Корневые модули: utun, config, TUN, firewall, NAT, NTP, control (~14 файлов) +├── tests/ # ~70 тестов, 64 в check_PROGRAMS ├── doc/ # Technical Specifications ├── tools/ # Auxiliary tools │ ├── etcpmon/ # GUI монитор ETCP -│ ├── chatgui/ # GUI чат (Qt 5, отдельная сборка через CMake) +│ ├── chatgui/ # GUI чат (Qt 6 с Qt 5 fallback, сборка CMake) +│ ├── chatgui-android/ # Android P2P чат (Jetpack Compose + libutun_lite) │ ├── tdesktop-dev/ # Референс: Telegram Desktop (только для изучения) │ ├── proxy/ # UDP прокси для тестов │ └── bping/ # BPing (bandwidth ping) @@ -248,49 +257,53 @@ KEEPALIVE=21, ETCPROUTE=22, BBR=23, ETCP_DUMP=24 - `tun_if.c/h` - TUN interface API (init/write/close, cross-platform) - `tun_linux.c` `tun_freebsd.c` `tun_windows.c` - Platform-specific TUN implementations - `tun_route.c/h` - TUN routing table sync +- `config_parser.c/h` - INI-style config file parsing +- `config_updater.c/h` - Config file modification utilities +- `control_server.c/h` - Control/monitoring server (etcpmon backend API) +- `firewall.c/h` - Firewall rules (per-interface filtering) +- `eim_nat.c/h` - Endpoint-Independent Mapping NAT engine +- `nat_transport.c/h` - NAT transport layer (packet relay) +- `ntp_time.c/h` - NTP time synchronization +- `ntp_node_time.c/h` - Inter-node time synchronization -**Network Stack (src/)** +**Transport Layer (src/transport_layer/)** - `etcp.c/h` - ETCP protocol implementation (inflight queues, retrans, ACK, RTT/jitter) - `etcp_api.c/h` - ETCP public API (send/recv/bind callbacks) - `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 +- `etcp_connect.c/h` - ETCP outbound connections - `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) - -**BBR (src/BBR/)** -- `bbr_v3.c` - BBR congestion control algorithm v3 - -**STCP (src/)** +- `secure_channel.c/h` - AES-CCM encryption with X25519 key exchange, pubkey obfuscation +- `crc32.c/h` - CRC32 checksums - `stcp.c/h` - STCP протокол (Secure TCP) - `stcp_server.c/h` - STCP сервер - `stcp_client.c/h` - STCP клиент - `stcp_link.c/h` - STCP линк-уровень +- `node_conn_direct.c/h` - Direct config-based connections +- `socket_monitor.c/h` - Socket state monitoring -**Топология / Маршрутизация (src/)** -- `routing.c/h` - Таблица маршрутов (локальные) -- `route_lib.c/h` - Библиотека маршрутизации -- `route6_lib.c/h` - IPv6 маршрутизация -- `route_ping.c/h` - Route ping probing (NAT check, liveness) -- `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/priv.h` + `conn_mgr_core|indirect|monitor.c` — Менеджер соединений (handle-based API, 3 фазы DIR/REV/IND, Invite) - -**Crypto (src/)** -- `secure_channel.c/h` - AES-CCM encryption with X25519 key exchange, pubkey obfuscation -- `crc32.c/h` - CRC32 checksums +**BBR (src/transport_layer/BBR/)** +- `bbr_v3.c` - BBR congestion control algorithm v3 -**NAT (src/)** -- `eim_nat.c/h` - Endpoint-Independent Mapping NAT engine -- `nat_transport.c/h` - NAT transport layer (packet relay) +**Routing Layer (src/routing_layer/)** +- `routing.c/h` - Routing table (local) +- `route_lib.c/h` - Routing library +- `route6_lib.c/h` - IPv6 routing +- `route_ping.c/h` - Route ping probing (NAT check, liveness) +- `route_connectivity.c/h` - Route connectivity checks +- `topo_group.c/h` - BGP-like route exchange between nodes +- `topo_group_connect.c/h` - BGP group connections +- `topo_node.c/h` - Node management (peer management) +- `topo_node_sqlite.c/h` - SQLite persistence for nodes +- `topo_recovery.c/h` - Topology recovery +- `conn_mgr.h` + `conn_mgr_core.c`/`conn_mgr_indirect.c`/`conn_mgr_monitor.c` + `conn_mgr_priv.h` — Connection Manager (handle-based API, 3-phase DIR/REV/IND) +- `etcp_router.c/h` - ETCP router/multiplexer (мультиплексирование каналов, transit forwarding) +- `nat_detection.c/h` - NAT type detection **Chat (src/chat/)** — децентрализованный P2P чат: сообщения и участники автоматически синхронизируются между всеми узлами канала без центрального сервера. - `chat_core.c/h` - Главный модуль чата. Единственная точка входа из GUI: принять сообщение, создать канал, изменить настройку. Управляет БД и жизненным циклом всех chat-модулей @@ -306,13 +319,6 @@ KEEPALIVE=21, ETCPROUTE=22, BBR=23, ETCP_DUMP=24 - `chat_msg.c` - Отправка и приём сообщений: запись в локальную БД, автоматическая рассылка всем участникам канала (часть chat_core) - `chat_status.c` - Сбор диагностики: текущее время, активные соединения, типы NAT. Отправляется в GUI (часть chat_core) -**Config (src/)** -- `config_parser.c/h` - INI-style config file parsing -- `config_updater.c/h` - Config file modification utilities - -**Control (src/)** -- `control_server.c/h` - Control/monitoring server (etcpmon backend API) - **Прокси (src/proxy/)** - `socks_proxy.c/h` - SOCKS5 прокси - `udp_proxy.c/h` - UDP прокси @@ -326,13 +332,20 @@ KEEPALIVE=21, ETCPROUTE=22, BBR=23, ETCP_DUMP=24 - `lwip_pbuf.c/h` - Пакетные буферы lwIP - `lwip_tcp_priv.h`, `lwip_tcp_opts.h` - Внутренние настройки lwIP +**Media Delivery (src/media_delivery/)** +- `media_delivery.c/h` + `media_delivery_proto.h` - Доставка медиафайлов, протокол +- `media_download.c/h` - Скачивание медиа +- `media_index.c/h` - Индексация медиафайлов + +**Media Async (src/media_async/)** +- `media_async.c/h` - Асинхронный движок (thread-per-task для crypto/file операций) + **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 - `memory_pool.c/h` - Fast object pool allocator (pre-allocated blocks) - `debug_config.c/h` - Debug logging system (levels, categories, dual output, runtime config) - `timeout_heap.c/h` - Min-heap for timer management (used by u_async) -- `sha256.c/h` - SHA256 hashing (fallback; OpenSSL preferred via USE_OPENSSL) - `mem.c/h` - Memory wrappers with leak tracking (`u_malloc`/`u_free`/`u_calloc`/`u_strdup`) - `serialize.c/h` - Binary serialization utilities - `swm_min.c/h` - Sliding window minimum (for RTT min tracking) @@ -342,6 +355,10 @@ KEEPALIVE=21, ETCPROUTE=22, BBR=23, ETCP_DUMP=24 - `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) +- `sqlite3.c/h` - SQLite3 amalgamation (embedded database) +- `opus_codec.c/h` - Opus audio codec wrapper +- `audio_compressor.c/h` - Audio dynamic range compressor +- `json_flat.c/h` - Flat JSON parser - `wintun.h` - Wintun API header for Windows TUN driver **Memory Pools in UTUN_INSTANCE:**