guard/docs/development.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

116 lines
6.4 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.

# 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*