Skip to content

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.

  • 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 as Arc<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 inventory sweep 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.
  • 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 typed Denial mapped to 401/403/429, and may attach context a handler on any edge reads through Ambient<T>.
  • Endpoint guards — EndpointGuards<V, (G1, …)>, the guards a module adds to the request of /graphql or /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 and Piped<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 a Server-Timing entry.
  • Exception filter — answers a failure whose source chain carries its Exception type, or every failure with dyn 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 UnitContext every 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 through cx.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 through cx.reflector() on every edge.
  • Problem — nest_rs::core::Problem, the one client-error contract: a status, a Code and a detail, which each edge renders in its own form — a problem document on HTTP, extensions.code on GraphQL.
  • Repo — the single audited DB gateway every service uses; runs every query against the ambient executor and folds the ambient ability’s condition_for into reads and by-id writes.
  • CrudService — the entity’s API choke point (list/page/access/create/update/delete); controllers, resolvers, and gateways delegate, never touch Repo directly.
  • 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 Repo call 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::carry says 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 (an id argument on GraphQL), calls Service::access(action, id) through the ambient ability, and hands the loaded + authorized entity to the operation’s Authorized<Action, E> parameter (404 absent, 403 denied).
  • scope_for — the explicit-condition counterpart to a bound subject; hands a hand-built query a SeaORM Condition derived 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 SeaORM Model the database returns.
  • Nullable column — #[expose(nullable)] on a column of a type with no null: a grant on Read may withhold it, and its wire field then reads null. An Option column is one already; a grant withholding any other column fails when the ability builds.
  • Strategy — a plain #[injectable] that turns a request into a principal; AuthnGuard<S> is generic over it.
  • Principal — the typed identity a strategy returns (Claims for JWT, a session for OAuth); read back in a handler through Ambient<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 enum Repo::scoped keys on.
  • Predicate — the row-level condition a rule attaches to an action (org_id = $caller_org_id); what condition_for lifts into SQL.
  • Field set — the column list a rule grants on Read; what a wire row holds, every other exposed column reading null.
  • Masking — withholding a column from a caller: each wire row is judged on its whole Model where From<&Model> builds it, a withheld column no value in it. Nothing reads a reply back.
  • Row-level filtering — Ability::condition_for joined into the SQL by Repo::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.
  • 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 HttpTransport instead of being its own transport, inheriting its port, CORS, and TLS: the WS #[gateway], /graphql, MCP, and OpenAPI all self-mount, each declaring a Handler whose 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] impl block.
  • 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 on HttpTransport.
  • Processor (queue) — a provider whose #[processor] impl block holds #[process(queue = …)] methods that consume jobs; run by the port’s QueueWorker transport, attached by the QueueModule it brings.
  • Scheduler — the transport that drains #[scheduled] orchestrators; each method tagged with exactly one of #[every] / #[cron] / #[after].
  • 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/features and the database but never RPC each other.
  • Workspace — the shape nestrs new scaffolds: a monorepo hosting one binary per app under apps/<name>/, over a shared crates/features. One app is the starting point; a second workload is another nestrs new inside 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/).