utun2/src/tun_if_doc.md

TUN Interface (tun_if)

TUN связывает IP-трафик ОС с ядром. Все операции с интерфейсом, очередями, пулом и публичными счётчиками выполняются в потоке его UASYNC. tun_close() вызывается вне callbacks TUN, после остановки внешних пользователей и до уничтожения uasync.

Форматы и направления

API	Направление	Формат
output_queue	ОС → ядро	префикс(1) + IP
input_queue	ядро → ОС	префикс(1) + IP
tun_write(tun, buf, len)	ядро → ОС	чистый IP
tun_inject_packet(tun, buf, len)	тест → output_queue	чистый IP
tun_read_packet(tun, buf, capacity)	тест читает доставленное ОС	чистый IP

input_queue снимает префикс и вызывает общий tun_write(). NAT и TCP proxy пользуются тем же API. Платформенный tun_platform_write() вызывается только модулем TUN. tun_write() сохраняет владение buf у вызывающего и возвращает len только после полной записи, иначе -1 с errno. Неполная запись считается ошибкой. Пакет, отклонённый queue_data_put(), уже освобождён очередью.

Создание и MTU

tun_init(ua, config) создаёт основной IPv4 TUN с MTU 1500. tun_init_nat(ua, name, ip, mtu, test_mode) создаёт отдельный интерфейс для NAT или TCP proxy: ip — IPv4 без CIDR, MTU — 68..1500. Обе функции используют общий путь создания, регистрации чтения и отката; возвращают NULL при любой ошибке запуска. Платформенный init сам освобождает ресурсы при ошибке, успешный init передаёт cleanup общему коду. Длинные имена, неверный IPv4 и неподдерживаемый MTU отклоняются.

[global] mtu управляет ETCP, поэтому основной и NAT TUN используют TUN_MTU_DEFAULT. TCP proxy передаёт собственный настроенный MTU и до создания PCB вызывает lwip_tcp_set_mtu(): локальный предел MSS равен IPv4 MTU минус 40 байт. Он ограничивает начальный MSS, объявление в SYN и MSS, согласованный с пиром.

Чтение и backpressure

На Linux/FreeBSD fd зарегистрирован в uasync. Перед чтением регистрация приостанавливается; после передачи пакета reader ждёт пустую output_queue через queue_waiter_wait(). Затем чтение разрешается снова. Синхронный consumer допустим. tun_inject_packet() копирует пакет, возвращает 0 при успехе и -1 при ошибке; если output_queue занята, возвращает EAGAIN без передачи пакета.

Windows использует Wintun: session, заимствованный read event, stop event, auto-reset read permit и read thread. Оба конструктора проверяют read event и создают reader до сообщения об успешном запуске. Worker ожидает данные и разрешение отдельно; stop event прерывает оба ожидания. Следующий пакет разрешается после освобождения output_queue, поэтому поток не накапливает задачи в uasync.

Worker не обращается к LL_QUEUE и пулу. Один пакет передаётся через tun_post_packet() и uasync_post_reserved(). Пакет и оболочка принадлежат ожидающей передаче; posted_task — первый член оболочки, которую освобождает uasync. Указатель ожидающей передачи и ошибки worker защищены mutex. Callback снимает ожидающую передачу, переносит ошибки в общую статистику и передаёт пакет очереди.

Тестовый backend

test_mode=1 поддерживается только на POSIX, прав на устройство ОС не требует. Оба конца socketpair(AF_UNIX, SOCK_DGRAM) неблокирующие. Заимствованный tun_get_test_fd() живёт до tun_close(); закрывать его тестам нельзя.

• send(test_fd, ip, len, 0) моделирует исходящий IP от ОС и запускает обычный reader.
• Запись через tun_write()/input_queue доступна через recv(test_fd, ...) либо helper.
• tun_read_packet() возвращает размер чистого IP, 0 при пустом сокете, -1 при ошибке. При недостаточной ёмкости возвращает EMSGSIZE и сохраняет пакет для следующего чтения. Helper и прямой recv требуют одного последовательного consumer.

Тестовые сокеты обходят платформенный TUN read/write. В частности, FreeBSD AF-заголовок в socketpair не добавляется и не снимается.

Закрытие, статистика и диагностика

Закрытие выставляет closing, останавливает и присоединяет Windows worker, освобождает пакет ожидающей передачи и обнуляет её ссылку на TUN. Её оболочку позже освобождает uasync: callback становится пустым, а destroy без callback также освобождает блок. Это безопасно и для задачи из уже снятой uasync порции; исполнение чужих задач ради очистки не требуется.

Затем отменяется read waiter и регистрация fd, снимаются callbacks и освобождаются элементы очередей, очереди и пул, закрывается backend. Для test_mode закрываются оба fd обычным close, без удаления интерфейса ОС. Wintun session закрывается после join; заимствованный read event отдельно не закрывается. Внешние владельцы waiters должны отменять их перед закрытием TUN.

Счётчики bytes учитывают чистый IP: read — пакеты, принятые output_queue, write — полностью записанные пакеты. Helper их не меняет. Ошибки worker переносятся при доставке следующего пакета либо при закрытии. Категория tun: INFO — запуск и итог закрытия, DEBUG — направление/размер/сводка IP, TRACE — разрешение чтения, WARN/ERROR — некорректные пакеты, отказы памяти/очереди и системных операций.

test_tun_if проверяет направления, границы helper, освобождение повреждённых элементов, очередь с отказом, паузу reader, fd, откаты init и post lifetime на реальном uasync. test_nat_transport проверяет полный socketpair roundtrip. test_lwip_tcp 12345 1200 и test_lwip_tcp 12345 68 проверяют TCP-обмен с разными MTU, объявления MSS и размеры каждого выходного IP-пакета. Нативный Wintun требует отдельной проверки на Windows.