Glossary
One-line definitions for the vocabulary NestRS uses across the docs.
The docs lean on a small set of recurring terms — shaper, endpoint guards, ambient context, masking. This page collects them in one place with a one-line definition and a link to the canonical page that goes deep on each.
Container and wiring
Section titled “Container and wiring”- Module — the composition unit; a struct
decorated with
#[module]that owns a flat list of providers and imports other modules. - Provider — anything
#[injectable]the container builds once and shares asArc<T>(singleton by default, request-scoped on opt-in). - Container — the single flat
type-id-keyed map the framework builds at boot; reachable through
#[inject]fields on a provider, never named directly. - Access graph — the boot-time check that
every
#[inject]and every guard/interceptor/filter the provider declares is reachable through its module’s imports; the boot fails with a clear graph error otherwise. - Discovery — the link-time
inventorysweep each transport runs to find its endpoints; gated by the access graph so only items reachable from the running app’s root are mounted. - Dynamic module — a module produced by a
call like
OpenApiModule::for_root(opts); the same#[module]shape but parameterised at the import site. - Instance
— one of several copies of a resource an app opens, told apart by a marker
type declared with
#[instance]; the default one,Unnamed, needs no marker, and a named one’s variables carry its name after the vendor.
Request layers
Section titled “Request layers”- Shaper — what the
#[routes]expansion selects by type off a route’s posture: its class gate, and whether the route reads under the caller’s ability, as an entity’s posture does. A shaper is plumbing the framework writes, never a unit you declare. - Guard — a pre-handler gate; returns
Ok(())to let the request through or a typedDenialmapped to 401/403/429, and may attach context a handler on any edge reads throughAmbient<T>. - Endpoint guards —
EndpointGuards<V, (G1, …)>, the guards a module adds to the request of/graphqlor/mcp, beside the global pool; what they attach is ambient for every operation the request carries. - Pipe — a stateless edge transform that
parses a single input, never a DI provider; bound to a handler argument
through
Piped<P, E>on HTTP andPiped<P>on every other edge. Validation needs none: each edge holds what it decoded to its type’s rules. - Interceptor — wraps a unit from the
outside, after its guards; one declared
#[interceptor(stage = unit)]runs around them, the seam that appends aServer-Timingentry. - Exception filter —
answers a failure whose source chain carries its
Exceptiontype, or every failure withdyn Error + Send + Sync; bound with#[use_exception_filters(...)], the method’s tried first. The unit stays failed whatever it answers. - Ability shaper — the
Authorize<A, S>wrapper the#[routes]macro emits when a route declares#[authorize(A, S)]or#[public(A, S)], never a parameter; declares the route’s class gate and opens its reads under the caller’s ability. Layer order. - Unit — one piece of work the framework dispatches and files one operation line for: an HTTP request, a GraphQL field, a WebSocket message, an MCP operation, a job’s attempt, a tick, a listener call. Every layer runs around a unit.
- Site — one place a unit is dispatched: a route, a field, a message, a tool, a worker method, a self-mount’s request, what the router answers itself. Its chains — the unit stage, the guard stage and the class gate, the exception filters, the handler stage — are composed once per app; the stages run in the order the request lifecycle gives.
- Unit context — the
UnitContextevery layer is handed: which unit, which handler, what it declared, what it carries, and the edge’s view of it. - View — an
edge’s own reading of its unit (
HttpView,GraphqlView,WsView,McpView,QueueView,ScheduleView,EventsView), reached throughcx.switch_to::<V>(); a layer answers or settles the unit through it. - Outcome — what an interceptor returns: the unit ran, or a layer answered it in its place. Only running the rest of the unit or answering it produces one, and a failure stays a failure whatever a layer answers.
- Reflector — the reader that pulls back the values a handler or its
host declared with
#[meta(EXPR)], and its posture; a layer reaches it throughcx.reflector()on every edge. - Problem —
nest_rs::core::Problem, the one client-error contract: a status, aCodeand a detail, which each edge renders in its own form — a problem document on HTTP,extensions.codeon GraphQL.
- Repo — the single audited DB
gateway every service uses; runs every query against the ambient
executor and folds the ambient ability’s
condition_forinto reads and by-id writes. - CrudService — the entity’s API choke point
(
list/page/access/create/update/delete); controllers, resolvers, and gateways delegate, never touchRepodirectly. - Executor — the data layer’s trait
for the handle a unit of work installs in the ambient context; SeaORM’s is
the pool on safe routes or a transaction on mutations. Every
Repocall runs on it, and nothing hands it to a service. - Ambient context —
the values a unit of work carries for the code it calls (the executor,
the ability, a package’s own), so singletons read per-request state
without an argument on every method; each value’s
AmbientValue::carrysays how far it travels — into a streaming body, a DataLoader batch, a spawned task, after-commit work, a socket’s next messages. - Bound subject —
#[authorize(Action, bind = Service)]: parses the id from the URL (anidargument on GraphQL), callsService::access(action, id)through the ambient ability, and hands the loaded + authorized entity to the operation’sAuthorized<Action, E>parameter (404 absent, 403 denied). scope_for— the explicit-condition counterpart to a bound subject; hands a hand-built query a SeaORMConditionderived from the ambient ability.#[expose]— the opt-in read-side exposure attribute on an entity column or relation: a column crosses HTTP/GraphQL/WS only with#[expose], silence = hidden — fail-secure on schema evolution. The struct-level form emits the wire DTO;input(...)on a field opts it into the generated create/update input types — the write side is opt-in the same way.- Wire model — the
#[expose]output struct (User) the wire produces; distinct from the SeaORMModelthe database returns. - Nullable column
—
#[expose(nullable)]on a column of a type with no null: a grant onReadmay withhold it, and its wire field then readsnull. AnOptioncolumn is one already; a grant withholding any other column fails when the ability builds.
Security
Section titled “Security”- Strategy — a plain
#[injectable]that turns a request into a principal;AuthnGuard<S>is generic over it. - Principal — the typed identity a
strategy returns (
Claimsfor JWT, a session for OAuth); read back in a handler throughAmbient<P>. - Ability — the policy object the authz guard installs for the request; answers “may this caller take this action on this subject?” against rules, predicates, and field grants.
- Subject — what an ability
rule targets: an entity (
users::Entity), or a capability no table holds that#[subject]declares (Transcoding); how an action is scoped to a type. Note the vocabulary: the subject is the resource type acted upon, never the caller — the caller is the principal. - Action — the verb a rule
governs (
Read,Create,Update,Delete, custom variants); the same enumRepo::scopedkeys on. - Predicate — the row-level
condition a rule attaches to an action (
org_id = $caller_org_id); whatcondition_forlifts into SQL. - Field set — the column list
a rule grants on
Read; what a wire row holds, every other exposed column readingnull. - Masking — withholding a
column from a caller: each wire row is judged on its whole
ModelwhereFrom<&Model>builds it, a withheld column no value in it. Nothing reads a reply back. - Row-level filtering
—
Ability::condition_forjoined into the SQL byRepo::scoped, so every read returns only rows the ability allows. - Resource server vs authorization server — the split-deploy pattern: the issuer app holds the signing key and mints tokens; the resource server holds only the public key and verifies them.
Transports
Section titled “Transports”- Transport — what serves the app: the HTTP server, the queue worker, the scheduler; each runs a discovery sweep to find its decorated items and mounts only those reachable from the running app’s root. GraphQL, WebSockets and MCP are self-mounts on the HTTP transport, not transports of their own.
- Self-mount — an edge that mounts onto
HttpTransportinstead of being its own transport, inheriting its port, CORS, and TLS: the WS#[gateway],/graphql, MCP, and OpenAPI all self-mount, each declaring aHandlerwhose posture (Gated,InBand,Public) decides how the global guard chain reaches it. - Controller (HTTP) — a struct marked with
#[controller(path = "...")]that owns route methods declared in a#[routes] implblock. - Resolver (GraphQL) — a struct
marked with
#[resolver]whose#[operations]impl block holds the#[query]/#[mutation]/#[field_resolver]methods that compose into the schema at boot; every#[query]/#[mutation]declares an access posture —#[authorize(Action, Subject)],#[public(Action, Subject)]or a bare#[public]. - Gateway (WS) — a struct marked with
#[gateway(path = "/ws")]whose#[subscribe_message]methods handle WS events; self-mounts onHttpTransport. - Processor (queue) — a provider whose
#[processor]impl block holds#[process(queue = …)]methods that consume jobs; run by the port’sQueueWorkertransport, attached by theQueueModuleit brings. - Scheduler — the transport that drains
#[scheduled]orchestrators; each method tagged with exactly one of#[every]/#[cron]/#[after].
Observability
Section titled “Observability”- Probe vs Indicator — a probe is one of
the three HTTP routes (
live/ready/startup); an indicator is a unit the probe aggregates (the one a resource the framework opens attaches, a custom one).
- Modular monolith, deployed per workload —
the architecture NestRS builds: the domain written once, as modules in
crates/features, and deployed as one binary per workload, or as one binary from the same modules. As proposed, the binaries share the code and the database, hand work over through the queue, and the framework generates no RPC between them. - Workload — one deployable binary with one
operational job (the HTTP API, the WS server, the token issuer, the
queue worker). One product splits into several workloads that share
crates/featuresand the database but never RPC each other. - Workspace — the shape
nestrs newscaffolds: a monorepo hosting one binary per app underapps/<name>/, over a sharedcrates/features. One app is the starting point; a second workload is anothernestrs newinside it. An app that needs a database of its own is a workspace of its own, in its own repository. - Port + adapters — the per-feature
folder shape: the port (
entity.rs,service.rs,dto.rs,error.rs,module.rs) at the root, one sub-folder per transport adapter (http/,graphql/,ws/,queue/,mcp/).