guard/docs/roadmap/v0.4-xdp-ci-harness.md
loki5512344 280284667f
docs: per-task roadmap, architecture and changelog
- Split TODO into a thin status index plus docs/roadmap/ with one file per
  task (v0.4 reliability, v0.5 product, v0.6 research, icebox).
- Add docs/architecture.md (current processes, packet/data path, layers,
  storage, metrics) and docs/development.md (rules, gates, DoD).
- Add CHANGELOG.md reconstructed from history; move round details out of
  TODO.
- Align docs with the code: config defaults and missing [detect]/
  [protocol.http] sections, XDP metric names, ClickHouse table and TTL,
  Redis RDB restore, multiarch clang include, CLI binary name.
- Add scripts/check_docs_links.sh and run it in CI.
- release profile: thin LTO + one codegen unit. Binary 12.3 MB -> 9.7 MB,
  http parser bench 314 ns -> 278 ns; panic=abort stays off for
  catch_unwind in the Redis subscriber.
- Drop the unused JWT role claim; fix 'rampart doctor' hints in the CLI.
2026-11-16 14:51:50 +01:00

3.7 KiB
Raw Permalink Blame History

v0.4 — XDP netns+veth harness в CI

Milestone v0.4
Status planned
Priority P0
Depends on —

Цель

Каждый PR проверяет XDP-программу на реальном ядре: загрузка через verifier, attach в netns, баны, whitelist, expiry — без ручных шагов на живой ноде.

Зачем

Сейчас scripts/xdp_ipv6_smoke.sh, xdp_pkt_test.sh и xdp_netns_smoke.sh запускаются вручную. Регрессии ловятся только на реальном сервере, а раунд 2026-11 показал, что именно там ломается (UAF при чтении map, .rodata-раскладка, имена карт в загрузчике). В конкурентном анализе (вывод №7) такой харнесс отсутствует у всех — это наше преимущество в надёжности.

Scope

  • Единая точка входа scripts/xdp_ci.sh: поднимает netns+veth, собирает BPF через build.rs, грузит программу, гоняет фазы v4/v6/ban/whitelist/expiry/udp.
  • Формат вывода и код возврата, пригодные для CI (без интерактивных шагов).
  • CI-job: либо self-hosted runner с CAP_BPF/CAP_NET_ADMIN, либо hosted ubuntu-24.04 с sudo и проверкой, что kernel ≥ 5.10 и программа реально загрузилась (не только скомпилировалась).
  • Документация: как запустить локально и что делать, если в окружении нет прав.

Non-goals

  • Нагрузочный тест на 1M pps: это deploy/test/stress/, отдельный стенд.
  • Проверка на всех драйверах: native/generic режимы достаточно проверить на veth.

Approach

  1. Обернуть существующие скрипты общим хелпером (создание netns/veth, cleanup через trap) — сейчас логика дублируется.
  2. Добавить --ci режим: короткие таймауты, машиночитаемые PASS/FAIL строки.
  3. Job в .github/workflows/ci.yml; при отсутствии прав — честный SKIP, а не зелёный тест.
  4. Регрессионный тест на загрузчик: tests/xdp_object_maps.rs уже проверяет имена карт без root, оставить его обязательным.

Критерии приёмки

  • sudo bash scripts/xdp_ci.sh проходит на kernel ≥ 5.10 с bpftool.
  • CI-job падает при регрессе в universal_filter.c, config.h, maps.h.
  • Нет root-прав — job выдаёт SKIP с причиной, а не ложный успех.
  • README/testing.md и docs/testing.md описывают один и тот же путь запуска.

Верификация

sudo bash scripts/xdp_ci.sh на dev-машине + прогон job в PR с намеренно сломанным заголовком config.h (должен упасть).

Риски

  • GitHub-hosted runner может не дать CAP_BPF; тогда нужен self-hosted runner. Решение принимается на этапе дизайна, до реализации.
  • veth не воспроизводит offload-поведение реального NIC; паддинг и VLAN покрываются xdp_pkt_test.sh отдельно.