Rust Coding Standard

Rust Coding Standard

Rules for writing Rust in the onde crate. These are traps to avoid, not maps to follow.

Correctness First

Prioritize correctness and clarity. Performance is secondary unless explicitly stated. Complete, mostly-correct code beats perfect code that doesn't solve the problem.

Error Handling

• Propagate errors with ?. Never call .unwrap() or .expect() outside of #[cfg(test)] code.
• Never silently discard errors with let _ = on fallible operations:
  • Propagate with ? when the caller should handle it.
  • Use log::warn! or log::error! when you need to ignore but want visibility.
  • Use match or if let Err(e) when custom recovery logic is needed.
• Use anyhow for internal application errors in engine.rs.
• Use thiserror for the InferenceError enum — it crosses the FFI boundary via UniFFI.
• Be careful with indexing operations that may panic if out of bounds. Prefer .get() and safe alternatives.

Naming

• Use full words for all variable and parameter names. No single-letter names, no abbreviations (environment not env, client not c, message not msg).
• snake_case for functions and variables, CamelCase for types, SCREAMING_SNAKE_CASE for constants.
• Model constants live in src/inference/models.rs. Prefix HuggingFace repo IDs with the org name: BARTOWSKI_QWEN25_....

Comments

• Comments explain why, never what. Do not write comments that summarize or re-describe the code.
• Doc comments (///) on public items are fine and encouraged — they explain the contract, not the implementation.
• Do not add organizational separators like // --- Helper functions --- unless they are already established in the file's style.

Module Structure

• No mod.rs for new modules. Use src/some_module.rs instead of src/some_module/mod.rs. Exception: inference/mod.rs already exists and is the intentional module root — don't move it.
• Prefer implementing functionality in existing files unless it's a genuinely new logical component. Avoid creating many small single-purpose files.

Async

• Runtime is tokio. All async functions use tokio::sync::Mutex, not std::sync::Mutex.
• Use variable shadowing to scope .clone() calls inside async closures, minimizing borrow lifetimes:

tokio::spawn({
    let engine = engine.clone();
    async move {
        engine.do_work().await;
    }
});

Logging

• Use log crate macros: log::debug!, log::info!, log::warn!, log::error!.
• No println! or eprintln! in library code. Ever.
• Log at debug for routine operations, info for lifecycle events (model loaded/unloaded), warn for recoverable issues, error for failures.

Platform Gating

• Use #[cfg(target_os = "...")] blocks. Match Cargo.toml's target-conditional dependency sections.
• When a function is only used on specific platforms, gate the function itself — not just the call site. This prevents dead-code warnings on other targets.
• When an import is only used on specific platforms, gate the use statement separately. Do not put platform-only imports inside a shared use block.
• The supported target_os values are: macos, ios, tvos, windows, linux, android.
• ISQ model loading is #[cfg(target_os = "macos")] only. Gate the Isq variant, its match arms, and its imports (IsqBits, TextModelBuilder) to macOS.

Clippy Compliance

All code must pass cargo clippy --all-targets -- -D warnings. Common traps:

• &PathBuf in function parameters → use &Path instead.
• unwrap_or_else(Type::default) → use unwrap_or_default().
• filter_map(|x| { ... Some(y) }) where every path returns Some → use map.
• .map(|x| f(x)) where f is a plain function → use .map(f).
• Redundant type annotations in closures: .map(|c: &String| c.trim()) → .map(|c| c.trim()).
• Unused imports/variants on platform-gated code → gate the import/variant to the same platform.

Types for FFI

• usize / isize are not FFI-safe. Use u64 / i64 in any type that crosses the UniFFI boundary.
• impl Into<String> is not FFI-safe. Use concrete String in exported signatures.
• All UniFFI-exported types go in src/inference/types.rs. The FFI wrapper lives in src/inference/ffi.rs.
• ChatEngine (engine.rs) owns Rust-idiomatic logic. OndeChatEngine (ffi.rs) is the thin FFI wrapper. Never put #[uniffi::export] on ChatEngine.

Re-exports

mistralrs, hf_hub, and mistralrs_core are re-exported from lib.rs for downstream Rust consumers. Keep these in sync with what's actually available per platform.

Testing

• Unit tests go in a #[cfg(test)] mod tests block at the bottom of the file they test.
• Use #[tokio::test] for async tests.
• Tests may use .unwrap() and .expect() — the panics are the assertions.
• Test names describe the scenario: engine_send_without_model_errors, not test_send or test_1.
• Run cargo test --lib to skip integration tests that require model downloads.

Adding a New Model

This is a common task with a specific checklist:

1. Add pub const entries in src/inference/models.rs for repo ID, GGUF filename, and TOK_MODEL_ID.
2. Add the repo ID to SUPPORTED_MODELS.
3. Add a SupportedModelInfo entry to SUPPORTED_MODEL_INFO with expected_size_bytes from the HF API.
4. Add a constructor to GgufModelConfig in engine.rs (follow qwen25_1_5b pattern).
5. Export a free function in ffi.rs (follow qwen25_1_5b_config pattern).

Build Verification

Always run cargo check before returning work. If code does not compile, fix it — do not return with TODOs. On macOS, also run cargo clippy --all-targets -- -D warnings to catch lint issues before CI does.

Source: ondeinference/onde — distributed by TomeVault.