mirror of
https://github.com/rustfs/rustfs.git
synced 2026-07-28 17:18:58 +00:00
houseme
ed73952cb6
* docs(object-capacity): add localized crate docs * fix(ecstore): improve quorum and transport diagnostics * perf(ecstore): add safe single-block write fast path * refactor(ecstore): collapse layered small write paths * chore(docs): keep issue 662 design note tracked * fix(docs): restore issue 662 design note * chore(docs): keep issue 662 design local only * feat(obs): add internode reliability metrics and dashboard * feat(obs): extend internode diagnostics and service logging * fix(docs): use AGENTS guide filename * perf(ecstore): reuse owned buffer in small encode * fix(ecstore): tighten small write diagnostics --------- Co-authored-by: cxymds <Cxymds@qq.com>
88 lines
3.5 KiB
Markdown
88 lines
3.5 KiB
Markdown
# rustfs-object-capacity Agent Guide
|
|
|
|
This document is a lightweight maintainer-oriented guide for collaborators working in `crates/object-capacity`.
|
|
|
|
## Purpose
|
|
|
|
`rustfs-object-capacity` is responsible for estimating and refreshing RustFS object-data usage, not general filesystem capacity. Changes in this crate can affect:
|
|
|
|
- admin `used_capacity` responses
|
|
- refresh latency and background work
|
|
- dirty-disk propagation after writes, heal, and data movement
|
|
- capacity-related metrics and operational observability
|
|
|
|
Keep changes narrow and source-driven.
|
|
|
|
## Source of Truth
|
|
|
|
Before changing behavior, read these files first:
|
|
|
|
- `src/scan.rs`
|
|
- `src/capacity_manager.rs`
|
|
- `src/capacity_scope.rs`
|
|
- `src/types.rs`
|
|
- `../../rustfs/src/capacity/service.rs`
|
|
- `../config/src/constants/capacity.rs`
|
|
|
|
Do not treat shell scripts or old docs as the authoritative behavior definition when the Rust code says otherwise.
|
|
|
|
## Change Priorities
|
|
|
|
Prefer the following order:
|
|
|
|
1. correctness of returned capacity values
|
|
2. safety of degraded behavior under timeout, stall, or partial failure
|
|
3. consistency of dirty-subset refresh and per-disk cache state
|
|
4. bounded scan cost and runtime overhead
|
|
5. clarity of metrics and logs
|
|
|
|
## Important Behavioral Constraints
|
|
|
|
- This crate intentionally prefers a usable degraded result over hard failure when partial progress is available.
|
|
- Dirty-subset refresh is safe only after a complete per-disk cache has been established.
|
|
- Subset refresh failures with partial errors must not silently corrupt aggregate cache state.
|
|
- Environment-derived configuration is cached behind `OnceLock` in non-test builds, so runtime env changes usually require a restart.
|
|
- Symlink following is disabled by default for safety and determinism.
|
|
- Multi-disk scans are concurrent, so avoid changes that introduce hidden shared-state coupling.
|
|
|
|
## Editing Guidance
|
|
|
|
- Keep scan-path changes local and easy to audit.
|
|
- Avoid refactoring the control flow unless it is necessary for correctness.
|
|
- Preserve the current exact-vs-estimated semantics unless the task explicitly changes them.
|
|
- Reuse existing configuration constants from `rustfs-config` instead of introducing duplicate literals.
|
|
- Treat metric names and labels as compatibility-sensitive unless the task explicitly allows a metric contract change.
|
|
|
|
## Validation Guidance
|
|
|
|
For code changes, prefer focused verification close to the changed behavior:
|
|
|
|
- scan correctness tests in `src/scan.rs`
|
|
- manager/refresh-state tests in `src/capacity_manager.rs`
|
|
- scope propagation tests in `src/capacity_scope.rs`
|
|
- integration behavior in `../../rustfs/src/capacity/service.rs` or related app tests when needed
|
|
|
|
Useful commands:
|
|
|
|
```bash
|
|
cargo test -p rustfs-object-capacity
|
|
cargo test -p rustfs-object-capacity --doc
|
|
cargo bench -p rustfs-object-capacity --bench capacity_scan
|
|
```
|
|
|
|
If the change is documentation-only, lightweight verification is enough.
|
|
|
|
## Documentation Expectations
|
|
|
|
- Keep `README.md` in English.
|
|
- Keep `README_ZH.md` aligned when behavior or public usage changes.
|
|
- Prefer describing real behavior from code instead of aspirational architecture.
|
|
|
|
## Common Pitfalls
|
|
|
|
- Assuming `used_capacity` means total disk usage instead of object-data usage.
|
|
- Forgetting that the initial full refresh is required before safe dirty-subset refresh.
|
|
- Forgetting that partial errors can still produce a returned result.
|
|
- Overlooking the fallback path that stores externally supplied disk-used capacity as `DataSource::Fallback`.
|
|
- Changing timeout or sampling behavior without reviewing the observable effects on degraded results and metrics.
|