utun2/src/dummynet_doc.md

Dummynet — UDP Network Emulator

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

Эмулятор сетевых условий для тестирования: задержка (фиксированная + случайная), ограничение пропускной способности (token bucket) и случайные потери пакетов. Два режима работы: FULL (автономный UDP-прокси между портами) и INLINE (встраиваемый фильтр в send_hook ETCP_LINK без создания своего сокета).

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

Режим FULL (автономный UDP-прокси)

1. dummynet_create(ua, bind_ip, listen_port) — создаёт контекст, открывает UDP-сокет на listen_port.
2. dummynet_set_direction(dn, DUMMYNET_FORWARD, ...) и DUMMYNET_BACKWARD — настраивает параметры для каждого направления.
3. Пакеты от listen_port-1 идут в направлении FORWARD, от listen_port+1 — в BACKWARD.

[port-1] → [dummynet: delay→loss→shaper] → [dest_forward]
[port+1] → [dummynet: delay→loss→shaper] → [dest_backward]

Режим INLINE (send_hook в ETCP_LINK)

1. dummynet_filter_create(ua) — создаёт фильтр (нет своего сокета).
2. dummynet_filter_set_loss(df, permille) / dummynet_filter_set_delay(df, ms, jitter_ms) — настройка.
3. dummynet_filter_attach(df, link) — встраивается в link->send_hook, перехватывая все вызовы socket_sendto.
4. Дополнительно: dummynet_filter_block_addr/unblock_addr — блокировка отправки на конкретные адреса.

Механизмы эмуляции

Механизм	Реализация
Delay (fixed + random)	При приёме пакета создаётся uasync-таймер (dummynet_delay_callback). После срабатывания пакет кладётся в ll_queue направления
Bandwidth (token bucket)	Shaper-таймер забирает из очереди по одному пакету с интервалом len × 8 / bw_kbps (timebase 0.1ms). Гарантирует не более bandwidth_kbps
Loss (permille)	При приёме: rand() % 1000 < loss_permille → дроп. В INLINE-режиме — в хуке отправки

Статистика

Структура dummynet_stats: recv, sent, dropped (переполнение очереди), lost (random loss), queue_size (текущий), queue_max (пиковый).
Дополнительные отладочные счётчики: delay_timer_set/fire, shaper_timer_set/fire.

Ключевые нюансы

• В FULL-режиме порты listen_port-1, listen_port, listen_port+1 должны быть свободны. Направление определяется по порту источника.
• Шейпер использует burst allowance (SHAPER_BURST_TB = 10 timebase units), допуская небольшие всплески.
• При переполнении очереди (> max_queue_pkts) пакет дропается, увеличивается dropped.
• INLINE-фильтр в режиме блокировки адреса не дропает пакет, а возвращает len (пакет «успешно отправлен», но фактически никуда не ушёл).

3. API

FULL-режим

Функция	Назначение
dummynet_create(ua, bind_ip, listen_port)	Создать контекст, открыть UDP-сокет, зарегистрировать в uasync
dummynet_destroy(dn)	Закрыть сокет, отменить таймеры, очистить очереди, освободить память
dummynet_set_direction(dn, dir, delay_fixed_ms, delay_random_ms, bw_kbps, max_q, loss_permille, dest_ip, dest_port)	Настроить параметры направления
dummynet_get_stats(dn, dir)	Получить статистику направления
dummynet_reset_stats(dn, dir)	Сбросить статистику (-1 = все направления)
dummynet_get_socket(dn)	Вернуть fd сокета
dummynet_get_listen_port(dn)	Вернуть listen_port
dummynet_get_uasync(dn)	Вернуть указатель на UASYNC
dummynet_get_queue_size(dn, dir)	Вернуть текущий размер очереди направления
dummynet_get_debug_counters(dn, dir, ...)	Вернуть отладочные счётчики таймеров

INLINE-режим (dummynet_filter)

Функция	Назначение
dummynet_filter_create(ua)	Создать фильтр
dummynet_filter_set_loss(df, permille)	Установить вероятность потерь
dummynet_filter_set_delay(df, delay_ms, jitter_ms)	Установить задержку (NOTE: в текущей реализации delay не применяется в хуке)
dummynet_filter_attach(df, link)	Прикрепить хук к ETCP_LINK
dummynet_filter_detach(df)	Открепить хук
dummynet_filter_destroy(df)	Уничтожить фильтр
dummynet_filter_get_stats(df)	Получить статистику
dummynet_filter_block_addr(df, ip, port)	Заблокировать адрес (до 4 адресов)
dummynet_filter_unblock_addr(df, ip, port)	Разблокировать адрес

Структуры

Структура	Назначение
dummynet_stats	Статистика: recv, sent, dropped, lost, queue_size, queue_max
dummynet_dir	Внутренняя: параметры направления, очередь, таймеры шейпера, отладочные счётчики
dummynet	Контекст FULL-режима: ua, сокет, два dummynet_dir, пул пакетов
dummynet_filter	Контекст INLINE-режима: ua, loss_permille, delay, link, статистика, список блокировок

Зависимости

u_async.h, ll_queue.h, memory_pool.h, socket_compat.h, etcp_connections.h (для ETCP_LINK), platform_compat.h