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-admin-observability-storage-reads
• Baseline: origin/main at 8ae0cad6671562c0fffe56a7f288cd97fb87309d
• PR type for this branch: consumer-migration
• Runtime behavior changes: none.
• Rust code changes: migrate grouped observability, RPC health, server-info, realtime metrics, and notification read-side consumers from old StorageAPI::{backend_info, storage_info, local_storage_info} trait imports to the inventory-facing StorageAdminApi contract.
• CI/script changes: none.
• Docs changes: record API-007 expanded read-side consumer-migration 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.
  • Current branch slice: migrate grouped read-side observability and health consumers: obs cluster/disk/config/erasure-set metrics, RPC local storage info response construction, ECStore server-info local disk/backend reads, realtime disk metrics, and notification storage-info aggregation.
  • Acceptance: these consumers no longer import old StorageAPI only to read admin storage information; peer RPC client calls remain unchanged.
  • Must preserve: old StorageAPI trait shape, StorageAPI::get_disks behavior, obs metric values, RPC msgpack map encoding and response shape, server-info shape, realtime metric shape, notification peer aggregation/cache fallback, heal/scanner consumers, object paths, replication/config persistence, and storage hot paths.
  • Risk defense: group only read-side callers that delegate to the existing ECStore admin info implementation; do not migrate object APIs, scanner, heal, replication, config persistence, or storage implementation internals 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 read-side consumer migration and the rustfs-obs contract dependency, with no object, scanner, heal, replication, config persistence, or storage hot-path scope creep.
Migration preservation	pass	Confirmed obs metric calculations, RPC response encoding, server-info shape, realtime disk metric shape, notification peer aggregation/timeout/cache fallback, and peer REST calls remain unchanged.
Testing/verification	pass	Confirmed focused tests, joint compile check, migration guards, diff hygiene, and added-line Rust quality scan are sufficient for this equivalent trait-entry migration while skipping full pre-commit under the current instruction.

Verification Notes

Passed:

• cargo fmt --all.
• cargo fmt --all --check.
• cargo check -p rustfs-storage-api -p rustfs-ecstore -p rustfs-obs -p rustfs --lib.
• cargo test -p rustfs-obs stats_collector --lib; 14 passed.
• cargo test -p rustfs-ecstore admin_server_info --lib; 1 passed.
• cargo test -p rustfs-ecstore metrics_realtime --lib; 5 passed.
• cargo test -p rustfs-ecstore notification_sys --lib; 17 passed.
• cargo test -p rustfs local_storage_info_rpc_payload_uses_msgpack_map_encoding --lib; 1 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:

• This branch adds a direct rustfs-obs dependency on the existing rustfs-storage-api workspace contract crate.
• 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 and pre-existing admin_server_info.rs println/eprintln; the added-line scan found no new risky code patterns.
• No ECStore handler implementation, old StorageAPI trait, peer RPC client, heal/scanner consumer, object path, replication/config persistence path, or storage hot path is changed.
• No temporary compatibility shim was added.

Handoff Notes

• Keep this API-007 slice as a grouped observability/health/server-info read-side consumer-migration PR.
• Do not migrate object APIs, scanner, heal, replication, config persistence, or storage hot-path consumers in this PR.
• Do not remove or route around StorageAPI::get_disks in this PR.
• 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.