Writing a package
Ship a crate other NestRS apps import: its manifest and names, a module that owns its configuration, the resources it opens and closes, and its tests.
A package is a crate an app adds beside the umbrella and imports as a module: its providers, its configuration under its own namespace, the resources it opens and closes when the app ends. At the end of this page your module boots in every app that imports it, in none that does not, and your tests boot it the same way.
A module that owns a configuration reads it from its bare import, and offers
one for_root taking the value an app pins:
#[module(providers = [AcmeClient])]pub struct AcmeModule;pub type AcmeSetup = ConfigSetup<AcmeModule, AcmeConfig>;
impl AcmeModule { pub fn for_root(config: AcmeConfig) -> AcmeSetup { ConfigModule::setup(config) }}AcmeClient injects Arc<AcmeConfig>, and that injection loads the config,
so a bare AcmeModule import reads its variables; for_root pins the base
those variables overlay, field by field, and takes no None: nothing pinned
is the bare import. A second pin of the same config fails the boot, naming both
imports: one config has one seam. A module that reads its config only in a
register of its own, injecting it nowhere, queues it from its collect with
ConfigModule::provide_feature::<Unnamed, AcmeConfig>(builder), and a
hand-written setup pins it with ConfigModule::provide_root(config, builder).
The manifest and the names
Section titled “The manifest and the names”Your crate depends on the umbrella alone, at the minor it builds against, with
the default features off and the capabilities it uses named —
the semver page’s manifest rules give each its
reason. Its name is
nestrs-<subject>, and every name it owns is rooted at that crate: its path,
its span target, its units, its configuration namespace, its datastore keys
and its health indicators (Naming a package).
nestrs-acme reads <PREFIX>_ACME__* and logs on nestrs_acme, so
nest_rs=off never silences it.
Its configuration
Section titled “Its configuration”A #[config] struct names its namespace, and each field reads the variable
its name spells over the base it is handed — Default, or the value an app
pinned:
#[config(namespace = "social_probe")]#[derive(Clone, Debug)]pub struct ProbeSocialConfig { /// The OAuth client id. #[validate(length(min = 1))] pub client_id: String, /// The OAuth client secret. #[validate(length(min = 1))] pub client_secret: Secret<String>,}A credential is a nest_rs::core::Secret, so the struct derives Debug and
still prints <redacted> in its place; the code that needs the value reads it
with expose_secret().
Every field is settable both ways — from <PREFIX>_SOCIAL_PROBE__CLIENT_ID
and from a pinned struct — and a field your users can only reach one way is a
setting missing from the other. A field you add in a minor is a minor for your
users too, provided they build the struct as the
semver page says.
A resource it opens
Section titled “A resource it opens”What your module opens — a client, a pool — is a factory that names the
outputs it reads as its inputs, so the boot runs it once they exist,
wherever the imports fall. It reads the config with ConfigModule::resolved,
whose refusal names the config when nothing resolved it:
pub struct Bucket(String);
pub struct BucketSetup(BucketConfig);
impl DynamicModule for BucketSetup { fn module() -> TypeId { TypeId::of::<Self>() }
fn collect(&self, builder: ContainerBuilder, _: Collecting<Self>) -> ContainerBuilder { ConfigModule::provide_root(self.0.clone(), builder) .provide_factory_after::<Bucket, (BucketConfig,), _, _>(|container| async move { let config = ConfigModule::resolved::<BucketConfig>(&container)?; Ok(Bucket(config.name.clone())) }) }}Declare how long it waits. A resource that waits on a server — for a
connection, for a reply — has a budget, and the boot holds every budget below
each net that waits on the resource: a ThrottlerGuard that gives up after
18 seconds must never wait on a client that gives up after 30. Declare it
beside the factory, read off the value it opened:
pub(crate) fn declared_budget() -> nest_rs_core::Budget { nest_rs_core::Budget::of::<Self>( "the Redis connection", RedisConfig::CONNECT_TIMEOUT.var_or_field(RedisInstance::of::<I>().namespace()), |conn| Some(conn.budget()), )}A budget at or past a net reaching it fails the boot with
BudgetPastNetError, naming the resource, the port and the setting that
lowers it. A port you bind declares its net over the resource, and its TLS
and its proof at boot follow the same contract: each
driver page shows the three
steps in the same order.
Close what you opened. provide_close hands the kernel a close for the
value, run once the app ends, after every shutdown hook, the value installed
last closing first — one step of the way down:
impl Module for PoolModule { fn register(builder: ContainerBuilder, _: Registering<Self>) -> ContainerBuilder { builder .provide(Pool) .provide_close::<Pool, _, _>(|pool| async move { pool.goodbye().await }) }}A close for a factory’s output is attached in collect, beside its factory:
a boot whose later factory fails then closes what the earlier ones opened,
which a close attached in register would never reach. A value the app was
handed instead — a seed, a test’s override — is not yours to close, and the
kernel skips it. The database driver page
shows a pool’s close that waits for the units still settling.
A resource an app may open more than once is generic over its instance:
I: Instance = Unnamed on the resource, its setup and each binding, its bare
import typed (AcmeModule::<Cache>), the config queued with
ConfigModule::provide_feature::<I, C> and read with
ConfigModule::resolved_for::<I, C> under the instance’s namespace — as
RedisModule::<Cache> opens a second Valkey. A binding your package ships over
the resource imports its module bare, from both phases, by its instance, so an
app writes the binding and names the resource only to pin it. The resource’s key
is the app’s own type, which no DependencyRemedy can be filed under, so the
type carries the line a provider injecting it unopened is told:
impl<I: Instance> CarriesRemedy for Pool<I> { fn remedy() -> Cow<'static, str> { match I::NAME { "" => "Import `acme::PoolModule`, which opens the default pool.".into(), name => format!("Import `acme::PoolModule` for the `{name}` instance.").into(), } }}A registry it fills
Section titled “A registry it fills”A module that collects what the app declares — handlers, routes, listeners — fills its registry once, from the assembled container, through a wiring step:
impl Module for RecipesModule { fn register(builder: ContainerBuilder, _: Registering<Self>) -> ContainerBuilder { builder.provide_wiring("acme::recipes::catalog", |_container| Ok(())) }}It runs after the container is sealed and before any transport is built or
any lifecycle hook runs, so a hook reads the registry full. It is synchronous:
nothing in it waits on I/O. The first wiring that fails ends the boot with
WiringFailedError, naming the registry by the string you gave it. What a
decorator of yours registers is read there, gated on the app’s imports — see
Writing a decorator.
A value every unit carries
Section titled “A value every unit carries”A per-unit value your package provides — a tenant, a locale — becomes ambient
because its type implements nest_rs::core::AmbientValue, and a layer of
yours attaches it to the unit with cx.attach(..). Everything the unit
reaches reads it back, and its carry decides which continuations it crosses
into: what a unit carries
is the whole contract. Reading is not deciding: an authorization decision
still belongs in a guard.
Test it
Section titled “Test it”Your suite boots your module the way an app does. A package that serves no
HTTP boots headless, which compiles without the http feature:
#[injectable]struct Transcoder;
#[module(providers = [Transcoder])]struct WorkerModule;
let app = HeadlessApp::builder().module::<WorkerModule>().build_headless().await?;assert!(app.container().get::<Transcoder>().is_some());app.close().await;TestApp::for_module::<M>() boots one with HTTP. Both seal the app’s
composition as App::run does, so what your module discovers is gated in the
test as in production. A test against live services shares them with every
other suite: it takes a database, a Redis database and a bucket of its own as
end-to-end tests do, and what it files where nothing drains,
it names uniquely and deletes.
Your providers live only where your module is imported. nestrs-hooks-probe,
a package-shaped fixture of nest-rs-core’s suite, declares a #[hooks] host
that an app without its HooksProbeModule never runs: the boot says so once
at debug, with cause="dependency" and a hint naming the module.
What your users build on
Section titled “What your users build on”Your crate is a dependency in someone’s app, and the same policy binds it: its public items, its decorator keys, its variables and their defaults, its span target, its unit names and its datastore keys are what your users match, and a change to any of them is a major of your crate. The list is NestRS’s own, on the semver page; yours follows it.
What fails if you get it wrong
Section titled “What fails if you get it wrong”- Two
for_rootpins of one config fail the boot withContestedDeclarationError, naming both imports. - A namespace two crates read fails the boot, naming the pair.
- A budget at or past a net fails the boot with
BudgetPastNetError. - A close attached in
registerfor a factory’s output never runs when a later factory fails the boot, and your client stays open until the process exits. - A request-scoped or transient layer on a job, a tick or a listener your
package declares fails the boot with
ScopedLayerError: such a site resolves its layers once, at boot. Make the layer a singleton. - A seed your module’s check refuses — a config a test hands a container
it builds by hand — fails
buildwithContainerError::SeedRefused, as the value your factory read would have been refused.
Going further
Section titled “Going further”- Writing a transport — serve something of your own, or a surface over HTTP.
- Writing a decorator — an attribute your users write, and the registry it fills.
- Configuration — the cascade your namespace is read through.