rustfs/docs/architecture/migration-progress.md

Architecture Migration Progress

Status values: [ ] not started, [~] in progress, [x] complete, [!] blocked.

Current Context

• Issue: rustfs/backlog#660
• Branch: overtrue/arch-storage-admin-read-cleanup
• Baseline: origin/main at 94c53af264b8d011b19b0b35eed5990a21592d70
• PR type for this branch: consumer-migration
• Runtime behavior changes: none.
• Rust code changes: route ECStore internal admin-read aggregation through crate-internal Sets/SetDisks snapshot helpers and the inventory-facing StorageAdminApi contract while preserving the old StorageAPI compatibility surface.
• CI/script changes: none.
• Docs changes: record API-007 internal admin-read cleanup context, verification evidence, and expert review outcomes.

Phase 0 Tasks

• G-001 Refresh main and record baseline.
  • Acceptance: baseline commit, title, and branch are recorded.
  • Verification: git fetch upstream main --prune; git rev-parse upstream/main.
• G-002 Create migration tracking checklist.
  • Acceptance: this file records task state, context, verification, and handoff.
• G-003 Classify PR types.
  • Acceptance: crate-boundaries.md lists exactly one allowed PR type per PR.
• G-004 Define re-export and wrapper policy.
  • Acceptance: temporary compatibility code must use RUSTFS_COMPAT_TODO.
• G-005 Add dependency direction guard.
  • Acceptance: ./scripts/check_layer_dependencies.sh passes on current upstream/main while still rejecting new unaccepted layer dependencies.
• [~] G-006 Create migration loss-prevention checks.
  • Current branch: add a mechanical admin route matrix guard from admin-route-action-snapshot.md and rustfs/src/admin/route_registration_test.rs.
  • Remaining follow-up: add checks for public re-export and storage trait coverage before pure moves.
• G-007 Create startup timeline table.
  • Acceptance: startup-timeline.md records current binary startup order, side effects, fatal boundaries, and readiness stages.
• G-008 Capture admin route-action snapshot.
  • Acceptance: admin-route-action-snapshot.md records current route families, handler ownership, authorization actions, public exceptions, table-catalog routes, and /minio/admin compatibility alias behavior.
• G-009 Enforce pre-push three-expert review.
  • Acceptance: crate-boundaries.md requires quality/architecture, migration-preservation, and testing/verification review before push.
• G-010 Inventory ecstore::config::{Config, KV, KVS} consumers.
  • Acceptance: ecstore-config-consumer-inventory.md records the current model definitions, global accessors, persistence helpers, consumer groups, migration risks, and do-not-change contract.
• TEST-PRTYPE-001 Check PR type enum consistency.
  • Acceptance: ./scripts/check_architecture_migration_rules.sh parses the allowed PR types from crate-boundaries.md and fails when ARCHITECTURE.md or architecture docs reference an unknown PR type.
• COMPAT-REG-001 Check temporary compatibility cleanup consistency.
  • Acceptance: ./scripts/check_architecture_migration_rules.sh fails when a source RUSTFS_COMPAT_TODO(<task-id>) marker lacks a cleanup-register entry, when a register entry lacks a source marker, or when a source marker omits a removal condition.

Phase 1a Config Model Tasks

• CFG-001 Inventory ecstore::config::{Config, KV, KVS} consumers.
  • Acceptance: ecstore-config-consumer-inventory.md records the current definitions, persistence helpers, global accessors, consumer groups, migration risks, and do-not-change contract.
• CFG-002 Decide model boundary.
  • Acceptance: config-model-boundary-adr.md records rustfs-config as the target package, server_config as the future model module, allowed dependencies, forbidden dependencies, preserved shape, and extraction verification gates.
• CFG-003 Move pure model definitions.
  • Next boundary: move only Config, KV, KVS, and default-registration surface into rustfs-config; keep persistence helpers and global server-config state in ecstore.
• CFG-004 Keep old ecstore::config::* compatibility path.
  • Required compatibility: source must contain RUSTFS_COMPAT_TODO(CFG-004) and a matching cleanup-register entry.

Phase 1 Security Governance Tasks

• S-001 Add crates/security-governance.
  • Acceptance: the crate is a workspace member and has no dependency on rustfs, ecstore, admin handlers, Axum, or runtime state.
  • Verification: cargo check -p rustfs-security-governance.
• S-002 Add admin route matrix core types.
  • Acceptance: AdminRouteSpec, AdminRouteAccess, AdminActionRef, PublicRouteKind, RouteRiskLevel, and validation errors model route governance metadata without registering routes or enforcing auth.
  • Verification: cargo test -p rustfs-security-governance.
• S-003 Add redaction contract types.
  • Acceptance: RedactionRule, RedactionLevel, and validation errors model sensitive field handling without logging, masking, or runtime integration.
  • Verification: cargo test -p rustfs-security-governance.
• S-004 Add serde policy marker types.
  • Acceptance: SerdePolicy, SerdePolicyKind, UnknownFieldPolicy, and validation errors model strict ingress and compatibility serde contracts without changing deserialization behavior.
  • Verification: cargo test -p rustfs-security-governance.
• S-005 Add supply-chain policy contract types.
  • Acceptance: ArtifactIntegrityPolicy, ArtifactSourceKind, and validation errors model digest, signature, and provenance requirements without changing release or CI behavior.
  • Verification: cargo test -p rustfs-security-governance.
• S-006 Add rustfs/src/admin/route_policy.rs backed by these contract types, without changing route registration or auth behavior.
  • Acceptance: direct AdminRouteSpec entries cover routes with a single stable admin policy action, deferred inventory records routes that need richer contract support, and tests prove the combined inventory covers every registered admin route.
• S-011 Add KMS action taxonomy.
  • Acceptance: KmsAction can parse and serialize dedicated configure, service-control, clear-cache, generate-data-key, delete, rotate, list, and describe actions; wildcard matching still works.
  • Verification: cargo test -p rustfs-policy action --no-fail-fast.
• S-012 Migrate KMS handlers to dedicated actions.
  • Acceptance: KMS data-key, delete/cancel-delete, cache, configure, service-control, list, and describe handlers use dedicated kms:* actions.
  • Compatibility: legacy KMS create/status admin actions are retained only as temporary compatibility paths and registered in compat-cleanup-register.md.
  • Verification: focused handler and route policy tests, migration rules, formatting, and make pre-commit.
• S-013 Apply KMS redaction.
  • Acceptance: KMS Debug output and admin status response summaries contain no Vault token, AppRole secret ID, or local master key values.
  • Must preserve: internal KMS config values remain available to runtime code and persisted config serialization still writes the original secret values.
  • Verification: focused KMS redaction/status tests, full KMS tests, migration guards, Rust quality scan, clippy, and make pre-commit passed.
• KMSD-001 Inventory KMS development defaults.
  • Acceptance: kms-development-defaults-inventory.md records Local and Vault defaults for missing master keys, temp key dirs, HTTP Vault addresses, default dev-token credentials, and skip-TLS behavior.
  • Must preserve: no KMS runtime behavior, config serialization, authorization, startup order, storage path, or crate boundary changes.
  • Verification: docs diff review, migration guards, metrics reference guard, and git diff --check.

Phase 2 Storage API Tasks

• API-001 Add crates/storage-api.
  • Acceptance: rustfs-storage-api is a workspace member and remains a dependency-free contract crate.
  • Verification: cargo check -p rustfs-storage-api.
• API-002 Move public storage error/result contracts.
  • Current PR: rustfs/rustfs#3313 merged.
  • Completed slice: add public StorageErrorCode and StorageResult contracts in rustfs-storage-api, then make ECStore StorageError::to_u32/from_u32 consume the shared code table.
  • Deferred: keep the full ECStore StorageError enum and ECStore-specific conversions in rustfs-ecstore until the DiskError, filemeta, lock, and std::io::Error downcast boundary is proven safe.
  • Acceptance: storage-api contract tests pass, ECStore compatibility tests prove numeric codes match the new contract, and cargo check -p rustfs-storage-api -p rustfs-ecstore passes.
  • Must preserve: storage error display, conversions, object error mapping, quorum classification, and reserved code gaps 0x2B/0x2C.
  • Risk defense: no storage hot-path enum move in this PR; only numeric code mapping uses the new contract.
• API-003 Move DTOs.
  • Current PR: rustfs/rustfs#3314 merged.
  • Completed slice: move the pure bucket/options DTO subset: MakeBucketOptions, SRBucketDeleteOp, DeleteBucketOptions, BucketOptions, and BucketInfo.
  • Acceptance: rustfs-storage-api exports these DTOs, ECStore re-exports them from the old ecstore::store_api path, and compatibility cleanup is registered with RUSTFS_COMPAT_TODO(API-003).
  • Must preserve: no ObjectOptions, ObjectInfo, reader, compression, encryption, filemeta conversion, multipart conversion, route, storage, or runtime behavior changes in this PR.
• API-006 Add disk inventory/admin trait.
  • Current PR: rustfs/rustfs#3330 merged.
  • Completed slice: add StorageAdminApi and DiskSetSelector to rustfs-storage-api.
  • Acceptance: StorageAdminApi exposes backend info, global storage info, local storage info, disk-set inventory, and drive-count surfaces without depending on ECStore implementation types.
  • Must preserve: no StorageAPI::get_disks removal, no ECStore implementation change, no admin/readiness/capacity behavior change.
  • Risk defense: use associated types for backend/storage/disk DTOs so this contract slice does not pull rustfs-madmin or rustfs-ecstore into rustfs-storage-api.
  • Verification: focused storage-api tests, dependency tree, migration guards, formatting, and diff hygiene.
• [~] API-007 Dual-route get_disks consumers.
  • Completed first slice: rustfs/rustfs#3331 bound ECStore to StorageAdminApi while keeping all consumers unchanged.
  • Completed second slice: rustfs/rustfs#3332 migrated the admin storage-class config drive-count consumer to StorageAdminApi::set_drive_counts.
  • Completed third slice: rustfs/rustfs#3333 migrated DefaultAdminUsecase storage-info reads to StorageAdminApi::storage_info.
  • Completed fourth slice: rustfs/rustfs#3334 migrated account-info backend_info, rebalance status storage_info, and runtime readiness storage_info.
  • Completed fifth slice: rustfs/rustfs#3335 migrated grouped observability, RPC health, server-info, realtime metrics, and notification read-side consumers.
  • Current branch slice: add crate-internal admin snapshot helpers for Sets/SetDisks, then migrate ECStore internal decommission space, local-storage-info, backend-info, drive-count, and disk-inventory admin handlers away from old StorageAPI method calls.
  • Acceptance: ECStore internal admin-read aggregation no longer relies on old StorageAPI method calls where crate-internal helpers or StorageAdminApi already represent the same read-only contract.
  • Must preserve: old StorageAPI trait shape, StorageAPI::get_disks behavior, storage-info disk aggregation, local-only disk filtering, decommission pool space calculation, storage-info deduplication, backend info construction, object/rebalance selection paths, scanner/heal consumers, object paths, replication/config persistence, and storage hot paths.
  • Risk defense: keep the old trait implementation as a delegating compatibility surface, avoid implementing the full admin contract for partial internal types, and do not migrate object APIs, scanner, heal, replication, config persistence, or storage implementation hot paths in this PR.

Phase 8 Background Controller Tasks

• BGC-001 Inventory background services.
  • Acceptance: background-services-inventory.md records scanner, heal, lifecycle, replication, config reload, metrics, shutdown, cancellation, and side-effect surfaces before controller work.
  • Must preserve: no code behavior change and no new controller contract in this PR.
  • Verification: docs-only architecture checks and diff hygiene.
• BGC-002 Define minimal controller contract.
  • Acceptance: background-controller-contract.md defines desired/current/status/reconcile vocabulary, status state semantics, service boundaries, and side-effect rules without starting workers or changing scheduling.
  • Must preserve: no Rust trait, scheduler, service registry, worker start/stop path, storage write, readiness change, peer signal, or runtime behavior change.
  • Verification: docs-only architecture checks and diff hygiene.

Next PRs

1. consumer-migration: migrate the remaining readiness/admin/capacity consumers to the inventory-facing admin contract one group at a time.
2. dependency-migration: remove duplicate old-path admin surfaces only after consumer migration proves equivalent behavior.
3. api-extraction: move only the pure server-config model into rustfs-config as CFG-003.
4. api-extraction: keep the old rustfs_ecstore::config::* path with RUSTFS_COMPAT_TODO(CFG-004) and cleanup-register coverage.
5. consumer-migration: migrate external consumers one group at a time only after the model path and compatibility shim are stable.
6. security-change: make Local KMS unsafe defaults explicit development opt-ins or production failures in KMSD-002.
7. security-change: make Vault unsafe defaults explicit development opt-ins or production failures in KMSD-003.

Pre-Push Review Log

Expert	Status	Notes
Quality/architecture	pass	Confirmed the diff stays limited to ECStore internal admin-read cleanup plus migration notes; helper visibility and naming are scoped, and the Handoff Notes correctly exclude object/hot-path get_disks consumers.
Migration preservation	pass	Confirmed old StorageAPI shape remains, Sets/SetDisks helpers preserve previous aggregation/filtering/get-disks logic, and decommission/local-info/admin inventory call sites only change entry point.
Testing/verification	pass	Confirmed focused ECStore checks, migration guards, diff hygiene, and added-line Rust quality scan are sufficient for this equivalent internal call-path cleanup while skipping full pre-commit under the current instruction.

Verification Notes

Passed:

• cargo fmt --all.
• cargo fmt --all --check.
• cargo check -p rustfs-ecstore.
• cargo test -p rustfs-ecstore store::rebalance --lib; 19 passed.
• cargo test -p rustfs-ecstore pools --lib; 141 passed.
• cargo test -p rustfs-ecstore set_disk --lib; 86 passed.
• ./scripts/check_architecture_migration_rules.sh.
• ./scripts/check_layer_dependencies.sh.
• ./scripts/check_metrics_migration_refs.sh.
• ./scripts/check_unsafe_code_allowances.sh.
• git diff --check.
• Rust code-quality scan on changed .rs files, plus added-line scan for unwrap/expect, numeric casts, Result<_, String>, Box<dyn Error>, println/eprintln, and Ordering::Relaxed.

Notes:

• Full pre-commit was intentionally skipped because the focused tests and guards above passed, per the current migration instruction to increase PR granularity.
• The broad changed-file quality scan reports pre-existing test unwrap/expect plus pre-existing casts and relaxed atomics in touched ECStore files; the added-line scan found no new risky code patterns.
• Old StorageAPI trait shape and implementations remain in place; Sets and SetDisks delegate the admin-read subset to crate-internal helpers.
• Object/rebalance selection paths, scanner/heal consumers, object APIs, replication/config persistence paths, and storage hot paths are unchanged.
• No temporary compatibility shim was added.

Handoff Notes

• Keep this API-007 slice as an ECStore-internal admin-read cleanup consumer-migration PR.
• Do not migrate object APIs, scanner, heal, replication, config persistence, or storage hot-path consumers in this PR.
• Do not remove StorageAPI::get_disks or route object/hot-path consumers around it in this PR; only the ECStore internal admin disk-inventory handler is in scope.
• Do not make the old StorageAPI trait inherit StorageAdminApi in this PR.
• Do not add temporary compatibility code unless a matching RUSTFS_COMPAT_TODO(<task-id>) marker and cleanup-register entry are added.