utun2/src/ntp_node_time_doc.md

NTP Node Time

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

Синхронизация времени между узлами uTun через ETCP-канал. Позволяет вычислять смещение часов относительно каждого соседа, обнаруживать дрейф и, если узел сам не синхронизирован с NTP, корректировать свои часы по времени синхронизированного соседа. Используется для точной координации событий между узлами (db_sync, timestamp-ы сообщений в чате).

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

ntp_node_time_init() регистрирует callback на новые ETCP-соединения и callback на приём данных через raw etcp_bind (packet ID ETCP_ID_NTP_TIME = 0x04, P2P без роутера). При установке нового соединения автоматически вызывается ntp_node_on_conn_init — отправка TIME_SYNC соседу. При получении TIME_SYNC вычисляется per-peer offset, проверяется дрейф, и если мы не синхронизированы а сосед синхронизирован — корректируем свои часы и рассылаем коррекцию всем остальным соседям.

ntp_node_sync_peers() — широковещательная рассылка TIME_SYNC всем активным соседям. Вызывается автоматически после успешной NTP-синхронизации из ntp_time.

Нюансы:

• До 32 соседей (NTP_NODE_MAX_PEERS), при переполнении новый не добавляется
• Дрейф >2с — WARN, >10с — ERROR. Смещение не применяется автоматически к глобальному offset_us, кроме случая когда свой узел не синхронизирован
• Offset считается как t4 - t_sender_us (одностороннее смещение, без учёта RTT — предполагается что задержка ETCP мала)

3. API

Структуры:

• struct NTP_NODE_PEER — пара node_id + offset_us для одного соседа
• struct NTP_NODE_TIME — фиксированный массив peers[32] + счётчик peer_count

Функции:

• ntp_node_time_init(inst) — регистрирует bind в etcp_bind (ID 0x04) и callback на новые соединения
• ntp_node_time_destroy(inst) — снимает регистрацию bind и callback, обнуляет peer_count
• ntp_node_sync_peers(inst) — отправляет TIME_SYNC всем активным/initialized соседям (вызывается после NTP-синхронизации)