diff --git a/src/dm/dm_core.h b/src/dm/dm_core.h index 3bd92a6e..00f72fcf 100644 --- a/src/dm/dm_core.h +++ b/src/dm/dm_core.h @@ -9,7 +9,11 @@ * при недоступности пира — через dm_mailbox (суперузлы). * - содержимое шифруется E2E (AES-256-CCM), запись подписывается Ed25519. * - * Два независимых направленных потока (я→пир и пир→я) с монотонным seq. + * Два независимых направленных потока (я→пир и пир→я) с монотонным исходящим seq. + * Все API и трамплины выполняются в uasync-потоке с живым instance/SQLite/router. + * Входные строки/тела заимствуются на время вызова; функции не забирают их владение. + * Запросы трамплинов — один блок u_malloc/u_calloc с NUL-строками; обработчик освобождает блок. + * Instance должен пережить запрос и его отложенное завершение; остановка сериализуется через uasync. */ #ifndef DM_CORE_H @@ -29,7 +33,9 @@ extern "C" { /* ── Каноническое тело DM-сообщения (общий wire-формат dm_core и dm_mailbox) ── * [conv_id:8][seq:8][ts:8][author:8][ct_len:1][ct:ct_len][data_len:2][data_enc:data_len][media?:56][sig:64] * media присутствует только для ct="file", подписан вместе с сообщением. - * data_enc — AES-256-CCM (шифротекст + tag), sig — Ed25519 автора по всем полям до sig. */ + * data_enc — AES-256-CCM (шифротекст + tag), sig — Ed25519 автора по всем полям до sig. + * Числа native-endian; seq=1..INT64_MAX, ts — миллисекунды NTP-времени instance. + * ETCP_RT_ID_DM=0x34: [MSG=1][тело] либо [ACK=2][квитанция:136]; router-пакет подписан. */ #define DM_MSG_FIXED_HDR 33 /* conv_id+seq+ts+author(32) + ct_len(1) — до ct */ #define DM_MSG_SIG_SIZE 64 #define DM_DATA_MAX 1024 @@ -54,22 +60,29 @@ static inline int dm_msg_len(const uint8_t* msg, size_t avail, size_t* out_len) return 1; } -/* Общие операции протокола DM; все вызовы в uasync-потоке. - * group_id — только область маршрутизации, идентичность беседы от неё не зависит. - * route_group выбирает общую группу с живым путём, возвращает 1/0. - * verify_message проверяет каноническое тело и подпись автора для recipient. - * accept_message возвращает 0 только после commit (включая точный повтор). - * Квитанция: ["DMACK001":8][conv:8][seq:8][author:8][recipient:8][SHA256(msg):32][sig:64]. - * verify_receipt проверяет подпись получателя и при msg!=NULL точное соответствие телу. - * accept_receipt удаляет только соответствующее исходящее pending-сообщение. */ +/* Выбрать общую CHAT-группу с путём router к peer, сначала preferred (0=без предпочтения). + * 1 и *group_id при успехе; 0 при отсутствии пути/ошибке, выход не меняется. + * group_id обязателен; наличие пути не гарантирует успешной последующей отправки. */ int dm_route_group(struct UTUN_INSTANCE* inst, uint64_t peer, uint64_t preferred, uint64_t* group_id); +/* Проверить точную длину msg/len, conv/author/recipient/seq, descriptor и подпись автора из nodes. + * 0=корректно, -1=отказ. Нужна SQLite, владелец dm_core не требуется. + * Не расшифровывает тело и не проверяет членство/роль router-отправителя: это обязанность вызывающего. */ int dm_verify_message(struct UTUN_INSTANCE* inst, uint64_t recipient, const uint8_t* msg, size_t len); +/* Проверить и расшифровать входящее тело для локального узла, атомарно сохранить историю/беседу/media. + * 0 и receipt после commit либо точного повтора; -1 при отказе. Для file нужен живой dm_media. + * Точный удалённый повтор подтверждается по отпечатку без восстановления истории; конфликт отклоняется. + * receipt — обязательные 136 байт; при -1 буфер не использовать. Ошибка подписи квитанции возможна после commit. */ int dm_accept_message(struct UTUN_INSTANCE* inst, const uint8_t* msg, size_t len, uint8_t receipt[DM_RECEIPT_SIZE]); +/* receipt — ровно 136 доступных байт: ["DMACK001":8][conv:8][seq:8][author:8][recipient:8][SHA256(msg):32][sig:64]. + * Проверяет идентичность и подпись B по первым 72 байтам; при msg!=NULL также точное тело msg/len. + * 0=корректно, -1=отказ. Не проверяет наличие outbox и ничего не записывает. */ int dm_verify_receipt(struct UTUN_INSTANCE* inst, const uint8_t receipt[DM_RECEIPT_SIZE], const uint8_t* msg, size_t len); +/* Для локального автора проверить receipt и удалить только точный outbox; история/file receipt сохраняются. + * 0=удалено либо outbox уже отсутствует, -1=ошибка/конфликт. Требуется запущенный dm_core. */ int dm_accept_receipt(struct UTUN_INSTANCE* inst, const uint8_t receipt[DM_RECEIPT_SIZE]); /* Жизненный цикл в uasync: init после chat_core_init с SQLite/router/ua ядра; 0=успех, -1=ошибка. - * Повторный init запущенного владельца возвращает 0. Для send/accept нужен также dm_media_init. + * Повторный init запущенного владельца возвращает 0. Для file-send/accept нужен также dm_media_init. * destroy отменяет invite/таймер и снимает bind; БД/outbox сохраняются. Вызывать до chat_core_destroy. */ int dm_core_init(struct UTUN_INSTANCE* inst); void dm_core_destroy(struct UTUN_INSTANCE* inst); @@ -99,9 +112,16 @@ int dm_start(struct UTUN_INSTANCE* inst, uint64_t peer_node_id, int dm_send(struct UTUN_INSTANCE* inst, const char* conv_id, const char* content_type, const uint8_t* data, uint32_t data_len); -/* Локальное удаление; generation защищает повторно открытую беседу от старого запроса. */ -struct dm_delete_req { struct UTUN_INSTANCE* inst; char conv_id[64]; uint64_t generation, request_id; }; +/* Локальное удаление по dm_history_delete; generation защищает повторно открытую беседу. + * CHAT_EVT_DM_DELETE_RESULT: [request_id:8][conv:u64][generation:8][success:u8], всего 25 байт native-endian. */ +struct dm_delete_req { + struct UTUN_INSTANCE* inst; /* Заимствованное ядро до завершения запроса. */ + char conv_id[64]; /* Десятичный ID беседы с NUL. */ + uint64_t generation; /* Ненулевое ожидаемое поколение. */ + uint64_t request_id; /* Корреляция результата с запросом UI. */ +}; void dm_delete_trampoline(void* arg); +/* После commit удаления отменить ожидающий invite этой беседы; квитанции/другие беседы не меняет. */ void dm_cancel_pending_history(struct UTUN_INSTANCE* inst, const char* conv); /* До 200 видимых бесед по last_ts DESC: [{conv_id,peer_node_id,peer_name,last_ts,out_seq,in_seq,generation}]. @@ -113,7 +133,9 @@ int dm_list_conversations_json(struct UTUN_INSTANCE* inst, char* buf, size_t buf * count=1..200 задаёт предел; count<=0 или count>200 означает 200. * offset>=0 отсчитывается от новых сообщений; offset=0 выбирает последние count. * Выбранная страница возвращается по возрастанию ts, seq, dir. - * buf — выходной буфер с NUL; 0 и *out_len байт без NUL при успехе, -1 при ошибке. */ + * buf — выходной буфер с NUL; 0 и *out_len байт без NUL при успехе, -1 при ошибке. + * pending относится к квитанции сообщения. media_status: delivered/ready/downloading/expired/pending. + * hidden здесь не фильтруется; интерфейс выбирает видимую беседу по списку/поколению. */ int dm_list_messages_json(struct UTUN_INSTANCE* inst, const char* conv_id, int count, int offset, char* buf, size_t buf_size, size_t* out_len); @@ -123,20 +145,20 @@ int dm_list_messages_json(struct UTUN_INSTANCE* inst, const char* conv_id, int c * пира в таблице nodes (как headless hc_handle_dm_start), после чего вызывает * dm_start(). Результат — событие CHAT_EVT_DM_CONV_UPDATED. */ struct dm_start_req { - struct UTUN_INSTANCE* inst; - uint64_t peer_node_id; - char source_ch_id[64]; - char peer_name[128]; + struct UTUN_INSTANCE* inst; /* Заимствованное ядро. */ + uint64_t peer_node_id; /* Другой участник общей группы; ключи читаются из nodes. */ + char source_ch_id[64]; /* Десятичный ID общей группы либо пустая строка. */ + char peer_name[128]; /* UTF-8 имя с NUL; dm_start ограничит до 63 байт. */ }; void dm_start_trampoline(void* arg); /* Отправить текстовое сообщение в беседу (content_type="text"). */ struct dm_send_req { - struct UTUN_INSTANCE* inst; - char conv_id[64]; + struct UTUN_INSTANCE* inst; /* Заимствованное ядро. */ + char conv_id[64]; /* Десятичный ID беседы с NUL. */ uint64_t generation; /* 0: захватить при входе в uasync, до любой фоновой работы. */ - uint32_t data_len; - uint8_t* data; /* data_len байт (выделяется в хвосте структуры) */ + uint32_t data_len; /* Число байт текста, до DM_DATA_MAX. */ + uint8_t* data; /* Указывает на data_len байт в том же блоке после структуры. */ }; void dm_send_trampoline(void* arg); @@ -151,12 +173,15 @@ enum dm_invite_result { DM_INVITE_SEND_ERROR = -3, DM_INVITE_CANCELLED = -4, DM_INVITE_BUSY = -5 }; struct dm_invite_req { - struct UTUN_INSTANCE* inst; - uint64_t request_id, peer_node_id, channel_id, generation; + struct UTUN_INSTANCE* inst; /* Заимствованное ядро до итогового callback. */ + uint64_t request_id; /* Ненулевой ID; cancel использует тот же ID. */ + uint64_t peer_node_id; /* Фиксированный получатель, не локальный узел. */ + uint64_t channel_id; /* Выбранная активная CHAT-группа отправителя. */ + uint64_t generation; /* Заполняет uasync до регистрации; проверяет callback. */ char source_ch_id[64]; /* общая группа для новой PM; из шапки PM может быть пустой */ - char peer_name[128]; - int cancel; - struct chat_invite_build* pending; /* только uasync */ + char peer_name[128]; /* UTF-8 имя для новой беседы с NUL. */ + int cancel; /* 0=создать, 1=отменить ожидающий request_id. */ + struct chat_invite_build* pending; /* Внутренний handle; запрос создаётся обнулённым. */ }; void dm_invite_trampoline(void* arg); @@ -164,15 +189,18 @@ void dm_invite_trampoline(void* arg); * [conv_id_len:1][conv_id:var][generation:8][JSON:utf8]. Все чтения в uasync. * Ненулевое generation проверяется до чтения; 0 захватывает текущее поколение. GUI отбрасывает старый снимок. */ struct dm_messages_req { - struct UTUN_INSTANCE* inst; - char conv_id[64]; + struct UTUN_INSTANCE* inst; /* Заимствованное ядро. */ + char conv_id[64]; /* Десятичный ID с NUL, также для запроса маршрута звонка. */ uint64_t generation; /* Поколение выбранного PM; для запроса маршрута не используется. */ }; void dm_messages_trampoline(void* arg); -/* Живой BGP-маршрут PM; group_id=0 в снимке означает недоступность. Все вызовы в uasync. */ +/* 1 при живом BGP-маршруте общей группы, 0 при недоступности/ошибке. peer/group_id обязательны. + * При корректных аргументах выходы сначала обнуляются; peer может быть известен и без маршрута. + * Трамплин выдаёт CHAT_EVT_DM_CALL_ROUTE: [conv_len:1][conv][peer:8][group:8]; group=0 без маршрута. */ int dm_call_route(struct UTUN_INSTANCE* inst, const char* conv_id, uint64_t* peer, uint64_t* group_id); void dm_call_route_trampoline(void* arg); /* аргумент: dm_messages_req */ -struct dm_conversations_req { struct UTUN_INSTANCE* inst; }; +/* Снимок бесед публикуется как CHAT_EVT_DM_CONVERSATIONS с JSON без NUL. */ +struct dm_conversations_req { struct UTUN_INSTANCE* inst; /* Заимствованное ядро. */ }; void dm_conversations_trampoline(void* arg); #ifdef __cplusplus diff --git a/src/dm/dm_history.h b/src/dm/dm_history.h index 22eb4212..9c906de5 100644 --- a/src/dm/dm_history.h +++ b/src/dm/dm_history.h @@ -1,7 +1,9 @@ /* Локальная история DM: поколения, скрытые беседы и точные отпечатки удалённых сообщений. * Все операции выполняются в uasync с SQLite ядра. init вызывается после создания DM-таблиц. * Удаление скрывает беседу и сохраняет её ключи/счётчики в dm_conversations; show открывает её снова. - * Поколение передавать в отложенные операции и проверять current перед применением результата. */ + * Поколение передавать в отложенные операции и проверять current перед применением результата. + * Беседой/seq владеет dm_core, файлами/загрузками — dm_media; этот модуль связывает их удаление. + * Аргументы заимствованы на время вызова; самостоятельные транзакции выполняются без внешней транзакции. */ #ifndef DM_HISTORY_H #define DM_HISTORY_H #include @@ -10,7 +12,8 @@ extern "C" { #endif struct UTUN_INSTANCE; -/* Создать служебные таблицы, сбросить busy файлов после restart. 0=успех, -1=ошибка. +/* Создать dm_history, dm_deleted_messages и dm_local_files; сбросить busy после restart. + * 0=успех, -1=ошибка. Вызывает dm_core_init; повторять при живых workers нельзя: они ещё держат пути. * inst и его topo_sqlite_db обязательны; частично созданные таблицы при ошибке остаются. */ int dm_history_init(struct UTUN_INSTANCE* inst); /* Поколение существующей беседы: 1 до первого удаления; 0 при отсутствии/ошибке. @@ -28,8 +31,11 @@ int dm_history_show(struct UTUN_INSTANCE* inst, const char* conv); int dm_history_deleted(struct UTUN_INSTANCE* inst, const uint8_t* body, size_t len, int dir, uint8_t* media_receipt); /* Удалить видимую беседу текущего generation