nx9-auth/docs/runtime-lifecycle.md

Runtime Lifecycle Subsystem

The nx9-auth runtime lifecycle subsystem provides an enterprise-grade, lock-free, deterministic architecture for application startup, dependency assembly, operational observability, background worker coordination, prioritized shutdown hooks, and graceful HTTP server termination.

Architecture Overview

CLI Commands / binary entrypoint (main.rs)
   │
   ▼
ApplicationBuilder
   │
   ├── Database Initialization (SQLite / PostgreSQL)
   ├── Repository Provider Assembly
   ├── AppState Construction
   └── Router Construction (Axum API + SPA UI)
   │
   ▼
Application Container (Lifecycle)
   │
   ├── AtomicRuntimeState Machine
   ├── SignalManager (SIGINT / SIGTERM)
   ├── ShutdownCoordinator (CancellationToken Hierarchy)
   ├── WorkerManager (Task Groups)
   ├── HookRegistry (Prioritized Shutdown Hooks)
   └── RuntimeMetrics
   │
   ▼
axum::serve (HTTP Server)

Lifecycle States (RuntimeState)

The state machine is lock-free and driven by AtomicU8 with compare_exchange transitions.

State	Value	Description
Initializing	0	Runtime configuration loading and dependency assembly.
Starting	1	Database connection pool init, migrations, router assembly.
Running	2	HTTP server bound and actively serving requests.
Draining	3	Shutdown signal received; server stops accepting new connections, draining existing HTTP requests.
StoppingWorkers	4	Cancelling and joining active background worker tasks.
ExecutingHooks	5	Executing registered shutdown hooks in priority order (First -> Normal -> Last).
ClosingResources	6	Closing database connection pools and flushing logs.
Stopped	7	All resources released cleanly; runtime process exits with status 0.

Startup Sequence

1. main() parses CLI flags and loads configuration via Config::find_and_load().
2. run_server() invokes Application::builder(config).build().await.
3. ApplicationBuilder creates Application and executes initialize().
4. initialize() transitions state to Starting, connects database pool, executes migrations, and builds Router.
5. app.start().await transitions state to Running, binds TcpListener, prints Listening on <addr>, and awaits axum::serve.

Graceful Shutdown Sequence

1. SIGINT (Ctrl+C) or SIGTERM signal received by SignalManager or ShutdownCoordinator.
2. axum::serve completes its graceful shutdown loop, stopping the TCP listener.
3. State transitions to Draining.
4. State transitions to StoppingWorkers; WorkerManager cancels and joins task groups.
5. State transitions to ExecutingHooks; HookRegistry executes registered hooks.
6. State transitions to ClosingResources; PoolHandle closes the database pool.
7. State transitions to Stopped; application returns Ok(()) with exit status 0.