AGENTS.md

Памятка для тех, кто правит код awg-proxy, в том числе с помощью ИИ-агентов. Пользовательская документация — в README.md и docs/.

Что это

UDP-прокси на C, который превращает обычный трафик WireGuard в AmneziaWG и обратно. Работает в контейнере RouterOS на слабых роутерах MikroTik (Cortex-A53 на 870 МГц, 32-битный arm, armv5), поэтому размер бинарника (110–200 КБ, образ ~90 КБ) и такты на пакет важнее удобства кода.

MikroTik WG ──UDP──> [awg-proxy в контейнере] ──UDP──> сервер AmneziaWG

Шифрует WireGuard самого роутера. Прокси сессионных ключей не видит: он меняет только заголовки типов (H1–H4), паддинг (S1–S4), мусорные пакеты (junk, I1–I5), пересчитывает MAC1 и, для AWG 3.x, шифрует заголовок.

Устройство репозитория

Сборка и тесты

make build              # бинарник в ../builds/awg-proxy
make test               # все юнит-тесты (gcc)
make test-transform     # отдельный набор; остальные — в Makefile
make test-stress        # интеграционный стресс-тест, только Linux, в make test не входит

На Windows собирать и гонять тесты в Docker:

MSYS_NO_PATHCONV=1 docker run --rm -v "$PWD:/src" -w /src debian:bookworm-slim sh -c \
  "apt-get update -qq && apt-get install -y -qq gcc musl-dev musl-tools make >/dev/null 2>&1 && \
   make build CC=musl-gcc && make test CC=gcc"

Конфигуратор:

npm install jsdom
for f in tests/*.test.js; do node "$f" || break; done

Скрипт диапазона портов для сервера (три контейнера, нужен NET_ADMIN):

bash tests/awg-ports.test.sh

Смена порта против своего же хаба (настоящий WireGuard с обеих сторон, NAT диапазона на хабе, 10 минут: в тишине и под iperf3; нужен образ bench/awg3-interop и свежий бинарник в ../builds/awg-proxy):

bash bench/awg3-interop/hubrot.sh all

В GitHub Actions тестов нет и не будет. Сетевые тесты в CI однажды привели к блокировке репозитория. Workflow только собирают релиз по тегу v*, публикуют образы в GHCR и выкладывают docs/ на Pages. Тесты гоняются локально.

Ограничения

• Только libc. Никаких внешних библиотек, статическая линковка с musl, образ scratch.
• Флаги -Wall -Wextra -Werror -std=c11: предупреждение = ошибка сборки.
• Платформы: linux/arm64, linux/arm/v7, linux/arm/v5, linux/amd64. Код должен собираться и работать на всех четырёх, включая 32-битные.
• Размер и скорость. Каждая новая зависимость, таблица или аллокация на пакет должна себя оправдать замером на роутере, а не на ПК: Go-версия на ПК быстрее, на MikroTik медленнее.

Инварианты, которые легко сломать

Протокол (сверяться с amneziawg-go, а не с его README):

• Ключ header protection не задан → байт в байт AWG 2.0. Ветка ChaCha20 не вызывается вообще. Это проверяет hp_off_matches_v2 в test_transform.c.
• AWG 3.x требует S1–S4 ≥ 12. Nonce — первые 12 байт S-паддинга. Прокси с меньшими значениями не стартует. В README amneziawg-go написано 8, в коде HeaderCipherNonceSize = 12.
• Порядок автоопределения версии: v3.1 (trailers или disable cookies) → v3 (ключ HP) → v2 (S3/S4 или диапазоны H) → v1.5 (I1–I5) → v1. Конфиги пользователей рассчитаны на эту семантику.
• MAC1 пересчитывается после подмены типа на ключах AWG_SERVER_PUB / AWG_CLIENT_PUB. В режиме server для прямых клиентов ключ ищется по AWG_CLIENT_PUBS (см. docs/server-mode-multi-peer.md).
• Теги I1–I5 совпадают с device/obf.go. <c> — наше расширение, эталон его не примет.
• AWG_RANDOM_TRAILERS должен совпадать с сервером. Ступень отката без trailers остаётся байт в байт прежней.
• Transport-пакеты без ключей не трогаются внутри: content padding и тайминги 3.0 эмулировать нельзя, такие параметры только принимаются и пишутся в лог.

Горячий путь и сеть:

• BATCH_SIZE не поднимать. 32 → 128 уронило пропускную способность с 208 до 127 Мбит/с: буферы батча перестали влезать в кэш Cortex-A53.
• GSO на отправке и GRO на приёме остаются. Без GSO пропускная способность падала вдвое.
• Семья адреса не ветвит горячий путь. Адрес клиента хранится в общем виде фиксированной длины.
• EMSGSIZE на удалённом сокете — не обрыв. Это ICMP «fragmentation needed». Переподключаться нельзя: до 1.4.2 это давало секунду тишины и смену порта. Path MTU читается через IP_MTU раз в 5 секунд (check_path_mtu()).
• Потолок MTU: MTU ≤ 1440 − S4 по IPv4 и 1420 − S4 по IPv6 (awg_max_wg_mtu()), иначе каждый пакет данных уходит двумя фрагментами.
• Файл состояния (AWG_STATE_FILE) пишется не чаще раза за запуск процесса: flash роутера маленький.

Особенности RouterOS:

• Контейнер без CAP_NET_ADMIN. SO_RCVBUFFORCE отвечает EPERM, net.core.rmem_max из контейнера не поменять. AWG_RT и AWG_RPS работают только при privileged=yes (RouterOS 7.24+).
• Тюнинг зависит от класса железа. Пины потоков, AWG_RT и AWG_RPS отбрасываются при < 4 ядрах или 32-битном CPU (perf_fit_hw). На hAP ac² пин плюс RT уронили отдачу со 100 до 34 Мбит/с. Любую ручку производительности мерить на слабом arm (hAP ac²) и на сильном arm64 (hAP ax²).
• AWG_SPIN несовместим с AWG_RT. Спин под real-time отнимает ядро у softirq, который считает крипто WireGuard.
• RouterOS обрезает строку лога контейнера на 179 символах вместе с именем. Новые поля выносить отдельной строкой, а число ставить в начало.
• Потери в приёмном буфере снаружи контейнера не видны. Для диагностики — AWG_STATS.

Конфигуратор (docs/conf3.0.html):

• Ничего не отправляет в сеть. Ни fetch, ни внешних скриптов и шрифтов: пользователь вставляет приватный ключ, и вся ценность страницы в том, что ключ не покидает браузер.
• Скрипты, которые он кладёт на роутер, сами себя не обновляют. Исправление в генерации доходит до пользователя только после повторного запуска. В CHANGELOG это нужно писать прямо.
• Версия RouterOS разбирается по цифрам до первой буквы: бывают 7.25beta5, 7.22rc1.
• tools/awg-gen.js ходит по форме страницы: id полей, имена радиокнопок, generate(), SERVICES, EXCLUSIONS. Переименовали — поправьте CLI; расхождение ловит tests/awg-gen.test.js.

Документация

• README.md и README_en.md короткие: выжимка, таблица моделей, быстрый старт, ссылки. Подробности живут в docs/ (русский) и docs/en/ (английский, те же разделы). Меняя поведение, правьте оба языка.
• На каждом релизе обновляйте в README строку «Последняя сверка документации» и, если менялось, таблицу моделей. Краткая выжимка для ИИ-ассистентов — docs/llms.txt, её тоже держите в актуальном состоянии.
• Тексты ошибок в docs/troubleshooting.md приводите дословно: по ним ищут.

Коммиты и релизы

• Сообщения коммитов и CHANGELOG — на русском, в стиле патчноутов: что поменялось, как было, что стало, кого касается.
• Релиз: запись в CHANGELOG.md → тег vX.Y.Z → CI собирает 8 архивов (4 архитектуры × OCI и classic Docker) и образы ghcr.io/timbrs/awg-proxy:latest и :latest-armv5.