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