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

6.4 KiB
Raw Blame History

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-правила

  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. Гейты

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