mirror of
https://github.com/rustfs/rustfs.git
synced 2026-08-05 12:57:42 +00:00
安正超
b5e565c0ce
* docs: update security advisory lessons * chore(agents): add Rust code quality rules and skill Add rules derived from full-project code review (48 findings across 7 dimensions) to prevent recurring issues in agent-generated code. AGENTS.md changes: - crates/AGENTS.md: error type design, concurrency, recursion safety, type casting, test quality rules - root AGENTS.md: serde safety, naming conventions - crates/ecstore/AGENTS.md: allocation discipline, lock ordering, recursion safety, dead code policy - crates/notify/AGENTS.md: lock ordering for runtime_view/facade Skill changes: - code-change-verification: add Rust-specific checks (unwrap, as cast, clone, lock order, recursion, error types, test assertions) - security-advisory-lessons: add serde deserialization safety pattern - NEW rust-code-quality: automated scan + manual review checklist
53 lines
2.2 KiB
Markdown
53 lines
2.2 KiB
Markdown
# ECStore Crate Instructions
|
|
|
|
Applies to `crates/ecstore/`.
|
|
|
|
## Data Durability and Integrity
|
|
|
|
- Do not weaken quorum checks, bitrot checks, or metadata validation paths.
|
|
- Treat any change affecting read/write/repair correctness as high risk and test accordingly.
|
|
- Prefer explicit failure over silent data corruption or implicit success.
|
|
|
|
## Performance-Critical Paths
|
|
|
|
- Be careful with allocations and locking in hot paths.
|
|
- Keep network and disk operations async-friendly; avoid introducing unnecessary blocking.
|
|
- Benchmark-sensitive changes should include measurable rationale.
|
|
|
|
## Allocation Discipline in Hot Paths
|
|
|
|
- Do not implement `Clone` on structs with >5 heap-allocated fields without considering `Arc` for heavy fields.
|
|
- Before cloning a struct in a loop or per-request path, check if a reference or `Cow` would suffice.
|
|
- When a struct contains a large buffer (e.g., erasure coding block), wrap it in `Arc` and pass by reference rather than cloning.
|
|
- Use `&str` and `Cow<str>` instead of `String` for temporary computations (header parsing, signature building, path manipulation).
|
|
- Use `HashMap::with_capacity()` / `Vec::with_capacity()` when the size is known or estimable.
|
|
|
|
## Lock Ordering
|
|
|
|
- When a function acquires multiple locks, document the acquisition order in a comment.
|
|
- Never acquire the same set of locks in different orders across code paths — this is a deadlock.
|
|
- Prefer `compare_exchange` loops over load-then-store for concurrent counters.
|
|
|
|
## Recursion Safety
|
|
|
|
- Recursive tree traversals (cache trees, directory walks) must have a depth limit or use iterative traversal with an explicit `Vec` stack.
|
|
- `flatten()`, `delete_recursive()`, `copy_with_children()`, `total_children_rec()`, `mark()` — all must handle deep or corrupted trees safely.
|
|
|
|
## Dead Code
|
|
|
|
- Do not add `#![allow(dead_code)]` at the crate root. If code is unused, remove it or gate it behind a feature flag.
|
|
- Each `#[allow(dead_code)]` annotation must have a comment explaining why the code is kept.
|
|
|
|
## Cross-Module Coordination
|
|
|
|
- Validate behavior impacts on:
|
|
- `rustfs/src/storage/`
|
|
- `crates/filemeta/`
|
|
- `crates/heal/`
|
|
- `crates/checksums/`
|
|
|
|
## Suggested Validation
|
|
|
|
- `cargo test -p rustfs-ecstore`
|
|
- Full gate before commit: `make pre-commit`
|