Provider scopes
Singleton, request or transient: when the container builds a provider, what shares it, and how a handler reaches one that is not a singleton.
A provider is built once at boot unless it says
otherwise. #[injectable(scope = …)] picks one of three lifetimes; this page is
when each is built, what shares it, and how a handler reaches one that is not a
singleton.
#[injectable] // singleton — defaultpub struct PostsService { /* ... */ }
#[injectable(scope = request)] // one instance per requestpub struct RequestLogger { /* ... */ }
#[injectable(scope = transient)] // fresh instance every resolutionpub struct IdGenerator { /* ... */ }| Scope | Built | Shared as |
|---|---|---|
singleton (default) | Once at boot | Arc<T> everywhere |
request | Once per request | Cached for that request |
transient | On every resolution | Never cached |
A type has one provider, whatever its scope. Listing it in two modules, or
registering it once as a singleton and once request-scoped, fails the boot with
a DuplicateProviderError naming both registrations and, when they differ,
both scopes.
Singletons — PostsService, PostsController, the DB pool: built at
boot, injected as Arc<T>.
Request-scoped providers
Section titled “Request-scoped providers”Request-scoped — may inject singletons; singletons may not
inject request-scoped types (they exist before any request). Reach them
through the request boundary, not #[inject] on a singleton:
use nest_rs::core::Scoped;
#[get("/trace")]async fn trace(&self, log: Scoped<RequestLogger>) -> String { log.line("listed posts"); "ok".into()}A Scoped<T> parameter is inside the access contract, like an
#[inject] field: RequestLogger must be provided by the controller’s module
or a module it imports. One reached through no import fails the boot with an
AccessGraphError, and one no module provides with a
MissingDependencyError naming it — never a 500 at the first request. A
request-scoped provider is the point of the parameter, so the boot checks where
it comes from, never its scope. A route or an operation declaring
#[authorize(A, bind = S)] is held the same way for the service S it loads
through, and for the unit of work that load runs in, which
SeaOrmDatabaseModule binds.
HTTP, WebSockets, GraphQL, and MCP each install a fresh request scope per call
(one per request for HTTP and MCP — every operation one /mcp request or one
GraphQL POST carries shares it — one per message for WebSockets, one per
operation on a graphql-ws socket, a subscription’s for as long as it streams).
Within a scope, request-scoped providers are cached and shared; across scopes,
fresh instances are built. A WebSocket message, a GraphQL resolver and an MCP
operation take them as the same parameter a route does, nest_rs::core::Scoped<T>
— no schema argument on GraphQL, and inside the access contract on all four. A
request-scoped provider may itself inject another request-scoped provider (both
share the per-request cache); providers waiting on each other fail the boot,
naming the chain (ProviderCycleError).
Transient providers
Section titled “Transient providers”Transient — rebuild on every Scoped<T> / get::<T>() extraction.
Use for throw-away per-call state (a one-shot builder — never a
correlation id, which the framework already carries). A transient that
depends on itself, directly or through others, fails the boot the same way.
Going further
Section titled “Going further”- Providers — what the container builds, and the
access graph a
Scoped<T>parameter joins. - Extractors —
Scoped<T>on a route, beside the other parameters a handler takes. - Lifecycle — the hooks a singleton runs as the app comes alive and winds down.