diff --git a/doc/v0.6/es/src/explanation/architecture.md b/doc/v0.6/es/src/explanation/architecture.md index c423b31..808223b 100644 --- a/doc/v0.6/es/src/explanation/architecture.md +++ b/doc/v0.6/es/src/explanation/architecture.md @@ -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 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 `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 diff --git a/doc/v0.6/es/src/how-to/navigation.md b/doc/v0.6/es/src/how-to/navigation.md index fe15f36..50220e4 100644 --- a/doc/v0.6/es/src/how-to/navigation.md +++ b/doc/v0.6/es/src/how-to/navigation.md @@ -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 `Navbar` combina marca, menús y otros elementos. Con `brand_left()`, en pantallas estrechas los diff --git a/doc/v0.6/es/src/how-to/routes.md b/doc/v0.6/es/src/how-to/routes.md index 881cf1b..2893677 100644 --- a/doc/v0.6/es/src/how-to/routes.md +++ b/doc/v0.6/es/src/how-to/routes.md @@ -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 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 Para agrupar rutas bajo un prefijo común, crea un `Router` aparte y anídalo con `nest()`. Todas diff --git a/doc/v0.6/es/src/how-to/users.md b/doc/v0.6/es/src/how-to/users.md index 240477d..9d43c01 100644 --- a/doc/v0.6/es/src/how-to/users.md +++ b/doc/v0.6/es/src/how-to/users.md @@ -304,6 +304,72 @@ Html::with(|cx| { Ocultar el botón no basta: la ruta debe comprobar el permiso igualmente, porque cualquiera puede 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 { + 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 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); } +#[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; #[async_trait] @@ -369,12 +457,8 @@ impl Extension for Board { fn configure_router(&self, routes: Routes) -> Routes { routes - .public_route("/", web::get(board)) - .route( - "/notices/new", - Access::Permission(&BoardPermission::PostNotices), - web::get(new_notice), - ) + .endpoint(BoardRoute::Home, web::get(board)) + .endpoint(BoardRoute::NewNotice, web::get(new_notice)) } } @@ -399,14 +483,12 @@ impl Component for TopBar { } async fn board(request: HttpRequest) -> Result { - let can_post = has_permission(&request, &BoardPermission::PostNotices); - let mut page = Page::new(request) + Page::new(request) .with_title(Lc::n("Garden board")) - .with_child(Html::with(|_| html! { p { "The water tank is full." } })); - if can_post { - page = page.with_child(Button::anchor(Lc::n("Post a notice"), "/notices/new")); - } - page.render().await + .with_child(Html::with(|_| html! { p { "The water tank is full." } })) + .with_child(Button::anchor(Lc::n("Post a notice"), BoardRoute::NewNotice)) + .render() + .await } async fn new_notice(request: HttpRequest) -> Result { diff --git a/doc/v0.6/es/src/reference/cheatsheet.md b/doc/v0.6/es/src/reference/cheatsheet.md index 41f7c1f..a8a7bb8 100644 --- a/doc/v0.6/es/src/reference/cheatsheet.md +++ b/doc/v0.6/es/src/reference/cheatsheet.md @@ -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)` | | [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))` | +| [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)` | | [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` | | [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))` |