Skip to content

App state

Where an app stands between its boot and its exit — the sequence App::run walks, and the AppLifecycle any provider injects to read it.

An app walks one fixed sequence from its boot to its exit, and every provider can ask where it stands on it: starting, serving, or draining and why. The lifecycle hooks bracket the serving window; AppLifecycle is what a loop, a factory or a hook reads in between.

crates/features/src/blog/service.rs
use std::sync::Arc;
use nest_rs::core::{AppLifecycle, AppState, injectable};
#[injectable]
pub struct BlogService {
#[inject]
lifecycle: Arc<AppLifecycle>,
}
impl BlogService {
pub fn serving(&self) -> bool {
self.lifecycle.state() == AppState::Ready
}
}

App::run walks a fixed sequence. The hooks bracket the serving window:

build container — Starting; `app starting`, with the binary and the framework
→ wire registries — events, health, social: filled before any hook
→ attach + configure transports
→ on_module_init ┐ strict, once — first error or panic aborts boot
→ on_application_bootstrap ┘
→ every transport listens — binds its port, checks its TLS material
→ Ready — `app ready`, with the addresses it listens on
→ serve (until SIGINT / SIGTERM, or a transport errors or ends on its own)
→ Draining — `app draining`, with its cause
→ transports stop — each within its own window, held by the kernel
→ on_module_destroy ┐ exhaustive — every hook starts, errors and
→ before_application_shutdown │ panics logged; five seconds between all of
→ on_application_shutdown │ them, what still waits then is abandoned
→ resources close │ the pool's goodbye, last opened first
→ the container drops ┘ every provider's `Drop`, off the runtime thread

Nothing serves until everything listens. Once the init hooks ran, each transport takes what serving needs — the HTTP transport binds its port and checks its TLS material — and only when every one has does the app turn Ready and the transports start serving. A port already taken fails the boot there, naming the step (the `listen` of transport `http` ), with the failed boot’s teardown, before the queue worker has consumed a single job. A transport that panics as it configures or listens fails the boot the same way, its panic one error line. A transport you write does its binding in listen, never in serve: one that binds in serve counts as ready before it is.

Shutdown is triggered by SIGINT / SIGTERM, or by the first transport that errors — or that stops serving on its own: a serve that returns before a stop was asked, Ok included, files error (transport stopped serving before the app was asked to stop) and fails the app. Either one turns the app Draining, which cancels the stop token every transport serves under; the teardown phases run once the last transport has stopped.

What a module opened, it closes. A resource module attaches a close to the handle it opened — SeaORM’s pool sends Postgres a goodbye on every connection rather than letting the sockets fall — and the closes run after every shutdown hook, so no hook finds its pool gone, the last opened first: a client a factory opened over a pool closes before the pool. Each runs by the hooks’ rules: a failure is logged at error, one still waiting when the budget is spent is abandoned at warn naming it, and the next still starts. Every unit of work has settled by then, so the pool waits half a second at most (SHUTDOWN_SETTLE_TIMEOUT) for a connection still on its way back: one a cut request left running a statement falls with the process, since sqlx hands it back with no goodbye, and one warn counts it. Then the container drops, on a thread of its own: a provider whose Drop blocks is abandoned at warn rather than holding the exit. A Valkey connection owes its server no goodbye, so Redis attaches none.

Some code needs more than a hook’s moment: whether the app serves yet, or why it is stopping. Every app carries one AppLifecycle, seeded before the first factory runs, so a factory, a constructor or a hook injects it like any other provider — and only the kernel moves it.

MethodAnswers
state()AppState::Starting from the start of the boot, Ready once every transport listens and they serve, Draining once a stop is asked
cause()None until the app drains, then why: StopCause::Interrupt (SIGINT, or Ctrl-C on Windows), Terminate (SIGTERM), TransportFailed (a transport returned an error, panicked, or stopped serving on its own), NoTransport (run found no transport attached, so nothing served), BootFailed (a transport’s configure or listen, or an init hook, failed before it served), Closed (App::close ended an app that was not serving)
stopping()a CancellationToken, cancelled the instant the app turns Draining
ready().awaittrue once the app is Ready, false once it drains, whether or not it served first

Each move is one info on nest_rs::app: app ready, with the transports it serves and the addresses they listen on — the real port when one was bound to 0 —, then app draining, with its cause (sigint, sigterm, transport_failed, no_transport, boot_failed or closed) and the signal when a signal asked. The first cause wins: a transport that fails while the app already drains for a SIGTERM leaves it at Terminate.

A loop running beside the app stops at stopping() — the instant a stop is asked, before the transports drain, so it is not still working when the shutdown hooks run. A constructor cannot await, so the loop starts in a hook and is joined in the provider’s own shutdown hook:

crates/features/src/blog/heartbeat.rs
use std::sync::Arc;
use std::time::Duration;
use nest_rs::core::{AppLifecycle, hooks, injectable};
use tokio::sync::Mutex;
use tokio::task::JoinHandle;
#[injectable]
pub struct Heartbeat {
#[inject]
lifecycle: Arc<AppLifecycle>,
beating: Mutex<Option<JoinHandle<()>>>,
}
#[hooks]
impl Heartbeat {
#[on_application_bootstrap]
async fn start(&self) {
let stopping = self.lifecycle.stopping();
let beating = tokio::spawn(async move {
loop {
tokio::select! {
() = stopping.cancelled() => return,
() = tokio::time::sleep(Duration::from_secs(10)) => {}
}
tracing::debug!(target: crate::blog::TARGET, interval_ms = 10_000, "heartbeat");
}
});
*self.beating.lock().await = Some(beating);
}
#[on_module_destroy]
async fn stop(&self) -> anyhow::Result<()> {
if let Some(beating) = self.beating.lock().await.take() {
beating.await?;
}
Ok(())
}
}

crate::blog::TARGET is the log target the feature declares at the top of blog/mod.rs once it logs — pub const TARGET: &str = "features::blog"; — since the blog feature nestrs new writes emits nothing and starts without one.

A shutdown hook that must know why the app stops reads cause().

A migration, a one-shot command, a test: some programs boot the app to do one piece of work, never to serve. They take the same way up and the same way down, without the transports:

apps/blog/src/bin/reindex.rs
#[nest_rs::main]
async fn main() -> anyhow::Result<()> {
let app = App::builder().module::<BlogModule>().build().await?;
app.init().await?;
let reindexed = match app.container().get::<SearchIndex>() {
Some(index) => index.rebuild().await,
None => Err(anyhow::anyhow!("BlogModule provides no SearchIndex")),
};
app.close().await;
reindexed
}

init() runs the init phases once, as run() would. close() turns the app Draining with StopCause::Closed, runs the shutdown phases in reverse when the init ran, closes the resources and drops the container — the same tail as run(), inside the same five seconds. It returns nothing: what fails on the way down is logged, never handed back. An app dropped without close() runs none of it. Under #[nest_rs::main], an app that is never served keeps running at the first signal, its stopping() cancelled, until it closes or a second signal exits it.

  • Lifecycle — the hooks that run on the way up and the way down.
  • Shutdown — every bounded step from the signal to the exit.
  • Health — the probes an orchestrator reads.