gsadmin/rustfs
1
0
Fork 0
mirror of https://github.com/rustfs/rustfs.git synced 2026-08-09 22:59:59 +00:00
Code Issues Packages Projects Releases Wiki Activity

refactor: centralize startup command bootstrap (#3471)

Browse Source
This commit is contained in:
安正超
2026-06-15 14:55:33 +08:00
committed by GitHub
parent 941b8afee8
commit 57260c8314
6 changed files with 232 additions and 188 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture/migration-progress.md
+46 -26
View File
@@ -5,17 +5,18 @@ 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-ready-shutdown-runtime`
- Baseline: `origin/main` at `e26eea7f3a5ef6c272a322a47f58f5a10cb2342b0`
- Branch: `overtrue/arch-startup-command-bootstrap`
- Baseline: `origin/main` at `941b8afee8619c6a038c20aac51565a65c959ee4`
- PR type for this branch: `pure-move`
- Runtime behavior changes: no external behavior change expected; server-ready
publication, global init time, scanner start, shutdown wait, and shutdown
ordering still run in the same relative order after runtime services.
- Rust code changes: add `startup_services::run_startup_runtime_lifecycle` and
use it from binary startup.
- Runtime behavior changes: no external behavior change expected; the binary
entrypoint still builds the Tokio runtime, applies preflight, dispatches
non-server commands, and starts server/bootstrap stages in the same order.
- Rust code changes: add `startup_entrypoint::run_process`, move remaining
command dispatch, server bootstrap orchestration, and fatal stderr helpers
out of `main.rs`, and keep `main.rs` as the process entry shim.
- CI/script changes: none.
- Docs changes: record `R-018` startup runtime lifecycle progress and
verification.
- Docs changes: record `R-019` startup command/bootstrap entrypoint progress
and update startup timeline ownership.
## Phase 0 Tasks
@@ -721,10 +722,26 @@ Status values: `[ ]` not started, `[~]` in progress, `[x]` complete, `[!]` block
formatting, migration guards, Rust risk scan, branch freshness check, and
pre-commit quality gate.
- [x] `R-019` Centralize startup command and bootstrap entrypoint.
- Do: move Tokio runtime result handling, command parsing/dispatch, server
preflight error mapping, startup run orchestration, and pre-observability
fatal stderr formatting behind `startup_entrypoint::run_process`.
- Acceptance: `main.rs` only owns the global allocator declarations and calls
the startup entrypoint; `startup_entrypoint` preserves the existing
command, preflight, listen, storage, runtime-service, ready, and shutdown
order.
- Must preserve: Tokio runtime build fatal `expect`, command parse fatal
stderr context and exit code, info/TLS subcommand behavior, observability
fatal sentinel suppression, server runtime failure log fields, startup stage
ordering, readiness publication, and shutdown ownership.
- Verification: focused startup entrypoint and observability guardrail tests,
binary/lib compile checks, formatting, migration guards, Rust risk scan,
branch freshness check, and pre-commit quality gate.
## Next PRs
1. `pure-move`: continue collapsing remaining binary startup glue around command
dispatch and server bootstrap without changing fatal stderr behavior.
1. `pure-move`: continue shrinking startup entrypoint orchestration only where a
clean module boundary remains without changing fatal stderr behavior.
2. `ci-gate`: finish `G-006` public re-export and storage trait coverage checks
before the remaining cleanup slices.
@@ -732,40 +749,43 @@ Status values: `[ ]` not started, `[~]` in progress, `[x]` complete, `[!]` block
| Expert | Status | Notes |
|---|---|---|
| Quality/architecture | passed | Pure-move slice removes ready/scanner/shutdown lifecycle details from binary startup behind the existing startup services boundary. |
| Migration preservation | passed | Server-ready publication, scanner start, shutdown wait, background/protocol/notifier/audit/profiling/HTTP shutdown order, and stopped state are preserved. |
| Testing/verification | passed | Focused startup services tests, compile checks, formatting, migration/layer guards, Rust risk scan, branch freshness check, and full `make pre-commit` passed. |
| Quality/architecture | passed | Pure-move slice removes command dispatch and bootstrap orchestration details from binary startup behind a dedicated startup entrypoint boundary. |
| Migration preservation | passed | Command parse stderr, info/TLS dispatch, observability fatal sentinel, startup order, readiness publication, and shutdown ownership are preserved. |
| Testing/verification | passed | Focused startup entrypoint and observability guardrail tests, compile checks, formatting, migration/layer guards, Rust risk scan, branch freshness check, and full `make pre-commit` passed. |
## Verification Notes
Passed on `e26eea7f3a5ef6c272a322a47f58f5a10cb2342b0`:
Passed on `941b8afee8619c6a038c20aac51565a65c959ee4`:
- `cargo test -p rustfs startup_services --no-fail-fast`: passed.
- `cargo test -p rustfs startup_entrypoint --no-fail-fast`: passed.
- `cargo test -p rustfs-obs startup_ --no-fail-fast`: passed.
- `cargo check -p rustfs --lib`: passed.
- `cargo check -p rustfs --bin rustfs`: passed.
- `cargo fmt --all --check`: passed.
- `git diff --check`: passed.
- `./scripts/check_architecture_migration_rules.sh`: passed.
- `./scripts/check_layer_dependencies.sh`: passed.
- Added-line Rust risk scan for changed Rust files: passed.
- Full-file risk scan for changed Rust files: existing `main.rs` process setup
entries only.
- `make pre-commit`: passed, including nextest `6027` passed / `111` skipped
- Added-line and changed-file Rust risk scan: expected fatal-boundary
`expect`/`eprintln!` only.
- Full-file risk scan for changed Rust files: expected process exit and fatal
stderr entries are isolated in `startup_entrypoint.rs`.
- `make pre-commit`: passed, including nextest `6038` passed / `111` skipped
and doctests.
- `git rev-list --left-right --count HEAD...origin/main`: returned `1 0`
after commit.
Notes:
- This slice centralizes startup lifecycle completion without changing startup
ordering, shutdown token ownership, readiness ownership, or shutdown handle
ownership.
- Ready publication and scanner start remain after runtime services; shutdown
wait remains after scanner start.
- This slice centralizes remaining command/bootstrap entrypoint orchestration
without changing startup ordering, fatal stderr behavior, readiness ownership,
shutdown token ownership, or shutdown handle ownership.
- Ready publication, scanner start, and shutdown wait remain owned by
`startup_services`; `startup_entrypoint` only orchestrates the existing
startup sequence and process-level fatal handling.
## Handoff Notes
- R-018 is implemented, locally verified, and current with `origin/main`.
- R-019 is implemented, locally verified, and current with `origin/main`.
- Next startup slices can keep using larger pure moves, but must keep startup
ordering, fatal/non-fatal boundaries, shutdown ownership, readiness ownership,
and fatal stderr behavior explicit in tests and review notes.
docs/architecture/startup-timeline.md
+19 -18
View File
@@ -7,8 +7,9 @@ new startup semantics.
## Scope
- Baseline commit: `ae9d25879d72bc8977f08e61062c022e2142483b`
- Entry points covered: `rustfs/src/main.rs::main`, `async_main`, `run`, and
`handle_shutdown`
- Entry points covered: `rustfs/src/main.rs::main`,
`rustfs/src/startup_entrypoint.rs::{run_process, async_main, run}`, and
startup lifecycle helpers
- Related migration task: `G-007`
- Out of scope for this baseline: embedded startup, admin route-action matrix,
and any runtime/lifecycle code movement
@@ -17,22 +18,22 @@ new startup semantics.
| Step | Source | Current action | Side effects | Fatal boundary | Ready stage |
|---|---|---|---|---|---|
| `BOOT-001` | `rustfs/src/main.rs:84` | Apply external-prefix environment compatibility before the Tokio runtime is created. | Copies supported external env aliases into canonical `RUSTFS_*` process env keys and prints warnings or info to stderr. | Non-fatal; failure is logged to stderr and startup continues. | None |
| `BOOT-002` | `rustfs/src/main.rs:89` | Build the Tokio runtime. | Installs runtime configuration and any runtime telemetry guard created by the runtime builder. | Fatal through `expect`; process exits if the runtime cannot be built. | None |
| `BOOT-003` | `rustfs/src/main.rs:139` | Parse CLI command and dispatch non-server commands. | `info` and `tls` commands execute and return without server startup. | Command parse exits process with code 1; TLS command errors propagate. | None |
| `BOOT-004` | `rustfs/src/main.rs:167` | Initialize config snapshot and license state. | Publishes config snapshot for later readers and initializes runtime license state. | License init is non-fallible in this path. | None |
| `BOOT-005` | `rustfs/src/main.rs:173` | Initialize observability and store the global guard. | Initializes tracing/observability, stores the guard globally, and logs license/runtime telemetry status. | Fatal if observability init or guard publication fails. | None |
| `BOOT-006` | `rustfs/src/main.rs:208` | Log startup logo, initialize profiling, trusted proxies, rustls provider, and outbound TLS material. | Starts optional profiling tasks, trusted proxy config, default rustls provider, outbound TLS global state, TLS generation metric, and TLS metrics when enabled. | Profiling/proxy/provider setup is non-fatal; configured TLS material load is fatal on error. | None |
| `RUN-001` | `rustfs/src/main.rs:256` | Enter `run` and create `GlobalReadiness`. | Allocates the readiness tracker shared with HTTP readiness gates. | Non-fatal. | Initial readiness state is not ready |
| `RUN-002` | `rustfs/src/main.rs:261` | Parse and publish the configured region. | Updates ECStore global region when configured. | Fatal if the configured region is invalid. | None |
| `RUN-003` | `rustfs/src/main.rs:268` | Resolve server address and warn on default credentials. | Computes server port/address and emits production credential warning when defaults are used. | Address parse is fatal; default credentials warning is non-fatal. | None |
| `RUN-004` | `rustfs/src/main.rs:286` | Initialize global action credentials. | Publishes root/action credentials used by auth paths. | Fatal if global credentials cannot be initialized. | None |
| `RUN-005` | `rustfs/src/main.rs:298` | Publish server port and address. | Updates global RustFS port and global address. | Non-fatal in this path. | None |
| `RUN-006` | `rustfs/src/main.rs:302` | Build endpoint pools and enforce unsupported filesystem policy. | Derives pool/set/disk layout from configured volumes and validates unsupported filesystem policy. | Fatal on endpoint build or unsupported filesystem policy error. | None |
| `RUN-007` | `rustfs/src/main.rs:308` | Publish endpoints and erasure type. | Updates global endpoints and erasure type. | Non-fatal in this path. | None |
| `RUN-008` | `rustfs/src/main.rs:311` | Initialize local disks, prewarm local disk id map, and initialize lock clients. | Opens local disk state, primes disk id lookup, and creates global lock clients. | Local disk init is fatal; prewarm and lock-client setup are non-fatal in this path. | None |
| `RUN-009` | `rustfs/src/main.rs:350` | Initialize capacity management and service state manager. | Starts capacity management and moves service state to `Starting`. | Non-fatal in this path. | None |
| `RUN-010` | `rustfs/src/main.rs:356` | Start S3 HTTP listener and optional console listener before storage is ready. | Starts HTTP servers with readiness gates; console listener starts only when enabled and configured. | Fatal if a configured listener cannot start. | Requests remain gated until full readiness except probe/admin/console/rpc/tonic/table-catalog exempt paths |
| `BOOT-001` | `rustfs/src/startup_entrypoint.rs` | Apply external-prefix environment compatibility during async startup before command parsing. | Copies supported external env aliases into canonical `RUSTFS_*` process env keys and prints warnings or info to stderr. | Non-fatal; failure is logged to stderr and startup continues. | None |
| `BOOT-002` | `rustfs/src/main.rs` and `rustfs/src/startup_entrypoint.rs` | Call the startup entrypoint and build the Tokio runtime. | Installs runtime configuration and any runtime telemetry guard created by the runtime builder. | Fatal through `expect`; process exits if the runtime cannot be built. | None |
| `BOOT-003` | `rustfs/src/startup_entrypoint.rs` | Parse CLI command and dispatch non-server commands. | `info` and `tls` commands execute and return without server startup. | Command parse exits process with code 1; TLS command errors propagate. | None |
| `BOOT-004` | `rustfs/src/startup_preflight.rs` | Initialize config snapshot and license state. | Publishes config snapshot for later readers and initializes runtime license state. | License init is non-fallible in this path. | None |
| `BOOT-005` | `rustfs/src/startup_preflight.rs` | Initialize observability and store the global guard. | Initializes tracing/observability, stores the guard globally, and logs license/runtime telemetry status. | Fatal if observability init or guard publication fails. | None |
| `BOOT-006` | `rustfs/src/startup_runtime.rs` | Log startup logo, initialize profiling, trusted proxies, rustls provider, and outbound TLS material. | Starts optional profiling tasks, trusted proxy config, default rustls provider, outbound TLS global state, TLS generation metric, and TLS metrics when enabled. | Profiling/proxy/provider setup is non-fatal; configured TLS material load is fatal on error. | None |
| `RUN-001` | `rustfs/src/startup_server.rs` | Enter startup run orchestration and create `GlobalReadiness`. | Allocates the readiness tracker shared with HTTP readiness gates. | Non-fatal. | Initial readiness state is not ready |
| `RUN-002` | `rustfs/src/startup_server.rs` | Parse and publish the configured region. | Updates ECStore global region when configured. | Fatal if the configured region is invalid. | None |
| `RUN-003` | `rustfs/src/startup_server.rs` | Resolve server address and warn on default credentials. | Computes server port/address and emits production credential warning when defaults are used. | Address parse is fatal; default credentials warning is non-fatal. | None |
| `RUN-004` | `rustfs/src/startup_server.rs` | Initialize global action credentials. | Publishes root/action credentials used by auth paths. | Fatal if global credentials cannot be initialized. | None |
| `RUN-005` | `rustfs/src/startup_server.rs` | Publish server port and address. | Updates global RustFS port and global address. | Non-fatal in this path. | None |
| `RUN-006` | `rustfs/src/startup_storage.rs` | Build endpoint pools and enforce unsupported filesystem policy. | Derives pool/set/disk layout from configured volumes and validates unsupported filesystem policy. | Fatal on endpoint build or unsupported filesystem policy error. | None |
| `RUN-007` | `rustfs/src/startup_storage.rs` | Publish endpoints and erasure type. | Updates global endpoints and erasure type. | Non-fatal in this path. | None |
| `RUN-008` | `rustfs/src/startup_storage.rs` | Initialize local disks, prewarm local disk id map, and initialize lock clients. | Opens local disk state, primes disk id lookup, and creates global lock clients. | Local disk init is fatal; prewarm and lock-client setup are non-fatal in this path. | None |
| `RUN-009` | `rustfs/src/startup_server.rs` | Initialize capacity management and service state manager. | Starts capacity management and moves service state to `Starting`. | Non-fatal in this path. | None |
| `RUN-010` | `rustfs/src/startup_server.rs` | Start S3 HTTP listener and optional console listener before storage is ready. | Starts HTTP servers with readiness gates; console listener starts only when enabled and configured. | Fatal if a configured listener cannot start. | Requests remain gated until full readiness except probe/admin/console/rpc/tonic/table-catalog exempt paths |
| `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` |