From 89552e1df0c585d27a14003787121db350819715 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 09:17:11 +0800 Subject: [PATCH] refactor: guard root compat facade aliases (#3714) --- docs/architecture/migration-progress.md | 47 ++++++++++++++----- rustfs/src/storage/s3_api/storage_compat.rs | 4 +- scripts/check_architecture_migration_rules.sh | 14 ++++++ 3 files changed, 53 insertions(+), 12 deletions(-) diff --git a/docs/architecture/migration-progress.md b/docs/architecture/migration-progress.md index a38709655..163184148 100644 --- a/docs/architecture/migration-progress.md +++ b/docs/architecture/migration-progress.md @@ -5,16 +5,16 @@ 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-remaining-local-compat-exports` -- 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/API-091/API-092/API-093/API-094/API-095/API-096/API-097/API-098/API-099/API-100/API-101/API-102/API-103/API-104`. -- Based on: `overtrue/arch-local-compat-explicit-exports` after the API-103 slice. +- Branch: `overtrue/arch-root-compat-local-facade-aliases` +- 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/API-091/API-092/API-093/API-094/API-095/API-096/API-097/API-098/API-099/API-100/API-101/API-102/API-103/API-104/API-105`. +- Based on: `overtrue/arch-remaining-local-compat-exports` after the API-104 slice. - PR type for this branch: `pure-move` - Runtime behavior changes: none. -- Rust code changes: narrow remaining local compatibility boundaries from glob - re-exports to explicit re-exports. -- CI/script changes: guard all narrowed local compatibility boundaries against - restoring glob re-exports. -- Docs changes: record the API-104 remaining local compatibility export cleanup. +- Rust code changes: route the S3 API storage compatibility ETag helper through + a local ECStore client module alias. +- CI/script changes: guard all storage compatibility boundaries against + scattered raw ECStore facade paths outside local `ecstore_*` module aliases. +- Docs changes: record the API-105 root compatibility facade alias cleanup. ## Phase 0 Tasks @@ -490,6 +490,19 @@ Status values: `[ ]` not started, `[~]` in progress, `[x]` complete, `[!]` block compatibility glob-export scan, migration and layer guards, formatting, diff hygiene, Rust risk scan, pre-commit quality gate, and three-expert review. +- [x] `API-105` Guard root compatibility facade aliases. + - Completed slice: route the S3 API storage compatibility ETag helper through + a local ECStore client module alias and add a repository-wide storage + compatibility guard against scattered raw ECStore facade paths. + - Acceptance: storage compatibility boundaries may import ECStore facade + modules as local `ecstore_*` aliases, but no compatibility wrapper body or + signature may reintroduce a scattered raw `rustfs_ecstore::api::...` path. + - Must preserve: S3 API ETag conversion behavior and all existing + compatibility module import boundaries. + - Verification: RustFS test-target compile coverage, full storage + compatibility raw-facade residual scan, migration and layer guards, + 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 @@ -3523,14 +3536,26 @@ Status values: `[ ]` not started, `[~]` in progress, `[x]` complete, `[!]` block | Expert | Status | Notes | |---|---|---| -| Quality/architecture | pass | API-104 narrows the remaining local compatibility re-export surfaces without changing owner call sites or ECStore contracts. | -| Migration preservation | pass | The guard now rejects restoring glob re-exports across all narrowed local compatibility boundaries. | -| Testing/verification | pass | Focused compile, narrowed glob-export scan, migration guard, layer guard, formatting, diff hygiene, risk scan, and full pre-commit passed. | +| Quality/architecture | pass | API-105 keeps S3 API ETag conversion behind a local ECStore client alias and extends guard coverage without changing call behavior. | +| Migration preservation | pass | The guard now rejects scattered raw ECStore facade paths across storage compatibility boundaries while preserving local `ecstore_*` imports. | +| Testing/verification | pass | Focused compile, raw-facade residual scan, migration guard, layer guard, formatting, diff hygiene, risk scan, and full pre-commit passed. | ## Verification Notes Passed before push: +- Issue #660 API-105 current slice: + - `cargo check -p rustfs --tests`: passed. + - `cargo fmt --all`: 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. + - `./scripts/check_layer_dependencies.sh`: passed. + - Full storage compatibility raw-facade residual scan: passed. + - Rust risk scan on changed Rust files and guard script: passed. + - `make pre-commit`: passed. + - Issue #660 API-104 current slice: - `cargo check -p rustfs --tests`: passed. - `cargo fmt --all`: passed. diff --git a/rustfs/src/storage/s3_api/storage_compat.rs b/rustfs/src/storage/s3_api/storage_compat.rs index 30f4a506b..98928221b 100644 --- a/rustfs/src/storage/s3_api/storage_compat.rs +++ b/rustfs/src/storage/s3_api/storage_compat.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +use rustfs_ecstore::api::client as ecstore_client; + pub(crate) fn to_s3s_etag(etag: &str) -> s3s::dto::ETag { - rustfs_ecstore::api::client::object_api_utils::to_s3s_etag(etag) + ecstore_client::object_api_utils::to_s3s_etag(etag) } diff --git a/scripts/check_architecture_migration_rules.sh b/scripts/check_architecture_migration_rules.sh index 15ec73875..c0ce9977c 100755 --- a/scripts/check_architecture_migration_rules.sh +++ b/scripts/check_architecture_migration_rules.sh @@ -95,6 +95,7 @@ RUSTFS_STORAGE_COMPAT_RAW_FACADE_PATH_HITS_FILE="${TMP_DIR}/rustfs_storage_compa RUSTFS_APP_ADMIN_COMPAT_RAW_FACADE_PATH_HITS_FILE="${TMP_DIR}/rustfs_app_admin_compat_raw_facade_path_hits.txt" OUTER_CONSUMER_COMPAT_RAW_FACADE_PATH_HITS_FILE="${TMP_DIR}/outer_consumer_compat_raw_facade_path_hits.txt" RUSTFS_ROOT_E2E_COMPAT_RAW_FACADE_PATH_HITS_FILE="${TMP_DIR}/rustfs_root_e2e_compat_raw_facade_path_hits.txt" +ALL_STORAGE_COMPAT_RAW_FACADE_PATH_HITS_FILE="${TMP_DIR}/all_storage_compat_raw_facade_path_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" @@ -999,6 +1000,19 @@ if [[ -s "$RUSTFS_ROOT_E2E_COMPAT_RAW_FACADE_PATH_HITS_FILE" ]]; then report_failure "RustFS root/e2e storage compatibility must use local ecstore_* module aliases instead of scattered raw ECStore facade paths: $(paste -sd '; ' "$RUSTFS_ROOT_E2E_COMPAT_RAW_FACADE_PATH_HITS_FILE")" fi +( + cd "$ROOT_DIR" + rg -n --with-filename 'rustfs_ecstore::api::' rustfs/src crates fuzz \ + --glob '*storage_compat.rs' \ + --glob '*_compat.rs' \ + | rg -v '^[^:]+:[0-9]+:use rustfs_ecstore::api::\{' \ + | rg -v '^[^:]+:[0-9]+:use rustfs_ecstore::api::[a-z_]+ as ecstore_[a-z_]+;' || true +) >"$ALL_STORAGE_COMPAT_RAW_FACADE_PATH_HITS_FILE" + +if [[ -s "$ALL_STORAGE_COMPAT_RAW_FACADE_PATH_HITS_FILE" ]]; then + report_failure "storage compatibility boundaries must keep raw ECStore facade paths behind local ecstore_* module aliases: $(paste -sd '; ' "$ALL_STORAGE_COMPAT_RAW_FACADE_PATH_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*;' \