Glossary

The docs lean on a small set of recurring terms — shaper, bridge, 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

• 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.

Request layers

• 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 the handler reads through Ctx<T>.
• Pipe — a stateless edge transform that parses and validates a single input, never a DI provider; bound to a handler argument through Valid<E> or Piped<P, E>.
• Interceptor — wraps the handler call from the outside; the seam that installs the ambient executor, records a span, or appends a Server-Timing entry.
• Filter — error-path mapper from nest-rs-filters; sees any poem::Error the inner chain raises. Bound with #[use_filters(...)]. Transparent on the success path.
• Exception filter — typed catch via downcast inside RouteShaper; bound with #[use_exception_filters(...)]. Only fires when the error matches Self::Exception.
• Ability shaper — the Authorize<A, S> wrapper the #[routes] macro emits when that type appears in a handler signature; runs response masking after a 2xx. Innermost per-route layer, just outside the handler. Layer order.
• RouteShaper — the per-route orchestrator inside nest-rs-guards; runs guards and body pipes on the way in, exception filters when the handler returns Err. Documented on Guards.
• Reflector — the request-time reader that pulls back the values a handler attached with #[meta(EXPR)]; how a guard inspects per-route metadata.

Data

• 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 SeaORM connection installed per request in a task_local! (pool on safe routes, a transaction on mutations); Repo reads it back through Repo::<E>::conn().
• Ambient context — the pair of request-scoped task_local!s the framework installs (executor + ability) so singletons can read per-request state without an argument on every method.
• Bind (extractor) — parses the id from the URL, calls Service::access(id) through the ambient ability, returns the loaded + authorized entity (404 absent, 403 denied).
• Scope (extractor) — the explicit-condition counterpart to Bind; 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.
• Wire model defaults — impl WireModelDefaults for Entity, emitted by the #[expose] macro, that fills unexposed columns (those without #[expose]) the masker cannot infer from the wire body.

Security

• Strategy — a plain #[injectable] that turns a request into a principal; AuthGuard<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 Ctx<P>.
• Ability — the CASL-style 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 — the entity an ability rule targets (users::Entity); how an action is scoped to a type. CASL 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 Ability::mask keeps, with everything else zeroed.
• Masking — the shaper’s post-handler pass that rebuilds a Model from the wire body, runs Ability::mask, then re-emits only the wire keys.
• 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 Issuer — 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.
• Bridge (transport bridge) — the per-transport seam that re-seeds the ambient ability and executor at GraphQL/WS/MCP dispatch points so the data layer stays transparent off the HTTP request path.

Transports

• 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 #[query] / #[mutation] / #[field_resolver] methods compose into the schema at boot; every #[query] / #[mutation] declares an access posture — #[authorize(Action, Entity)] or #[public].
• Gateway (WS) — a struct marked with #[gateway(path = "/ws")] whose #[subscribe_message] methods handle WS events; self-mounts on HttpTransport.
• Processor (queue) — a struct marked with #[processor] whose #[process(queue, ...)] methods consume jobs; activated by importing QueueWorkerModule.
• Scheduler — the transport that drains #[scheduled] orchestrators; each method tagged with exactly one of #[every] / #[cron] / #[after].

Observability

• Probe vs Indicator — a probe is one of the three HTTP routes (live / ready / startup); an indicator is a unit the probe aggregates (a DatabaseHealthIndicator, a custom one).

Other

• Marker guard — a unit guard with no logic that exists so the access graph can prove a transport’s authz seam is wired; omitting the authz module fails the boot naming the missing guard.
• 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/).