Lifecycle
Hook into the moments an app comes alive and winds down — #[hooks] tags methods for the init and shutdown phases the framework drains in order.
A binary has a beginning and an end. Between the container being built and the first request served, providers may need to warm a cache, open a long-lived connection, or check a migration ran. When the process receives a signal, those same providers want a chance to flush, drain, or report before the runtime tears down. The lifecycle hooks are where that work hangs.
A provider opts in by tagging methods on an impl block with
#[hooks]. Each tagged method names exactly one phase. The framework
collects every hook at link time and drains them phase by phase — init
phases after wiring and before serving, shutdown phases after the
transports stop.
use nest_rs::core::{hooks, injectable};
#[injectable]pub struct BlogService;
#[hooks]impl BlogService { #[on_application_bootstrap] async fn warm(&self) -> anyhow::Result<()> { tracing::info!(target: crate::blog::TARGET, entries = 0, "cache warmed"); Ok(()) }
#[on_application_shutdown] async fn flush(&self) { tracing::info!(target: crate::blog::TARGET, pending = 0, "buffers flushed"); }}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";, one
constant the feature’s files name, never a literal each one retypes. A
generated port emits nothing, so it starts without one.
The #[hooks] block is an impl of its own, beside the struct #[injectable]
decorates — a provider keeps its primary impl for methods, and adds a second,
hook-only impl the macro scans. The phase attributes
(#[on_application_bootstrap], …) need no import; #[hooks] consumes
them.
The host must be a singleton provider — the phases resolve it
with Container::get::<Host>(), outside any request, which answers for
exactly one registration shape. Three hosts can never satisfy that, and
all three are compile errors naming the fix rather than a notice at boot:
| Host | Why it cannot |
|---|---|
an edge host (#[controller], #[gateway], #[resolver], #[mcp]) | registers metadata; the instance is built at mount |
#[injectable(scope = request)] | the container holds a factory, not a value |
#[injectable(scope = transient)] | resolution would build a throwaway, and the hook’s effects would be dropped |
Each decorator records which of these it built, as
ProviderResidency::SINGLETON, and #[hooks] reads it. So the refusal
is not a marker you can satisfy by implementing it: contradicting what
your decorator already wrote is a coherence error. A provider you
register by hand with ContainerBuilder::provide is the one case nothing
has spoken for, and it says so itself:
impl ProviderResidency for MyHandWrittenProvider { const SINGLETON: bool = true;}A fourth shape is your composition rather than a contradiction, so it warns
at boot instead. A host the container holds under some other key has
nothing under Foo itself — imported through a for_root, or registered by
hand under a name or a trait. Move the methods to a provider listed under its
own type. A host bound as providers = [Foo as dyn Trait] is not one of them:
the binding holds its one Foo under its own type too, so the hooks run on the
instance every Arc<dyn Trait> consumer holds.
The five phases
Section titled “The five phases”Two run on the way up, three on the way down. They drain in this fixed order:
| Phase | Attribute | When |
|---|---|---|
| Module init | #[on_module_init] | After the container is built, its registries wired and transports configured, before serving. |
| Application bootstrap | #[on_application_bootstrap] | After every module-init hook has run, still before serving. |
| Module destroy | #[on_module_destroy] | After the transports stop. |
| Before shutdown | #[before_application_shutdown] | After every module-destroy hook has run. |
| Application shutdown | #[on_application_shutdown] | Last — after every before-shutdown hook has run. |
The container is flat, so the init pair isn’t about per-module
resolution order the way a tree-shaped framework would split them —
both run against the assembled container. The two names exist so you
can express “everyone’s on_module_init finishes before anyone’s
on_application_bootstrap starts”: late hooks see the side effects of
early ones. The three shutdown phases give the same staged unwind in
reverse-intent order: each module tears its own down, dependents first, then
before_application_shutdown does what spans modules, then
on_application_shutdown runs last, before the resources close.
They start once every transport has stopped, never at the signal: a
request, a job or a socket message still running uses the providers they tear
down, so none is torn down under it. The one exception is a transport still
serving past the bound it states: the kernel abandons it there, and the hooks
start anyway (the way down). Work due at the signal itself —
stop starting new work, end a loop — waits on
stopping() instead, and taking the replica out of
the load balancer is the platform’s
(leaving the load balancer first).
Method shape
Section titled “Method shape”A hook method takes &self, and is an async fn or a plain fn — only
an async fn is awaited. Its return is either:
- nothing — the hook is infallible (
async fn flush(&self)), or Result<(), E>whereE: Into<anyhow::Error>— the hook can fail, and the framework folds the error into the phase outcome.
#[on_module_init]async fn check(&self) -> Result<(), MyError> { /* ... */ Ok(()) } // fallible
#[on_module_destroy]async fn drain(&self) { /* ... */ } // infallibleA hook that needs another provider injects it — there is no
attribute to declare “run after OtherService’s hook.” The injection is
the declaration: the DI graph orders the hooks, as the next section shows.
Ordering and failure
Section titled “Ordering and failure”Within a phase, hooks run one at a time, dependencies first: a provider’s hooks run after the hooks of every provider it injects, at any depth. The three shutdown phases run in the exact reverse, so a repository flushes before the pool it writes through closes, and a client a service used at init is still connected while that service tears down.
use std::sync::Arc;
use nest_rs::core::{hooks, injectable};
use crate::blog::BlogService;
#[injectable]pub struct PostsService { #[inject] blog: Arc<BlogService>,}
#[hooks]impl PostsService { #[on_application_bootstrap] async fn warm(&self) { /* ... */ }
#[on_application_shutdown] async fn flush(&self) { /* ... */ }}PostsService injects BlogService, so its warm runs once
BlogService::warm has returned, and its flush runs before
BlogService::flush starts.
Hosts the graph does not order follow the composition, the same way in
every build: an imported module’s hosts run before the module importing
it, imports in the order imports = [...] lists them, then each module’s
providers = [...] from left to right. A host no module lists — a value
seeded with provide, a factory’s output, a provider a hand-written
Module registers — runs before every listed one at init and after them
at shutdown, and those hosts run among themselves by type name, then
module path. A host’s own hooks run in the order its impl declares
them; spread over several impl blocks, they follow the module each
block sits in, then that order, then the method name, so keep them in
one impl to choose. For every host a module lists, names never decide:
renaming it moves nothing.
A provider reached only through Container::get has no edge in the
graph, so nothing orders its hooks against yours. Inject it to order it.
The two halves of the lifecycle treat failure differently, and deliberately:
- Init is strict, and runs once.
on_module_initthenon_application_bootstraprun one hook at a time; the first error aborts boot with a message naming the hook’s module, provider, method, and phase. Nothing is listening yet, so a failed warm-up never leaves a half-started server accepting traffic.App::init()andApp::run()share the phases: whichever comes second skips them, and after an init that failed both returnInitFailedErrorwithout running a hook again. - A failed boot still tears down. What the hooks that did run took — a
lease, a discovery registration, a connection — would otherwise leak until
it expired, so an init that fails, panics or is stopped by a signal runs the
three shutdown phases, in reverse, for every host, then closes the
resources, before it returns its own error. One
warnonnest_rs::lifecycleopens it,the boot failed after init hooks ran: running the shutdown hooks, naming the failed hook. So write a shutdown hook to tolerate an init that never ran:if let Some(..)on what the init would have filled, never anexpect. - Shutdown is exhaustive. The three teardown phases start every hook
even if one fails or panics — either is logged at
erroron thenest_rs::lifecycletarget, naming the hook, and the next hook still runs, so one provider’s botched cleanup can’t skip another’s. (At init a panic aborts the boot like an error does, with the same sentence naming the hook.) - Shutdown is bounded — once, for all of it. The three phases share one
five-second budget (
SHUTDOWN_HOOKS_TIMEOUT), not five seconds each: a hook still waiting when it is spent is abandoned — dropped where it waits, so what it had not done stays undone — and awarnnames its phase, provider, method and module. Every hook after it still starts, and is polled once: one that finishes without waiting (a count logged, a buffer handed to a channel) finishes, one that waits is abandoned at once, with its ownwarn. The bound reaches a hook that awaits; one that blocks its thread is past any timer’s reach.
The budget is one of the bounded steps on the way down, and it is sized against their sum. A bound per hook could not hold a sum — four hooks that hang would spend twenty seconds — which is why it is a budget.
Error: the `#[on_module_init]` hook `MigrationGuard::check` in `api::migrations` failed
Caused by: pending migrationsA hook is a unit of work
Section titled “A hook is a unit of work”Each hook runs as one lifecycle.hook unit of work, the way a request or a
scheduled tick does. It gets a trace of its own — a hook has no caller — and
files one line on nest_rs::operation when it ends, with its phase,
host, method, origin and outcome. A shutdown hook abandoned at the
budget, or an init hook a signal stopped, files outcome="cancelled".
It also gets the data context a tick gets. With SeaOrmDatabaseModule
imported, a hook runs in one transaction, opened on its first data-layer touch,
committed when it returns Ok and rolled back on an error, a panic or an
abandonment at the budget. So a hook reaches the database through its service and Repo, like
any handler:
#[hooks]impl UsersService { #[on_application_shutdown] async fn report(&self) -> Result<()> { let count = Repo::<Users>::scoped(Action::Read).count().await?; tracing::debug!(target: crate::users::TARGET, count, "users present at shutdown"); Ok(()) }}A hook is system work: no ability is attached, so Repo reads unscoped, as a
job does. A commit that fails is the hook’s error, so at init it aborts the
boot. An event the hook emits waits for its commit, and each listener runs in a
transaction of its own. Shutdown hooks run before the pool closes, so they have
it too. With no database binding imported, a hook runs bare.
Common things a hook does
Section titled “Common things a hook does”- Init — warm a cache, verify migrations applied, register with a service discovery backend, prime a connection pool, assert an external dependency is reachable (fail boot if not).
- Shutdown — flush a buffer, deregister from discovery, emit a final metric or report, all of it inside the five-second budget. Draining in-flight work belongs to a transport’s own window, which a deployment sets.
The UsersService in the Publish workspace uses
#[on_application_shutdown] to count its users through Repo at teardown —
a one-method #[hooks] block beside the service’s main impl, shown
above.
Going further
Section titled “Going further”- Shutdown — every bounded step from the signal to the exit, the shutdown hooks’ budget among them.
- App state — the sequence
App::runwalks, and a program that runs it without serving. - Providers — the things that own hooks;
built once, shared as
Arc<T>. - Testing / e2e — booting the real
ApiModule, whereApp::init()drives the init phases.