mirror of
https://github.com/rustfs/rustfs.git
synced 2026-07-28 09:08:58 +00:00
Zhengchao An
d1db9a10cd
Agent-instruction and architecture docs had drifted from the code: - CLAUDE.md: slim to commands + pointers; fix wrong claim that `make pre-commit` is the full pre-PR gate (that is `make pre-pr`); drop stale pre-#3929 file paths and merged bug narratives - AGENTS.md: drop dead `rust-refactor-helper` skill rule and the hand-maintained (already stale) scoped-AGENTS index; link architecture docs from Sources of Truth - .github/AGENTS.md: replace the outdated copied CI command matrix with a pointer to ci.yml - crates/AGENTS.md: merge duplicated Testing sections - ARCHITECTURE.md: resolve the utils->config contradiction (edges are removed), mark volatile counts as snapshots, fix a bad path - docs/architecture: add README router; move one-shot plans/trackers (rebalance-decommission phases, migration-progress ledger, PR template) to docs/superpowers/plans with archive headers; fix stale source paths in kept inventories (core/sets.rs, core/pools.rs, store/mod.rs, startup_* split from #3671) - docs/operations/tier-ilm-debugging.md: extracted tier debugging playbook with corrected paths - scripts/check_doc_paths.sh: new guard failing pre-commit/pre-pr when instruction/architecture docs reference nonexistent file paths - .claude/skills: add tier-debug and arch-checks repo skills; .gitignore now keeps .claude/skills and docs/operations committable Verification: ./scripts/check_doc_paths.sh, ./scripts/check_architecture_migration_rules.sh (both pass) Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
92 lines
3.9 KiB
Markdown
92 lines
3.9 KiB
Markdown
# RustFS Architecture Evolution
|
|
|
|
This document set tracks the architecture migration from
|
|
[`rustfs/backlog#660`](https://github.com/rustfs/backlog/issues/660).
|
|
|
|
## Baseline
|
|
|
|
- Baseline branch: `upstream/main`
|
|
- Baseline commit: `61f0dfbc40f748be313be84d834d8259cf3e19c9`
|
|
- Baseline title: `fix(ecstore): invalidate wiped disk id cache (#3251)`
|
|
- First migration PR type: `docs-only`
|
|
|
|
## Core Principle
|
|
|
|
Cut wrong dependency directions with directories and contracts first, migrate global
|
|
state in small steps next, and split crates only after boundaries are stable. Storage
|
|
hot-path behavior must not drift during this migration.
|
|
|
|
## Architecture Documents
|
|
|
|
- [`runtime-lifecycle.md`](runtime-lifecycle.md): runtime, AppContext,
|
|
startup/readiness, and shutdown contracts.
|
|
- [`readiness-matrix.md`](readiness-matrix.md): request-surface behavior,
|
|
runtime dependency readiness, probe semantics, and preservation rules.
|
|
- [`s3-tables-support-matrix.md`](s3-tables-support-matrix.md): supported,
|
|
preview, reference-only, and not-claimed S3 Tables and Iceberg REST Catalog
|
|
surfaces.
|
|
- [`storage-control-data-plane.md`](storage-control-data-plane.md): boundaries
|
|
between StorageCore, ECStore, ClusterControlPlane, and BackgroundControllers.
|
|
- [`background-services-inventory.md`](background-services-inventory.md): current
|
|
scanner, heal, lifecycle, replication, config reload, metrics, and shutdown
|
|
surface before BackgroundController work.
|
|
- [`background-controller-contract.md`](background-controller-contract.md):
|
|
desired/current/status/reconcile vocabulary and lifecycle boundaries for
|
|
future read-only BackgroundController work.
|
|
- [`crate-boundaries.md`](crate-boundaries.md): PR types, crate direction,
|
|
compatibility rules, and migration guardrails.
|
|
- [`global-state-crate-split-plan.md`](global-state-crate-split-plan.md): late
|
|
global-state cleanup, runtime-source boundaries, fallback removal rules, and
|
|
crate-split evaluation criteria.
|
|
- [`obs-ecstore-dependency-inventory.md`](obs-ecstore-dependency-inventory.md):
|
|
observability-to-ECStore dependency inventory, classification, and extraction
|
|
guardrails.
|
|
- [`ecstore-config-consumer-inventory.md`](ecstore-config-consumer-inventory.md):
|
|
current `ecstore::config::{Config, KV, KVS}` definitions, consumers,
|
|
migration risks, and do-not-change contract.
|
|
- [`ecstore-api-facade-inventory.md`](ecstore-api-facade-inventory.md): current
|
|
`rustfs_ecstore::api` facade groups, external consumer boundaries, shrink
|
|
rules, and split dependency inventory.
|
|
- [`config-model-boundary-adr.md`](config-model-boundary-adr.md): target crate,
|
|
module path, dependency rules, and verification gates for moving the pure
|
|
server-config model.
|
|
- [`migration-progress.md`](../superpowers/plans/migration-progress.md): historical
|
|
task ledger for the closed migration (execution tracking moved to issue #665).
|
|
- [`compat-cleanup-register.md`](compat-cleanup-register.md): temporary
|
|
compatibility code that must be removed later.
|
|
|
|
## Phase Order
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
G["Phase 0: Baseline and guardrails"]
|
|
CFG["Phase 1a: Config model contract"]
|
|
SEC["Phase 1: Security governance"]
|
|
API["Phase 2: Storage API contracts"]
|
|
RT["Phase 3: Runtime and lifecycle"]
|
|
EC["Phase 4: ECStore internal layout"]
|
|
CP["Phase 5: Cluster control plane"]
|
|
EXT["Phase 6: Extension plane"]
|
|
GS["Phase 7: Global-state reduction"]
|
|
CR["Crate split evaluation"]
|
|
|
|
G --> CFG
|
|
G --> SEC
|
|
G --> API
|
|
G --> RT
|
|
CFG --> EXT
|
|
API --> EC
|
|
RT --> GS
|
|
EC --> CP
|
|
EXT --> CR
|
|
GS --> CR
|
|
```
|
|
|
|
The first implementation sequence is conservative:
|
|
|
|
1. Record baseline and migration context.
|
|
2. Establish PR and compatibility rules.
|
|
3. Add dependency and loss-prevention checks in a separate `ci-gate` PR.
|
|
4. Inventory `ecstore::config::{Config, KV, KVS}` before moving any code.
|
|
5. Decide the config model boundary before extracting or migrating consumers.
|