diff --git a/docs/architecture/global-state-crate-split-plan.md b/docs/architecture/global-state-crate-split-plan.md index 507d199e2..d278add03 100644 --- a/docs/architecture/global-state-crate-split-plan.md +++ b/docs/architecture/global-state-crate-split-plan.md @@ -9,6 +9,9 @@ the root facade and into explicit owner-local boundaries. Future work should therefore treat broad fallback removal as complete and use this document for the remaining ECStore-owned bootstrap state and crate-split decisions. +The issue #730 global-state baseline and runtime migration target inventory are +recorded in [`global-state-inventory.md`](global-state-inventory.md). + ## Remaining Global Owners | Owner | Current role | Migration stance | diff --git a/docs/architecture/global-state-inventory.md b/docs/architecture/global-state-inventory.md new file mode 100644 index 000000000..2a225571d --- /dev/null +++ b/docs/architecture/global-state-inventory.md @@ -0,0 +1,80 @@ +# Global State Inventory + +This inventory records the issue #730 baseline for global runtime state after +the AppContext foundation and owner-local runtime-source boundaries were added. +It is intentionally documentation-only: it classifies migration targets without +changing startup, readiness, object IO, lifecycle, replication, or notification +behavior. + +## Counting Baseline + +The audit uses the current workspace Rust sources and keeps broad static +caches separate from runtime migration targets. + +| Scope | Count | Command | +|---|---:|---| +| Rust source files | 1,237 | `rg --files -g '*.rs'` | +| `OnceLock` references | 221 lines | `rg -n --glob '*.rs' 'OnceLock'` | +| `GLOBAL_*` references | 302 lines | `rg -n --glob '*.rs' '\bGLOBAL_[A-Za-z0-9_]*\b'` | +| `static NAME:` definitions | 621 lines | `rg -n --glob '*.rs' '^\s*(pub(\([^)]*\))?\s+)?static(\s+mut)?\s+[A-Za-z_][A-Za-z0-9_]*\s*:'` | +| `lazy_static!` `static ref` definitions | 59 lines | `rg -n --glob '*.rs' '^\s*(pub\s+)?static\s+ref\s+[A-Za-z_][A-Za-z0-9_]*\s*:'` | +| `static mut` definitions | 0 lines | `rg -n --glob '*.rs' '^\s*(pub(\([^)]*\))?\s+)?static\s+mut\s+'` | + +## Global State Classification + +| Category | Rule | Representative owners | +|---|---|---| +| Process-global | Process identity, metrics registries, lock manager, audit guard, TLS material, or other state that is intentionally one per process. | `crates/credentials`, `crates/common`, `crates/io-metrics`, `crates/lock`, `crates/obs`, `crates/tls-runtime` | +| Runtime migration target | Mutable runtime state that describes the active object store, endpoints, local disks, lifecycle, replication, notification, config, or background controllers. | `crates/ecstore/src/runtime/global.rs`, `crates/ecstore/src/runtime/sources.rs`, `rustfs/src/app/context/*` | +| Owner-local compatibility | Existing compatibility adapters that are allowed to read globals while callers migrate to AppContext-first or owner-local runtime-source APIs. | `rustfs/src/*/runtime_sources.rs`, `rustfs/src/*/storage_api.rs`, `crates/*/storage_api.rs` | +| Test or fixture state | Static setup used by tests to amortize expensive ECStore setup or isolate compatibility harness state. | `rustfs/src/app/*_test.rs`, `crates/scanner/tests/*`, `crates/ecstore/src/**/tests` | +| Cache or constant | Regexes, metrics descriptors, defaults, KVS registrations, headers, path constants, and small process caches that are not runtime ownership handles. | `crates/config`, `crates/obs/src/metrics`, `crates/utils`, `rustfs/src/server/readiness.rs` | +| Legacy naming or review-needed | Mixed-case `GLOBAL_*`, old MinIO-port naming, stale comments, or names that need owner confirmation before code movement. | `GLOBAL_IsErasure`, `GLOBAL_Endpoints`, `GLOBAL_LocalNodeName`, `globalDeploymentIDPtr` | + +## Runtime Migration Inventory + +These are the issue #730 targets that should remain visible until an owner +migration PR removes or replaces each item. + +| State | Current boundary | Category | Migration stance | +|---|---|---|---| +| `APP_CONTEXT_SINGLETON` | `rustfs/src/app/context/global.rs` | Owner-local compatibility | Keep as the context-first facade while no-context startup and embedded callers still exist. | +| `GLOBAL_OBJECT_API`, `GLOBAL_OBJECT_STORE_RESOLVER` | `crates/ecstore/src/runtime/global.rs` | Runtime migration target | Do not migrate first; it is tied to storage startup, IAM-after-storage AppContext publication, and data-plane resolver compatibility. | +| `GLOBAL_Endpoints`, `GLOBAL_IsErasure`, `GLOBAL_IsDistErasure`, `GLOBAL_IsErasureSD`, `GLOBAL_RootDiskThreshold` | `crates/ecstore/src/runtime/global.rs` and `crates/ecstore/src/runtime/sources.rs` | Runtime migration target | Move only after endpoint, setup-type, and root-disk-threshold ownership can be tested without changing readiness or quorum behavior. | +| `GLOBAL_LOCAL_DISK_MAP`, `GLOBAL_LOCAL_DISK_ID_MAP`, `GLOBAL_LOCAL_DISK_SET_DRIVES` | `crates/ecstore/src/runtime/global.rs` and `crates/ecstore/src/runtime/sources.rs` | Runtime migration target | Needs an ECStore local-disk registry handle before code movement; preserve disk lookup, remote/local classification, and test reset hooks. | +| `GLOBAL_ExpiryState`, `GLOBAL_TransitionState`, `GLOBAL_LifecycleSys` | `crates/ecstore/src/bucket/lifecycle/*` and `crates/ecstore/src/runtime/sources.rs` | Runtime migration target | First code-bearing candidate is `GLOBAL_ExpiryState`, because AppContext already has an `ExpiryStateInterface`, resolver, and tests. | +| `GLOBAL_REPLICATION_POOL`, `GLOBAL_REPLICATION_STATS`, `GLOBAL_BUCKET_MONITOR` | `crates/ecstore/src/bucket/replication/*`, `crates/ecstore/src/runtime/global.rs` | Runtime migration target | Keep behind AppContext replication and bucket-monitor resolvers until queue admission, stats, and admin reporting coverage are explicit. | +| `GLOBAL_TierConfigMgr`, `GLOBAL_STORAGE_CLASS`, `GLOBAL_CONFIG_SYS`, `GLOBAL_SERVER_CONFIG` | `crates/ecstore/src/config`, `crates/config`, `rustfs/src/app/context/runtime_sources.rs` | Runtime migration target | Move through config/runtime-source owners only; do not combine with storage-class behavior or persistence changes. | +| `GLOBAL_EventNotifier`, `GLOBAL_NotificationSys` | `crates/ecstore/src/services/*` | Runtime migration target | Preserve notification and audit side effects; move only through notify/runtime-source boundaries. | +| `GLOBAL_BOOT_TIME`, `globalDeploymentIDPtr`, `GLOBAL_REGION`, `GLOBAL_RUSTFS_PORT`, `GLOBAL_LocalNodeName` | `crates/ecstore/src/runtime/global.rs` | Runtime migration target | Scalar handles may migrate in small PRs after call sites use AppContext or owner-local runtime-source readers. | +| `GLOBAL_LOCAL_LOCK_CLIENT`, `GLOBAL_LOCK_CLIENTS`, `GLOBAL_LOCK_MANAGER` | `crates/ecstore/src/runtime/global.rs`, `crates/lock` | Runtime migration target / process-global split | Preserve lock quorum and lock client selection; keep process-level lock manager separate from ECStore endpoint-specific clients. | +| `GLOBAL_CONN_MAP`, `GLOBAL_RUSTFS_HOST`, `GLOBAL_RUSTFS_ADDR`, `GLOBAL_ROOT_CERT`, `GLOBAL_MTLS_IDENTITY`, `GLOBAL_OUTBOUND_TLS_GENERATION` | `crates/common`, `crates/tls-runtime`, `crates/ecstore/src/runtime/sources.rs` | Runtime migration target / process-global split | Migrate only after internode transport and outbound TLS ownership are explicit; do not change cached channel reuse or TLS reload semantics. | +| `GLOBAL_HEAL_MANAGER`, `GLOBAL_HEAL_CHANNEL_PROCESSOR`, `GLOBAL_AHM_SERVICES_CANCEL_TOKEN` | `crates/heal` and `crates/common` | Runtime migration target | Needs heal runtime owner handles and queue tests; do not combine with ECStore disk-state movement. | +| `AUDIT_SYSTEM`, `GLOBAL_CAPACITY_MANAGER`, `GLOBAL_BUCKET_TARGET_SYS`, `GLOBAL_PROCESSORS`, `INTERNODE_DATA_TRANSPORT`, `GLOBAL_KMS_SERVICE_MANAGER` | Owner crates | Runtime migration target / process-global split | Track as owner-specific follow-ups; each owner must decide whether AppContext, a runtime-source facade, or process-global state is the right final shape. | + +## First Code-Bearing Candidate + +`GLOBAL_ExpiryState` is the safest first runtime migration candidate: + +- AppContext already exposes `ExpiryStateInterface` and resolver coverage in + `rustfs/src/app/context.rs`. +- ECStore access is already concentrated in + `crates/ecstore/src/runtime/sources.rs`. +- The main external readers can be moved through storage/observability facades + before changing lifecycle queue ownership. + +Do not migrate `GLOBAL_OBJECT_API` first. It is coupled to storage startup, +object-store resolver publication, IAM-after-storage AppContext initialization, +and broad data-plane compatibility. + +## Verification + +Inventory and guardrail PRs should run: + +- `bash -n scripts/check_architecture_migration_rules.sh` +- `./scripts/check_architecture_migration_rules.sh` +- `cargo fmt --all --check` +- `git diff --check` + +Code-bearing migration PRs must add focused tests for the owner being moved +before running broader gates. diff --git a/docs/architecture/runtime-lifecycle.md b/docs/architecture/runtime-lifecycle.md index 0f53ca62c..7c77dcedb 100644 --- a/docs/architecture/runtime-lifecycle.md +++ b/docs/architecture/runtime-lifecycle.md @@ -113,3 +113,8 @@ address normalization, and process-local shutdown cleanup. Early AppContext work should split resolver files and add compatibility tests before boot extraction or consumer migration. This keeps the migration context-first while preserving the old global fallback path during transition. + +AppContext remains a context-first facade, not a full replacement for every +process global. New migration work must keep fallback reads inside owner-local +runtime-source boundaries and follow the global-state target inventory in +[`global-state-inventory.md`](global-state-inventory.md). diff --git a/scripts/check_architecture_migration_rules.sh b/scripts/check_architecture_migration_rules.sh index d8f0cb6db..0bf8d1121 100755 --- a/scripts/check_architecture_migration_rules.sh +++ b/scripts/check_architecture_migration_rules.sh @@ -67,6 +67,10 @@ require_source_contains "docs/architecture/global-state-crate-split-plan.md" "## require_source_contains "docs/architecture/global-state-crate-split-plan.md" "## Fallback Removal Plan" "global state plan fallback section" require_source_contains "docs/architecture/global-state-crate-split-plan.md" "## Crate Split Evaluation" "global state plan crate split section" require_source_contains "docs/architecture/global-state-crate-split-plan.md" "rustfs_ecstore::api::global" "global state plan facade boundary" +require_source_contains "docs/architecture/global-state-crate-split-plan.md" "global-state-inventory.md" "global state inventory plan link" +require_source_contains "docs/architecture/global-state-inventory.md" "## Global State Classification" "global state inventory classification section" +require_source_contains "docs/architecture/global-state-inventory.md" "## Runtime Migration Inventory" "global state inventory migration section" +require_source_contains "docs/architecture/global-state-inventory.md" "GLOBAL_ExpiryState" "global state inventory first candidate" require_source_contains "docs/architecture/obs-ecstore-dependency-inventory.md" "## Dependency Inventory" "observability ECStore dependency inventory section" require_source_contains "docs/architecture/obs-ecstore-dependency-inventory.md" "## Extraction Plan" "observability ECStore extraction plan section" require_source_contains "docs/architecture/obs-ecstore-dependency-inventory.md" "crates/obs/src/metrics/storage_api.rs" "observability ECStore storage_api boundary"