From eb33e9f2ead9cdf6f27ce7cd7fdca9718bf08fc5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=AE=89=E6=AD=A3=E8=B6=85?= Date: Mon, 22 Jun 2026 00:15:34 +0800 Subject: [PATCH] refactor: prune outer compat signature aliases (#3701) --- docs/architecture/crate-boundaries.md | 4 ++ docs/architecture/migration-progress.md | 47 ++++++++++++++----- rustfs/src/admin/storage_compat.rs | 6 ++- rustfs/src/app/storage_compat.rs | 5 +- rustfs/src/storage/storage_compat.rs | 8 ++-- scripts/check_architecture_migration_rules.sh | 13 +++++ 6 files changed, 65 insertions(+), 18 deletions(-) diff --git a/docs/architecture/crate-boundaries.md b/docs/architecture/crate-boundaries.md index 514ce2ae3..a1a0b4cba 100644 --- a/docs/architecture/crate-boundaries.md +++ b/docs/architecture/crate-boundaries.md @@ -180,6 +180,10 @@ facade aliases must stay anchored on storage-api associated object types and local `StorageError` aliases. They must not reintroduce raw `rustfs_ecstore::api::object::{ObjectInfo,ObjectOptions}` or `rustfs_ecstore::api::error::{Error,Result}` references. +Outer compatibility function signatures must also use local aliases for ECStore +metadata, object-lock, lifecycle journal, monitor, and notification facade +types. The boundary may define the local alias, but call signatures must not +expose the raw ECStore facade path once narrowed. Scanner, notify, observability, and e2e `storage_compat.rs` boundaries must also stay narrow. Scanner must not restore grouped bucket compatibility exports for target, lifecycle, metadata, replication, or versioning modules. Notify diff --git a/docs/architecture/migration-progress.md b/docs/architecture/migration-progress.md index 5e2c9ece2..0275b70bb 100644 --- a/docs/architecture/migration-progress.md +++ b/docs/architecture/migration-progress.md @@ -5,16 +5,17 @@ Status values: `[ ]` not started, `[~]` in progress, `[x]` complete, `[!]` block ## Current Context - Issue: [`rustfs/backlog#660`](https://github.com/rustfs/backlog/issues/660) -- Branch: `overtrue/arch-outer-compat-surface-prune` -- Baseline: completed `C-011/C-012/C-013/API-055/API-059/API-079/API-080/API-081/API-082/API-083/API-084/API-085/API-086/API-087/API-088/API-089`. -- Stacked on: `origin/main` after API-089 merged. +- Branch: `overtrue/arch-outer-compat-common-facade-prune` +- Baseline: completed `C-011/C-012/C-013/API-055/API-059/API-079/API-080/API-081/API-082/API-083/API-084/API-085/API-086/API-087/API-088/API-089/API-090`. +- Stacked on: `origin/main` after API-090 merged. - PR type for this branch: `pure-move` - Runtime behavior changes: none. -- Rust code changes: prune raw ECStore object/error facade aliases from outer - app/admin/storage compatibility boundaries. -- CI/script changes: guard app/admin/storage compatibility boundaries against - restoring raw ECStore object/error facade aliases. -- Docs changes: record the API-090 outer compatibility facade alias cleanup. +- Rust code changes: prune raw ECStore metadata/object-lock/lifecycle/monitor/ + notification facade paths from outer app/admin/storage compatibility + signatures. +- CI/script changes: guard app/admin/storage compatibility signatures against + restoring raw ECStore facade paths for those narrowed types. +- Docs changes: record the API-091 outer compatibility signature alias cleanup. ## Phase 0 Tasks @@ -292,6 +293,20 @@ Status values: `[ ]` not started, `[~]` in progress, `[x]` complete, `[!]` block - Verification: RustFS compile coverage, residual scan, migration guard, formatting, diff hygiene, Rust risk scan, pre-commit quality gate, and three-expert review. +- [x] `API-091` Prune outer compat signature facade paths. + - Completed slice: replace app/admin/storage raw ECStore metadata, + object-lock, lifecycle journal, monitor, and notification facade paths in + compatibility function signatures with local aliases. + - Acceptance: app/admin/storage compatibility function signatures no longer + expose raw ECStore facade paths for `BucketMetadataSys`, + `ObjectLockBlockReason`, lifecycle `Jentry`, bandwidth `Monitor`, or + `NotificationSys`. + - Must preserve: test metadata-system access, object-lock retention checks, + lifecycle tier-delete journal persistence, admin bandwidth monitor access, + and notification-system access. + - Verification: RustFS compile coverage, signature residual scan, migration + guard, formatting, diff hygiene, Rust risk scan, pre-commit quality gate, + and three-expert review. - [x] `G-012` Inventory placement and repair invariants. - Acceptance: [`placement-repair-invariants.md`](placement-repair-invariants.md) records @@ -3325,14 +3340,24 @@ Status values: `[ ]` not started, `[~]` in progress, `[x]` complete, `[!]` block | Expert | Status | Notes | |---|---|---| -| Quality/architecture | passed | API-090 replaces raw ECStore object/error facade aliases in outer app/admin/storage compatibility boundaries with storage-api object aliases and local StorageError aliases. | -| Migration preservation | passed | Lifecycle, object-lock, replication, admin config, and storage S3 error paths keep the same concrete ECStore contracts through narrower local names. | -| Testing/verification | passed | RustFS compile coverage, outer facade alias residual scan, migration guard, formatting, diff hygiene, Rust risk scan, full pre-commit, and three-expert review passed. | +| Quality/architecture | passed | API-091 replaces raw ECStore facade paths in outer app/admin/storage compatibility signatures with local aliases. | +| Migration preservation | passed | Metadata-system, object-lock, lifecycle journal, bandwidth monitor, and notification-system access keep the same ECStore contracts through narrower local names. | +| Testing/verification | passed | RustFS compile coverage, signature residual scan, migration guard, formatting, diff hygiene, Rust risk scan, full pre-commit, and three-expert review passed. | ## Verification Notes Passed before push: +- Issue #660 API-091 current slice: + - `cargo check -p rustfs`: passed. + - `cargo fmt --all --check`: passed. + - `git diff --check`: passed. + - `bash -n scripts/check_architecture_migration_rules.sh`: passed. + - `./scripts/check_architecture_migration_rules.sh`: passed. + - Outer app/admin/storage raw signature facade path residual scan: passed. + - Rust added-line risk scan on changed Rust files and guard script: passed. + - `make pre-commit`: passed. + - Issue #660 API-090 current slice: - `cargo check -p rustfs`: passed. - `cargo fmt --all --check`: passed. diff --git a/rustfs/src/admin/storage_compat.rs b/rustfs/src/admin/storage_compat.rs index 415afe60b..085dfbb15 100644 --- a/rustfs/src/admin/storage_compat.rs +++ b/rustfs/src/admin/storage_compat.rs @@ -24,6 +24,7 @@ pub(crate) type DiskStat = rustfs_ecstore::api::rebalance::DiskStat; pub(crate) type ECStore = rustfs_ecstore::api::storage::ECStore; pub(crate) type EndpointServerPools = rustfs_ecstore::api::layout::EndpointServerPools; pub(crate) type MetricType = rustfs_ecstore::api::metrics::MetricType; +pub(crate) type NotificationSys = rustfs_ecstore::api::notification::NotificationSys; pub(crate) type PeerRestClient = rustfs_ecstore::api::rpc::PeerRestClient; pub(crate) type RebalSaveOpt = rustfs_ecstore::api::rebalance::RebalSaveOpt; pub(crate) type RebalanceCleanupWarnings = rustfs_ecstore::api::rebalance::RebalanceCleanupWarnings; @@ -50,6 +51,7 @@ pub(crate) type RebalanceInfo = rustfs_ecstore::api::rebalance::RebalanceInfo; pub(crate) mod bandwidth { pub(crate) mod monitor { pub(crate) type BandwidthDetails = rustfs_ecstore::api::bucket::bandwidth::monitor::BandwidthDetails; + pub(crate) type Monitor = rustfs_ecstore::api::bucket::bandwidth::monitor::Monitor; } } @@ -309,7 +311,7 @@ pub(crate) async fn load_data_usage_from_backend( rustfs_ecstore::api::data_usage::load_data_usage_from_backend(store).await } -pub(crate) fn get_global_bucket_monitor() -> Option> { +pub(crate) fn get_global_bucket_monitor() -> Option> { rustfs_ecstore::api::global::get_global_bucket_monitor() } @@ -336,7 +338,7 @@ pub(crate) async fn collect_local_metrics( rustfs_ecstore::api::metrics::collect_local_metrics(types, opts).await } -pub(crate) fn get_global_notification_sys() -> Option<&'static rustfs_ecstore::api::notification::NotificationSys> { +pub(crate) fn get_global_notification_sys() -> Option<&'static NotificationSys> { rustfs_ecstore::api::notification::get_global_notification_sys() } diff --git a/rustfs/src/app/storage_compat.rs b/rustfs/src/app/storage_compat.rs index 9d34428c1..ac0c07c60 100644 --- a/rustfs/src/app/storage_compat.rs +++ b/rustfs/src/app/storage_compat.rs @@ -21,6 +21,7 @@ pub(crate) type DynReader = rustfs_ecstore::api::rio::DynReader; pub(crate) type ECStore = rustfs_ecstore::api::storage::ECStore; pub(crate) type EndpointServerPools = rustfs_ecstore::api::layout::EndpointServerPools; pub(crate) type HashReader = rustfs_ecstore::api::rio::HashReader; +pub(crate) type NotificationSys = rustfs_ecstore::api::notification::NotificationSys; pub(crate) type ObjectStoreResolver = dyn Fn() -> Option> + Send + Sync + 'static; pub(crate) type ObjectInfo = ::ObjectInfo; pub(crate) type ObjectOptions = ::ObjectOptions; @@ -162,7 +163,7 @@ pub(crate) mod lifecycle { pub(crate) async fn persist_tier_delete_journal_entry( api: Arc, - je: &rustfs_ecstore::api::bucket::lifecycle::tier_sweeper::Jentry, + je: &super::tier_sweeper::Jentry, ) -> std::io::Result<()> { rustfs_ecstore::api::bucket::lifecycle::tier_delete_journal::persist_tier_delete_journal_entry(api, je).await } @@ -515,7 +516,7 @@ pub(crate) fn set_object_store_resolver(resolver: Arc) -> b rustfs_ecstore::api::global::set_object_store_resolver(resolver) } -pub(crate) fn get_global_notification_sys() -> Option<&'static rustfs_ecstore::api::notification::NotificationSys> { +pub(crate) fn get_global_notification_sys() -> Option<&'static NotificationSys> { rustfs_ecstore::api::notification::get_global_notification_sys() } diff --git a/rustfs/src/storage/storage_compat.rs b/rustfs/src/storage/storage_compat.rs index c109e34ff..b34d8ca9b 100644 --- a/rustfs/src/storage/storage_compat.rs +++ b/rustfs/src/storage/storage_compat.rs @@ -29,6 +29,8 @@ pub(crate) const SERVICE_SIGNAL_RELOAD_DYNAMIC: u64 = rustfs_ecstore::api::rpc:: pub(crate) const STORAGE_CLASS_SUB_SYS: &str = rustfs_ecstore::api::config::com::STORAGE_CLASS_SUB_SYS; pub(crate) type BucketMetadata = rustfs_ecstore::api::bucket::metadata::BucketMetadata; +#[cfg(test)] +pub(crate) type BucketMetadataSys = rustfs_ecstore::api::bucket::metadata_sys::BucketMetadataSys; pub(crate) type BucketVersioningSys = rustfs_ecstore::api::bucket::versioning_sys::BucketVersioningSys; pub(crate) type CollectMetricsOpts = rustfs_ecstore::api::metrics::CollectMetricsOpts; pub(crate) type DeleteOptions = rustfs_ecstore::api::disk::DeleteOptions; @@ -39,6 +41,7 @@ pub(crate) type ECStore = rustfs_ecstore::api::storage::ECStore; pub(crate) type FileInfoVersions = rustfs_ecstore::api::disk::FileInfoVersions; pub(crate) type LocalPeerS3Client = rustfs_ecstore::api::rpc::LocalPeerS3Client; pub(crate) type MetricType = rustfs_ecstore::api::metrics::MetricType; +pub(crate) type ObjectLockBlockReason = rustfs_ecstore::api::bucket::object_lock::objectlock_sys::ObjectLockBlockReason; pub(crate) type PolicySys = rustfs_ecstore::api::bucket::policy_sys::PolicySys; pub(crate) type ReadMultipleReq = rustfs_ecstore::api::disk::ReadMultipleReq; pub(crate) type ReadMultipleResp = rustfs_ecstore::api::disk::ReadMultipleResp; @@ -66,8 +69,7 @@ pub(crate) fn bucket_metadata_sys_initialized() -> bool { } #[cfg(test)] -pub(crate) fn get_global_bucket_metadata_sys() --> Option>> { +pub(crate) fn get_global_bucket_metadata_sys() -> Option>> { rustfs_ecstore::api::bucket::metadata_sys::get_global_bucket_metadata_sys() } @@ -152,7 +154,7 @@ pub(crate) fn check_retention_for_modification( new_mode: Option<&str>, new_retain_until: Option, bypass_governance: bool, -) -> Option { +) -> Option { rustfs_ecstore::api::bucket::object_lock::objectlock_sys::check_retention_for_modification( user_defined, new_mode, diff --git a/scripts/check_architecture_migration_rules.sh b/scripts/check_architecture_migration_rules.sh index 6d1c5e60c..973013a5c 100755 --- a/scripts/check_architecture_migration_rules.sh +++ b/scripts/check_architecture_migration_rules.sh @@ -87,6 +87,7 @@ RUSTFS_STORAGE_OWNER_COMPAT_REEXPORT_HITS_FILE="${TMP_DIR}/rustfs_storage_owner_ RUSTFS_ADMIN_BUCKET_STORAGE_COMPAT_MODULE_HITS_FILE="${TMP_DIR}/rustfs_admin_bucket_storage_compat_module_hits.txt" RUSTFS_APP_BUCKET_STORAGE_COMPAT_MODULE_HITS_FILE="${TMP_DIR}/rustfs_app_bucket_storage_compat_module_hits.txt" RUSTFS_OUTER_COMPAT_FACADE_ALIAS_HITS_FILE="${TMP_DIR}/rustfs_outer_compat_facade_alias_hits.txt" +RUSTFS_OUTER_COMPAT_SIGNATURE_ALIAS_HITS_FILE="${TMP_DIR}/rustfs_outer_compat_signature_alias_hits.txt" SCANNER_BUCKET_STORAGE_COMPAT_MODULE_HITS_FILE="${TMP_DIR}/scanner_bucket_storage_compat_module_hits.txt" NOTIFY_STORAGE_COMPAT_MODULE_HITS_FILE="${TMP_DIR}/notify_storage_compat_module_hits.txt" OBS_STORAGE_COMPAT_PASSTHROUGH_HITS_FILE="${TMP_DIR}/obs_storage_compat_passthrough_hits.txt" @@ -892,6 +893,18 @@ if [[ -s "$RUSTFS_OUTER_COMPAT_FACADE_ALIAS_HITS_FILE" ]]; then report_failure "RustFS outer storage compatibility must use storage-api object aliases and local StorageError aliases instead of raw ECStore object/error facade aliases: $(paste -sd '; ' "$RUSTFS_OUTER_COMPAT_FACADE_ALIAS_HITS_FILE")" fi +( + cd "$ROOT_DIR" + rg -n --no-heading '(fn .*rustfs_ecstore::api::(bucket::metadata_sys::BucketMetadataSys|bucket::object_lock::objectlock_sys::ObjectLockBlockReason|bucket::lifecycle::tier_sweeper::Jentry|bucket::bandwidth::monitor::Monitor|notification::NotificationSys)|-> .*rustfs_ecstore::api::(bucket::metadata_sys::BucketMetadataSys|bucket::object_lock::objectlock_sys::ObjectLockBlockReason|bucket::lifecycle::tier_sweeper::Jentry|bucket::bandwidth::monitor::Monitor|notification::NotificationSys)|: &?rustfs_ecstore::api::(bucket::metadata_sys::BucketMetadataSys|bucket::object_lock::objectlock_sys::ObjectLockBlockReason|bucket::lifecycle::tier_sweeper::Jentry|bucket::bandwidth::monitor::Monitor|notification::NotificationSys))' \ + rustfs/src/app/storage_compat.rs \ + rustfs/src/admin/storage_compat.rs \ + rustfs/src/storage/storage_compat.rs || true +) >"$RUSTFS_OUTER_COMPAT_SIGNATURE_ALIAS_HITS_FILE" + +if [[ -s "$RUSTFS_OUTER_COMPAT_SIGNATURE_ALIAS_HITS_FILE" ]]; then + report_failure "RustFS outer storage compatibility signatures must use local aliases for metadata, object-lock, lifecycle, monitor, and notification facade types: $(paste -sd '; ' "$RUSTFS_OUTER_COMPAT_SIGNATURE_ALIAS_HITS_FILE")" +fi + ( cd "$ROOT_DIR" rg -n --no-heading 'pub\(crate\)\s+use rustfs_ecstore::api::bucket::\{[^}]*\b(?:bucket_target_sys|lifecycle|metadata_sys|replication|versioning|versioning_sys)\b[^}]*\}\s*;' \