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

60 lines
3.2 KiB
Markdown
Raw 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 — 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`.