- 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.
116 lines
6.4 KiB
Markdown
116 lines
6.4 KiB
Markdown
# Development — правила разработки Rampart
|
||
|
||
> Как мы пишем код, тесты и коммиты. Планы задач — в [roadmap/](roadmap/README.md),
|
||
> устройство системы — в [architecture.md](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-правила
|
||
|
||
1. `unwrap()` — только в `main()` и тестах; в коде — `?` или явная обработка.
|
||
2. `unsafe` — только в `xdp/`, обязателен комментарий `// SAFETY:` с предусловиями.
|
||
3. `clone()` осознанно: горячий путь профилируется, а не «на всякий случай».
|
||
4. Блокирующие операции — в `spawn_blocking`.
|
||
5. Логи — `tracing::{info,debug,warn,error}`; `print_*` запрещён clippy-линтом.
|
||
6. Метрика регистрируется один раз при старте, инкремент — в горячем пути.
|
||
7. `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. Рабочий процесс
|
||
|
||
1. Новая функциональность → сначала дизайн (что и зачем, альтернативы), потом план.
|
||
2. Баг → сначала корневая причина, потом фикс; симптомные заплатки запрещены.
|
||
3. Любая правка кода → тест (сначала падающий) → реализация.
|
||
4. Перед «готово» — свежий прогон гейтов и вывод, а не воспоминания.
|
||
|
||
## 7. Гейты
|
||
|
||
```bash
|
||
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*
|