Skip to content

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.

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.

crates/features/src/posts/service.rs
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:

crates/features/src/posts/module.rs
use nest_rs::core::module;
use super::service::PostsService;
#[module(providers = [PostsService])]
pub struct PostsModule;

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.

crates/features/src/posts/http/controller.rs
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:

crates/features/src/authz/ability.rs
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 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.

crates/features/src/posts/http/module.rs
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;
crates/features/src/posts/http/mod.rs
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.

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:

apps/blog/src/module.rs
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:

  • BlogHttpModule is the scaffold’s greeting on /, there so page 1 had something to prove: drop it with crates/features/src/blog/ whenever you want.
  • PostsHttpModule serves the five CRUD routes. It imports AuthzModule, and AuthzModule imports AuthnModule, so the root lists the edge and nothing it brings: the access graph checks each import where it is used.
  • SeaOrmDatabaseModule is the data layer every route #[crud] generates runs on — the next page reads it.
  • AuthnHttpModule serves POST /auth/dev-token, the development token the next page’s curls carry, behind the framework’s DevelopmentOnlyGuard, which refuses the boot outside development and test: delete it with crates/features/src/authn/http/ the day you write the real login.

No manifest line moves: apps/blog/Cargo.toml depends on features already.

  • A PostsService that owns the entity through Repo<Posts>.
  • A PostsController with the full CRUD surface #[crud] generated, behind AuthnGuard + AuthzGuard.
  • An AuthzAbility granting Manage on Post.
  • A BlogModule importing the adapter, the data layer it runs on and the token route — everything but a database to reach.
  • 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].