Expose over HTTP
PostsService through Repo, PostsController's one #[crud] block declaring the routes, the guards in front of it, and the policy's first rule.
You read the service, the controller and the HTTP module nestrs g resource
wrote, and grant the policy in front of them its first rule. By the end of this
page, blog imports everything the five CRUD routes need but the table
Persist through Postgres gives them.
The service
Section titled “The service”A service is the entity’s single DB gateway. Every read and write goes
through Repo<Posts>; controllers, resolvers, gateways never touch
SeaORM directly. The controller’s #[crud(...)] expands against the service’s
CrudService, which
nest-rs-seaorm
provides beside Repo and ServiceError.
use nest_rs::core::injectable;use nest_rs::seaorm::{Creatable, CrudService, Deletable, Updatable};
use super::entity::{CreatePost, Entity as Posts, UpdatePost};
#[injectable]pub struct PostsService;
// Read API + the audited ORM choke point.impl CrudService for PostsService { type Entity = Posts;}
// Opt-in write capabilities — drop any your resource does not offer (and the// matching #[crud] op), instead of declaring a placeholder input type.impl Creatable for PostsService { type Create = CreatePost;}
impl Updatable for PostsService { type Update = UpdatePost;}
impl Deletable for PostsService {}#[injectable] marks the struct as a provider — the container builds it once
and shares it as Arc<PostsService>. CrudService carries the read half:
it names the entity, and every resource implements it. Writes are opt-in
traits — Creatable (type Create), Updatable (type Update) and
Deletable — each implemented only for an operation the resource offers, so a
read-only projection implements CrudService alone.
Every Repo::<Posts> call runs on the ambient executor the data layer installs
before the handler runs: you never pass a connection in.
The port module registers it:
use nest_rs::core::module;
use super::service::PostsService;
#[module(providers = [PostsService])]pub struct PostsModule;The controller
Section titled “The controller”A controller is a struct with #[controller(path = ...)] and a
#[crud(service = PostsService)] impl block naming the service it injects. The
macro generates every CRUD verb — list, get, create, update, delete —
and reads each type they name off that service: the entity off CrudService,
the bodies off Creatable and Updatable, the answer off the entity’s
#[expose(name = "Post")]. A verb whose trait is missing — a create with no
Creatable impl — is a build break, not a silent no-op; ops = [list, get]
lists the verbs a read-only resource has. You write a handler body only for
domain logic the trait doesn’t cover.
use std::sync::Arc;
use nest_rs::http::{controller, crud};
use crate::authn::AuthnGuard;use crate::authz::AuthzGuard;use crate::posts::PostsService;
#[controller(path = "/posts")]#[use_guards(AuthnGuard, AuthzGuard)]pub struct PostsController { #[inject] svc: Arc<PostsService>,}
// Every operation is authenticated, ability-filtered, transactional, and// answers rows judged for its caller — declared by the two guards, generated// by #[crud]. Each route answers 403 until AuthzAbility grants its action on// `crate::posts::Entity`.#[crud(service = PostsService)]impl PostsController {}Every read is filtered by its caller, starting here
Section titled “Every read is filtered by its caller, starting here”From this line on, no row crosses the data layer without someone to answer for
it. Repo ANDs the caller’s ambient Ability into
every read and every by-id write; nothing but AuthzGuard installs one, so a
request with no ability reads nothing rather than everything: row-level
filtering you never write a WHERE for. There is no “skip auth for now”
switch: even a public read runs under an ability, the one your
AbilityFactory’s define_visitor grants an anonymous caller.
AuthnGuard and AuthzGuard are your types: the framework is generic over
the principal and the policy, so nestrs g resource wrote them on the last
page — crates/features/src/authn/ holds the Claims a token carries and
AuthnGuard, authz/ holds AuthzGuard and the policy. It also drew two
random <PREFIX>_AUTHN__SECRETs, yours into the git-ignored .env.local and
the test suites’ into .env.test; the committed .env, which every
environment reads, holds no secret: a deployment sets its own.
The policy starts empty, so Post needs a rule. Rename define’s _ab to
ab and grant it, as the generator’s next steps printed:
use nest_rs::authz::{AbilityBuilder, AbilityFactory, Action};use nest_rs::core::injectable;
use crate::authn::Claims;use crate::posts as post;
#[injectable]pub struct AuthzAbility;
impl AbilityFactory for AuthzAbility { type Actor = Claims;
/// Every rule this app grants, keyed off the authenticated actor. Nothing /// is granted until you add a `can` here — reads return 403 and no row /// crosses the data layer. /// /// `nestrs g resource <name>` prints the grant to paste for the resource it /// just generated, with `_ab` renamed `ab`; narrow it to a user's own rows /// with `.when(|p| p.eq(Column::AuthorId, user_id))` under /// `if let Some(user_id) = actor.sub.user_id()` — a client owns none. fn define(&self, _actor: &Claims, ab: &mut AbilityBuilder) { ab.can(Action::Manage, post::Entity); }
/// What an *unauthenticated* caller may do, on what `#[public(Action, Entity)]` /// opens. Empty on purpose: nothing is public until you say so here, and a /// route naming its read still serves no row without a grant — a /// `can(Action::Read, …)` narrowed by `.when(…)` to the rows meant for /// anyone. /// /// Such a route reached with a valid token uses `define` instead — this branch /// answers only for the visitor. fn define_visitor(&self, _ab: &mut AbilityBuilder) {}}Manage is every action on Post, unconditionally — the smallest rule that
lets the tutorial move, which Secure your posts narrows.
The HTTP module
Section titled “The HTTP module”The feature’s HTTP adapter is a separate module. It imports the port
(PostsModule) and AuthzModule, which makes the ability guard reachable —
omit it and the access graph fails the boot by name. The controller brings
HttpModule, the server it is served on.
use nest_rs::core::module;
use super::controller::PostsController;use crate::authz::AuthzModule;use crate::posts::PostsModule;
#[module( imports = [PostsModule, AuthzModule], providers = [PostsController],)]pub struct PostsHttpModule;mod controller;mod module;
pub use module::PostsHttpModule;The folder exports the module alone: the controller is the adapter’s own, and an app imports the edge it serves, never the type serving it.
Wired in
Section titled “Wired in”nestrs g resource wrote blog’s root in the same run — every import the
generated code needs, beside the greeting the scaffold wired on page 1:
use nest_rs::core::module;use nest_rs::seaorm::SeaOrmDatabaseModule;
use features::authn::AuthnHttpModule;use features::blog::BlogHttpModule;use features::posts::PostsHttpModule;
#[module( imports = [ BlogHttpModule, PostsHttpModule, SeaOrmDatabaseModule, AuthnHttpModule, ],)]pub struct BlogModule;Each line is an edge blog serves or a backend its root chooses:
BlogHttpModuleis the scaffold’s greeting on/, there so page 1 had something to prove: drop it withcrates/features/src/blog/whenever you want.PostsHttpModuleserves the five CRUD routes. It importsAuthzModule, andAuthzModuleimportsAuthnModule, so the root lists the edge and nothing it brings: the access graph checks each import where it is used.SeaOrmDatabaseModuleis the data layer every route#[crud]generates runs on — the next page reads it.AuthnHttpModuleservesPOST /auth/dev-token, the development token the next page’scurls carry, behind the framework’sDevelopmentOnlyGuard, which refuses the boot outside development and test: delete it withcrates/features/src/authn/http/the day you write the real login.
No manifest line moves: apps/blog/Cargo.toml depends on features already.
What you have now
Section titled “What you have now”- A
PostsServicethat owns the entity throughRepo<Posts>. - A
PostsControllerwith the full CRUD surface#[crud]generated, behindAuthnGuard+AuthzGuard. - An
AuthzAbilitygrantingManageonPost. - A
BlogModuleimporting the adapter, the data layer it runs on and the token route — everything but a database to reach.
Going further
Section titled “Going further”- Persist through Postgres — the next step: start Postgres, create the table, and see the first curl return a post.
- Controllers — the reference page for
#[controller]and#[crud].