- 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.
3.2 KiB
3.2 KiB
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
- Вынести общий «вердикт» в
src/xdp/probe/, чтобы CLI и демон печатали одно и то же. - В
app::runtimeпередstart_xdpлогировать отчёт; при ошибке attach — приложить вердикт к ошибке. - Тесты: чистая функция форматирования отчёта (без root), плюс существующие
tests/xdp_diagnostics.rs. - Документация: раздел в
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.