📝 Document links shown by route access

This commit is contained in:
Manuel Cillero 2026-11-08 10:14:45 +01:00
parent 345bd26974
commit c0e86f132d
5 changed files with 164 additions and 13 deletions

View file

@ -142,6 +142,14 @@ toma de la página de la que cuelgan: `user/users/{id}/edit` exige el de `user/u
panel montada de otra forma, o que no cuelgue de ninguna página, impide arrancar la aplicación. El panel montada de otra forma, o que no cuelgue de ninguna página, impide arrancar la aplicación. El
menú del panel y la ruta no pueden quedar desalineados. menú del panel y la ruta no pueden quedar desalineados.
El resto de rutas consiguen lo mismo con `Endpoint`: un `enum` por extensión cuyas variantes
declaran su ruta y su acceso, que se montan con `routes.endpoint()` y se usan como destino de los
enlaces. El acceso con el que se monta una ruta queda dentro de su capa y no se puede consultar
después, así que es el enlace el que lleva consigo el acceso, sin guardarlo en ningún registro: el
mismo valor protege la ruta y decide si el enlace se muestra
([Enlaces según el acceso](../how-to/navigation.md#enlaces-según-el-acceso)). Es una ayuda para la
interfaz, no para la seguridad: quien escriba la URL recibe la respuesta del acceso de la ruta.
Quién tiene cada permiso no lo sabe PageTop: lo decide una **extensión de autenticación**, como Quién tiene cada permiso no lo sabe PageTop: lo decide una **extensión de autenticación**, como
`pagetop-user`. Deja el usuario actual (`CurrentUser`) en la petición desde su *middleware*, concede `pagetop-user`. Deja el usuario actual (`CurrentUser`) en la petición desde su *middleware*, concede
permisos con la acción `CheckPermission` y, si quiere, decide qué responder a un anónimo sin acceso permisos con la acción `CheckPermission` y, si quiere, decide qué responder a un anónimo sin acceso

View file

@ -36,6 +36,61 @@ Nav::new().with_item(nav::Item::dropdown(
# } # }
``` ```
## Enlaces según el acceso
Un enlace a una ruta declarada con `Endpoint` no se muestra a quien no tiene acceso a ella, y un
`Nav` o un `Dropdown` sin nada que mostrar tampoco se pinta. Funciona con cualquier tema, y el
enlace no repite el permiso de la ruta:
```rust,no_run
# use pagetop::prelude::*;
# #[derive(Clone, Copy, Debug)]
# enum GardenPermission { SeeHarvest, ManageBeds }
# impl Permission for GardenPermission {
# fn key(&self) -> CowStr { "garden:permission".into() }
# }
#[derive(Clone, Copy, Debug)]
enum GardenRoute {
Harvest,
Beds,
BedEdit,
}
impl Endpoint for GardenRoute {
fn path(&self) -> CowStr {
match self {
Self::Harvest => "/harvest".into(),
Self::Beds => "/beds".into(),
Self::BedEdit => "/beds/{id}/edit".into(),
}
}
fn access(&self) -> Access {
match self {
Self::Harvest => Access::Permission(&GardenPermission::SeeHarvest),
Self::Beds | Self::BedEdit => Access::Permission(&GardenPermission::ManageBeds),
}
}
}
# fn f(bed: i32) -> Nav {
Nav::new()
.with_item(nav::Item::link(Lc::n("Harvest"), GardenRoute::Harvest))
.with_item(nav::Item::dropdown(
Dropdown::new()
.with_title(Lc::n("Beds"))
.with_item(dropdown::Item::link(Lc::n("All the beds"), GardenRoute::Beds))
.with_item(dropdown::Item::link(Lc::n("This bed"), GardenRoute::BedEdit.to(bed))),
))
# }
```
Las rutas se montan con `routes.endpoint(GardenRoute::Harvest, web::get(...))`. Los encabezados y
separadores de un `Dropdown` sólo se muestran si separan elementos visibles: si se ocultan todos los
enlaces de un grupo, su encabezado desaparece con ellos.
Más sobre `Endpoint` en
[Proteger rutas y adaptar la interfaz](users.md#5-protege-rutas-y-adapta-la-interfaz).
## Barra de navegación ## Barra de navegación
`Navbar` combina marca, menús y otros elementos. Con `brand_left()`, en pantallas estrechas los `Navbar` combina marca, menús y otros elementos. Con `brand_left()`, en pantallas estrechas los

View file

@ -53,6 +53,10 @@ encadenan para atender varios en la misma ruta. Si cada método necesita un acce
para todos y guardar con un permiso, por ejemplo), registra la misma ruta dos veces, cada una con para todos y guardar con un permiso, por ejemplo), registra la misma ruta dos veces, cada una con
su método y su acceso. su método y su acceso.
Si enlazas a una ruta protegida desde otras páginas, declárala con `Endpoint` y móntala con
`routes.endpoint()`, para que [sus enlaces](navigation.md#enlaces-según-el-acceso) se oculten solos
a quien no pueda entrar.
## 2. Agrupa rutas bajo un prefijo ## 2. Agrupa rutas bajo un prefijo
Para agrupar rutas bajo un prefijo común, crea un `Router` aparte y anídalo con `nest()`. Todas Para agrupar rutas bajo un prefijo común, crea un `Router` aparte y anídalo con `nest()`. Todas

View file

@ -304,6 +304,72 @@ Html::with(|cx| {
Ocultar el botón no basta: la ruta debe comprobar el permiso igualmente, porque cualquiera puede Ocultar el botón no basta: la ruta debe comprobar el permiso igualmente, porque cualquiera puede
escribir la URL. escribir la URL.
Con `has_permission()`, el permiso queda escrito en dos sitios, en la ruta y en el enlace. PageTop
no permite preguntar después qué acceso tiene una ruta, de modo que, si cambias uno y olvidas el
otro, el enlace llevará a un 403 o se ocultará a quien sí podría entrar. Para los enlaces hay una
forma mejor: declara las rutas con su acceso en un `enum`, como los permisos, implementando
`Endpoint`:
```rust,no_run
# use pagetop::prelude::*;
# #[derive(Clone, Copy, Debug)]
# enum BoardPermission { PostNotices }
# impl Permission for BoardPermission {
# fn key(&self) -> CowStr { "board:post_notices".into() }
# }
# async fn new_notice() -> &'static str { "" }
#[derive(Clone, Copy, Debug)]
enum BoardRoute {
Home,
NewNotice,
}
impl Endpoint for BoardRoute {
fn path(&self) -> CowStr {
match self {
Self::Home => "/".into(),
Self::NewNotice => "/notices/new".into(),
}
}
fn access(&self) -> Access {
match self {
Self::Home => Access::Public,
Self::NewNotice => Access::Permission(&BoardPermission::PostNotices),
}
}
}
# pub struct Board;
# #[async_trait]
# impl Extension for Board {
fn configure_router(&self, routes: Routes) -> Routes {
routes
.endpoint(BoardRoute::Home, web::get(board))
.endpoint(BoardRoute::NewNotice, web::get(new_notice))
}
# }
async fn board(request: HttpRequest) -> Result<Markup, ErrorPage> {
Page::new(request)
.with_title(Lc::n("Garden board"))
.with_child(Html::with(|_| html! { p { "The water tank is full." } }))
.with_child(Button::anchor(Lc::n("Post a notice"), BoardRoute::NewNotice))
.render()
.await
}
```
`routes.endpoint()` monta la ruta con su acceso, y `Button::anchor()` y los enlaces de los menús
([`nav::Item` y `dropdown::Item`](navigation.md#enlaces-según-el-acceso)) no se muestran a quien no
lo cumple. El enlace nunca nombra el permiso, así que no puede desalinearse de la ruta, y una ruta
nueva sin acceso no compila. Una ruta con parámetro se enlaza con `to()`:
`BoardRoute::EditNotice.to(7)` lleva a `/notices/7/edit` si la ruta es `/notices/{id}/edit`.
`Endpoint` sólo responde por el acceso de la ruta, no por lo que compruebe además su *handler*, y
lo aplican esos enlaces, no todo lo que muestre la página. Para el resto, y cuando un permiso decide
varias cosas dentro de una misma página, sigue estando `has_permission()`.
## 6. Asigna el permiso ## 6. Asigna el permiso
Inicia sesión como `admin` y entra en **Administración** desde el menú de cuenta. En la lista de Inicia sesión como `admin` y entra en **Administración** desde el menú de cuenta. En la lista de
@ -350,6 +416,28 @@ fn declare_permissions(registry: &mut PermissionRegistry) {
registry.register(&BoardPermission::PostNotices); registry.register(&BoardPermission::PostNotices);
} }
#[derive(Clone, Copy, Debug)]
enum BoardRoute {
Home,
NewNotice,
}
impl Endpoint for BoardRoute {
fn path(&self) -> CowStr {
match self {
Self::Home => "/".into(),
Self::NewNotice => "/notices/new".into(),
}
}
fn access(&self) -> Access {
match self {
Self::Home => Access::Public,
Self::NewNotice => Access::Permission(&BoardPermission::PostNotices),
}
}
}
struct Board; struct Board;
#[async_trait] #[async_trait]
@ -369,12 +457,8 @@ impl Extension for Board {
fn configure_router(&self, routes: Routes) -> Routes { fn configure_router(&self, routes: Routes) -> Routes {
routes routes
.public_route("/", web::get(board)) .endpoint(BoardRoute::Home, web::get(board))
.route( .endpoint(BoardRoute::NewNotice, web::get(new_notice))
"/notices/new",
Access::Permission(&BoardPermission::PostNotices),
web::get(new_notice),
)
} }
} }
@ -399,14 +483,12 @@ impl Component for TopBar {
} }
async fn board(request: HttpRequest) -> Result<Markup, ErrorPage> { async fn board(request: HttpRequest) -> Result<Markup, ErrorPage> {
let can_post = has_permission(&request, &BoardPermission::PostNotices); Page::new(request)
let mut page = Page::new(request)
.with_title(Lc::n("Garden board")) .with_title(Lc::n("Garden board"))
.with_child(Html::with(|_| html! { p { "The water tank is full." } })); .with_child(Html::with(|_| html! { p { "The water tank is full." } }))
if can_post { .with_child(Button::anchor(Lc::n("Post a notice"), BoardRoute::NewNotice))
page = page.with_child(Button::anchor(Lc::n("Post a notice"), "/notices/new")); .render()
} .await
page.render().await
} }
async fn new_notice(request: HttpRequest) -> Result<Markup, ErrorPage> { async fn new_notice(request: HttpRequest) -> Result<Markup, ErrorPage> {

View file

@ -34,6 +34,8 @@ Lo esencial de PageTop en una página. Cada línea enlaza con la guía que lo ex
| [Responder JSON](../how-to/routes.md#4-elige-la-respuesta) | `Json(value)` | | [Responder JSON](../how-to/routes.md#4-elige-la-respuesta) | `Json(value)` |
| [Un error de API en JSON](../how-to/error-pages.md#7-errores-de-una-api-json) | `impl IntoResponse for ApiError` | | [Un error de API en JSON](../how-to/error-pages.md#7-errores-de-una-api-json) | `impl IntoResponse for ApiError` |
| [Exigir un permiso en una ruta](../how-to/users.md#5-protege-rutas-y-adapta-la-interfaz) | `routes.route("/path", Access::Permission(&MyPermission::X), web::get(handler))` | | [Exigir un permiso en una ruta](../how-to/users.md#5-protege-rutas-y-adapta-la-interfaz) | `routes.route("/path", Access::Permission(&MyPermission::X), web::get(handler))` |
| [Declarar una ruta con su acceso](../how-to/users.md#5-protege-rutas-y-adapta-la-interfaz) | `impl Endpoint for MyRoute` y `routes.endpoint(MyRoute::X, web::get(handler))` |
| [Un enlace que se oculta sin acceso](../how-to/navigation.md#enlaces-según-el-acceso) | `nav::Item::link(Lc::n("..."), MyRoute::X)`, o `MyRoute::X.to(id)` con parámetro |
| [Conceder permisos desde tu autenticación](../how-to/auth.md#2-concede-los-permisos) | `action::auth::CheckPermission::new(grant)` con `fn grant(&HttpRequest, PermissionRef, &mut bool)` | | [Conceder permisos desde tu autenticación](../how-to/auth.md#2-concede-los-permisos) | `action::auth::CheckPermission::new(grant)` con `fn grant(&HttpRequest, PermissionRef, &mut bool)` |
| [Llevar al anónimo al inicio de sesión](../how-to/auth.md#3-ofrece-el-inicio-de-sesión-al-anónimo) | `action::auth::AnonymousDenied::new(offer_login)` con `fn offer_login(&HttpRequest) -> Option<Response>` | | [Llevar al anónimo al inicio de sesión](../how-to/auth.md#3-ofrece-el-inicio-de-sesión-al-anónimo) | `action::auth::AnonymousDenied::new(offer_login)` con `fn offer_login(&HttpRequest) -> Option<Response>` |
| [Montar una página del panel](../how-to/admin.md#5-añade-una-página-con-tu-propio-contenido) | `routes.admin_route("reports/harvest", web::get(handler))` | | [Montar una página del panel](../how-to/admin.md#5-añade-una-página-con-tu-propio-contenido) | `routes.admin_route("reports/harvest", web::get(handler))` |