# Rust Code Rules

## 1. Назначение документа

Этот документ фиксирует Rust-specific правила кода для проекта:

- toolchain;
- linting;
- formatting;
- ошибки;
- async;
- ownership;
- visibility;
- dependency hygiene.

Цель документа - убрать плавающие договоренности по стилю и практике командной Rust-разработки.

## 2. Toolchain

### 2.1. Версия Rust

Для проекта должен быть зафиксирован `rust-toolchain.toml`.

В нем должны быть определены:

- стабильный `channel`;
- `protocol`;
- при необходимости `components`.

Рекомендуемый состав:

- `rustfmt`
- `clippy`

### 2.2. MSRV

Нужно зафиксировать `MSRV` - минимально поддерживаемую версию Rust.

Правило:

- без необходимости не использовать возможности языка новее зафиксированного `MSRV`;
- обновление `MSRV` - это отдельное осознанное решение.

## 3. Formatting и linting

### 3.1. Formatting

Обязательное правило:

- весь код форматируется через `cargo fmt`.

Ручной стиль форматирования не обсуждается и не поддерживается.

### 3.2. Clippy

Обязательное правило:

- `cargo clippy --all-targets --all-features -- -D warnings`

Предупреждения считаются ошибками, если нет явно зафиксированного исключения.

### 3.3. CI quality gates

Минимально в CI должны запускаться:

- `cargo fmt --check`
- `cargo clippy --all-targets --all-features -- -D warnings`
- `cargo test`

Опционально позже:

- `cargo deny`
- `cargo audit`

## 4. `unsafe`

Для проекта принимается правило:

- `unsafe` запрещен по умолчанию.

Если когда-либо потребуется `unsafe`, то:

- это должно быть отдельное осознанное решение;
- причина должна быть технически обоснована;
- блок должен быть минимальным;
- вокруг него должны быть тесты.

Для MVP можно считать:

- `unsafe_code = deny`

## 5. Panic policy

В production code запрещены:

- `unwrap()`
- `expect()`
- `todo!()`
- `unimplemented!()`
- `dbg!()`
- необоснованные `panic!()`

Допускается:

- в тестах;
- в очень раннем bootstrap-коде, если это действительно аварийное завершение и не часть доменной логики.

Базовое правило:

- ошибки возвращаются через `Result`, а не через panic.

## 6. Правила ошибок

### 6.1. Domain и service errors

В домене и сервисах использовать типизированные ошибки.

Рекомендуемо:

- `thiserror`

### 6.2. Application boundary

На верхних слоях приложений допускается агрегирование ошибок, если это упрощает wiring.

При необходимости:

- `anyhow` только на внешних границах приложения, не в доменной модели.

### 6.3. Error context

Ошибка должна сохранять стадию отказа:

- schema
- mapping
- adapter
- persistence
- external service
- internal runtime

## 7. Visibility rules

Правило:

- по умолчанию все приватное;
- `pub(crate)` предпочтительнее `pub`;
- публичный API должен быть минимальным.

Нельзя:

- открывать модуль наружу "на всякий случай";
- делать `pub` просто ради удобства из соседнего файла;
- реэкспортировать целые деревья модулей без причины.

## 8. Ownership и данные

### 8.1. Клонирование

Правило:

- не клонировать данные без необходимости;
- клон должен быть осознанным, а не способом обойти borrow checker без понимания причины.

### 8.2. Shared mutability

Правило:

- не использовать `Arc<Mutex<_>>` как универсальный контейнер состояния;
- shared mutability допускается только там, где она действительно нужна по архитектуре.

### 8.3. ID types

Идентификаторы должны быть отдельными типами, а не просто `String`.

Примеры:

- `OperationId`
- `DescriptorId`
- `AuthProfileId`

## 9. Async rules

### 9.1. Где допускается `async`

`async` используется только там, где есть:

- I/O;
- network;
- storage;
- async boundary приложения.

### 9.2. Где `async` не нужен

Нельзя превращать:

- schema validation;
- mapping;
- чистую доменную логику;
- небольшие derived methods

в `async fn` без причины.

### 9.3. `tokio`

`tokio` должен находиться:

- в приложениях;
- в I/O слоях;
- в адаптерах и runtime orchestration, если там есть реальный async.

Доменный слой не должен зависеть от `tokio`.

## 10. API design rules

### 10.1. Конструкторы

Использовать:

- `new()` для гарантированно валидного и простого создания;
- `try_new()` там, где есть валидация и возможна ошибка.

### 10.2. Builders

Если структура имеет много параметров и прямой конструктор становится нечитаемым, допускается builder.

Но:

- builder не должен маскировать плохую модель данных;
- builder не должен использоваться как замена нормальной декомпозиции.

### 10.3. DTO отдельно от domain

Если HTTP payload начинает расходиться с доменной моделью, нужно вводить отдельный DTO слой.

Нельзя:

- тащить `serde`-ориентированный API payload прямо в домен только ради удобства.

## 11. Dependency rules

### 11.1. Внешние crates

Правило:

- сначала использовать `std`;
- потом существующие внутренние abstractions;
- только потом тянуть новый внешний crate.

Нельзя:

- добавлять зависимость "на всякий случай";
- дублировать crates с пересекающейся функцией без причины.

### 11.2. Макросы

Правило:

- не злоупотреблять макросами там, где обычный Rust-код читается лучше;
- derive-макросы допустимы;
- сложные процедурные макросы без сильной причины не нужны.

## 12. Serialization rules

### 12.1. JSON/YAML

Правило:

- доменная модель одна;
- `JSON` и `YAML` - только два формата сериализации;
- нельзя допускать, чтобы YAML export стал отдельной несовместимой моделью.

### 12.2. Secrets

Никогда не сериализовать:

- реальные токены;
- пароли;
- API keys

в exports, logs и test snapshots.

## 13. Тестовые практики на уровне Rust-кода

Минимально:

- unit tests рядом с модулем или в `tests`;
- integration tests для crate boundaries;
- фикстуры для schema/mapping/proto/yaml roundtrip.

Полезное правило:

- баг сначала воспроизводится тестом, потом фиксится кодом.

## 14. Что часто запрещают в Rust-командах

Практически всегда под запретом:

- `unwrap()` в production code;
- `unsafe` без review;
- giant modules;
- giant enums со всем подряд;
- giant services, где смешаны orchestration и transport;
- абстракции "на будущее" без второго реального кейса.

## 15. Практический итог

Для этого проекта правильный Rust-профиль такой:

- фиксированный toolchain;
- обязательные `fmt` и `clippy`;
- `unsafe` запрещен по умолчанию;
- panics запрещены в production code;
- ошибки типизированы;
- `pub` минимизируется;
- `async` только на реальных async boundaries;
- код читается за счет имен и декомпозиции, а не за счет комментариев.