/* conn_mgr — соединение с узлом группы напрямую, в обратную сторону или через посредника.
 * Один менеджер принадлежит одной группе; open выдаёт отдельный handle владельцу.
 * DIRECT использует NCD, REVERSE просит пира подключиться, INDIRECT выбирает посредника.
 * Используется сервисами для доставки данных. Групповые сессии открывают через
 * topo_group_peer_open(). Все операции — в потоке uasync; handle закрывает вызывающий. */
#ifndef CONN_MGR_H
#define CONN_MGR_H

#ifdef __cplusplus
extern "C" {
#endif

#include <stdint.h>
#include "../lib/ll_queue.h"
#include "topo_node.h"

struct CONN_MGR;           /* opaque */
struct CONN_MGR_HANDLE;    /* opaque */
struct UTUN_INSTANCE;
struct ETCP_CONN;
struct TOPO_GROUP;

enum conn_mgr_event {
    CONN_EVENT_UP      = 0,  /* связь есть. handle жив, можно отправлять данные               */
    CONN_EVENT_DOWN    = 1,  /* связь потеряна; handle остаётся у владельца, успех восстановления не гарантирован */
    CONN_EVENT_TIMEOUT = 2,  /* подключение не удалось. handle жив, закройте сами             */
};

/**
 * Единый коллбэк для всех операций.
 * @param h        handle (NULL при ошибках до создания handle)
 * @param node_id  целевой узел
 * @param group_id группа
 * @param event    UP / DOWN / TIMEOUT
 */
typedef void (*conn_mgr_cb_t)(struct CONN_MGR_HANDLE* h,
                               uint64_t node_id, uint64_t group_id,
                               enum conn_mgr_event event, void* arg);

/* ═══════ lifecycle ═══════ */

/* Создать менеджер группы и его фоновые проверки; NULL при ошибке. */
struct CONN_MGR* conn_mgr_init(struct TOPO_GROUP* group);
/* Остановить проверки и освободить менеджер. Все клиентские handles закрыть ДО destroy. */
void conn_mgr_destroy(struct CONN_MGR* mgr);
/* Приём управляющего пакета от etcp_router; забирает entry. */
void conn_mgr_router_recv_handler(struct ETCP_CONN* conn, struct ll_entry* entry);

/* ═══════ единая точка входа ═══════ */

/**
 * Единственная публичная функция подключения — 3-фазное (DIRECT→REVERSE→INDIRECT).
 * Возврат 0 — запрос принят, -1 — ошибка запуска. cb обязателен.
 * Ошибка до запуска может возвращаться без callback. В callback h может быть NULL.
 * Успешно выданный handle закрывает вызывающий, в том числе после TIMEOUT.
 */
int conn_mgr_open(struct UTUN_INSTANCE* inst,
                  uint64_t group_id,
                  uint64_t node_id,
                  conn_mgr_cb_t cb, void* cb_arg,
                  struct CONN_MGR_HANDLE** out_handle);

/** Закрыть свой handle. Последний освобождает ресурсы CM; чужие NCD-владельцы сохраняют транспорт. */
void conn_mgr_close(struct CONN_MGR_HANDLE* h);

/* ═══════ доступ к соединению ═══════ */

/** Заимствованный ETCP_CONN от NCD, если он есть; NULL для INDIRECT или отсоединённого handle. */
struct ETCP_CONN* conn_mgr_get_conn(struct CONN_MGR_HANDLE* h);

/** Передать e->dgram через маршрутизатор CM. Освобождает entry при ненулевом h;
 * буфер dgram отдельно не освобождает. При h==NULL entry остаётся у вызывающего. */
int conn_mgr_send(struct CONN_MGR_HANDLE* h, struct ll_entry* e);

/* ═══════ мониторинг (вызывается извне) ═══════ */

/** Обновить RTT кандидата-посредника (≤3, сортировка по возрастанию). */
void conn_mgr_update_best_candidates(struct CONN_MGR* mgr, uint64_t node_id, uint16_t rtt);

#ifdef __cplusplus
}
#endif
#endif