✨ (pagetop): Oculta enlaces sin acceso con Endpoint

Las rutas se declaran con su acceso en un enum que implementa Endpoint y
se montan con `routes.endpoint()`. Convertidas en Route, `nav::Item`,
`dropdown::Item` y `Button::anchor()` no se muestran a quien no cumple
el acceso, sin repetir el permiso. `to()` rellena el parámetro de la
ruta.
This commit is contained in:
Manuel Cillero 2026-11-08 08:56:57 +01:00
parent 87711e4a37
commit e2e2ccb31e
13 changed files with 677 additions and 10 deletions

View file

@ -250,6 +250,11 @@ pub type PermissionRef = &'static dyn Permission;
/// La decisión de conceder o denegar permisos al usuario anónimo también es responsabilidad de cada
/// extensión.
///
/// Sirve para mostrar u ocultar lo que no se puede usar. Una ruta se protege con el acceso que se
/// indica al montarla ([`Access`]), y un enlace a ella se oculta solo si se declara con
/// [`Endpoint`](crate::web::Endpoint); para un permiso más concreto dentro del *handler* está
/// [`require_permission()`].
///
/// # Ejemplo
///
/// ```rust,no_run
@ -260,10 +265,12 @@ pub type PermissionRef = &'static dyn Permission;
/// # fn key(&self) -> CowStr { "myapp:edit".into() }
/// # }
/// async fn my_handler(request: HttpRequest) -> Result<Markup, ErrorPage> {
/// if !has_permission(&request, &MyPermission::Edit) {
/// return Err(ErrorPage::NotFound(Some(request)));
/// let can_edit = has_permission(&request, &MyPermission::Edit);
/// let mut page = Page::new(request);
/// if can_edit {
/// page.push_message(MessageLevel::Info, Lc::n("You can edit this page."));
/// }
/// Page::new(request).render().await
/// page.render().await
/// }
/// ```
pub fn has_permission(request: &HttpRequest, perm: PermissionRef) -> bool {
@ -321,6 +328,9 @@ pub fn require_permission(request: &HttpRequest, perm: PermissionRef) -> Result<
/// comprueba antes de llegar al *handler*, que sólo comprueba permisos más concretos, si los hay
/// (p. ej. que el usuario sea el autor de lo que edita). A quien no tiene acceso se le responde
/// con [`deny_access()`].
///
/// El acceso con el que se monta una ruta no se puede consultar después. Para que sus enlaces lo
/// conozcan sin repetirlo, ruta y acceso se declaran juntos con [`Endpoint`](crate::web::Endpoint).
#[derive(Clone, Copy)]
pub enum Access {
/// Cualquiera, también un usuario anónimo.

View file

@ -78,6 +78,10 @@ impl Component for Button {
self.props.get_id()
}
fn is_renderable(&self, cx: &Context) -> bool {
self.href().is_accessible(cx)
}
fn setup(&mut self, cx: &mut Context) {
use button::{Size, Style};
@ -182,6 +186,8 @@ impl Button {
/// [`with_style()`](Self::with_style)), por lo que el tema activo puede mostrarlo igual que
/// cualquier otra variante de `Button`. No confundir con [`button::Style::Link`], que es sólo
/// un estilo visual sobre un `<button>`.
///
/// No se renderiza si el usuario actual no puede acceder a la ruta (ver [`Endpoint`]).
pub fn anchor(label: Lc, route: impl Into<Route>) -> Self {
Self {
label,

View file

@ -40,6 +40,9 @@ pub enum ItemKind {
///
/// Permite definir el identificador, las clases de estilo adicionales y el tipo de interacción
/// asociada, manteniendo una interfaz común para renderizar todos los elementos del menú.
///
/// Un enlace no se renderiza si el usuario actual no puede acceder a su ruta (ver [`Endpoint`]).
/// Los encabezados y separadores no dependen de ningún enlace y se muestran aunque queden solos.
#[derive(AutoDefault, Clone, Debug, Getters)]
pub struct Item {
/// Devuelve identificador, clases CSS, atributos HTML y valores extra del componente.
@ -58,6 +61,13 @@ impl Component for Item {
self.props.get_id()
}
fn is_renderable(&self, cx: &Context) -> bool {
match self.item_kind() {
ItemKind::Link { route, .. } => route.is_accessible(cx),
_ => true,
}
}
async fn prepare(&self, cx: &mut Context) -> Result<Markup, ComponentError> {
Ok(match self.item_kind() {
ItemKind::Void => html! {},

View file

@ -5,7 +5,8 @@ use crate::prelude::*;
/// Presenta una lista de elementos [`nav::Item`](super::Item), donde alguno puede desplegar un
/// [`Dropdown`](super::super::Dropdown) embebido.
///
/// Si no contiene elementos, el componente **no se renderiza**.
/// Si no contiene elementos, o si ninguno se muestra (ver [`Endpoint`]), el componente **no se
/// renderiza**.
///
/// # Ejemplo
///

View file

@ -52,6 +52,8 @@ impl ItemKind {
///
/// Permite definir el identificador, las clases de estilo adicionales y el tipo de interacción
/// asociada, manteniendo una interfaz común para renderizar todos los elementos del menú.
///
/// Un enlace no se renderiza si el usuario actual no puede acceder a su ruta (ver [`Endpoint`]).
#[derive(AutoDefault, Clone, Debug, Getters)]
pub struct Item {
/// Devuelve identificador, clases CSS, atributos HTML y valores extra del componente.
@ -77,6 +79,13 @@ impl Component for Item {
self.props.get_id()
}
fn is_renderable(&self, cx: &Context) -> bool {
match self.item_kind() {
ItemKind::Link { route, .. } => route.is_accessible(cx),
_ => true,
}
}
fn setup(&mut self, _cx: &mut Context) {
self.alter_prop(PropsOp::prepend_classes(self.item_kind().as_str()));
}

View file

@ -1,6 +1,9 @@
use crate::CowStr;
use crate::auth::Access;
use crate::core::component::{Context, Contextual};
use crate::html::RoutePath;
use crate::util;
use crate::web::Endpoint;
use std::fmt;
use std::sync::Arc;
@ -64,6 +67,13 @@ use std::sync::Arc;
/// [`Route::external()`] explícitamente cuando quieras dejar clara la intención sin ambigüedad, o
/// para esquemas que la heurística aplicada no reconozca.
///
/// # Rutas con acceso
///
/// Una `Route` creada a partir de un [`Endpoint`] lleva además el acceso de esa ruta, y
/// [`is_accessible()`](Self::is_accessible) dice si el usuario actual lo cumple. Los enlaces de los
/// menús y [`Button::anchor()`](crate::base::component::Button::anchor) lo usan para no mostrarse a
/// quien no podría entrar. Cualquier otra `Route` se considera pública.
///
/// # Ejemplos
///
/// El caso más común es una ruta relativa dependiente del contexto, normalmente usando
@ -118,7 +128,10 @@ use std::sync::Arc;
/// let route = Route::external("ftp://files.example.com");
/// ```
#[derive(Clone)]
pub struct Route(Arc<dyn Fn(&Context) -> RoutePath + Send + Sync>);
pub struct Route {
resolver: Arc<dyn Fn(&Context) -> RoutePath + Send + Sync>,
access: Access,
}
impl Route {
/// Crea una `Route` a partir de un closure que resuelve la ruta según el contexto.
@ -126,7 +139,10 @@ impl Route {
where
F: Fn(&Context) -> RoutePath + Send + Sync + 'static,
{
Route(Arc::new(f))
Route {
resolver: Arc::new(f),
access: Access::Public,
}
}
/// Crea una `Route` para una URL externa fija.
@ -142,7 +158,7 @@ impl Route {
/// Invoca el closure interno para obtener la [`RoutePath`] final.
pub fn resolve(&self, cx: &Context) -> RoutePath {
(self.0)(cx)
(self.resolver)(cx)
}
/// Como [`resolve()`](Self::resolve), pero devuelve `None` cuando la ruta calculada está vacía.
@ -153,6 +169,27 @@ impl Route {
let route = self.resolve(cx);
(!route.is_empty()).then_some(route)
}
/// Devuelve `true` si el usuario actual puede acceder a esta ruta.
///
/// Sirve para decidir qué se muestra: la ruta ya se protege con su propio acceso. Sólo una ruta
/// creada a partir de un [`Endpoint`] lleva acceso; cualquier otra es pública.
pub fn is_accessible(&self, cx: &Context) -> bool {
match self.access {
Access::Public => true,
access => cx.request().is_some_and(|request| access.allows(request)),
}
}
// Enlace a una ruta de un `Endpoint`, con su acceso: lo crean la conversión desde un `Endpoint`
// y `Endpoint::to()`.
pub(crate) fn endpoint(path: impl Into<CowStr>, access: Access) -> Self {
let path = path.into();
Route {
resolver: Arc::new(move |cx| cx.route(RoutePath::new(path.clone()))),
access,
}
}
}
impl fmt::Debug for Route {
@ -186,6 +223,21 @@ impl From<RoutePath> for Route {
}
}
/// Enlaza con una ruta declarada con [`Endpoint`], conservando su acceso.
///
/// Una ruta con parámetro se enlaza con [`Endpoint::to()`]; en desarrollo y en las pruebas, esta
/// conversión falla si se olvida.
impl<E: Endpoint> From<E> for Route {
fn from(endpoint: E) -> Self {
let path = endpoint.path();
debug_assert!(
!path.contains('{'),
"route `{path}` needs its parameter, link to it with `to()`"
);
Route::endpoint(path, endpoint.access())
}
}
impl From<&'static str> for Route {
fn from(path: &'static str) -> Self {
if util::url_looks_external(path) {

View file

@ -287,6 +287,9 @@ pub trait Extension: AnyInfo + Send + Sync {
/// }
/// ```
///
/// Las rutas que se enlazan desde otros sitios se declaran mejor con [`Endpoint`] y se montan
/// con [`Routes::endpoint()`]: sus enlaces se ocultan solos a quien no tiene acceso.
///
/// ## Rutas agrupadas con su propio middleware
///
/// Un `Router::new()` aparte, con sus capas, se añade bajo un prefijo con
@ -314,7 +317,9 @@ pub trait Extension: AnyInfo + Send + Sync {
/// [`Access::Public`]: crate::auth::Access::Public
/// [`Routes`]: crate::web::Routes
/// [`Routes::public_route()`]: crate::web::Routes::public_route
/// [`Routes::endpoint()`]: crate::web::Routes::endpoint
/// [`Routes::nest()`]: crate::web::Routes::nest
/// [`Endpoint`]: crate::web::Endpoint
/// [`configure_static_files`]: Self::configure_static_files
/// [`configure_middleware`]: Self::configure_middleware
fn configure_router(&self, routes: Routes) -> Routes {

View file

@ -36,8 +36,9 @@ pub use crate::locale::*;
pub use crate::datetime::*;
pub use crate::web;
pub use crate::web::{HttpRequest, IntoResponse, Layers, Response, Router, Routes, StaticFiles};
pub use crate::web::{
self, Endpoint, HttpRequest, IntoResponse, Layers, Response, Router, Routes, StaticFiles,
};
pub use crate::core::{AnyCast, AnyInfo, TypeInfo};

View file

@ -73,6 +73,10 @@ pub(crate) use csrf::reject_cross_origin;
mod routes;
pub use routes::{Layers, Routes, StaticFiles};
// Rutas declaradas junto con su acceso, para montarlas y enlazarlas sin repetirlo.
mod endpoint;
pub use endpoint::Endpoint;
use axum::body::Body;
use axum::extract::FromRequestParts;

127
src/web/endpoint.rs Normal file
View file

@ -0,0 +1,127 @@
use crate::CowStr;
use crate::auth::Access;
use crate::core::component::Route;
use crate::web::push_percent_encoded;
use std::fmt;
/// Ruta de la aplicación con el acceso que la habilita, para montarla y enlazarla sin repetirlo.
///
/// Se implementa con un `enum` por extensión, igual que [`Permission`]: cada variante es una ruta
/// y, si `access()` es un `match` sin comodín (`_`), añadir una sin decir quién puede acceder a
/// ella no compila. La ruta se monta con [`Routes::endpoint()`] y se convierte en una [`Route`]
/// para usarla como destino de un enlace.
///
/// [`nav::Item`], [`dropdown::Item`] y [`Button::anchor()`] no se renderizan si el usuario actual
/// no tiene acceso a su ruta (y un [`Nav`] o un [`Dropdown`] sin elementos que mostrar, tampoco),
/// así que un enlace nunca nombra el permiso y no puede desalinearse de la ruta. El resto de
/// componentes usan la ruta sin ocultar nada. Sólo es una ayuda para la interfaz: quien escriba la
/// URL recibe la respuesta del acceso de la ruta.
///
/// # Ejemplo
///
/// ```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 notices() -> &'static str { "" }
/// # async fn new_notice() -> &'static str { "" }
/// # async fn edit_notice() -> &'static str { "" }
/// #[derive(Clone, Copy, Debug)]
/// enum BoardRoute {
/// Notices,
/// NewNotice,
/// EditNotice,
/// }
///
/// impl Endpoint for BoardRoute {
/// fn path(&self) -> CowStr {
/// match self {
/// Self::Notices => "/notices".into(),
/// Self::NewNotice => "/notices/new".into(),
/// Self::EditNotice => "/notices/{id}/edit".into(),
/// }
/// }
///
/// fn access(&self) -> Access {
/// match self {
/// Self::Notices => Access::Public,
/// Self::NewNotice | Self::EditNotice => {
/// Access::Permission(&BoardPermission::PostNotices)
/// }
/// }
/// }
/// }
///
/// fn configure_router(routes: Routes) -> Routes {
/// routes
/// .endpoint(BoardRoute::Notices, web::get(notices))
/// .endpoint(BoardRoute::NewNotice, web::get(new_notice))
/// .endpoint(BoardRoute::EditNotice, web::get(edit_notice))
/// }
///
/// // Quien no pueda publicar no verá ni el segundo enlace ni el botón.
/// fn menu(id: i32) -> (Nav, Button) {
/// let nav = Nav::new()
/// .with_item(nav::Item::link(Lc::n("Notices"), BoardRoute::Notices))
/// .with_item(nav::Item::link(Lc::n("New notice"), BoardRoute::NewNotice));
/// (nav, Button::anchor(Lc::n("Edit"), BoardRoute::EditNotice.to(id)))
/// }
/// ```
///
/// El acceso sólo responde por la ruta, no por lo que compruebe además su *handler*. Si varios
/// métodos de una misma ruta exigen un acceso distinto, cada uno es una variante con la misma ruta,
/// y el enlace usa la del método `GET`.
///
/// [`Permission`]: crate::auth::Permission
/// [`Routes::endpoint()`]: crate::web::Routes::endpoint
/// [`nav::Item`]: crate::base::component::nav::Item
/// [`dropdown::Item`]: crate::base::component::dropdown::Item
/// [`Button::anchor()`]: crate::base::component::Button::anchor
/// [`Nav`]: crate::base::component::Nav
/// [`Dropdown`]: crate::base::component::Dropdown
pub trait Endpoint {
/// Devuelve la ruta tal como se monta, con la sintaxis de parámetros de Axum si lo tiene
/// (`"/notices/{id}/edit"`).
fn path(&self) -> CowStr;
/// Devuelve quién puede acceder a la ruta.
fn access(&self) -> Access;
/// Crea el enlace a una ruta con parámetro, conservando su acceso.
///
/// Sustituye el parámetro `{...}` por el valor indicado: `BoardRoute::EditNotice.to(7)` enlaza
/// con `/notices/7/edit`. El valor se codifica (`%XX`) salvo letras, dígitos, `-`, `_`, `.` y
/// `~`, así que no puede añadir tramos, parámetros de consulta ni otro dominio a la URL. Aun
/// así, un valor vacío deja un tramo vacío, que no coincide con la ruta, y el navegador
/// resuelve `.` y `..` como otra ruta: los identificadores numéricos o validados no tienen ese
/// problema.
///
/// En desarrollo y en las pruebas falla si la ruta no tiene exactamente un parámetro.
fn to(&self, param: impl fmt::Display) -> Route {
let pattern = self.path();
let parts = pattern
.split_once('{')
.and_then(|(prefix, rest)| Some((prefix, rest.split_once('}')?.1)));
debug_assert!(
parts.is_some(),
"route `{pattern}` has no parameter to fill"
);
let Some((prefix, suffix)) = parts else {
return Route::endpoint(pattern, self.access());
};
debug_assert!(
!suffix.contains('{'),
"route `{pattern}` has more than one parameter"
);
let param = param.to_string();
let mut path = String::with_capacity(prefix.len() + param.len() + suffix.len());
path.push_str(prefix);
push_percent_encoded(&mut path, param);
path.push_str(suffix);
Route::endpoint(path, self.access())
}
}

View file

@ -1,6 +1,6 @@
use crate::admin::{AdminRegistry, admin_path, strip_admin_path, undeclared_permission};
use crate::auth::{Access, PermissionRegistry, deny_access};
use crate::web::{HttpRequest, IntoResponse, Request, Response, Router, middleware};
use crate::web::{Endpoint, HttpRequest, IntoResponse, Request, Response, Router, middleware};
use crate::{global, trace};
use axum::extract::State;
@ -19,6 +19,9 @@ use std::convert::Infallible;
/// comprueba antes de llegar al *handler* y responde con [`deny_access()`] a quien no lo cumple.
/// Una ruta [`Access::Public`] no añade ninguna comprobación.
///
/// Las rutas que se enlazan desde otros sitios se declaran mejor con [`Endpoint`] y se montan con
/// [`endpoint()`](Self::endpoint): así, sus enlaces conocen el acceso sin repetirlo.
///
/// Las rutas del panel de administración (bajo [`admin_path`]) se montan con [`admin_route()`], que
/// exige el permiso de la página declarada ([`AdminPage`]) de la que cuelgan: el permiso se declara
/// sólo en la página. Montar una con cualquier otro método, o una que no cuelgue de ninguna página,
@ -111,6 +114,13 @@ impl Routes {
self.route(path, Access::Public, method_router)
}
/// Añade una ruta declarada con [`Endpoint`], con sus *handlers* por método.
///
/// Equivale a [`route()`](Self::route) con la ruta y el acceso que declara.
pub fn endpoint(self, endpoint: impl Endpoint, method_router: MethodRouter) -> Self {
self.route(&endpoint.path(), endpoint.access(), method_router)
}
/// Añade una ruta del panel de administración, relativa a su raíz, con sus *handlers* por
/// método.
///