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

docs(knowledge-base): prune stale content and add agent-facing index (#7035)

Browse Source
This commit is contained in:
Zhengchao An
2026-09-02 08:26:59 +08:00
committed by GitHub
parent ceeff52229
commit 0a975f2fe2
99 changed files with 3312 additions and 10590 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture/runtime-lifecycle.md
+40 -103
View File
@@ -1,120 +1,57 @@
# Runtime And Lifecycle Contracts
Runtime and lifecycle work must preserve startup ordering, readiness behavior, and
shutdown semantics.
**Use this when:** moving or reordering anything in `rustfs/src/startup_*.rs`, changing readiness publication, or touching shutdown ordering.
**Source of truth:** the `rustfs/src/startup_*.rs` modules listed below; readiness semantics in [readiness-matrix.md](readiness-matrix.md); global-state targets in [global-state-inventory.md](global-state-inventory.md).
Runtime and lifecycle work must preserve startup ordering, readiness behavior, and shutdown semantics.
## Startup And Readiness
- HTTP can listen early, but normal requests must remain behind readiness gates.
- Effective `FullReady = storage_ready && iam_ready && lock_quorum_ready &&
peer_health_ready`; `peer_health_ready` is true by default unless
`RUSTFS_HEALTH_PEER_READY_CHECK_ENABLE` is enabled.
- Boot phases must keep the old fatal and non-fatal boundaries.
- AppContext migration keeps context-first lookup with global fallback until the
global path is proven unused.
- HTTP can listen early, but normal requests stay behind the readiness gate.
- The `FullReady` formula, its dependencies, and the `RUSTFS_HEALTH_PEER_READY_CHECK_ENABLE` gate are defined once in [readiness-matrix.md](readiness-matrix.md); do not restate them elsewhere.
- Boot phases keep the existing fatal and non-fatal boundaries.
- AppContext migration keeps context-first lookup with global fallback until the global path is proven unused.
- Notify and audit lifecycle behavior must not drift during lifecycle movement.
- IAM and KMS startup, deferred recovery, and fatal boundary behavior must not be
changed by pure movement PRs.
- Request-surface and dependency details are tracked in
[`readiness-matrix.md`](readiness-matrix.md).
- IAM and KMS startup, deferred recovery, and fatal-boundary behavior must not be changed by pure movement PRs.
## Service Registry Scope
## Startup Module Ownership
`ServiceRegistry` is only for lifecycle and shutdown ordering. It must not become a
general dependency injection container.
Each module owns one concern; orchestration order is owned by `startup_services`, `startup_lifecycle`, and `startup_shutdown`. Movement PRs may pass handles between modules but must not reorder the steps a module owns.
Allowed responsibilities:
- Register start and stop order.
- Expose read-only status snapshots.
- Coordinate graceful shutdown.
Disallowed responsibilities:
- Construct arbitrary dependencies for business logic.
- Hide globals behind a service-locator API.
- Change startup side effects while moving code.
| Module (`rustfs/src/`) | Owns |
|---|---|
| `startup_entrypoint.rs` | CLI command dispatch into preflight and the runtime lifecycle. |
| `startup_preflight.rs` | License init, external env compatibility, runtime foundation bootstrap. |
| `startup_runtime.rs` | Runtime foundation orchestration; outbound TLS fatal boundary when configured material fails to load. |
| `startup_runtime_hooks.rs` | Startup diagnostics, profiling hook dispatch, default crypto provider installation. |
| `startup_tls_material.rs` | Outbound TLS material loading, global publication, generation recording, TLS metrics init. |
| `startup_runtime_sources.rs` | Process-local runtime source publication (port, buffer profile, KMS manager, TLS generation). |
| `startup_fs_guard.rs` | Unsupported-filesystem policy enforcement for endpoint paths. |
| `startup_deadlock.rs` | Deadlock detector state logging. |
| `startup_server.rs` | HTTP listener start and `ServiceStateManager` publication. |
| `startup_storage.rs` | Endpoints, local disks, ECStore, lock clients, global config, background replication init; `StorageReady`. |
| `startup_bucket_metadata.rs` | Bucket metadata system init, legacy meta-bucket import (`try_migrate_bucket_metadata`, `try_migrate_iam_config`), resync intents. |
| `startup_iam.rs` | IAM init, deferred recovery, `IamReady` publication. |
| `startup_auth.rs` | OIDC and federated identity setup. |
| `startup_notification.rs` | Notification system and bucket notification configuration. |
| `startup_audit.rs` | Event notifier and audit system start. |
| `startup_observability.rs` | Auto-tuner, update check, server info, compression totals. |
| `startup_background.rs` | Scanner, heal, bitrot self-test, workload-admission provider publication. |
| `startup_protocols.rs` | FTP/FTPS/SFTP/WebDAV sidecar start and shutdown senders. |
| `startup_optional_runtime_sidecars.rs` | Handles, shutdown planning, and shutdown execution for optional sidecars that are not readiness boundaries (currently protocol servers only). New sidecars enter here with explicit shutdown handles and status snapshots, not ad hoc work in `startup_services`. |
| `startup_services.rs` | Orchestration order of runtime service startup: KMS, optional runtimes, audit, metadata, IAM, auth, notification, background services, observability. |
| `startup_lifecycle.rs` | Ready publication, global init-time publication, scanner startup, shutdown-signal wait, shutdown delegation, final stopped-state log. |
| `startup_shutdown.rs` | The shutdown sequence (see below). |
| `startup_embedded.rs`, `startup_embedded_optional.rs` | Embedded-mode reuse of the phase owners above (see below). |
## Shutdown Lifecycle Boundary
`startup_shutdown` owns the main shutdown sequence after the process receives a
shutdown signal. Startup modules may pass handles into this boundary, but they
must not reorder runtime-token cancellation, background service shutdown,
optional runtime shutdown planning, notifier/audit/profiling shutdown, HTTP
shutdown, optional runtime waits, or final service-state publication.
`startup_shutdown` owns the main shutdown sequence after the process receives a shutdown signal. Startup modules may pass handles into this boundary, but they must not reorder runtime-token cancellation, background service shutdown, optional runtime shutdown planning, notifier/audit/profiling shutdown, HTTP shutdown, optional runtime waits, or final service-state publication.
## Startup Lifecycle Boundary
## Embedded Startup Reuse
`startup_lifecycle` owns the ready-to-shutdown orchestration after runtime
services initialize. Service modules may return initialized handles into this
boundary, but they must not reorder ready publication, global init-time
publication, scanner startup, shutdown-signal wait, shutdown delegation, or the
final stopped-state log.
## Startup Service Component Boundary
`startup_service_components` owns individual runtime service startup component
helpers while `startup_services` preserves their orchestration order. Migration
PRs must not change KMS, optional runtime, audit, metadata, IAM, auth,
notification, background service, or observability startup ordering while moving
these helpers.
## Optional Runtime Boundary
`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`.
## Startup Runtime Hook Boundary
`startup_runtime_hooks` owns runtime hook side effects that wrap the startup
foundation but are not TLS material loading: startup diagnostics, profiling
hook dispatch, and default crypto provider installation. `startup_runtime`
preserves BOOT-006 orchestration and outbound TLS fatal behavior, while
`startup_profiling` remains a compatibility handoff for the old profiling hook
path.
## Startup TLS Material Boundary
`startup_tls_material` owns configured outbound TLS material loading, global
outbound TLS publication, generation recording, and TLS metrics initialization.
`startup_runtime` still owns BOOT-006 ordering and must preserve the fatal
boundary when configured TLS material fails to load.
## Embedded Startup Phase Reuse
Embedded startup should use the same startup server and storage phase owners for
listen context, endpoint/local disk setup, storage runtime setup, readiness
publication, and replication startup. Embedded-specific behavior still owns its
stable-port requirement, one-shot global initialization guard placement, S3-only
HTTP listener, and non-fatal KMS/audit/notification policy.
## Embedded Runtime Service Reuse
Embedded runtime service setup should share startup service helpers for optional
service initialization, bucket metadata/IAM setup, notification setup, and
shutdown cleanup. Embedded-specific behavior still owns warning-only
KMS/audit/notification failures, no binary-only background sidecars, no state
manager, and the one-shot server handle cleanup used by embedded shutdown.
## Embedded Lifecycle Publication Reuse
Embedded ready publication should share startup lifecycle helpers for IAM
readiness publication, global init-time publication, and ready-state logging.
Embedded-specific behavior still owns server handle construction, endpoint
address normalization, and process-local shutdown cleanup.
Embedded startup reuses the same phase owners as the binary: server and storage phases for listen context, endpoint/local disk setup, storage runtime setup, readiness publication, and replication startup; service helpers for optional service init, bucket metadata/IAM setup, notification setup, and shutdown cleanup; lifecycle helpers for IAM readiness publication, global init-time publication, and ready-state logging. Embedded-specific behavior that stays in `startup_embedded*.rs`: stable-port requirement, one-shot global initialization guard placement, S3-only HTTP listener, warning-only KMS/audit/notification failures, no binary-only background sidecars, no state manager, server handle construction, endpoint address normalization, and process-local one-shot shutdown cleanup.
## AppContext Foundation
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).
AppContext is a context-first facade, not a full replacement for every process global. Resolver files are split and covered by compatibility tests before boot extraction or consumer migration, so the old global fallback path keeps working during transition. New migration work keeps fallback reads inside owner-local runtime-source boundaries and follows the target inventory in [global-state-inventory.md](global-state-inventory.md).