utun2/src/proxy/tcp_proxy_client_doc.md

tcp_proxy_client

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

Клиентский оркестратор TCP прокси. Создаёт TUN-интерфейс, запускает встроенный lwIP TCP стек, перехватывает исходящие TCP-соединения со стороны клиента и туннелирует их через ETCP к удалённому exit-узлу (tcp_proxy_server). Поддерживает три режима перехвата трафика одновременно:

1. Прозрачное проксирование через TUN — весь TCP-трафик с TUN-интерфейса попадает в lwIP, который управляет реальными TCP-сессиями. Исходящие соединения прозрачно проксируются на exit-узел. UDP (через udp_proxy) и ICMP Echo (через icmp_proxy) также пробрасываются.
2. SOCKS5 proxy listener — встроенный SOCKS5-сервер, принимающий локальные подключения и туннелирующий их через ETCP.
3. HTTP CONNECT proxy listener — встроенный HTTP CONNECT-прокси (работает через тот же механизм SOCKS, что и SOCKS5).

Модуль полностью оркестрирует весь TCP-прокси-пайплайн на стороне клиента: захват трафика → lwIP TCP стек → ETCP-туннелирование → приём ответных данных → отдача в lwIP → запись IP-пакетов обратно в TUN.

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

Типовой сценарий

tcp_proxy_client_create(inst, ua, tun_name, tun_ip, mtu, test_mode,
                         mappings, mapping_count, via_node_id,
                         socks_enabled, socks_addr, http_proxy_enabled, http_proxy_addr)
→ TUN init (tun_init_nat) — создание TUN-интерфейса с NAT
→ lwIP init (lwip_tcp_init) — запуск встроенного TCP стека
→ Настройка port mappings — прослушивание локальных портов в lwIP
→ SOCKS5/HTTP listen — запуск локальных прокси-слушателей
→ ETCP router bind — регистрация коллбэка tcp_proxy_client_router_recv_cb
→ UDP/ICMP proxy init

Ключевые концепции

TUN interface через tun_init_nat(). IP-пакеты из output_queue TUN направляются в tcp_proxy_client_tun_input() — главную точку входа inbound-трафика.

Встроенный lwIP TCP стек (lwip_tcp_init()) с output-коллбэком tcp_proxy_client_output_cb, который пишет готовые IP-пакеты обратно в TUN (в сторону ОС клиента).

Inbound TUN трафик (tcp_proxy_client_tun_input()): парсинг IP-пакета → по протоколу:

• TCP → вызов lwip_tcp_input() — пакет попадает в lwIP, где срабатывает accept_cb для новых соединений или recv_cb для существующих
• UDP → udp_proxy_send_to_exit() — проброс UDP в exit
• ICMP (type 8/Echo) → icmp_proxy_send_to_exit() — проброс ping в exit

Connection accept (tcp_proxy_client_accept_cb): при новом входящем TCP-соединении в lwIP:

1. Выделяется struct tcp_proxy_client_conn
2. Определяется destination: поиск по port mapping config mappings[] (local_port → remote_ip:remote_port), иначе local_ip:local_port самого pcb
3. Назначается stream_id (инкремент next_stream_id)
4. Регистрируются lwIP коллбэки: recv, sent, err, poll
5. Создаётся очередь to_lwip для данных от exit
6. Отправляется ETCP CONNECT с dest_ip+dest_port через etcp_route_send(force=1)

Client-side lwIP — чтение данных (tcp_proxy_client_recv_cb):

• При получении данных от lwIP (клиент что-то отправляет): копируем pbuf → tcp_proxy_client_send_data() → ETCP DATA
• При backpressure (очередь нормализатора переполнена): сохраняем в tx_buf, регистрируем waiter через etcp_router_waiter_register(). При освобождении очереди tcp_proxy_client_tx_waiter_cb досылает данные и вызывает tcp_recved() для window update
• При p==NULL (FIN от lwIP): выставляется fin_local, отправляется ETCP FIN. Если обе стороны закрылись — ETCP CLOSE

Exit-side data — приём ответных данных (tcp_proxy_client_handle_data()):

• Данные от exit помещаются в очередь to_lwip
• tcp_proxy_client_feed_from_transport(): пока есть место в tcp_sndbuf(pcb), читает из to_lwip и пишет через tcp_write() в lwIP. После записи вызывает tcp_output() для отправки
• Trigger на feed: при получении DATA, при sent_cb (lwIP освободил send buffer)

Full lifecycle:

1. CONNECT — установка соединения с exit
2. DATA ↔ DATA — двунаправленный обмен данными
3. FIN (от клиента или exit) — half-close: tcp_shutdown(pcb, 0, 1) (закрытие только send-стороны)
4. CLOSE — полное закрытие после обоих FIN, очистка tcp_proxy_client_conn_free()
5. ERROR — аварийное закрытие (ошибка lwIP или exit), немедленная очистка

Per-port mapping конфигурация (tcp_proxy_client_mapping_config):

struct tcp_proxy_client_mapping_config {
    uint16_t local_port;       // локальный порт для прослушивания
    char     remote_ip[64];    // IP назначения на exit-узле
    uint16_t remote_port;      // порт назначения на exit-узле
};

При старте для каждого mapping создаётся listen pcb в lwIP. Также работает динамический listen для любых исходящих портов (tcp_proxy_client_ensure_outbound_listen()).

SOCKS5/HTTP proxy listeners — используют socks_proxy_init_listen() (общий код с SOCKS, флаг is_http различает режимы). SOCKS/HTTP обрабатываются приоритетно в router_recv_cb — им не нужен TUN/lwIP.

Протокол обмена с exit-узлом

Формат сообщения: svc_id(1) + subcmd(1) + stream_id(4) + [data] (заголовок TCP_PROXY_HDR_SIZE = 6 байт).

Subcmd	Код	Направление	Описание
CONNECT	0x01	client→exit	Установка TCP-соединения с destination
DATA	0x03	↔	Данные TCP-потока
CLOSE	0x04	↔	Полное закрытие потока
ERROR	0x05	↔	Ошибка, немедленная очистка
FIN	0x06	↔	Half-close (shutdown write)

Специальное сообщение: svc_id(1) + peer_id(8) (9 байт) — CLOSE_ALL: очистка всех соединений к указанному peer.

Механизмы надёжности

• Backpressure в нормализатор: etcp_router_waiter_register() — если etcp_route_send() не может отправить (очередь переполнена), данные буферизуются в tx_buf и досылаются при освобождении
• Повтор CLOSE/ERROR: если отправка CLOSE/ERROR не удалась, выставляется close_pending=1. В poll_cb повторяется попытка
• Очередь to_lwip: буферизует данные от exit до готовности lwIP send buffer, обеспечивая window-based flow control

3. API

Структуры

struct tcp_proxy_client_conn — одно проксируемое TCP-соединение

Поле	Тип	Назначение
next	*	Связный список всех соединений
proxy	*tcp_proxy_client	Обратный указатель на родительский прокси
pcb	*tcp_pcb	lwIP protocol control block для этого соединения
stream_id	uint32_t	Уникальный идентификатор потока в протоколе ETCP
to_lwip	*ll_queue	Очередь данных от exit → lwIP (flow control)
fin_local	uint8_t	Локальная сторона (lwIP) отправила FIN
fin_remote	uint8_t	Удалённая сторона (exit) отправила FIN
rem_closed	uint8_t	Exit прислал CLOSE — прекращаем обработку
error	uint8_t	Ошибка на любом конце — немедленная очистка
close_sent	uint8_t	CLOSE/ERROR отправлен на exit
close_pending	uint8_t	CLOSE/ERROR не доставлен, ждём повтора в poll
tx_buf	*uint8_t	Буфер при backpressure (lwIP→ETCP send fail)
tx_len	uint16_t	Длина данных в tx_buf
tx_waiter	queue_waiter_handle	Дескриптор waiter для backpressure
dest_ip	uint8_t[4]	IP назначения на exit-узле
dest_port	uint16_t	Порт назначения на exit-узле (network byte order)

struct tcp_proxy_client — состояние прокси-клиента

Поле	Тип	Назначение
inst	*UTUN_INSTANCE	Родительский инстанс uTun
ua	*UASYNC	Асинхронный event loop
tun	*tun_if	TUN-интерфейс для захвата/инжекции трафика
conns	*tcp_proxy_client_conn	Голова связного списка lwIP-соединений
conn_count	int	Количество активных lwIP-соединений
entry_pool	*memory_pool	Пул для struct ll_entry (данные to_lwip)
next_stream_id	uint32_t	Счётчик stream_id (начинается с 1)
via_node_id	uint64_t	Node ID exit-узла для маршрутизации ETCP
lwip	*lwip_tcp_ctx	Контекст встроенного lwIP TCP стека
mappings	*mapping_config	Указатель на массив port mapping конфигурации
mapping_count	int	Количество mapping записей
socks_enabled	int	Флаг включения SOCKS5 прокси
socks_conns	*socks_proxy_conn	Список активных SOCKS5-соединений
socks_conn_count	int	Количество SOCKS5-соединений
socks_listen	*listen_ctx	Слушающий сокет SOCKS5
http_proxy_enabled	int	Флаг включения HTTP CONNECT прокси
http_conns	*socks_proxy_conn	Список активных HTTP CONNECT соединений
http_conn_count	int	Количество HTTP CONNECT соединений
http_listen	*listen_ctx	Слушающий сокет HTTP CONNECT

Функции

tcp_proxy_client_create()

Создаёт и инициализирует весь прокси-клиент. Параметры: инстанс uTun, uasync, имя/IP/MTU TUN-интерфейса, test_mode, массив port mapping, via_node_id, флаги/адреса SOCKS и HTTP прокси. Возвращает NULL при ошибке.

tcp_proxy_client_destroy()

Полная очистка: отвязка от ETCP router, остановка UDP/ICMP прокси, закрытие SOCKS/HTTP listeners, освобождение всех соединений (lwIP abort + очистка очередей to_lwip + tx_buf + waiter cancel), уничтожение lwIP стека, закрытие TUN, освобождение memory pool.

tcp_proxy_client_router_recv_cb()

Главный ETCP-коллбэк (зарегистрирован через etcp_router_bind на ETCP_RT_ID_TCP_PROXY=0x04). Обрабатывает входящие сообщения от exit-узла:

• DATA → tcp_proxy_client_handle_data() — данные в очередь to_lwip и feed в lwIP
• CLOSE → tcp_proxy_client_handle_close() — пометка rem_closed, закрытие lwIP pcb, освобождение соединения
• ERROR → tcp_proxy_client_handle_error() — аварийное закрытие lwIP pcb, освобождение соединения
• FIN → tcp_proxy_client_handle_fin() — half-close через tcp_shutdown(pcb, 0, 1)
• CLOSE_ALL (9-байтовый пакет без conn) → очистка всех соединений к peer
• Сначала пробует SOCKS/HTTP обработчики (приоритет — могут работать без TUN)

Внутренние функции

lwIP коллбэки

• tcp_proxy_client_output_cb() — output lwIP: запись IP-пакетов в TUN (в сторону ОС клиента)
• tcp_proxy_client_accept_cb() — новый входящий TCP: создание tcp_proxy_client_conn, определение destination из mapping конфига, отправка ETCP CONNECT
• tcp_proxy_client_recv_cb() — данные от клиента (lwIP→ETCP): копирование pbuf → ETCP DATA с backpressure
• tcp_proxy_client_sent_cb() — lwIP освободил send buffer: вызов feed_from_transport для передачи накопленных данных
• tcp_proxy_client_err_cb() — ошибка lwIP: pcb уже уничтожен стеком, отправка ETCP ERROR
• tcp_proxy_client_poll_cb() — периодический poll (2 интервала): очистка при error, повтор close_pending

Отправка сообщений в ETCP

• tcp_proxy_client_send_msg() — базовая функция: сборка пакета svc_id+subcmd+stream_id+data, отправка через etcp_route_send()
• tcp_proxy_client_send_connect() — CONNECT с dest_ip+dest_port (6 байт данных), force=1
• tcp_proxy_client_send_data() — DATA с payload, без force (backpressure через waiter)
• tcp_proxy_client_send_close() — CLOSE, force=1, при ошибке выставляет close_pending
• tcp_proxy_client_send_error() — ERROR, force=1, при ошибке выставляет close_pending
• tcp_proxy_client_send_fin() — FIN, force=1

Обработка трафика

• tcp_proxy_client_tun_input() — коллбэк очереди output_queue TUN. Парсит IP-пакеты: TCP → lwip_tcp_input (с динамическим listen на целевой порт), UDP/ICMP → соответствующие прокси
• tcp_proxy_client_handle_non_tcp() — перенаправление UDP в udp_proxy_send_to_exit() и ICMP Echo в icmp_proxy_send_to_exit()
• tcp_proxy_client_feed_from_transport() — чтение данных из очереди to_lwip и запись в lwIP через tcp_write() пока есть место в send buffer. После feed вызывает tcp_output()
• tcp_proxy_client_tx_waiter_cb() — коллбэк backpressure waiter: досылка tx_buf при освобождении normalizer очереди, вызов tcp_recved() для window update
• tcp_proxy_client_ensure_outbound_listen() — динамическое создание listen pcb в lwIP для заданного порта (если ещё не создан), нужно для прозрачного проксирования любых исходящих TCP-соединений

Управление памятью и соединениями

• tcp_proxy_client_entry_from_data() — создание ll_entry из пула entry_pool с копированием данных
• tcp_proxy_client_find_conn() — линейный поиск соединения по stream_id
• tcp_proxy_client_conn_free() — полная очистка одного соединения: досылка pending CLOSE/ERROR, удаление из списка, очистка очереди to_lwip, освобождение tx_buf, cancel waiter, free памяти

Зависимости

• tun_if.h — TUN-интерфейс (инициализация, запись, закрытие)
• lwip_tcp/lwip_tcp.h — встроенный lwIP TCP стек (инициализация, input, управление pcb)
• etcp.h / etcp_api.h / etcp_router.h — ETCP-маршрутизация и отправка данных
• tcp_proxy_server.h — общие константы протокола (TCP_PROXY_SUBCMD_*, TCP_PROXY_HDR_SIZE)
• socks_proxy.h — SOCKS5/HTTP CONNECT прокси (init_listen, handle_etcp, conn_free_all)
• udp_proxy.h / icmp_proxy.h — проброс UDP и ICMP
• config_parser.h — tcp_proxy_client_mapping_config (local_port → remote_ip:remote_port)
• utun_instance.h — struct UTUN_INSTANCE с полем tcp_proxy_client
• lib/u_async.h — асинхронный event loop
• lib/ll_queue.h — lock-free очереди (to_lwip, output_queue TUN)
• lib/memory_pool.h — пул для struct ll_entry
• lib/mem.h — обёртки malloc/free с учётом утечек
• lib/debug_config.h — логирование