petekp/rust

Rust Engineering Guide

Patterns for building reliable Rust systems that handle file-backed data, external process integration, and cross-language boundaries.

Core Philosophy

Conservative by Default: Inputs from files, subprocesses, and external systems are untrusted.

• Prefer false negatives over false positives
• Same input → same output (deterministic)
• Never panic on user machines due to bad input

Canonical Model Ownership: When Rust is the source of truth, maintain separate representations:

| Layer | Purpose | Characteristics | |-------|---------|-----------------| | Internal domain | Business logic | Expressive enums, rich types | | FFI DTOs | Cross-language boundary | Flat, stable, String-heavy | | File format | Persistence | Versioned, round-trippable | | External input | Validation boundary | Strictly validated, never trusted |

Safe Rust Only: None of these patterns require unsafe. Use ecosystem crates for safe abstractions.

---

Reference Guides

Load the relevant reference when working in that domain:

| Domain | Reference | When to Load | |--------|-----------|--------------| | Data Modeling | references/data-modeling.md | Serde patterns, UniFFI, strong types, versioned schemas | | File I/O | references/file-io.md | Atomic writes, concurrency control, file watching | | Process Integration | references/process-integration.md | PID verification, subprocess handling, timestamps | | Text & Parsing | references/text-and-parsing.md | UTF-8 safety, path normalization, state machines | | Testing | references/testing.md | Round-trip tests, fuzz testing, Clippy lints |

---

Error Handling

Library vs Application Errors

Libraries (public API): Use thiserror with granular error types per operation:

// File operations have their own error type
#[derive(thiserror::Error, Debug)]
pub enum ReadError {
    #[error("failed to read {path}")]
    Io { path: PathBuf, #[source] source: std::io::Error },

    #[error("parse error at line {line}: {message}")]
    Parse { line: usize, message: String },
}

// Subprocess operations have their own error type
#[derive(thiserror::Error, Debug)]
pub enum SubprocessError {
    #[error("failed to spawn process")]
    Spawn(#[source] std::io::Error),

    #[error("process exited with {code:?}: {stderr}")]
    NonZeroExit { code: Option<i32>, stderr: String },

    #[error("output not valid UTF-8")]
    InvalidUtf8(#[source] std::str::Utf8Error),

    #[error("timed out after {0:?}")]
    Timeout(std::time::Duration),
}

Applications (internal/binary): Use anyhow for context-rich errors:

use anyhow::{Context, Result};

fn load_config(path: &Path) -> Result<Config> {
    let content = std::fs::read_to_string(path)
        .with_context(|| format!("failed to read config from {}", path.display()))?;
    // ...
}

Graceful Degradation

Errors degrade functionality, not crash. But log when being lenient:

match parse_metadata(&line) {
    Ok(meta) => entries.push(meta),
    Err(e) => {
        tracing::warn!("skipping malformed entry at line {}: {}", line_num, e);
        // Continue processing other entries
    }
}

---

Quick Reference

Do

• Use std::sync::LazyLock for static regex (Rust 1.80+)
• Hold locks across entire read-modify-write cycles
• Add #[serde(deny_unknown_fields)] for strict external input
• Truncate strings with .chars() or graphemes, not byte slicing
• Write files atomically with sync_all() before rename
• Verify PID identity with process start time
• Use saturating_sub for time arithmetic
• Run cargo clippy -- -D warnings and cargo fmt before commit

Don't

• Use #[from] without adding context (loses which file failed)
• Create monolithic error enums spanning unrelated operations
• Silently ignore errors without logging
• Slice strings with &s[..N] (panics on char boundaries)
• Assume directory iteration order is stable
• Trust subprocess output without validation
• Use unsafe (not needed for these patterns)

---

Bugs This Guide Prevents

| Bug | Pattern | Reference | |-----|---------|-----------| | PID reuse "ghost sessions" | Store + verify process start time | process-integration.md | | Timestamp unit mismatch (sec vs ms) | Normalize on read | process-integration.md | | UTF-8 panic on truncation | Use .chars().take(n) | text-and-parsing.md | | Lost updates under concurrency | Lock spans full read-modify-write | file-io.md | | Corrupt file on power loss | sync_all() before rename | file-io.md | | Silent metadata corruption | Anchor updates to heading lines | text-and-parsing.md | | Old data breaks new code | #[serde(default)] + alias | data-modeling.md |

---

Change Checklist

When modifying these systems, verify:

Schema / Serde

• [ ] New fields use Option + #[serde(default)]
• [ ] Old field names supported via alias (read) or rename (write)
• [ ] External input uses #[serde(deny_unknown_fields)]

Concurrency

• [ ] Mutex held across entire read-modify-write cycle
• [ ] Shared state uses Mutex<T>, not thread_local!
• [ ] File locking documents platform caveats if used

Robustness

• [ ] No panics on file I/O or parse errors
• [ ] Errors logged before being ignored
• [ ] Subprocesses have timeouts

Quality

• [ ] cargo clippy -- -D warnings passes
• [ ] cargo fmt --check passes
• [ ] No unsafe blocks (unless justified and audited)