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.
This commit is contained in:
Loki 2026-11-16 14:51:50 +01:00
parent 1b3ae5e546
commit 280284667f
Signed by: boba
GPG key ID: 6CDE87BC9A778D97
38 changed files with 1582 additions and 623 deletions

116
docs/development.md Normal file
View file

@ -0,0 +1,116 @@
# 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*