guard/docs/roadmap/v0.4-startup-diagnostics.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.2 KiB
Raw Permalink Blame History

v0.4 — Startup-диагностика окружения

Milestone v0.4
Status planned
Priority P1
Depends on —

Цель

Edge при старте сам говорит, что с окружением: kernel, BTF, драйвер NIC, поддержка native/generic XDP, доступные capabilities — и падает с внятной причиной, если XDP включён, но загрузиться не сможет.

Зачем

Диагностика уже есть в rampart-cli doctor (src/xdp/probe/, EnvironmentReport), но демон её не использует. У конкурентов ~80% issues про XDP — это attach на неподдерживаемом окружении (OpenVZ/LXC, старый kernel, отсутствие BTF), при этом сообщение появляется уже после неудачного load().

Scope

  • Переиспользовать EnvironmentReport/FilesystemProbe при старте edge, а не писать второй детектор.
  • Один структурированный лог-вердикт: kernel, virt, interface, driver, native|generic|none, причина отказа.
  • Fail-fast только когда [xdp] enabled = true и загрузка невозможна; иначе — предупреждение и работа без XDP (текущее поведение сохраняется).
  • Код возврата/сообщение для systemd: человек читает journalctl и понимает, что делать, без чтения исходников.

Non-goals

  • Автоматическое лечение окружения (загрузка модулей, смена драйвера).
  • Полноценный doctor в демоне: интерактивные проверки остаются в CLI.

Approach

  1. Вынести общий «вердикт» в src/xdp/probe/, чтобы CLI и демон печатали одно и то же.
  2. В app::runtime перед start_xdp логировать отчёт; при ошибке attach — приложить вердикт к ошибке.
  3. Тесты: чистая функция форматирования отчёта (без root), плюс существующие tests/xdp_diagnostics.rs.
  4. Документация: раздел в docs/troubleshooting.md и docs/runbook.md со ссылкой на тот же вердикт.

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

  • На kernel без BTF/в LXC лог содержит причину и рекомендацию.
  • В KVM с virtio вывод честно говорит generic (skb), а не «XDP works».
  • rampart-cli doctor и edge используют один код формирования отчёта.
  • cargo clippy --all-targets --all-features -- -D warnings чистый.

Верификация

Прогон в двух окружениях: обычный хост и контейнер без CAP_BPF; вывод сравнивается с docs/troubleshooting.md.