diff --git a/src/routing_layer/etcp_router.h b/src/routing_layer/etcp_router.h index a6440a2e..f1e07fce 100644 --- a/src/routing_layer/etcp_router.h +++ b/src/routing_layer/etcp_router.h @@ -20,10 +20,11 @@ // Изменяемый список находится вне end-to-end подписи/шифрования. Получатель // проверяет его границы, уникальность, первый ID=src и последний ID=ETCP peer. // Это защита от ошибок маршрутизации, а не доказательство пути от недоверенного пира. -// flags: bit7=START, bit6=RST, bit3=SIGNED, bit2=ENCRYPTED, bit1=CLOSE +// flags: bit7=START, bit6=RST, bit3=SIGNED, bit2=ENCRYPTED, bit1=CLOSE, bit0=RECEIVE_BUSY (ACK) // reset_id/peer_reset_id — идентификаторы отправителя/получателя во всех пакетах. // START=HELLO, RST=CHALLENGE, START|RST=CONFIRM; challenge используется только в handshake. -// ACK-пакет: тот же заголовок, seq=rx_seq, payload_len=0 +// ACK-пакет: тот же заголовок, seq=rx_seq, payload_len=0; RECEIVE_BUSY поддерживает ожидание без продвижения seq. +// Локальная доставка через etcp_route_send выполняется синхронно без сетевого канала/crypto/receive_ready. #ifndef ETCP_ROUTER_H #define ETCP_ROUTER_H @@ -48,7 +49,7 @@ struct SVC_ROUTE_HDR { uint64_t src_node_id; uint32_t seq; // data: tx_seq; ACK: rx_seq (ожидаемый seq) uint8_t svc_id; // идентификатор сервиса - uint8_t flags; // bit7=START, bit6=RST, bit3=SIGNED, bit2=ENCRYPTED, bit1=CLOSE + uint8_t flags; // ROUTER_FLAG_*; RECEIVE_BUSY допустим только в ACK без payload uint16_t timestamp; // часы отправителя (0.1ms), для RTT; ACK: эхо последнего data-пакета uint64_t reset_id; // случайный идентификатор локального экземпляра router_conn uint64_t peer_reset_id; // идентификатор экземпляра получателя (0 только в HELLO) @@ -128,12 +129,12 @@ struct ETCP_ROUTER_CONN { uint32_t tx_seq; // следующий seq для отправки uint32_t tx_sent; // граница фактически отправленных пакетов (ACK <= tx_sent) uint32_t rx_seq; // ожидаемый seq для сборки (next expected) - uint32_t tx_acked; // сколько наших пакетов подтвердил remote (для inflight) + uint32_t tx_acked; // следующий seq после подтверждённых пакетов, модульный uint32, не накопленный счётчик uint32_t last_sent_ack_seq; // последний отправленный ACK (= rx_seq на момент отправки) uint64_t last_ack_sent_tb; // время отправки последнего ACK (timebase 0.1ms) struct UTUN_INSTANCE* inst; - struct ETCP_CONN* recv_conn; // физический conn последнего принятого data-пакета (для deliver, не NULL) + struct ETCP_CONN* recv_conn; // заимствованный транспорт последнего DATA; NULL после reset/уничтожения транспорта struct ll_queue* recv_q; // reorder очередь: hash по seq (4 байта, offset 0) void* ack_timer; // периодический таймер (10ms при consumer_ack) void* idle_ack_timer; // idle таймер (дослать последний ack) @@ -160,7 +161,7 @@ struct ETCP_ROUTER_CONN { // Ретрансмиты: inflight очередь struct ll_queue* inflight_q; // хеш по seq (4 байта), непрерывный блок без SACK void* retrans_timer; // таймер проверки застоя ACK - uint64_t last_ack_changed_tb; // когда tx_acked последний раз менялся (0.1ms) + uint64_t last_ack_changed_tb; // отсчёт RTO: продвижение ACK, принятый RECEIVE_BUSY или начало повторного прохода (0.1ms) // Очередь приёма входящего трафика (между сетью и recv_q) struct ll_queue* incoming_q; // FIFO очередь входящих пакетов @@ -176,7 +177,7 @@ struct ETCP_ROUTER_CONN { uint32_t c_retrans_done; // число выполненых ретрансмитов uint32_t c_dup_dropped; // дропнуто дубликатов seq uint32_t c_oob_dropped; // дропнуто out-of-bounds seq - uint32_t c_stale_ack; // устаревших ACK + uint32_t c_stale_ack; // ACK вне диапазона или без продвижения seq, включая допустимый повтор RECEIVE_BUSY uint32_t c_sign_fail; // signature verification failures struct route_tx_meter delivery; // первые подтверждения исходного payload, без wire overhead }; @@ -191,7 +192,9 @@ struct ETCP_ROUTER_TX_STATS { int ready, no_route, receive_busy, probing; }; -/* Только uasync. 0 — снимок, 1 — канал отсутствует/закрыт, -1 — неверные аргументы. Канал не создаёт. */ +/* Только uasync. 0 — снимок, 1 — канал отсутствует/закрыт (out обнулён), -1 — неверные аргументы/время. + * now_us — монотонные микросекунды, не раньше последнего учтённого ACK. При -1 out не меняется; канал не создаётся. + * ready означает подтверждённый peer_reset_id, отдельно от READY топологии или готовности физического транспорта. */ int etcp_router_tx_stats(struct UTUN_INSTANCE *inst, uint64_t group, uint64_t peer, uint8_t svc, uint64_t now_us, struct ETCP_ROUTER_TX_STATS *out); @@ -223,7 +226,7 @@ struct ROUTER_INFLIGHT { struct ll_entry ll; // индекс по seq (4 байта, offset 0) uint32_t seq; uint64_t last_sent_tb; // время последней отправки (0.1ms) - uint8_t send_count; // число переотправок + uint8_t send_count; // успешные отправки, включая первую; диагностический циклический счётчик uint8_t* dgram; // неизменяемое тело [SVC_ROUTE_HDR][payload][sig?], без visited_ids/count size_t dgram_len; }; @@ -239,24 +242,32 @@ struct ETCP_ROUTER_BINDINGS { // 3. Публичное API (для сервисов) // ==================================================================== -// Инициализация: etcp_bind(ETCP_ID_SVC_ROUTE) + очистка bindings + создание router_conns +// Первичная инициализация ядра: очистить bindings, создать router_conns, etcp_bind(ETCP_ID_SVC_ROUTE); 0/-1. +// Вызывать один раз до запуска сервисов; после destroy можно инициализировать заново. int etcp_router_init(struct UTUN_INSTANCE* inst); -// Закрыть каналы, снять обработчик и освободить маршрутизатор. +// Снять обработчик, закрыть каналы и очистить все транзитные очереди/таймеры на живых ETCP. Повторный destroy допустим. +// До вызова остановить производителей/ожидания сервисов; из callback останавливаемого сервиса ядро не уничтожать. void etcp_router_destroy(struct UTUN_INSTANCE* inst); -// Зарегистрировать обработчик сервиса +// Зарегистрировать/заменить callback; 0/-1. Замена сохраняет receive_ready/crypto policy. +// callback=NULL снимает callback, receive_ready и policy, даже если сервиса не было; каналы не закрывает. +// Сервис получает владение entry: [26-byte ROUTER_SVC header][payload]. Пустой payload — уведомление close/reset. +// conn заимствован на время callback; при локальных событиях синтетический (instance, peer=self), отправлять через него нельзя. +// End-to-end src/dst/group читать из заголовка через memcpy; conn может обозначать промежуточного пира. int etcp_router_bind(struct UTUN_INSTANCE* inst, uint8_t svc_id, etcp_recv_fn callback); // Снять обработчик; само по себе не закрывает логические каналы сервиса. int etcp_router_unbind(struct UTUN_INSTANCE* inst, uint8_t svc_id); -// Задать обязательные ROUTER_FLAG_ENCRYPTED/SIGNED для зарегистрированного сервиса, в обе стороны. -// Проверка входящих данных — до состояния/очередей/receive_ready, только на конечном узле; управляющие пакеты без payload исключены. +// Задать обязательные ROUTER_FLAG_ENCRYPTED/SIGNED для зарегистрированного сервиса, в обе стороны сетевого обмена. +// Входящие данные проверяются до состояния/очередей/receive_ready, на конечном узле; header-only control исключён. +// Доверенная синхронная доставка dst=self обходит crypto policy и даёт rx_flags=0. // Работает в uasync; unbind очищает требование. Возвращает 0 при успехе, -1 при неверном instance/сервисе/маске. int etcp_router_require_crypto(struct UTUN_INSTANCE* inst, uint8_t svc_id, uint8_t flags); // Проверяется до доставки/ACK. 0 оставляет пакет в recv_q, сохраняя порядок; CLOSE не блокируется. -// ready получает заимствованный проверенный payload и работает в uasync без I/O. NULL снимает ограничение. +// ready получает заимствованный plaintext, работает в uasync без I/O и изменения состояния/закрытия роутера. +// NULL снимает ограничение; для уже приостановленных каналов вызвать resume_receive отдельно. Локальная доставка не проверяется. void etcp_router_set_receive_ready(struct UTUN_INSTANCE* inst, uint8_t svc_id, int (*ready)(struct UTUN_INSTANCE*, uint64_t, uint64_t, const uint8_t*, size_t)); // Продолжение отложено; канал не создаётся, waiter/arg сервиса не сохраняются. @@ -264,8 +275,11 @@ void etcp_router_resume_receive(struct UTUN_INSTANCE* inst, uint64_t group, uint // Отправить сервисный пакет (авто-conn, seq, inflight-контроль через send_q). // Принимает владение entry во всех исходах, включая ошибку. -// entry->dgram = svc_id[1] || payload; 0=принято в очередь, <0=ошибка, не подтверждение доставки. -// force разрешает превысить лимит числа пакетов в send_q. +// entry->dgram = svc_id[1] || непустой payload; mode должен содержать только допустимые биты. +// Для удалённого узла 0=принято в send_q, не подтверждение доставки. Предел включает wire-header, crypto и полный visited-list. +// Для dst=self callback вызывается синхронно, 0=доставлено callback, -1=размер/нет обработчика/ошибка памяти. +// В self-ветке нет канала, inflight, receive_ready и crypto; rx_flags=0, payload до UINT16_MAX-ROUTER_SVC_HDR_SIZE байт. +// force разрешает превысить лимит числа пакетов сетевой send_q; для self не используется. // mode — битовая маска ROUTE_CRYPTO_SIGN / ROUTE_CRYPTO_ENCRYPT (см. route_crypto.h), 0 = обычный пакет. int etcp_route_send(struct UTUN_INSTANCE* inst, uint64_t group_id, uint64_t dst_node_id, struct ll_entry* entry, int force, int mode); @@ -285,14 +299,17 @@ struct ETCP_ROUTER_PATH etcp_router_get_path(struct UTUN_INSTANCE* inst, uint64_ // Отправить данные с авто-seq и контролем inflight // data: payload без svc_id, mode: ROUTE_CRYPTO_SIGN / ROUTE_CRYPTO_ENCRYPT (0 = обычный) -// Копирует data; 0=принято в очередь, <0=ошибка. Доставка подтверждается отдельно протоколом. +// Копирует непустой data; 0=принято в очередь, <0=ошибка. Доставка подтверждается отдельно протоколом. +// Это сетевой API rconn; для синхронной локальной доставки использовать etcp_route_send. int etcp_router_conn_send(struct ETCP_ROUTER_CONN* rconn, const uint8_t* data, size_t len, int mode); -// Закрыть канал и уведомить сервис. После вызова rconn использовать нельзя. +// Снять канал с реестра, затем синхронно уведомить сервис и очистить ресурсы; память освобождается отложенно. +// Callback может закрывать другие каналы/группу или открыть замену с тем же ключом. После close rconn использовать нельзя. void etcp_router_conn_close(struct ETCP_ROUTER_CONN* rconn); -// Установить рабочий max_inflight, пересчитывает inflight_limit и state machine +// Установить max_inflight (минимум 4), пересчитать inflight_limit и state machine. +// В minRTT probe лимит равен 4; reset сессии возвращает default=256. void etcp_router_set_max_inflight(struct ETCP_ROUTER_CONN* rconn, uint16_t new_max); // Дождаться порога send_q. h должен быть обнулён и жить до callback/отмены. @@ -305,7 +322,7 @@ void etcp_router_on_send_ready(struct UTUN_INSTANCE* inst, uint64_t group_id, ui void etcp_router_cancel_send_ready(struct UTUN_INSTANCE* inst, uint64_t group_id, uint64_t node_id, uint8_t svc_id, struct queue_waiter_handle* h); -// Backpressure: проверить есть ли место в send_q (без регистрации waiter) +// Есть ли место в send_q существующего канала; 1/0. Канал не создаёт, его отсутствие даёт 0. int etcp_router_send_q_has_room(struct UTUN_INSTANCE* inst, uint64_t group_id, uint64_t node_id, uint8_t svc_id); // ==================================================================== @@ -321,7 +338,8 @@ void etcp_router_close_group(struct UTUN_INSTANCE* inst, uint64_t group_id); // Закрыть логические каналы одного пира в группе. void etcp_router_conn_close_all_for_node(struct UTUN_INSTANCE* inst, uint64_t group_id, uint64_t remote_node_id); -// Начать новую локальную сессию для конкретного peer+svc в группе и уведомить сервис. +// Сбросить существующий peer+svc: новая локальная эпоха, пустые очереди/seq/метрики, затем уведомление сервиса и HELLO. +// Отсутствующий канал не создаётся. Данные, отправленные сервисом из уведомления, относятся к новой сессии. void etcp_router_conn_restart(struct UTUN_INSTANCE* inst, uint64_t group_id, uint64_t remote_node_id, uint8_t svc_id); // Удалить все транзитные очереди соединения (вызывается при закрытии ETCP_CONN)