mirror of
https://github.com/rustfs/rustfs.git
synced 2026-08-06 21:33:14 +00:00
Zhengchao An
80 lines
4.4 KiB
Markdown
80 lines
4.4 KiB
Markdown
# Global State And Crate Split Plan
|
|
|
|
This document records the late global-state cleanup plan after the AppContext
|
|
foundation, storage API contracts, ECStore layout, runtime lifecycle, and cluster
|
|
control-plane boundaries are stable.
|
|
|
|
## Remaining Global Owners
|
|
|
|
| Owner | Current role | Migration stance |
|
|
|---|---|---|
|
|
| `rustfs/src/app/context.rs` | AppContext-first resolver facade with legacy fallback adapters. | Keep resolver entry points stable until every caller has an explicit context or owner-local runtime source. |
|
|
| `rustfs/src/app/context/runtime_sources.rs` | Default AppContext fallback adapters for KMS, IAM, object store, endpoints, config, metrics, and notification state. | This is an allowed fallback boundary, not a business logic owner. |
|
|
| `rustfs/src/*/runtime_sources.rs` | Root, admin, app, server, startup, and storage owner-local runtime-source boundaries. | Business modules use these boundaries instead of calling global state directly. |
|
|
| `rustfs/src/*/storage_api.rs` | Root, admin, app, and storage owner-local storage contract/facade boundaries. | Storage helper and ECStore facade access remains visible at local owner boundaries. |
|
|
| `crates/*/storage_api.rs` | External crate-local storage facade boundaries for IAM, scanner, heal, notify, observability, Swift, and S3 Select. | External runtime crates consume ECStore runtime state through `rustfs_ecstore::api::runtime` instead of the direct global facade. |
|
|
| `crates/ecstore/src/runtime/global.rs` | ECStore bootstrap/runtime state owner. | Keep internal until ECStore has explicit owner handles for all remaining bootstrap state. |
|
|
| `crates/ecstore/src/runtime/sources.rs` | ECStore runtime-source adapter over global state. | Preferred ECStore-internal access path while shrinking direct `runtime::global` reads. |
|
|
|
|
## Runtime Source Boundaries
|
|
|
|
Runtime-source modules are the allowed compatibility layer between migrated
|
|
consumers and process-global state. They must keep these properties:
|
|
|
|
- context-first lookup when an `AppContext` handle exists;
|
|
- explicit fallback to the existing global only where compatibility still
|
|
requires it;
|
|
- no hidden service construction in business logic;
|
|
- no startup, readiness, IAM, KMS, lock, notification, or storage behavior
|
|
change in inventory or guardrail PRs.
|
|
|
|
## Guarded Boundary List
|
|
|
|
The architecture guard snapshots the files currently allowed to reference
|
|
`rustfs_ecstore::api::global` directly:
|
|
|
|
- `rustfs/src/storage/storage_api.rs`
|
|
|
|
New direct uses must either move behind an existing owner-local boundary or
|
|
update this plan and the guard in the same reviewed migration PR.
|
|
|
|
## Fallback Removal Plan
|
|
|
|
1. Keep AppContext-first plus global fallback while compatibility tests still
|
|
cover both paths.
|
|
2. Move one remaining consumer group at a time to explicit context or
|
|
owner-local runtime-source handles.
|
|
- Current handoff: admin config, OIDC config, audit runtime config, and
|
|
dynamic KMS config storage reads/writes resolve through current
|
|
AppContext-aware boundaries before using the legacy object-store fallback.
|
|
3. Remove one fallback family per PR only after scans prove no production caller
|
|
depends on it.
|
|
4. Keep embedded startup and tests working before deleting any fallback.
|
|
5. Do not remove ECStore bootstrap globals until ownership handles exist for
|
|
local disks, endpoint pools, lock clients, notification state, tier config,
|
|
lifecycle state, and object-store publication.
|
|
|
|
## Crate Split Evaluation
|
|
|
|
`ecstore-erasure` and `storage-cluster` remain proposal-only until dependency
|
|
cycles and hot-path risks are proven safe.
|
|
|
|
Required evidence before a split:
|
|
|
|
- dependency graph showing no cycle with ECStore, storage API, runtime, or
|
|
cluster control-plane owners;
|
|
- benchmark or profiling evidence for erasure and bitrot hot paths;
|
|
- compatibility plan for public ECStore facade paths and test harnesses;
|
|
- rollback plan that preserves quorum, remote disk, lock, and data movement
|
|
behavior.
|
|
|
|
## Preservation Rules
|
|
|
|
- Do not remove AppContext fallback in a broad cleanup PR.
|
|
- Do not introduce direct global reads in admin, app, server, storage, scanner,
|
|
heal, IAM, notify, observability, Swift, or S3 Select business logic.
|
|
- Do not split crates in the same PR that moves runtime state.
|
|
- Do not change startup order, readiness, KMS fatal boundaries, IAM recovery,
|
|
lock quorum, object placement, reader behavior, or notification/audit
|
|
lifecycle while shrinking global state.
|