# chatgui-android — Архитектура ## 1. Обзор Android-версия чатгуи: P2P чат на базе STCP (Secure TCP) вместо ETCP/UDP. Весь UDP-стек (ETCP, BBR, loadbalancer, pkt_normalizer, NAT, routing, TUN) исключён. Сетевой транспорт: только STCP (X25519 + AES-CCM поверх TCP). Приложение работает в двух режимах: - **Headless** — без UI, с управляющим TCP-сокетом (для отладки сетевого стека) - **Full UI** — Android приложение с Jetpack Compose интерфейсом ## 2. Уровни приложения ``` ┌─────────────────────────────────────────────────┐ │ Android App (Kotlin / Jetpack Compose) │ │ ├─ UI Layer (Compose) │ │ │ ├─ ChannelListScreen │ │ │ ├─ ChatScreen (MessageList + InputBar) │ │ │ ├─ CreateChannelDialog │ │ │ └─ JoinChannelDialog │ │ ├─ ViewModel Layer │ │ │ └─ ChatViewModel (StateFlow, Coroutines) │ │ ├─ Repository Layer │ │ │ ├─ ChatRepository (JNI → native) │ │ │ └─ DbRepository (Room, read-only) │ │ └─ NativeLib.kt (JNI declarations) │ ├─────────────────────────────────────────────────┤ │ JNI Bridge (C: android_jni_bridge.c) │ │ ├─ Kotlin → C: init/send/create/connect │ │ └─ C → Kotlin: callbacks via JNI CallVoidMethod │ ├─────────────────────────────────────────────────┤ │ Headless Control (встроен в libutun_lite) │ │ ├─ TCP control socket (текстовый протокол) │ │ ├─ Команды: connect, send, status, debug, ... │ │ └─ Events: MSG, PEER_ONLINE/OFFLINE, ... │ ├─────────────────────────────────────────────────┤ │ libutun_lite.so │ │ ├─ Core: uasync, ll_queue, memory_pool, │ │ │ debug_config, timeout_heap │ │ ├─ Crypto: secure_channel (X25519+AES-CCM), │ │ │ crc32, sha256 │ │ ├─ Transport: STCP (server/client/link) │ │ ├─ Chat: chat_core, chat_event, chat_sync, │ │ │ member_sync, merkle_sync │ │ ├─ DB: sqlite3 (WAL, чтение из GUI, запись │ │ │ из uasync) │ │ └─ Platform: socket_compat, platform_compat │ │ (Linux/Android) │ └─────────────────────────────────────────────────┘ ``` ## 3. Потоковая модель (Android) - **Main thread (UI)** — Compose rendering, ViewModel state - **uasync thread** — event loop (один на процесс, как и в desktop-версии) - STCP соединения: каждое = одно TCP-соединение в uasync - chat_core: все DB-записи из этого потока - chat_sync: P2P синхронизация через STCP - **DB:** SQLite WAL mode - uasync thread: INSERT/UPDATE/DELETE (через chat_core) - Main thread: SELECT (через Room/DbRepository, read-only) ## 4. Потоковая модель (Headless, Linux) Один процесс, один uasync-поток. Всё в одном потоке, включая control socket. Дополнительный поток для control socket не нужен — uasync обрабатывает и сеть и control-команды. ## 5. STCP вместо ETCP — изменения ### 5.1. Что уходит | Модуль | Причина | |--------|---------| | ETCP (etcp.c, etcp_api.c, etcp_connections.c, etcp_router.c, etcp_loadbalancer.c, etcp_bbr.c, etcp_connect.c) | Заменено на STCP link | | BBR (bbr_v3.c) | Congestion control для ETCP | | pkt_normalizer.c | Фрагментация/сборка — не нужна для потокового STCP | | dummynet.c | Эмулятор сети для отладки ETCP | | tun_if/tun_linux/tun_windows/tun_route | Нет VPN-туннеля | | routing, route_lib, route6_lib, route_ping, route_connectivity | Нет роутинга трафика | | eim_nat, nat_transport | Нет NAT-транспорта | | topo_group, topo_node, topo_node_lmdb | BGP-топология — прямые P2P | | conn_mgr | Менеджер ETCP-соединений | | firewall, proxy/*, lwip_tcp/*, uip/* | Не нужны | | ntp_time, ntp_node_time | Пока не нужны (можно добавить позже) | | packet_dump, etcp_debug, etcp_dump | Отладочные утилиты ETCP | ### 5.2. chat_sync — адаптация Десктопная версия chat_sync использует ETCP-роутер: множество каналов мультиплексируется через одно ETCP-соединение. В Android-версии каждое P2P-соединение — отдельный STCP линк. Замены в chat_sync.c: - `etcp_send(conn, svc_id, data)` → `stcp_link_send(link, data)` - `etcp_api_bind(svc_id, callback)` → приём из `stcp_link` rx_queue - Каждый peer = одно `stcp_link` соединение - Сервер: `stcp_server_listen()` принимает входящие ### 5.3. merkle_sync — адаптация merkle_sync — универсальный протокол синхронизации на Merkle-деревьях. В десктопе работает поверх ETCP-сервиса. В Android-версии: - Вместо etcp_send в рамках ETCP-сервиса → отправка напрямую через stcp_link - Формат wire-сообщений не меняется (MSG_HASHES, MSG_REQUEST, MSG_BATCH) - Изменяется только транспорт: вместо ETCP datagram → STCP stream ## 6. Control Socket (Headless) Управляющий TCP-сокет для отладки и управления без UI. Аналог `control_server` из utun, но с текстовым протоколом для простоты ручного тестирования. Порт: настраивается в конфиге (по умолчанию 9999). ### Команды (клиент → сервер) ``` connect [pubkey_hex] — STCP-подключение к пиру disconnect — отключиться от пира connections — список активных STCP-соединений create_channel — создать канал invite — invite-ссылка (utun://...) join — подключиться по invite send — отправить сообщение messages [limit] — последние сообщения channels — список каналов status — статус (соединения, каналы, ключи) debug = — debug level на лету debug_level — показать уровни отладки subscribe — подписаться на push-события help — список команд quit — отключиться от control (не остановка сервера) ``` ### Unsolicited events (сервер → клиент, только после subscribe) ``` EVENT MSG — новое сообщение EVENT PEER_ONLINE — пир подключился EVENT PEER_OFFLINE — пир отключился EVENT CHANNEL_CREATED — канал создан (локально) EVENT CHANNEL_JOINED — канал принят (по invite) EVENT CONN_RESULT — результат connect EVENT DB_READY — БД открыта и готова EVENT STATUS — периодический статус ``` ## 7. База данных (SQLite) Схема та же, что в десктопной версии chatgui (см. `tools/chatgui/doc/desc.txt`). БД открывается в WAL-режиме. Записи — из uasync-потока, чтение — из любого. Таблицы: - `channels` — каналы (channel_id, name, ключи X25519/Ed25519, подписи) - `msg_` — сообщения per-channel (id, author, content_type, data, timestamp, chain_hash, signature) - `peers_` — участники канала (node_id, online, x25519, ed25519, join_sig, адреса) - `nodes` — узлы (node_id, x25519_pubkey, ed25519_pubkey, name, online) - `node_addresses` — адреса узлов (node_id, family, address, port) - `accounts` — локальные аккаунты/контакты - `ui_state` — key-value для UI состояния - `merkle_tree_hash` — сохранённые хеши Merkle-дерева - `local_identity` — локальные ключи узла ## 8. Структура каталогов ``` tools/chatgui-android/ ├── doc/ │ ├── ARCHITECTURE.md # этот документ │ └── IMPL_PLAN.md # план реализации с этапами ├── libutun_lite/ # урезанное C-ядро (статическая библиотека) │ ├── CMakeLists.txt │ └── utun_lite.h # публичное API ├── headless/ # CLI для Linux (тестирование без Android) │ ├── CMakeLists.txt │ ├── headless_main.c # точка входа │ └── headless_control.c/h # управляющий TCP-сокет ├── jni_bridge/ # JNI прослойка │ ├── CMakeLists.txt # (только для Android NDK) │ └── android_jni_bridge.c # JNI-функции + коллбэки ├── app/ # Android приложение │ ├── build.gradle.kts │ └── src/main/ │ ├── AndroidManifest.xml │ ├── cpp/ # NDK: jni_bridge + линковка libutun_lite │ │ └── CMakeLists.txt │ ├── java/com/utun/chat/ │ │ ├── ChatApplication.kt │ │ ├── MainActivity.kt │ │ ├── ui/screens/ # Compose экраны │ │ ├── ui/components/# Compose компоненты │ │ ├── viewmodel/ # ViewModels │ │ ├── data/ # Repository, NativeLib.kt, Room DAOs │ │ └── headless/ # HeadlessService.kt (фоновый сервис) │ └── res/ └── CMakeLists.txt # корневой (для headless + libutun_lite) ``` ## 9. Минимальный набор C-файлов (libutun_lite) ### lib/ (infrastructure) - `u_async.c/h` — event loop (epoll на Linux, poll/select fallback) - `ll_queue.c/h` — lock-free очередь с хеш-индексом - `memory_pool.c/h` — пулы объектов - `debug_config.c/h` — логирование (уровни, категории, файл/консоль) - `timeout_heap.c/h` — min-heap таймеров - `sha256.c/h` — SHA256 (fallback; приоритет OpenSSL) - `mem.c/h` — u_malloc/u_free/u_calloc (wrappers) - `platform_compat.c/h` — кроссплатформенность (byte order, time, random) - `socket_compat.c/h` — кроссплатформенные сокеты - `serialize.c/h` — бинарная сериализация ### src/transport_layer/ (crypto + STCP) - `secure_channel.c/h` — AES-CCM + X25519 key exchange + pubkey obfuscation - `crc32.c/h` — CRC32 checksum - `stcp.c/h` — STCP connection lifecycle (session keys, buffers, state machine) - `stcp_server.c/h` — STCP server (listen, accept, handshake) - `stcp_client.c/h` — STCP client (connect, handshake) - `stcp_link.c/h` — STCP link management (обёртка над stcp_conn для etcp-подобного API) ### src/chat/ (чатовая логика) - `chat_core.c/h` + `chat_core_priv.h` — центральный API чата (send, create channel, connect) - `chat_event.c/h` — система нотификаций (MSG_RECEIVED, PEER_ONLINE, ...) - `chat_channel.c` — операции с каналами (создание, invite, join) - `chat_msg.c` — приём/отправка/сохранение сообщений - `chat_status.c` — сбор статуса для control socket / UI - `chat_profile.c` — профиль узла (имя, ключи) - `chat_sync.c/h` — P2P синхронизация (адаптирована под STCP) - `member_sync.c/h` — синхронизация мемберов - `merkle_sync.c/h` — Merkle-дерево синхронизации - `db_sync.c/h` — DB синхронизация (вставка/обновление записей синхронизации) ### Упрощённый вариант src/ (без TUN/ETCP/BGP) - `utun_instance_lite.c/h` — облегчённый instance (только ua, my_keys, db, stcp_server, control_socket) - `config_parser.c/h` — парсинг конфига (без ETCP/TUN/BGP-секций) ### Внешние - `lib/sqlite3.c/h` — SQLite amalgamation - OpenSSL (Crypto) — SHA256, AES-CCM, X25519, Ed25519 ## 10. Конфиг (chatgui-android.cfg) Формат INI, упрощённый относительно десктопной версии: ```ini [node] private_key = hex... public_key = hex... node_name = My Node listen_port = 12345 ; STCP server port [control] port = 9999 ; управляющий сокет bind_ip = 127.0.0.1 [db] path = chat_data/chats.db [debug] console_level = info file_level = debug log_file = utun.log debug_categories = stcp=debug,chat_core=info ``` ## 11. Отличие от десктопной версии | Аспект | Desktop (chatgui) | Android (chatgui-android) | |--------|------------------|--------------------------| | UI | Qt 6 Widgets (C++) | Jetpack Compose (Kotlin) | | Bridge | gui_bridge (Qt signals) | JNI callbacks + StateFlow | | Core сборка | CMake → libutun.a (все src/) | CMake → libutun_lite.a (выборочно) | | Транспорт | ETCP (UDP) + STCP (TCP) | STCP только (TCP) | | VPN | TUN + routing + BGP | Нет | | NAT | EIM NAT engine | Нет | | Аудио | miniaudio + opus | Нет (пока) | | Эмодзи/анимации | rlottie + TGS | Нет (пока) | | QR | zxing-cpp | Нет (пока) | | FFmpeg | Да | Нет | | Control | control_server (binary protocol) | headless_control (text protocol) | | Платформы | Linux, FreeBSD, Windows | Linux (headless), Android (app) |