This page is the index of every decorator the framework ships, grouped
by concern. Skim the table for the one you need, click through to the
page that explains it in context. Each row says where the decorator
goes (struct, impl block, method, field) so you can confirm the
position without leaving the page.
What counts as a decorator here: everything you write. That is the whole
inclusion rule, and it is wider than “an attribute macro”. Roughly half the
rows below — #[get], #[query], #[public], #[on_module_init] — are
inert tokens an orchestrator reads (#[routes], #[operations], #[hooks]),
not macros of their own, and they need no import. What decides a row is
whether you type it, not how the compiler resolves it. A decorator of your
own reads its keys and words its refusals as these do, on the kit
Writing a decorator walks through.
| Decorator | Goes on | Summary | Read more |
|---|
#[module] | struct | Composes a binary: lists providers it owns and imports it depends on | Modules |
#[nest_rs::main] | main function | Installs the panic hook, publishes the .env cascade and captures the binary’s name, version and description (AppIdentity, which OpenAPI’s info, MCP’s serverInfo and OpenTelemetry’s service.name default to) before main, builds the runtime, and ends the process within the shutdown budget; written in full, never a bare #[main], which use tokio::main; would make tokio’s | Shutdown |
#[injectable] | struct | Marks a provider built from the container, with optional scope = request | transient | Providers, Provider scopes |
#[inject] | field | Resolves the field from the container by its type, at construction; takes no argument | Providers |
#[instance] | unit struct | Declares a marker naming one instance of a resource the app opens more than once; its name is the ident in snake case | Instances |
#[hooks] | impl block | Orchestrates lifecycle methods on a provider | Lifecycle |
#[on_module_init] | method | Runs once after wiring, before serving | Lifecycle |
#[on_application_bootstrap] | method | Runs once after every module init, before serving | Lifecycle |
#[on_module_destroy] | method | Runs on shutdown after transports stop | Lifecycle |
#[before_application_shutdown] | method | Runs on shutdown once every module-destroy hook has run | Lifecycle |
#[on_application_shutdown] | method | Runs last during shutdown, best-effort | Lifecycle |
| Decorator | Goes on | Summary | Read more |
|---|
#[controller] | struct | Mounts the struct as a controller with a base path and optional version | Controllers |
#[routes] | impl block | Wires methods to HTTP routes and emits the route table | Controllers |
#[get] #[post] #[put] #[patch] #[delete] | method | Binds the method to an HTTP verb at the given path | Controllers |
#[sse] | method | Binds a GET that answers a text/event-stream, with the keep-alive and the connection ceiling | Streaming |
#[http_code] | method | Overrides the default response status code | Responses |
#[response_header] | method | Sets a response header, set-cookie appended (repeatable) | Responses |
#[redirect] | method | Issues a redirect and discards the handler payload | Responses |
#[no_pipes] | method | Runs no global pipe over the route’s body, the app’s pool included | Global pipes |
#[version] | method | Narrows a route to one of the controller’s declared versions | Versioning |
One set for every edge: a host is a controller, a resolver, a gateway, an MCP
host or a worker’s impl block, and a method one of its handlers.
| Decorator | Goes on | Summary | Read more |
|---|
#[use_guards] | host or method | Binds container-resolved guards, first listed outermost | Guards |
#[force_guards] | method | Binds a guard and re-runs it though a broader scope already ran it — the opt-out from dedup | Guards |
#[use_pipes] | host or method | Binds global pipes to an HTTP or WebSocket site, beside the app’s pool | Global pipes |
#[use_interceptors] | host or method | Binds interceptors at the handler stage, after the guards | Interceptors |
#[use_exception_filters] | host or method | Binds exception filters — a typed catch, or every error with dyn Error + Send + Sync; the method’s tried first | Error handling |
#[interceptor(stage = unit)] | struct | Makes a struct an interceptor its module’s import brings around the guards of every unit; at the handler stage, an app-wide one is the root’s GlobalInterceptors<(…)> | Interceptors |
#[meta] | host or method | Declares typed metadata, the method’s over its host’s (repeatable); read back by a layer through cx.reflector() | Execution context |
#[public] | method | Access posture: the unit admits a caller with no credential — guards relax; bare it reads nothing a grant guards, and #[public(Action, Subject)] gates and reads on that caller’s ability, as #[authorize] does; refused at boot where the request’s guards would turn one away | Public reads |
#[authorize] | method | Access posture: gates the unit by ability (Action, Subject) and, on an entity, opens its reads under the caller’s ability, each wire row judged for that caller; bind = Service also loads the row an id names into an Authorized<Action, E> parameter, on a route, a GraphQL operation or an MCP #[resource] | Authorization, Route model binding |
#[subject] | unit struct | Declares a capability no table holds as an authorization subject: a rule grants it whole, a posture naming it gates on every edge and opens the unit’s reads to the caller’s ability | Policies |
| Decorator | Goes on | Summary | Read more |
|---|
#[derive(PrincipalIdentity)] | struct | Makes a claims type a principal: implements PrincipalIdentity and AmbientValue off the fields #[principal] marks | JWT |
#[principal] | field | Marks the role its field plays — actor (required), tenant or scopes — each played by one field | JWT |
One grammar holds every decorator pair: each layer attribute is taken where
its edge runs that family, and anywhere else it is a compile error that says
why — never a layer that silently never runs. The WebSocket #[on_connect] /
#[on_disconnect] hooks run outside any site: they refuse a #[meta] (no layer
runs around a hook to read it), a guard (the upgrade’s guards admitted the
socket), a pipe (a hook has no payload) and a posture (no gate stands before a
hook, so it reads nothing a grant guards), and run no interceptor or exception
filter yet.
| Attribute | HTTP | GraphQL | WebSockets | MCP | Queue, schedule, events | Hooks, indicators |
|---|
#[use_guards] | struct, method | struct, method | struct (the upgrade), method; — on a connection hook | struct, method | — no caller to gate | — |
#[force_guards] | method | method | method | method | — | — |
#[use_pipes] | struct, method | — bind a per-argument pipe | struct, method; — on a connection hook | — bind it inside Parameters<…> | — bind a per-argument pipe | — |
#[use_interceptors] | struct, method | struct, method | struct, method; not yet on a connection hook | struct, method | impl block, method | — |
#[use_exception_filters] | struct, method | struct, method | struct, method; not yet on a connection hook | struct, method | impl block, method | — |
#[meta] | struct, method | struct, method | struct, method; — on a connection hook | struct, method | impl block, method | — |
Not yet marks a family the edge does not run yet: the compiler refuses it
today, as a silent no-op would be worse, and the edge takes it once it runs it.
#[use_filters] is refused at every pair, naming #[use_exception_filters],
whose catch-all replaced it.
| Decorator | Goes on | Summary | Read more |
|---|
#[input] | struct | Shorthand for a DTO an edge decodes: Serialize + Deserialize + Validate + JsonSchema + deny_unknown_fields | Extractors |
#[output] | struct, enum | Shorthand for a DTO an edge only sends: Serialize + JsonSchema | Controllers |
#[wire_enum] | enum | Carries the wire derives for an enum both decoded and sent, a column’s or a claims role, and under graphql its Enum | Entities |
One decorator per shape, one definition — an HTTP body, a GraphQL input, a queue
payload, a WS message and a tool’s arguments all take them, from one path:
nest_rs::core, which nest_rs::prelude carries too.
| Decorator | Goes on | Summary | Read more |
|---|
#[resolver] | struct | Marks a resolver provider and declares its resolver-scope guards, interceptors and exception filters | GraphQL |
#[operations] | impl block | Orchestrates the block’s #[query] / #[mutation] / #[subscription] / #[entity] / #[field_resolver] methods | GraphQL |
#[query] | method | Root query operation; requires an access posture (#[authorize(…)], #[public(…)] or #[public]) | Queries and mutations |
#[mutation] | method | Root mutation operation; requires an access posture (#[authorize(…)], #[public(…)] or #[public]) | Queries and mutations |
#[subscription] | method | Root subscription over graphql-ws; same posture, gated at subscribe, each item judged for its subscriber | Subscriptions |
#[entity] | method | Federation entity resolver — the router resolves it by reference through _entities; same mandatory posture, and its arguments are the @key | Federation |
#[field_resolver] | method | Custom field resolver on a wire type; takes no posture attribute | Field resolvers |
#[dataloader] | impl block on service | Batches a method into a request-scoped DataLoader | Dataloader |
| Decorator | Goes on | Summary | Read more |
|---|
#[gateway] | struct | Mounts a WebSocket gateway at a path on the HTTP transport | WebSockets |
#[messages] | impl block | Binds gateway message handlers and lifecycle hooks | Messages |
#[subscribe_message] | method | Handles one event in the { event, data } envelope | Messages |
#[on_connect] | method | Runs after the socket upgrades | Rooms |
#[on_disconnect] | method | Runs after the socket closes | Rooms |
| Decorator | Goes on | Summary | Read more |
|---|
#[queue] | unit struct | Declares a queue’s wire name and payload type in one artifact both producer and consumer import | Queue |
#[processor] | impl block | Orchestrates queue consumers on a provider | Queue |
#[process] | method | Binds the method to a queue with a retries budget, a per-replica concurrency, a deployment-wide throttle, an attempt’s timeout and transactional settling; the method may take an Attempt and a Checkpoint<_> beside its job | Queue |
| Decorator | Goes on | Summary | Read more |
|---|
#[scheduled] | impl block | Orchestrates scheduled methods on a provider | Schedule |
#[every] | method | Fires the method on a fixed interval, optional timeout, transactional, replicas and key | Schedule |
#[cron] | method | Fires the method on a cron expression, optional timeout, tz, transactional, replicas and key | Schedule |
#[after] | method | Fires the method once after a delay from boot, optional timeout and transactional | Schedule |
| Decorator | Goes on | Summary | Read more |
|---|
#[listeners] | impl block | Orchestrates event listeners on a provider | Events |
#[on_event] | method | Subscribes the method to its second-parameter event type, each call a unit of work of its own, optional timeout and transactional | Events |
| Decorator | Goes on | Summary | Read more |
|---|
#[mcp] | struct | Mounts an MCP endpoint over HTTP, at /mcp or a declared path | MCP |
#[tools] | impl block | Serves the block’s #[tool], #[prompt], #[resource] and #[resources] methods, deriving the advertised capabilities | MCP |
#[tool] | method | Exposes the method as an MCP tool; description = "…", or the doc comment as a fallback | MCP |
#[prompt] | method | Exposes the method as an MCP prompt; description = "…", or the doc comment as a fallback | Resources and prompts |
#[resource] | method | Reads the URIs an RFC 6570 template = "…" writes, each variable a typed argument, or under bind = Service the row it names; description = "…", or the doc comment as a fallback | Resources and prompts |
#[resources] | method | Answers resources/list, one per host | Resources and prompts |
| Decorator | Goes on | Summary | Read more |
|---|
#[indicators] | impl block | Orchestrates health checks on a provider | Indicators |
#[liveness] | method | Binds the method to the liveness probe | Indicators |
#[readiness] | method | Binds the method to the readiness probe | Indicators |
#[startup] | method | Binds the method to the startup probe | Indicators |
| Decorator | Goes on | Summary | Read more |
|---|
#[config] | struct | Marks a struct as a namespaced configuration loaded from env and files | Configuration |
| Decorator | Goes on | Summary | Read more |
|---|
#[expose] | struct + field | Exposes a SeaORM entity to GraphQL and OpenAPI from one declaration | Database |
#[crud] | impl block | Generates standard CRUD operations on a controller or resolver | CRUD |
| Decorator | Goes on | Summary | Read more |
|---|
#[api] | method | Enriches the OpenAPI operation with summary, description, and tags | OpenAPI |