Module boot
The four phases a boot runs over the import tree, what is global and what an import gates, and why a module imported twice builds once.
Modules declare what they own and what they import; this page is what the boot does with that tree — the phases it runs, which values every provider reaches and which an import gates, and why a module two branches import is still built once.
Boot sequence
Section titled “Boot sequence”App::builder().build().await runs four phases, in order:
- Seeds — runtime values from
mainvia.provide(value). A seed wins over a factory of the same type; a seed of a type a module lists is a duplicate the boot refuses — a test replaces a provider with an override. - Collect — every imported module queues the async factories it
declares (DB pools, …), a dynamic module’s from its
collect. - Factories — the queue is awaited; outputs land in the container as global infrastructure.
- Register — every imported module builds its providers in
dependency order, its imports first. A provider whose dependency nothing
had registered yet — across an import cycle, or a type a hand-written
module registers later — fails the boot naming it and why
(
UnbuiltProviderError).
What is global
Section titled “What is global”What a seed or a factory makes is app-global: any provider may inject
it, whichever module queued it. What a module lists in providers is
import-gated: only that module and the modules importing it, at any
depth, reach it. The framework’s global outputs are the infrastructure an app
opens once:
- every
#[config]a module reads; - the connections —
DatabaseConnection, andRedisConnectiononce per instance; - the backend a binding plugs into a port —
dyn UnitOfWork, the queue’sJobs,dyn ThrottlerStore,dyn OccurrenceLock— and theThrottlerGuardover its store; JwtServiceandOAuthClient;- the kernel’s own:
AppLifecycle,ReachableProviders,ProviderOrderandComposition.
A value you seed with App::builder().provide(value) joins them. Global is
no licence for data access: a connection is still reached through a service
and Repo.
What a hand-written module installs in its own register — EventsModule’s
EventBus, OpenTelemetryModule’s Metrics — is neither global nor gated:
the access graph does not see it. A provider registered after it reaches it with no import, and
one registered before it fails the boot (UnbuiltProviderError, naming the
module), so import the module that installs it and it registers first. In a
module of your own, open app-wide infrastructure in a factory, and list what you gate in
providers.
Safe to import twice
Section titled “Safe to import twice”The framework runs each phase of a module once, however many modules import it, and a module’s collect before its register — a module never reaches another’s phases but through an import. A diamond import — two branches that both reach the same module — still builds that module’s providers once:
#[module(imports = [Common])]pub struct B;
#[module(imports = [Common])]pub struct C;
#[module(imports = [B, C])]pub struct A;flowchart TB A --> B A --> C B --> Common C --> Common
Common’s providers are registered once, not twice.
The same holds for a framework module you configure. Every controller brings a
bare HttpModule, and an app pinning it with
HttpModule::for_root(...) still runs one server; GraphqlModule, which
every resolver brings, mounts /graphql once, and McpModule, which
every #[mcp] host brings, reads <PREFIX>_MCP__* once. What a setup wires per
app — its transport, its mount, the close of what it opened — sits in the
module it imports by type, and an app runs one transport of each type.
What two imports cannot both have is a value each one chose. Two pinned
configs for one module, or two MCP server identities, fail the boot naming
both imports before anything is built — here BlogModule pins a port and so
does the PostsHttpModule it imports:
contested declaration: `HttpConfig` is declared twice — by `HttpModule::for_root(..)`at `imports[0]` of `BlogModule`, and by `HttpModule::for_root(..)` at `imports[0]`of `PostsHttpModule`. A config has one seam — pin it once, on the `for_root` ofthe module that owns it, and let every other import of that module stay bare.