mirror of
https://github.com/rustfs/rustfs.git
synced 2026-07-02 02:34:20 +08:00
112 lines
4.8 KiB
Markdown
112 lines
4.8 KiB
Markdown
# Runtime And Lifecycle Contracts
|
|
|
|
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.
|
|
- `FullReady = storage_ready && iam_ready && lock_quorum_ready`.
|
|
- 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.
|
|
- 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.
|
|
|
|
## Service Registry Scope
|
|
|
|
`ServiceRegistry` is only for lifecycle and shutdown ordering. It must not become a
|
|
general dependency injection container.
|
|
|
|
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.
|
|
|
|
## 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 Lifecycle Boundary
|
|
|
|
`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.
|
|
|
|
## 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.
|