gsadmin/rustfs
1
0
Fork 0
mirror of https://github.com/rustfs/rustfs.git synced 2026-08-05 12:57:42 +00:00
Code Issues Packages Projects Releases Wiki Activity

refactor: extract optional runtime sidecar boundary (#3637)

Browse Source
This commit is contained in:
安正超
2026-06-20 04:28:33 +08:00
committed by GitHub
parent aa5de1c908
commit 5e96151d9c
8 changed files with 242 additions and 190 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture/migration-progress.md
+43 -12
View File
@@ -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-startup-service-components-boundary`
- Baseline: `overtrue/arch-startup-ready-lifecycle-boundary`
(`a518f40489515c1ec37c3cbc5738e04955a942f2`).
- Stacked on: rustfs/rustfs#3635.
- Branch: `overtrue/arch-protocol-runtime-sidecar-boundary`
- Baseline: `origin/main`
(`aa5de1c908d6ffb778533c895c200f3c60ca1ed5`).
- Stacked on: rustfs/rustfs#3636.
- PR type for this branch: `pure-move`
- Runtime behavior changes: none.
- Rust code changes: move startup service component initialization helpers from
`startup_services` into a dedicated startup service component boundary.
- Rust code changes: move optional runtime sidecar ownership and protocol
shutdown planning from `startup_optional_runtimes` into
`startup_optional_runtime_sidecars`.
- CI/script changes: none.
- Docs changes: record the R-025 startup service component boundary slice.
- Docs changes: record the R-026 optional runtime sidecar boundary slice.
## Phase 0 Tasks
@@ -2094,10 +2095,25 @@ Status values: `[ ]` not started, `[~]` in progress, `[x]` complete, `[!]` block
risk scan, branch freshness check, pre-commit quality gate, and
three-expert review.
- [x] `R-026` Extract optional runtime sidecar boundary.
- Do: add `startup_optional_runtime_sidecars` and move optional runtime
sidecar ownership, shutdown planning, shutdown execution, and protocol
shutdown order tests out of `startup_optional_runtimes`.
- Acceptance: optional protocol startup still happens after KMS and before
buffer profiling, while shutdown planning still records FTP, FTPS, WebDAV,
then SFTP handles before later shutdown signaling.
- Must preserve: feature-gated protocol startup behavior, disabled-protocol
handling, protocol shutdown ordering, HTTP shutdown before optional protocol
shutdown signaling, and the compatibility `startup_optional_runtimes` API.
- Verification: focused optional runtime sidecar/runtime/shutdown tests,
RustFS lib check, migration/layer guards, formatting, diff hygiene, Rust
risk scan, branch freshness check, pre-commit quality gate, and
three-expert review.
## Next PRs
1. `pure-move`: continue larger lifecycle hook slices for optional runtime
sidecars while preserving startup and shutdown ordering.
1. `pure-move`: continue larger lifecycle hook slices for startup profiling and
diagnostics while preserving startup and shutdown ordering.
2. `contract`: continue extension contract coverage for future diagnostics and
profiler handoff surfaces after runtime owners are stable.
@@ -2105,9 +2121,9 @@ Status values: `[ ]` not started, `[~]` in progress, `[x]` complete, `[!]` block
| Expert | Status | Notes |
|---|---|---|
| Quality/architecture | passed | R-025 keeps `startup_services` as the orchestrator and moves component helpers into `startup_service_components`. |
| Migration preservation | passed | Runtime service startup order and embedded helper reuse remain unchanged. |
| Testing/verification | passed | Focused component, service, lifecycle, final hygiene, and full pre-commit checks passed. |
| Quality/architecture | passed | R-026 moves optional runtime sidecar ownership into `startup_optional_runtime_sidecars` while keeping the old module path as a compatibility handoff. |
| Migration preservation | passed | Protocol startup order, shutdown planning order, and HTTP-before-optional-runtime shutdown ordering remain unchanged. |
| Testing/verification | passed | Focused optional runtime sidecar/runtime/shutdown checks, guards, final hygiene, and full pre-commit passed. |
## Verification Notes
@@ -2203,6 +2219,21 @@ Passed before push:
- `make pre-commit`: passed.
- Three-expert review: passed.
- Issue #660 R-026 current slice:
- `cargo test -p rustfs --lib startup_optional_runtime_sidecars -- --nocapture`:
passed.
- `cargo test -p rustfs --lib startup_optional_runtimes -- --nocapture`:
passed.
- `cargo test -p rustfs --lib startup_shutdown -- --nocapture`: passed.
- `cargo check -p rustfs --lib`: passed.
- `./scripts/check_architecture_migration_rules.sh`: passed.
- `./scripts/check_layer_dependencies.sh`: passed.
- `cargo fmt --all --check`: passed.
- `git diff --check`: passed.
- Rust risk scan on changed Rust files: passed.
- `make pre-commit`: passed.
- Three-expert review: passed.
- Issue #660 R-020 current slice:
- `cargo test -p rustfs --lib startup_profiling -- --nocapture`: passed.
- `cargo check -p rustfs --lib`: passed.
docs/architecture/runtime-lifecycle.md
+7 -5
View File
@@ -57,11 +57,13 @@ these helpers.
## Optional Runtime Boundary
`startup_optional_runtimes` owns startup and shutdown handoff for optional
runtime services that are not readiness boundaries. The current owner set is
protocol servers only. Future optional sidecars must enter this boundary with
explicit shutdown handles and status snapshots instead of adding ad hoc startup
or shutdown work to `startup_services`.
`startup_optional_runtime_sidecars` owns startup handles, shutdown planning, and
shutdown execution for optional runtime services that are not readiness
boundaries. `startup_optional_runtimes` remains a compatibility handoff for the
old module path. The current owner set is protocol servers only. Future optional
sidecars must enter this boundary with explicit shutdown handles and status
snapshots instead of adding ad hoc startup or shutdown work to
`startup_services`.
## AppContext Foundation
docs/architecture/startup-timeline.md
+3 -3
View File
@@ -37,7 +37,7 @@ new startup semantics.
| `RUN-011` | `rustfs/src/startup_storage.rs` | Create cancellation token and initialize `ECStore`. | Creates the runtime cancellation token and storage engine. | Fatal if `ECStore::new` fails. | None |
| `RUN-012` | `rustfs/src/startup_storage.rs` | Initialize ECStore config and global config system. | Initializes ECStore config, attempts server-config migration, then retries global config init up to 15 times. | Migration attempt is non-fatal in this path; global config init becomes fatal after retries. | Marks the `GlobalReadiness` `StorageReady` stage after global config init succeeds; later runtime readiness still rechecks storage, IAM, and lock quorum before `FullReady` |
| `RUN-013` | `rustfs/src/startup_storage.rs` and `rustfs/src/startup_services.rs` | Start replication and KMS systems. | Starts background replication pool, then initializes KMS from startup services. | Replication init is non-fatal in this path; KMS init is fatal on error. | `StorageReady` stage is already marked; dynamic runtime storage readiness is still checked before `FullReady` |
| `RUN-014` | `rustfs/src/startup_optional_runtimes.rs` and `rustfs/src/startup_protocols.rs` | Initialize optional protocol servers. | Starts FTP/FTPS/WebDAV/SFTP when feature-enabled and configured, collecting shutdown handles. | Feature-enabled protocol init is fatal on error; disabled protocols are non-fatal. | None |
| `RUN-014` | `rustfs/src/startup_optional_runtime_sidecars.rs` and `rustfs/src/startup_protocols.rs` | Initialize optional protocol servers. | Starts FTP/FTPS/WebDAV/SFTP when feature-enabled and configured, collecting shutdown handles. | Feature-enabled protocol init is fatal on error; disabled protocols are non-fatal. | None |
| `RUN-015` | `rustfs/src/startup_services.rs` and `rustfs/src/startup_service_components.rs` | Initialize buffer profiling, event notifier, audit, and deadlock detector. | Starts buffer profile system, event notifier, audit system, and optional deadlock detector. | Audit startup failure is logged and non-fatal; the others are non-fatal in this path. | None |
| `RUN-016` | `rustfs/src/startup_service_components.rs` | List buckets and run bucket/replication/IAM metadata migrations. | Reads bucket names, migrates bucket metadata, initializes replication resync, migrates IAM config, and initializes bucket metadata system. | Bucket list and replication resync are fatal on error; metadata migration calls are non-fatal in this path. | Storage remains ready; IAM not yet ready |
| `RUN-017` | `rustfs/src/startup_service_components.rs` and `rustfs/src/startup_iam.rs` | Bootstrap IAM inline or defer recovery. | Initializes IAM when possible; otherwise starts the deferred IAM recovery path through `startup_iam`. | Fatal only when `bootstrap_or_defer_iam_init` returns an unrecoverable error. | Inline success marks `IamReady`; deferred mode publishes `IamReady` later from the recovery task |
@@ -71,9 +71,9 @@ new startup semantics.
|---|---|---|---|---|---|
| `STOP-001` | `rustfs/src/startup_shutdown.rs` | Cancel runtime token and move service state to `Stopping`. | Notifies cancellation-aware background tasks. | Non-fatal. | Service state moves to `Stopping`; readiness stages are not cleared here |
| `STOP-002` | `rustfs/src/startup_shutdown.rs` | Stop scanner/background services and AHM services according to enable flags. | Calls ECStore background shutdown and heal/scanner shutdown helpers. | Non-fatal in this path. | No readiness-stage change |
| `STOP-003` | `rustfs/src/startup_optional_runtimes.rs` | Plan optional runtime shutdown and log stopping state for FTP/FTPS/WebDAV/SFTP protocol servers. | Collects protocol shutdown handles. | Non-fatal in this path. | No readiness-stage change |
| `STOP-003` | `rustfs/src/startup_optional_runtime_sidecars.rs` | Plan optional runtime shutdown and log stopping state for FTP/FTPS/WebDAV/SFTP protocol servers. | Collects protocol shutdown handles. | Non-fatal in this path. | No readiness-stage change |
| `STOP-004` | `rustfs/src/startup_shutdown.rs` and `rustfs/src/startup_profiling.rs` | Stop event notifier, audit system, and profiling tasks. | Stops notifier and profiling tasks; audit stop failures are logged. | Non-fatal in this path. | No readiness-stage change |
| `STOP-005` | `rustfs/src/startup_shutdown.rs` and `rustfs/src/startup_optional_runtimes.rs` | Stop S3 and console HTTP servers, signal and wait for optional protocol shutdowns, then mark service state `Stopped`. | HTTP shutdown happens after notifier/audit/profiling shutdown in current order. | Join failures are logged by shutdown handles; this path does not return errors. | Service state moves to `Stopped`; readiness stages are not cleared here |
| `STOP-005` | `rustfs/src/startup_shutdown.rs` and `rustfs/src/startup_optional_runtime_sidecars.rs` | Stop S3 and console HTTP servers, signal and wait for optional protocol shutdowns, then mark service state `Stopped`. | HTTP shutdown happens after notifier/audit/profiling shutdown in current order. | Join failures are logged by shutdown handles; this path does not return errors. | Service state moves to `Stopped`; readiness stages are not cleared here |
## Migration Rules