- 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.
6.4 KiB
6.4 KiB
Development — правила разработки Rampart
Как мы пишем код, тесты и коммиты. Планы задач — в roadmap/, устройство системы — в architecture.md.
1. Принципы
KISS → DRY → SOLID → YAGNI.
- Не добавляй абстракцию до третьего повторения.
- Повтор > 2 раз выноси, но лучше копипаста, чем неправильная абстракция.
- S: один файл = одна ответственность. O: расширение через трейты (
ProtocolHandler,Filter). I: маленькие трейты вместо God-trait. D: core зависит от трейтов, не от Redis/ClickHouse напрямую. - Не пиши BGP до v0.6, WASM-плагины до стабилизации compile-time API. Feature flag только для готовой фичи.
2. Ограничения размера
- Функция ≤ 60 строк, файл ≤ 250 строк, ≤ 4
.rs-файлов на папку. - Больше — декомпозиция по доменам с реэкспортами в
mod.rs. - Гейт:
scripts/check_module_size.sh+ ratchet-базлайн.module_size_baseline(легаси — WARN, новое нарушение — FAIL; после рефакторинга--update-baseline). tests/вне лимита: Cargo требует один файл = один бинарь.
3. Rust-правила
unwrap()— только вmain()и тестах; в коде —?или явная обработка.unsafe— только вxdp/, обязателен комментарий// SAFETY:с предусловиями.clone()осознанно: горячий путь профилируется, а не «на всякий случай».- Блокирующие операции — в
spawn_blocking. - Логи —
tracing::{info,debug,warn,error};print_*запрещён clippy-линтом. - Метрика регистрируется один раз при старте, инкремент — в горячем пути.
panic,dbg!,exitзапрещены линтами; выход процесса — только вmain.
4. Тесты
- Тесты живут в
tests/, не вsrc/:#[cfg(test)]-модулей в коде нет. - Хелпер, нужный тесту, становится
pubтолько при наличии реального потребителя. - На новый слой — интеграционный тест на слой (config parse, filter logic, registry fail-fast).
- Для бага сначала красный тест, потом фикс.
- Feature-gated код обязан собираться и тестироваться в CI
(
--all-featuresи--no-default-features).
5. Комментарии
- Все комментарии и doc-комментарии — на английском. Русский остаётся в
docs/, README, TODO, логах (tracing::*!) и сообщениях CLI/ошибок. - Rustdoc-стиль:
//!для модуля (что он владеет),///для элемента; секции# Errors/# Panics/# Safetyсохраняются. - C:
/** ... */над функцией/структурой/картой/глобалом, с@param/@return, когда они есть. - Без эмодзи, ASCII-баннеров и декоративных разделителей.
- Инлайн-комментарий объясняет почему, а не пересказывает код.
- Правишь файл — переводи комментарии в нём целиком; не трогай строковые литералы, идентификаторы и логику.
6. Рабочий процесс
- Новая функциональность → сначала дизайн (что и зачем, альтернативы), потом план.
- Баг → сначала корневая причина, потом фикс; симптомные заплатки запрещены.
- Любая правка кода → тест (сначала падающий) → реализация.
- Перед «готово» — свежий прогон гейтов и вывод, а не воспоминания.
7. Гейты
cargo fmt --all --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features
cargo test --no-default-features --features protocol-http
cargo deny check
bash scripts/check_module_size.sh
bash scripts/check_default_secrets.sh
bash scripts/check_docs_links.sh
Плюс make ebpf (clang BPF) и make fuzz (nightly, 60 с на цель).
XDP-путь на реальном ядре — scripts/xdp_ci.sh (задача v0.4).
8. Definition of Done
☐ cargo check / cargo test проходят
☐ clippy --all-targets --all-features -- -D warnings — 0 warnings
☐ cargo fmt --check проходит
☐ ни один файл > 250 строк; ни в одной папке src/ > 4 .rs-файлов
☐ тесты покрывают happy path + 2+ error case
☐ нет мёртвого кода: pub без вызовов, конфиг-поле без потребителя, метрика без writer
☐ нет дефолтных секретов
☐ README/docs соответствуют коду; план задачи обновлён
☐ CHANGELOG обновлён
☐ CI зелёный
9. Anti-patterns
❌ Тесты после кода.
❌ Файл > 250 строк или > 4 .rs в папке.
❌ TODO в коде без ссылки на план.
❌ Мёртвый код: pub без вызовов, конфиг-поле без потребителя, метрика без writer.
❌ «Бумажный слой»: фича описана, но не вызывается.
❌ Дефолтный секрет.
❌ Парсер за «один read» — TCP-поток приходит фрагментами.
❌ Feature flag, который не собирается в CI.
❌ Документ, описывающий несуществующую команду.
Версия: 1.0 | Ноябрь 2026