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

65 lines
3.7 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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` отдельно.