lang-rust
Modern Rust (2021/2024 editions) engineering, safe-by-default with
- License 许可
- MIT
- 所属仓库
- poppyTM/oride
- 最近更新
- 2026-09-30
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- lang-rust
- description
- Modern Rust (2021/2024 editions) engineering, safe-by-default with
02 资源文件 6
- 参考文档checks/rust-rules.md1.7 KB
- 脚本examples/safe_rust.rs5.4 KB
- 参考文档manifest.json2.0 KB
- 参考文档references/rust-safety-miri.md2.6 KB
- 脚本scripts/verify.sh2.1 KB
- 参考文档templates/rust-verification-report.md1.3 KB
03 SKILL.md 正文
Rust Safe-by-Default & Systems Reliability Contract
1. Title and Description
Rust Safe-by-Default & Systems Reliability Contract (lang-rust)
Defines production-grade Rust engineering standards across application, library, embedded/no_std, and FFI profiles. Guarantees memory safety, data-race freedom, disciplined unsafe quarantine with Miri verification, idiomatic error handling, and zero-defect linting under Clippy.
2. Purpose
Enforce non-negotiable memory safety and type-level correctness in Rust projects within Prumo, ensuring code never relies on undefined behavior (UB), unchecked unwraps, or leaky concurrency abstractions.
3. Prerequisites
- Rust stable toolchain installed (
rustc,cargo,clippy,rustfmt). - Recommended:
cargo-audit,cargo-deny, andmiri(for unsafe validation:rustup component add miri). - Standard
Cargo.tomlworkspace or package manifest.
4. Inputs
- Rust source code (
src/**/*.rs), tests, and build configurations (Cargo.toml,Cargo.lock). - Project profile:
application,library,systems-engine, orembedded-no_std.
5. Outputs
- Fully formatted (
cargo fmt) and clippy-clean (cargo clippy -- -D warnings) Rust code. - Exhaustive error propagation using type-driven error hierarchies (
thiserror/anyhow). - Formally justified unsafe blocks with
// SAFETY:invariants and Miri verification evidence. - Verification report conforming to
templates/rust-verification-report.md.
6. Execution Steps
Step 1: Establish Project Profile & Safety Baseline
- Default to
#![forbid(unsafe_code)]:- Every binary application and safe library crate must declare
#![forbid(unsafe_code)]at the root oflib.rsormain.rs. - If low-level operations (e.g. FFI, SIMD, lock-free memory, custom allocators) strictly require
unsafe, change root to#![deny(unsafe_code)]and isolate unsafe blocks into quarantined leaf modules.
- Every binary application and safe library crate must declare
- Edition & MSRV: Specify the edition (2021 or 2024) and
rust-version(MSRV) explicitly inCargo.toml.
Step 2: Idiomatic Error Handling
- Zero
.unwrap()or.expect()in non-test code:- Never call
.unwrap()or.expect()on paths that could execute in production. - Use the question mark operator
?to bubble errors up the call stack.
- Never call
- Library vs Application Error Patterns:
- Libraries: Define domain error enums using
thiserror. Never expose erased error types (e.g.Box<dyn Error>) in public APIs. - Applications: Use
anyhow::Result<T>orcolor_eyreat the binary boundary to attach user-facing operational context (.context("reading config file")).
- Libraries: Define domain error enums using
- Parse, Don't Validate: Use the type system to enforce invariants at construction time (e.g.,
NonZeroUsize, validated newtypes with private fields and fallible constructors).
Step 3: Unsafe Code Guidelines (UCG) & Quarantine
When an escape hatch into unsafe is unavoidable:
- Document
// SAFETY:Invariant: Everyunsafeblock orunsafe fnmust be preceded immediately by a// SAFETY:comment proving:- Why pointers are valid, aligned, non-null, and point to initialized memory.
- Why lifetime bounds are preserved without aliasing violations.
- How no data races or unaligned reads can occur.
- Enforce Pointer Provenance:
- Never cast integer to pointer directly; use
std::ptr::NonNullfor non-null pointers. - Use
MaybeUninit<T>for uninitialized buffers. Never usemem::uninitialized(). - Respect strict aliasing: never create
&mut Tand&Tsimultaneously to the same memory location.
- Never cast integer to pointer directly; use
- Miri Verification: Run
cargo miri teston all crates containing unsafe code under both Stacked Borrows and Tree Borrows (-Zmiri-tree-borrows).
Step 4: Concurrency & Thread-Safety Invariants
- Send and Sync Markers:
- Types automatically implement
SendandSyncif all constituent fields do. - If manually implementing
unsafe impl SendorSync, prove that access through&Tacross thread boundaries cannot introduce data races.
- Types automatically implement
- Locking Hierarchy & Contention:
- Minimize lock hold times: never perform I/O, channel sends, or heavy computation while holding a
MutexGuard. - Prefer lock-free primitives from
std::sync::atomicwith explicitOrdering(Relaxed,Acquire,Release,SeqCst) rather than defaulting lazily toSeqCst. - For channel communications, prefer
crossbeam-channelortokio::sync::mpsc.
- Minimize lock hold times: never perform I/O, channel sends, or heavy computation while holding a
Step 5: Async Rust & Cancellation Safety
- Cancellation Invariant in
tokio::select!:- Ensure branches inside
tokio::select!are cancellation-safe. - If an async future holds partial state across
.awaitpoints and is dropped when another branch completes, it must not leave corrupted shared state or dropped resource locks.
- Ensure branches inside
- Pin Projections: Use
pin-project-litewhen implementing custom async streams or futures that require self-referential pinned pointers.
Step 6: Clippy, Deny & Security Linting
- Run
cargo clippy --all-targets --all-features -- -D warnings. - Configure
clippy::pedanticand selectively deny:clippy::unwrap_usedclippy::expect_usedclippy::panicclippy::wildcard_imports
- Verify dependencies against known vulnerability advisories using
cargo audit.
7. Verification
Run the verification sequence:
# 1. Format verification
cargo fmt --all -- --check
# 2. Strict linter gate
cargo clippy --all-targets --all-features -- -D warnings -D clippy::unwrap_used
# 3. Unit and integration test suite
cargo test --all-features
# 4. Unsafe memory interpretation (if unsafe blocks present)
cargo miri test
# 5. Dependency security audit
cargo audit
8. Fallbacks & Failure Recovery
| Failure Class | Root Cause | Deterministic Remediation |
|---|---|---|
| Borrow Checker E0502/E0499 | Simultaneous mutable and immutable borrow in scope | Reorder statements to shorten borrow lifetime. Use scoped blocks { ... }, or clone primitive small fields before borrowing mutable parent. |
| Lifetime Invariant E0106/E0495 | Lifetime of returned reference unbound from input struct | Tie lifetimes explicitly (fn get<'a>(&'a self) -> &'a Data), or return owned type (String, Arc<T>) if caller requires detached lifecycle. |
| Miri Aliasing Violation | Multiple raw pointers dereferenced into mutable reference alias | Switch raw pointer manipulation to std::cell::UnsafeCell or inspect under Tree Borrows (-Zmiri-tree-borrows). |
| Async Deadlock | Mutex held across .await point blocking async runtime executor |
Replace std::sync::Mutex with tokio::sync::Mutex only if held across .await, or restructure code to drop guard before awaiting. |
9. Constraints
- Forbid unhandled panics: No
.unwrap()in production code. Use?or explicit match/if-let. - Mandatory
// SAFETY:proofs: Unsafe code lacking an invariant proof will be rejected by CI. - Zero Clippy warnings: Code with compiler or clippy warnings fails the conformance gate immediately.
- No speculative dependencies: Only add dependencies approved in the project manifest.
10. Examples
Anti-Pattern: Unchecked Unwrap and Flawed Unsafe
// BAD: Panics on bad input, unaligned raw pointer dereference without safety invariants
pub fn parse_and_read(raw: &str, ptr: *const u32) -> u32 {
let _id: u32 = raw.parse().unwrap(); // PANIC RISK!
unsafe {
*ptr // UB RISK: ptr might be null, unaligned, or dangling!
}
}
Idiomatic Pattern: Type-Driven Safety & Sound Unsafe Boundary
use std::num::ParseIntError;
use std::ptr::NonNull;
use thiserror::Error;
#[derive(Debug, Error)]
pub enum ProcessingError {
#[error("invalid numeric payload: {0}")]
Parse(#[from] ParseIntError),
#[error("null buffer pointer encountered")]
NullBuffer,
#[error("index {index} exceeds buffer bounds {capacity}")]
OutOfBounds { index: usize, capacity: usize },
}
/// A sound, memory-safe wrapper around a contiguous allocated buffer.
pub struct SafeBuffer<T> {
ptr: NonNull<T>,
capacity: usize,
}
impl<T> SafeBuffer<T> {
/// Constructs a safe buffer from a verified non-null pointer and capacity.
///
/// # Safety
/// Caller must guarantee `ptr` points to `capacity` continuously allocated elements of `T`.
pub unsafe fn from_raw_parts(ptr: *mut T, capacity: usize) -> Result<Self, ProcessingError> {
let non_null = NonNull::new(ptr).ok_or(ProcessingError::NullBuffer)?;
Ok(Self { ptr: non_null, capacity })
}
pub fn get(&self, index: usize) -> Result<&T, ProcessingError> {
if index >= self.capacity {
return Err(ProcessingError::OutOfBounds { index, capacity: self.capacity });
}
// SAFETY: index is bounds-checked above, ptr is verified non-null,
// and caller lifetime is bound to &'self.
unsafe {
Ok(&*self.ptr.as_ptr().add(index))
}
}
}
// Send + Sync markers proven safe because T is Send + Sync and access is immutable
unsafe impl<T: Send> Send for SafeBuffer<T> {}
unsafe impl<T: Sync> Sync for SafeBuffer<T> {}
04 同仓库更多 Skills
zoom-reflow
暂无简介
wireframe-styleguide
暂无简介
visual-regression
Pixel-by-pixel snapshot testing, Playwright integration, dynamic content masking, deterministic font rendering, and cross-browser CI gates
ui-implementation
Component-driven UI implementation, multi-state matrix (default, hover, focus-visible, active, disabled, loading, empty, error), DTCG design tokens, responsive layout contracts, and accessibility tree mapping.
tui-editor-engine
Text buffer and editing semantics for a terminal code editor — index conversion, transaction-first editing, multi-cursor invariants, undo grouping, and large-file behaviour.
tree-sitter-context-indexing
暂无简介