Jon Chery
496303471d
---ci--- project: atelier phase: 7 milestone: v0.1 status: complete phase_role: final milestone_complete: true requirements: covered: [ATELIER-01, ATELIER-02, ATELIER-03, ATELIER-04, ATELIER-05, ATELIER-06, ATELIER-07, ATELIER-08, ATELIER-09, ATELIER-10, ATELIER-11, ATELIER-12, ATELIER-13, ATELIER-14, ATELIER-15, ATELIER-16, ATELIER-17, ATELIER-18, ATELIER-19, ATELIER-20, ATELIER-21, ATELIER-22, ATELIER-23, ATELIER-24, ATELIER-25, ATELIER-26, ATELIER-27, ATELIER-28, ATELIER-29, ATELIER-30, ATELIER-31, ATELIER-32, ATELIER-33, ATELIER-34, ATELIER-35] partial: [] ship: milestone: v0.1 type: NFR tag: v0.0.7 merge: milestone/v0.1-atelier -> main release: https://git.cloudinit.dev/cloudinit-bot/atelier/releases/tag/v0.0.7 ---/ci--- Milestone v0.1 — Initial Framework (NFR, complete). 8 core principles (C1-C8), 11 domains, 110 domain principles, 27 derived docs, 4 good + 3 bad examples, 4 language docs, full matrix, 3 review docs. All 35 requirements covered. 7 patches (v0.0.0 pre-execution through v0.0.7 final). v0.0.7 IS the v0.1.0 milestone release.
79 lines
3.1 KiB
Markdown
79 lines
3.1 KiB
Markdown
# Rust — Language Application
|
|
|
|
> How Atelier's domain principles apply in Rust specifically. Derives from `domains/` docs.
|
|
|
|
## Type System (C1 Correctness, Data P7 Type Fidelity)
|
|
|
|
- **Newtypes for domain concepts:** `struct UserId(String);` — zero-cost, type-safe.
|
|
- **`enum` for finite domains:** `enum Status { Pending, Paid, Shipped }` — exhaustive.
|
|
- **No `unsafe` without justification and review:** `unsafe` opts out of the compiler's guarantees.
|
|
|
|
```rust
|
|
struct UserId(String);
|
|
struct OrderId(String);
|
|
// Cannot pass OrderId where UserId is expected
|
|
fn get_user(id: UserId) -> Result<User, Error> { ... }
|
|
```
|
|
|
|
## Error Handling (Errors P1 Errors are Data)
|
|
|
|
- **`Result<T, E>` for fallible operations:** errors are values, not exceptions.
|
|
- **`thiserror` for error enums, `anyhow` for applications:**
|
|
```rust
|
|
#[derive(thiserror::Error)]
|
|
enum AppError {
|
|
#[error("not found: {0}")]
|
|
NotFound(String),
|
|
#[error("validation: {0}")]
|
|
Validation(String),
|
|
#[error(transparent)]
|
|
Io(#[from] std::io::Error),
|
|
}
|
|
```
|
|
- **`?` for propagation, not `unwrap()`:** `unwrap()` panics in production.
|
|
- **No `panic::catch_unwind` for control flow:** panics are for bugs, not errors.
|
|
|
|
## Concurrency (Concurrency — Rust's ownership model)
|
|
|
|
- **`Send` and `Sync` traits enforced by the compiler:** data races are compile errors.
|
|
- **`Arc<T>` for shared, `Mutex<T>`/`RwLock<T>` for mutation:** the lock is explicit.
|
|
- **`tokio` for async:** `async fn`, `.await`. Bounded channels (`tokio::sync::mpsc::channel(N)`).
|
|
- **`Drop` for cleanup:** no leaked resources (no `defer` needed; RAII).
|
|
|
|
```rust
|
|
async fn fetch_with_timeout(url: &str) -> Result<Response, Error> {
|
|
tokio::time::timeout(Duration::from_secs(5), fetch(url)).await??;
|
|
}
|
|
```
|
|
|
|
## Immutability (Concurrency P1 Immutability by Default)
|
|
|
|
- **Variables are immutable by default:** `let x = 5;` not `let mut x = 5;`.
|
|
- **`&T` (shared ref) over `&mut T` (exclusive ref):** the compiler enforces aliasing rules.
|
|
- **Interior mutability (`Cell`/`RefCell`) only when needed:** not as a default.
|
|
|
|
## Nullability (C1)
|
|
|
|
- **`Option<T>`, not nullable pointers:** `Some(x)` / `None`. The compiler enforces handling.
|
|
- **No `null`:** Rust has no null. `Option::None` is the explicit absence.
|
|
- **`?` on `Option` for propagation:** `fn get_name(user: User) -> Option<String> { user.profile?.name }`.
|
|
|
|
## Testing (Testing)
|
|
|
|
- **`#[test]` + `#[cfg(test)] mod tests`:** tests co-located.
|
|
- **`proptest` or `quickcheck` for property-based tests:** edge case coverage (P9).
|
|
- **`tokio::test` for async tests.**
|
|
- **No `SystemTime::now()` in tests:** inject an `Instant` or a mock clock.
|
|
|
|
## Observability (Observability P1)
|
|
|
|
- **`tracing` crate:** structured logs + spans + traces. Not `println!`.
|
|
- **`tracing::instrument` on functions:** automatic span context.
|
|
- **`tracing-subscriber` with JSON format:** structured output for production.
|
|
|
|
## Tooling (DevOps P2)
|
|
|
|
- **`cargo clippy`:** lint. `cargo clippy -- -D warnings` in CI.
|
|
- **`cargo fmt`:** format.
|
|
- **`cargo test`:** tests. `cargo test --release` for perf-sensitive.
|
|
- **Committed `Cargo.lock`:** reproducible builds (even for libraries, for CI). |