utun2/src/msg_transport_doc.md

Msg Transport (msg_transport)

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

TCP-сервер для обмена сообщениями между локальными приложениями (например, chatgui) и удалёнными пирами через ETCP. Принимает TCP-соединения от локальных клиентов, привязывает (BIND) их к конкретному peer_node_id и пересылает данные туда-обратно через etcp_router. Поддерживает подписанные сообщения (Ed25519).

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

1. Вызвать msg_transport_init() — создаёт слушающий TCP-сокет, регистрирует callback on_etcp_recv в etcp_router_bind().
2. Локальное приложение (chatgui) подключается по TCP и шлёт фреймы протокола.
3. При остановке вызвать msg_transport_shutdown().

Протокол фрейма:

[size:2][type:1][id:8][options:1][data...]

• size — полный размер (включая поле size), native endian, до 8192 байт.
• type — команда (MSG_CTL_*, MSG_DATA_*, MSG_RSP_*).
• id — peer_node_id (uint64_t).
• options — битовые флаги (MSG_OPT_SIGNED = 0x01).

Нюансы:

• Приватный ключ (GET_PRIVKEY) отдаётся только подключениям с loopback (127.0.0.1 / ::1).
• Каждый peer_id может быть забинден только одним клиентом одновременно.
• Сообщения от пира без привязанного клиента молча дропаются (счётчик drops_no_client).

3. API

Структуры

Структура	Назначение
struct msg_transport	Состояние сервера: listen_fd, связный список clients, svc_id, счётчики.
struct msg_client	Состояние TCP-клиента: fd, буфер приёма, bound_peer_id, флаг is_localhost.
struct msg_header	Заголовок фрейма: size, type, id, options (12 байт, packed).
struct msg_transport_counters	Счётчики: accepted, closed, bind/unbind, msg_sent/recv, errors, drops.

Функции

Функция	Назначение
msg_transport_init(out, instance, ua, bind_addr, max_clients, svc_id)	Создать сервер, привязаться к порту, зарегистрировать svc_id в etcp_router_bind.
msg_transport_shutdown(t)	Закрыть всех клиентов, освободить сокет.
msg_transport_get_counters(t, c)	Скопировать счётчики в переданную структуру.
msg_build_header(hdr, payload_size, msg_type, id, options)	Заполнить заголовок фрейма (inline).
msg_validate_header(hdr)	Проверить корректность заголовка (inline).

Типы сообщений

Тип	Направление	Описание
MSG_CTL_BIND (0x01)	GUI→utun	Привязать TCP-соединение к пиру id. Ответ: RSP_BIND_OK.
MSG_CTL_UNBIND (0x02)	GUI→utun	Отвязать соединение.
MSG_CTL_GET_PUBKEY (0x03)	GUI→utun	Запросить свой публичный ключ. Ответ: RSP_PUBKEY (32 байта).
MSG_CTL_GET_PRIVKEY (0x04)	GUI→utun	Запросить приватный ключ (только localhost). Ответ: RSP_PRIVKEY (32 байта).
MSG_CTL_GET_PEER_INFO (0x05)	GUI→utun	Запросить ключи пира id. Ответ: RSP_PEER_INFO (pubkey + ed25519_pubkey = 64 байта).
MSG_DATA_SEND (0x10)	GUI→utun	Отправить данные пиру id (через etcp_router_conn_send / send_signed).
MSG_DATA_RECV (0x11)	utun→GUI	Получены данные от пира id.
MSG_RSP_ERROR (0xFF)	utun→GUI	Ошибка (1 байт код + текст).

Коды ошибок

Код	Константа	Описание
0x01	MSG_ERR_INVALID_MSG	Некорректный заголовок или тип.
0x02	MSG_ERR_NOT_BOUND	Нет привязки к пиру.
0x03	MSG_ERR_NO_ROUTE	Нет маршрута до пира.
0x04	MSG_ERR_SEND_FAILED	Ошибка отправки.
0x06	MSG_ERR_ID_TAKEN	peer_id уже занят другим клиентом.
0x07	MSG_ERR_ACCESS_DENIED	Доступ запрещён (например, GET_PRIVKEY не с loopback).
0x08	MSG_ERR_PEER_NOT_FOUND	Пир не найден в BGP-топологии.