diff --git a/Cargo.lock b/Cargo.lock index c79e106..9a57d1c 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -160,6 +160,7 @@ dependencies = [ "matchit", "memchr", "mime", + "multer", "percent-encoding", "pin-project-lite", "serde_core", @@ -357,6 +358,12 @@ version = "0.8.7" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b" +[[package]] +name = "core_detect" +version = "1.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7f8f80099a98041a3d1622845c271458a2d73e688351bf3cb999266764b81d48" + [[package]] name = "crc32fast" version = "1.5.0" @@ -420,6 +427,20 @@ dependencies = [ "syn 2.0.104", ] +[[package]] +name = "encoding_rs" +version = "0.8.44" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "89253175e704ab869b04f9db224d38630e0211a53841a79181deae0889e169f5" +dependencies = [ + "cfg-if", + "core_detect", + "multiversion_no_op", + "rustversion", + "scopeguard", + "simdutf8", +] + [[package]] name = "equivalent" version = "1.0.2" @@ -975,6 +996,29 @@ dependencies = [ "windows-sys 0.59.0", ] +[[package]] +name = "multer" +version = "3.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "83e87776546dc87511aa5ee218730c92b666d7264ab6ed41f9d215af9cd5224b" +dependencies = [ + "bytes", + "encoding_rs", + "futures-util", + "http", + "httparse", + "memchr", + "mime", + "spin", + "version_check", +] + +[[package]] +name = "multiversion_no_op" +version = "1.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "743fb55ba31b18fb1ecef6bdc9aa2743314978ac084044301a7eee33fb99a20d" + [[package]] name = "nu-ansi-term" version = "0.46.0" @@ -1048,6 +1092,7 @@ dependencies = [ "pagetop-statics", "parking_lot", "serde", + "serde_qs", "terminal_size", "thiserror 2.0.21", "tokio", @@ -1513,6 +1558,18 @@ dependencies = [ "serde_core", ] +[[package]] +name = "serde_qs" +version = "1.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "475b9310e272827d34113bf8679b6dfb7fa0023ee049764ba003f8f984e8b5d1" +dependencies = [ + "itoa", + "percent-encoding", + "ryu", + "serde", +] + [[package]] name = "serde_spanned" version = "1.0.0" @@ -1558,6 +1615,12 @@ dependencies = [ "libc", ] +[[package]] +name = "simdutf8" +version = "0.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e3a9fe34e3e7a50316060351f37187a3f546bce95496156754b601a5fa71b76e" + [[package]] name = "siphasher" version = "1.0.1" diff --git a/doc/v0.6/es/src/SUMMARY.md b/doc/v0.6/es/src/SUMMARY.md index 4969be7..d3f1fed 100644 --- a/doc/v0.6/es/src/SUMMARY.md +++ b/doc/v0.6/es/src/SUMMARY.md @@ -37,6 +37,7 @@ - [Datos y usuarios]() - [Conectar una base de datos](how-to/database.md) - [Añadir usuarios y permisos](how-to/users.md) + - [Conectar tu propia autenticación](how-to/auth.md) - [Añadir páginas al panel de administración](how-to/admin.md) - [La aplicación]() - [Configurar la aplicación](how-to/configuration.md) diff --git a/doc/v0.6/es/src/explanation/architecture.md b/doc/v0.6/es/src/explanation/architecture.md index 8e619e7..c423b31 100644 --- a/doc/v0.6/es/src/explanation/architecture.md +++ b/doc/v0.6/es/src/explanation/architecture.md @@ -91,7 +91,8 @@ request +------------------------------------------------------------+ | middleware of the extensions (session, current user...) | | +------------------------------------------------------+ | -| | router -> your handler | | +| | router -> access of the route -> 403, or sign in | | +| | -> your handler | | | | Page::new(request) builds the Context: | | | | language, theme, user, zone | | | | .with_child(...) adds components, not HTML | | @@ -111,12 +112,48 @@ response (complete HTML, or a fragment for HTMX) servir una hoja de estilos no resuelve sesiones ni consulta la base de datos. - El **middleware** de cada extensión (`configure_middleware()`) envuelve las rutas de **todas** las extensiones. Así, `pagetop-user` resuelve la sesión una vez y cualquier ruta sabe quién pide. +- El **acceso de la ruta** se comprueba antes de llegar al *handler*: quien no lo cumple no + ejecuta nada de él (ver abajo). - El ***handler*** es un *handler* de Axum normal. `Page::new(request)` crea el **contexto** de la petición, que viajará por todos los componentes: el idioma negociado, el tema, el usuario, la zona horaria, los recursos y los mensajes. Qué pasa dentro de `render()` se explica en [Componentes, temas y renderizado](rendering.md). +## El acceso a cada ruta + +En PageTop no se puede registrar una ruta sin decir quién puede llegar a ella. `configure_router()` +no recibe el `Router` de Axum, sino `Routes`, cuyo `route()` exige un acceso: + +| Acceso | Quién llega al *handler* | +|---|---| +| `Access::Public` | Cualquiera, también un anónimo | +| `Access::Authenticated` | Quien haya iniciado sesión | +| `Access::Permission(&P)` | Quien tenga el permiso `P` | + +Lo público hay que escribirlo (con `Access::Public` o con `routes.public_route()`, que equivale), +así que una página no queda abierta porque alguien olvidara protegerla: sin indicar el acceso, no +compila. El acceso se fija al montar la ruta; en cada petición sólo se comprueba, y una ruta pública +no añade nada. + +Las rutas del **panel de administración** son un caso más estricto. El permiso se declara una sola +vez, en la página del panel (`AdminPage`), y sus rutas se montan con `routes.admin_route()`, que lo +toma de la página de la que cuelgan: `user/users/{id}/edit` exige el de `user/users`. Una ruta del +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. + +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 +con `AnonymousDenied` (`pagetop-user` le lleva al inicio de sesión y le devuelve después a donde +iba). Sin ella, nadie tiene ningún permiso y quien no cumple un acceso recibe un 403. Cómo escribir +una, en [Conectar tu propia autenticación](../how-to/auth.md). + +Lo que el acceso de la ruta no puede expresar, como «sólo el autor edita su aviso», lo comprueba el +propio *handler* con `require_permission()` o con su lógica. Los archivos estáticos son siempre +públicos; una descarga que deba protegerse se sirve desde una ruta con su acceso +(`web::Download`). + ## Sin estado mutable compartido Los ajustes son de sólo lectura, las acciones se registran una vez y los componentes globales diff --git a/doc/v0.6/es/src/explanation/coming-from-axum.md b/doc/v0.6/es/src/explanation/coming-from-axum.md index 5bc043c..69c6d05 100644 --- a/doc/v0.6/es/src/explanation/coming-from-axum.md +++ b/doc/v0.6/es/src/explanation/coming-from-axum.md @@ -9,7 +9,7 @@ necesita encima, y una forma de organizarlo. | En Axum | En PageTop | Qué cambia | |---|---|---| -| `Router::new().route(...)` | `configure_router()` de cada extensión | Cada extensión añade sus rutas al mismo `Router` | +| `Router::new().route(...)` | `routes.route(ruta, acceso, ...)` en `configure_router()` | Cada ruta declara quién puede llegar a su *handler* (`Access`); un `Router` propio se añade con `routes.nest()` | | `axum::routing::get`, `post`... | `web::get`, `web::post`... | Nada: son los mismos | | `Path`, `Query`, `Form`, `Json` | `web::Path`, `web::Query`, `web::Form`, `Json` | Nada | | `Request` | `HttpRequest` | Una vista clonable de la petición, que no consume el cuerpo y se puede pedir junto a cualquier extractor | diff --git a/doc/v0.6/es/src/faq.md b/doc/v0.6/es/src/faq.md index f7fd100..e7b6c2f 100644 --- a/doc/v0.6/es/src/faq.md +++ b/doc/v0.6/es/src/faq.md @@ -21,7 +21,7 @@ Reinicia el servidor al cambiar el código, la configuración o las traducciones **¿Puedo cambiar el CSS sin recompilar?** -Sí. Si publicas tus archivos con `serve_static_files!(router, ["./static", app] => "/static")`, +Sí. Si publicas tus archivos con `serve_static_files!(files, ["./static", app] => "/static")`, mientras el directorio `static/` exista se sirven desde el disco: editas, recargas el navegador y ves el cambio. En producción, sin ese directorio, se sirven desde el binario. Ver [Servir recursos estáticos](how-to/assets.md). diff --git a/doc/v0.6/es/src/how-to/admin.md b/doc/v0.6/es/src/how-to/admin.md index a5668d0..a2aae1d 100644 --- a/doc/v0.6/es/src/how-to/admin.md +++ b/doc/v0.6/es/src/how-to/admin.md @@ -3,10 +3,11 @@ **Objetivo:** dar a tu extensión su sitio en el panel `/admin`: una página de ajustes que el panel construye y guarda por ti, y una página propia con tu contenido, cada una protegida por su permiso. -El panel lo aporta `pagetop-admin`. No tienes que montarlo: llega con -[`pagetop-user`](users.md), que lo necesita para administrar usuarios y roles. Tu extensión sólo -**declara** sus páginas, y el panel las coloca en su sección, las enlaza desde el inicio del panel -(*dashboard*) y las muestra sólo a quien tenga permiso. +El panel es de PageTop: las páginas se **declaran** con acciones, y el panel las coloca en su +sección, las enlaza desde su página de inicio (*dashboard*) y las muestra sólo a quien tenga +permiso. Los permisos los concede [`pagetop-user`](users.md), que además declara en el panel la +gestión de usuarios y roles. Los formularios de ajustes que se guardan en la base de datos los +aporta `pagetop-admin`. ## 1. Añade la dependencia @@ -17,8 +18,9 @@ pagetop-user = { git = "https://git.cillero.es/manuelcillero/pagetop" } pagetop-seaorm = { git = "https://git.cillero.es/manuelcillero/pagetop", features = ["sqlite"] } ``` -Tu extensión sigue dependiendo sólo de `pagetop_user::User`, como en [Añadir usuarios y -permisos](users.md); el *crate* `pagetop-admin` hace falta para usar sus tipos. +Tu extensión depende de `pagetop_user::User`, como en [Añadir usuarios y permisos](users.md), y de +`pagetop_admin::Admin`, que monta las páginas de ajustes. Una extensión que sólo aporte páginas +propias, sin ajustes, no necesita `pagetop-admin`. Ese es el `Cargo.toml` de la **aplicación**, la única que elige el motor de base de datos (aquí SQLite) para todas sus extensiones. Si escribes una extensión aparte, declara `pagetop-admin` y @@ -61,15 +63,15 @@ impl Permission for GardenPermission { } ``` -Regístralo con `DeclarePermissions` para que aparezca en la pantalla de roles (lo verás en el +Decláralo con `DeclarePermissions` para que aparezca en la pantalla de roles (lo verás en el ejemplo completo). ## 3. Deja que el panel construya tus ajustes Para una página de ajustes no necesitas ni *handler* ni ruta. Describe los campos con un -`SettingsSchema` y declara la página con `AdminPageKind::ConfigForm`. El panel registra la ruta, -pinta el formulario con los valores actuales, comprueba que llegan los obligatorios y guarda lo -que se envía: +`SettingsSchema` y declara la página junto a su esquema con la acción `DeclareConfigForms` de +`pagetop-admin`. El panel registra la ruta, pinta el formulario con los valores actuales y guarda +lo que se envía, salvo que falte algún campo obligatorio o llegue vacío: ```rust,no_run # use pagetop::prelude::*; @@ -82,32 +84,38 @@ que se envía: fn garden_settings() -> SettingsSchema { SettingsSchema::new("garden") .with_field( - SettingField::text("notice", "Notice for the gardeners") - .with_help("Shown on the home page. Leave it empty to hide it."), + SettingField::text("notice", Lc::n("Notice for the gardeners")) + .with_help(Lc::n("Shown on the home page. Leave it empty to hide it.")), ) - .with_field(SettingField::number("plots", "Number of plots").with_required(true)) - .with_field(SettingField::boolean("open", "Open to new gardeners")) + .with_field(SettingField::number("plots", Lc::n("Number of plots")).with_required(true)) + .with_field(SettingField::boolean("open", Lc::n("Open to new gardeners"))) } -fn declare_pages(bag: &mut PageBag) { - bag.add(AdminPage { - path: "/admin/config/garden".to_owned(), - section: "config".to_owned(), - title: Lc::n("Garden"), - description: Some(Lc::n("Notice, plots and new gardeners.")), - weight: 0, - permission: &GardenPermission::Configure, - kind: AdminPageKind::ConfigForm(garden_settings()), +fn declare_forms(bag: &mut ConfigFormBag) { + bag.add(ConfigFormPage { + page: AdminPage::new( + "config/garden", + "config", + Lc::n("Garden"), + &GardenPermission::Configure, + ) + .with_description(Lc::n("Notice, plots and new gardeners.")), + schema: garden_settings(), }); } ``` +Regístrala en tu extensión con `actions![DeclareConfigForms::new(declare_forms)]`. + Los campos pueden ser `text`, `number`, `boolean` o `select` (con sus opciones), y admiten -`with_required()`, `with_help()` y `with_default()`. +`with_required()`, `with_help()` y `with_default()`. Las etiquetas, la ayuda y las opciones son +`Lc`, como cualquier texto visible: con `Lc::t()` salen traducidas al idioma de quien administra. Las páginas se agrupan en las secciones del panel: `people` (personas), `structure` (estructura), -`config` (configuración), `reports` (informes) y `help` (ayuda). El campo `path` es la ruta de la -página, que suele colgar de la de su sección (`/admin/config/...`). +`config` (configuración), `reports` (informes) y `help` (ayuda). El primer argumento de +`AdminPage::new()` es la ruta de la página **relativa a la raíz del panel**, que suele colgar de la +de su sección: `"config/garden"` es `/admin/config/garden` con la raíz por defecto (el ajuste +[`admin_path`](../reference/configuration.md) de `[app]`). ## 4. Lee los ajustes guardados @@ -141,54 +149,58 @@ El formulario guarda todos los valores **como texto**, también los números y l ## 5. Añade una página con tu propio contenido -Cuando la página no es un formulario de ajustes, declárala con `AdminPageKind::View` y registra tú -la ruta. El *handler* crea la página con `Page::admin()` y envuelve el contenido en un -`AdminFrame`, que añade la ruta de migas, el título y las pestañas y botones del panel: +Cuando la página no es un formulario de ajustes, declárala con la acción `DeclareAdminPages` y +registra tú su ruta con `routes.admin_route()`. El *handler* crea la página con +`Page::admin()`, le da título y añade su contenido. La plantilla de administración añade el resto: +la navegación del panel, la ruta de migas, el título y las pestañas y botones de la página: ```rust,no_run # use pagetop::prelude::*; -# use pagetop_admin::prelude::*; # #[derive(Clone, Copy, Debug)] # enum GardenPermission { SeeHarvest } # impl Permission for GardenPermission { # fn key(&self) -> CowStr { "garden.see_harvest".into() } # } -fn declare_report(bag: &mut PageBag) { - bag.add(AdminPage { - path: "/admin/reports/harvest".to_owned(), - section: "reports".to_owned(), - title: Lc::n("Harvest"), - description: Some(Lc::n("Kilos harvested by crop.")), - weight: 0, - permission: &GardenPermission::SeeHarvest, - kind: AdminPageKind::View, - }); +fn declare_report(bag: &mut AdminPageBag) { + bag.add( + AdminPage::new( + "reports/harvest", + "reports", + Lc::n("Harvest"), + &GardenPermission::SeeHarvest, + ) + .with_description(Lc::n("Kilos harvested by crop.")), + ); } async fn harvest(request: HttpRequest) -> Result { - require_permission(&request, &GardenPermission::SeeHarvest)?; - let rows = [("Tomatoes", 42), ("Lettuces", 18), ("Courgettes", 27)]; Page::admin(request) .with_title(Lc::n("Harvest")) - .with_child( - AdminFrame::new().with_title(Lc::n("Harvest")).with_child(Html::with(move |_| { - html! { - ul { - @for (crop, kilos) in rows { - li { (crop) ": " (kilos) " kg" } - } + .with_child(Html::with(move |_| { + html! { + ul { + @for (crop, kilos) in rows { + li { (crop) ": " (kilos) " kg" } } } - })), - ) + } + })) .render() .await } ``` -Declarar la página no protege la ruta: el `require_permission()` del principio sigue haciendo -falta, porque cualquiera puede escribir la URL. +La ruta se monta en `configure_router()` con `routes.admin_route("reports/harvest", +web::get(harvest))`, relativa a la raíz del panel como la página. No lleva permiso: exige el de la +página de la que cuelga, que se declara sólo una vez, en la página. PageTop lo comprueba antes de +llegar a `harvest()`, así que el *handler* no tiene que hacerlo. + +Una ruta cuelga de la página más cercana que se encuentra quitándole tramos por el final: +`reports/harvest/{year}` cuelga de `reports/harvest` y exige su mismo permiso. Una ruta del panel +que no cuelgue de ninguna página, o que se monte con `routes.route()` en vez de con +`admin_route()`, impide arrancar la aplicación. Sólo hace falta `require_permission()` para un +permiso más concreto que el de la página, como el de una acción que no todos pueden hacer. ## 6. Crea una sección propia (opcional) @@ -197,27 +209,21 @@ cuanto tenga alguna página que el usuario pueda abrir: ```rust,no_run # use pagetop::prelude::*; -# use pagetop_admin::prelude::*; -fn declare_sections(bag: &mut SectionBag) { - bag.add(AdminSection { - key: "garden".to_owned(), - path: "/admin/garden".to_owned(), - title: Lc::n("Garden"), - weight: 25, - }); +fn declare_sections(bag: &mut AdminSectionBag) { + bag.add(AdminSection::new("garden", Lc::n("Garden")).with_weight(25)); } ``` -Regístrala junto a las páginas: `actions![DeclareAdminSections::new(declare_sections), ...]`. El -peso decide su posición entre las demás (las de serie usan 10, 20, 30...). Con -`DeclareAdminTasks` y `DeclareAdminActions` puedes añadir también pestañas y botones a una página. +Regístrala junto a las páginas: +`actions![action::admin::DeclareAdminSections::new(declare_sections), ...]`. El peso decide su +posición entre las demás (las de serie usan 10, 20, 30...). Con `DeclareAdminTasks` y +`DeclareAdminActions` puedes añadir también pestañas y botones a una página. ## El ejemplo completo ```rust,no_run use pagetop::prelude::*; use pagetop_admin::prelude::*; -use pagetop_user::PermissionRegistry; use pagetop_user::prelude::*; #[derive(Clone, Copy, Debug)] @@ -258,46 +264,51 @@ fn declare_permissions(registry: &mut PermissionRegistry) { fn garden_settings() -> SettingsSchema { SettingsSchema::new("garden") .with_field( - SettingField::text("notice", "Notice for the gardeners") - .with_help("Shown on the home page. Leave it empty to hide it."), + SettingField::text("notice", Lc::n("Notice for the gardeners")) + .with_help(Lc::n("Shown on the home page. Leave it empty to hide it.")), ) - .with_field(SettingField::number("plots", "Number of plots").with_required(true)) - .with_field(SettingField::boolean("open", "Open to new gardeners")) + .with_field(SettingField::number("plots", Lc::n("Number of plots")).with_required(true)) + .with_field(SettingField::boolean("open", Lc::n("Open to new gardeners"))) } -fn declare_pages(bag: &mut PageBag) { - bag.add(AdminPage { - path: "/admin/config/garden".to_owned(), - section: "config".to_owned(), - title: Lc::n("Garden"), - description: Some(Lc::n("Notice, plots and new gardeners.")), - weight: 0, - permission: &GardenPermission::Configure, - kind: AdminPageKind::ConfigForm(garden_settings()), - }); - bag.add(AdminPage { - path: "/admin/reports/harvest".to_owned(), - section: "reports".to_owned(), - title: Lc::n("Harvest"), - description: Some(Lc::n("Kilos harvested by crop.")), - weight: 0, - permission: &GardenPermission::SeeHarvest, - kind: AdminPageKind::View, +fn declare_forms(bag: &mut ConfigFormBag) { + bag.add(ConfigFormPage { + page: AdminPage::new( + "config/garden", + "config", + Lc::n("Garden"), + &GardenPermission::Configure, + ) + .with_description(Lc::n("Notice, plots and new gardeners.")), + schema: garden_settings(), }); } +fn declare_pages(bag: &mut AdminPageBag) { + bag.add( + AdminPage::new( + "reports/harvest", + "reports", + Lc::n("Harvest"), + &GardenPermission::SeeHarvest, + ) + .with_description(Lc::n("Kilos harvested by crop.")), + ); +} + struct Garden; #[async_trait] impl Extension for Garden { fn dependencies(&self) -> Vec { - vec![&pagetop_user::User] + vec![&pagetop_user::User, &pagetop_admin::Admin] } fn actions(&self) -> Vec { actions![ - DeclarePermissions::new(declare_permissions), - DeclareAdminPages::new(declare_pages), + action::auth::DeclarePermissions::new(declare_permissions), + DeclareConfigForms::new(declare_forms), + action::admin::DeclareAdminPages::new(declare_pages), ] } @@ -306,10 +317,10 @@ impl Extension for Garden { Ok(()) } - fn configure_router(&self, router: Router) -> Router { - router - .route("/", web::get(home)) - .route("/admin/reports/harvest", web::get(harvest)) + fn configure_router(&self, routes: Routes) -> Routes { + routes + .public_route("/", web::get(home)) + .admin_route("reports/harvest", web::get(harvest)) } } @@ -352,22 +363,18 @@ async fn home(request: HttpRequest) -> Result { } async fn harvest(request: HttpRequest) -> Result { - require_permission(&request, &GardenPermission::SeeHarvest)?; - let rows = [("Tomatoes", 42), ("Lettuces", 18), ("Courgettes", 27)]; Page::admin(request) .with_title(Lc::n("Harvest")) - .with_child( - AdminFrame::new().with_title(Lc::n("Harvest")).with_child(Html::with(move |_| { - html! { - ul { - @for (crop, kilos) in rows { - li { (crop) ": " (kilos) " kg" } - } + .with_child(Html::with(move |_| { + html! { + ul { + @for (crop, kilos) in rows { + li { (crop) ": " (kilos) " kg" } } } - })), - ) + } + })) .render() .await } @@ -383,8 +390,8 @@ permisos](users.md#2-configura-la-base-de-datos-y-el-primer-administrador). ## Comprueba -1. Sin iniciar sesión, responde con la página de - acceso denegado (403). +1. Sin iniciar sesión, te lleva al formulario de + inicio de sesión. 2. Inicia sesión como `admin` y entra en **Administración** desde el menú de cuenta. El inicio del panel muestra «Garden» en Configuración y «Harvest» en Informes. 3. Abre «Garden», escribe un aviso, marca «Open to new gardeners» y guarda. La portada muestra el @@ -397,4 +404,5 @@ permisos](users.md#2-configura-la-base-de-datos-y-el-primer-administrador). - [Añadir usuarios y permisos](users.md): roles, permisos y el menú de cuenta. - [Extensiones oficiales](../reference/extensions.md#administración): lo que aporta `pagetop-admin`. -- [Intervenir con acciones](actions.md): `DeclareAdminPages` y compañía son acciones. +- [Intervenir con acciones](actions.md): `DeclareAdminPages`, `DeclareConfigForms` y compañía son + acciones. diff --git a/doc/v0.6/es/src/how-to/assets.md b/doc/v0.6/es/src/how-to/assets.md index 198e3fc..0fd5eec 100644 --- a/doc/v0.6/es/src/how-to/assets.md +++ b/doc/v0.6/es/src/how-to/assets.md @@ -60,9 +60,9 @@ pub struct MyApp; #[async_trait] impl Extension for MyApp { - fn configure_static_files(&self, router: Router) -> Router { - serve_static_files!(router, ["./static", app] => "/static"); - router + fn configure_static_files(&self, files: StaticFiles) -> StaticFiles { + serve_static_files!(files, ["./static", app] => "/static"); + files } } ``` diff --git a/doc/v0.6/es/src/how-to/auth.md b/doc/v0.6/es/src/how-to/auth.md new file mode 100644 index 0000000..c268f3d --- /dev/null +++ b/doc/v0.6/es/src/how-to/auth.md @@ -0,0 +1,301 @@ +# Conectar tu propia autenticación + +**Objetivo:** que PageTop sepa quién hace cada petición y qué permisos tiene cuando los usuarios no +vienen de `pagetop-user`, sino de otro sistema: un *proxy* que autentica, un directorio LDAP, un +proveedor OAuth o tu propia base de datos. + +PageTop no guarda usuarios ni decide quién tiene cada permiso. Sólo define cómo se **expresa** un +permiso y comprueba el acceso de cada ruta antes de llegar a su *handler*. Una extensión de +autenticación aporta tres piezas, cada una en su sitio: + +| Pieza | Dónde | Qué responde | +|---|---|---| +| `CurrentUser` | Un *middleware* en `configure_middleware()` | ¿Quién hace la petición? | +| `CheckPermission` | Una acción | ¿Tiene este permiso? | +| `AnonymousDenied` | Una acción (opcional) | ¿Qué se responde a un anónimo sin acceso? | + +`pagetop-user` es una extensión así. En esta guía escribes una más sencilla para el caso habitual +de un *proxy* inverso que ya ha autenticado al usuario y lo pasa en la cabecera `Remote-User`. + +> **Aviso:** fíate de `Remote-User` sólo si la aplicación únicamente es accesible a través del +> *proxy* y éste elimina la cabecera de las peticiones que recibe. Si un cliente puede llegar +> directamente a la aplicación, podría enviarla él mismo y hacerse pasar por cualquier usuario. + +## 1. Di quién hace la petición + +Un *middleware* lee la cabecera y deja un `CurrentUser` en la petición. PageTop lo recoge al crear +la página (`cx.current_user()`) y lo ven las acciones de permisos. Sin `CurrentUser`, el usuario es +anónimo. + +```rust,no_run +# use pagetop::prelude::*; +// Users the proxy can send: name, id and granted permissions. +const USERS: &[(&str, i32, &[&str])] = &[ + ("ana", 1, &["garden:see_harvest"]), + ("luis", 2, &[]), +]; + +async fn resolve_user(mut request: web::Request, next: web::middleware::Next) -> Response { + let user = request + .headers() + .get("remote-user") + .and_then(|value| value.to_str().ok()) + .and_then(|name| USERS.iter().find(|(user, ..)| *user == name)); + if let Some((name, id, _)) = user { + request + .extensions_mut() + .insert(CurrentUser::authenticated(*id, *name)); + } + next.run(request).await +} +``` + +Regístralo en `configure_middleware()`, que envuelve las rutas de todas las extensiones: + +```rust,no_run +# use pagetop::prelude::*; +# async fn resolve_user(request: web::Request, next: web::middleware::Next) -> Response { +# next.run(request).await +# } +# pub struct ProxyAuth; +# #[async_trait] +# impl Extension for ProxyAuth { +fn configure_middleware(&self, layers: Layers) -> Layers { + layers.layer(web::middleware::from_fn(resolve_user)) +} +# } +``` + +## 2. Concede los permisos + +La acción `CheckPermission` recibe la petición y un permiso, y pone `granted` a `true` si lo +concede. La consultan el acceso de cada ruta (`Access::Permission`), las rutas del panel de +administración y `has_permission()`. Si ninguna extensión concede un permiso, nadie lo tiene. + +```rust,no_run +# use pagetop::prelude::*; +# const USERS: &[(&str, i32, &[&str])] = &[("ana", 1, &["garden:see_harvest"])]; +fn grant(request: &HttpRequest, perm: PermissionRef, granted: &mut bool) { + let Some(id) = request.extension::().and_then(CurrentUser::id) else { + return; + }; + let key = perm.key(); + *granted = USERS + .iter() + .any(|(_, user, keys)| *user == id && keys.contains(&key.as_ref())); +} +``` + +Se registra en `actions()`. Si hay varias extensiones de autenticación, basta con que una lo +conceda. + +## 3. Ofrece el inicio de sesión al anónimo + +A quien no cumple el acceso de una ruta, PageTop le responde con la página de acceso denegado +(403). A un anónimo es mejor llevarle a identificarse: la acción `AnonymousDenied` devuelve esa +respuesta, aquí una redirección al inicio de sesión del *proxy* con la ruta a la que volver. + +```rust,no_run +# use pagetop::prelude::*; +fn offer_login(request: &HttpRequest) -> Option { + let login = RoutePath::new("/auth/login").with_param("rd", request.uri()); + // HTMX would follow the redirect and paint the login form inside the fragment it expected: + // ask it to load the whole page instead. + if request.headers().contains_key("hx-request") { + return Some([("hx-redirect", login.to_string())].into_response()); + } + Some(Redirect::see_other(login)) +} +``` + +Si devuelve `None`, responde la siguiente acción o, si no hay más, la página 403. Un usuario +autenticado sin el permiso recibe siempre el 403. + +## 4. Protege las rutas + +Las rutas no cambian: cada una declara su acceso, con independencia de qué extensión autentique +(ver [Añadir rutas](routes.md)). + +```rust,no_run +# use pagetop::prelude::*; +# #[derive(Clone, Copy, Debug)] +# enum GardenPermission { SeeHarvest } +# impl Permission for GardenPermission { +# fn key(&self) -> CowStr { "garden:see_harvest".into() } +# } +# async fn home() -> &'static str { "" } +# async fn harvest() -> &'static str { "" } +# pub struct Garden; +# #[async_trait] +# impl Extension for Garden { +fn configure_router(&self, routes: Routes) -> Routes { + routes + .public_route("/", web::get(home)) + .route( + "/harvest", + Access::Permission(&GardenPermission::SeeHarvest), + web::get(harvest), + ) +} +# } +``` + +`Access::Authenticated` sirve para lo que sólo pide haber iniciado sesión: lo cumple cualquier +petición con un `CurrentUser` autenticado. + +## El ejemplo completo + +```rust,no_run +use pagetop::prelude::*; + +// Users the proxy can send: name, id and granted permissions. +const USERS: &[(&str, i32, &[&str])] = &[ + ("ana", 1, &["garden:see_harvest"]), + ("luis", 2, &[]), +]; + +// **< Authentication >***************************************************************************** + +pub struct ProxyAuth; + +#[async_trait] +impl Extension for ProxyAuth { + fn actions(&self) -> Vec { + actions![ + action::auth::CheckPermission::new(grant), + action::auth::AnonymousDenied::new(offer_login), + ] + } + + fn configure_middleware(&self, layers: Layers) -> Layers { + layers.layer(web::middleware::from_fn(resolve_user)) + } +} + +async fn resolve_user(mut request: web::Request, next: web::middleware::Next) -> Response { + let user = request + .headers() + .get("remote-user") + .and_then(|value| value.to_str().ok()) + .and_then(|name| USERS.iter().find(|(user, ..)| *user == name)); + if let Some((name, id, _)) = user { + request + .extensions_mut() + .insert(CurrentUser::authenticated(*id, *name)); + } + next.run(request).await +} + +fn grant(request: &HttpRequest, perm: PermissionRef, granted: &mut bool) { + let Some(id) = request.extension::().and_then(CurrentUser::id) else { + return; + }; + let key = perm.key(); + *granted = USERS + .iter() + .any(|(_, user, keys)| *user == id && keys.contains(&key.as_ref())); +} + +fn offer_login(request: &HttpRequest) -> Option { + let login = RoutePath::new("/auth/login").with_param("rd", request.uri()); + if request.headers().contains_key("hx-request") { + return Some([("hx-redirect", login.to_string())].into_response()); + } + Some(Redirect::see_other(login)) +} + +// **< Application >******************************************************************************** + +#[derive(Clone, Copy, Debug)] +enum GardenPermission { + SeeHarvest, +} + +impl Permission for GardenPermission { + fn key(&self) -> CowStr { + match self { + Self::SeeHarvest => "garden:see_harvest".into(), + } + } + + fn label(&self) -> Lc { + Lc::n("See the harvest") + } +} + +fn declare_permissions(registry: &mut PermissionRegistry) { + registry.register(&GardenPermission::SeeHarvest); +} + +struct Garden; + +#[async_trait] +impl Extension for Garden { + fn dependencies(&self) -> Vec { + vec![&ProxyAuth] + } + + fn actions(&self) -> Vec { + actions![action::auth::DeclarePermissions::new(declare_permissions)] + } + + fn configure_router(&self, routes: Routes) -> Routes { + routes + .public_route("/", web::get(home)) + .route( + "/harvest", + Access::Permission(&GardenPermission::SeeHarvest), + web::get(harvest), + ) + } +} + +async fn home(request: HttpRequest) -> Result { + Page::new(request) + .with_title(Lc::n("Urban garden")) + .with_child(Html::with(|cx| { + let user = cx.current_user(); + html! { + @if let Some(name) = user.display_name() { + p { "Hello, " (name) "." } + } @else { + p { "Hello, visitor." } + } + } + })) + .render() + .await +} + +async fn harvest(request: HttpRequest) -> Result { + Page::new(request) + .with_title(Lc::n("Harvest")) + .with_child(Html::with(|_| html! { p { "Tomatoes: 42 kg." } })) + .render() + .await +} + +#[pagetop::main] +async fn main() -> std::io::Result<()> { + Application::prepare(&Garden).await.run().await +} +``` + +## Comprueba + +Sin el *proxy* delante, puedes simular sus cabeceras con `curl`: + +1. `curl -i -H "Remote-User: ana" http://localhost:8080/harvest` responde 200 con la cosecha. +2. `curl -i -H "Remote-User: luis" http://localhost:8080/harvest` responde 403: ha iniciado sesión, + pero no tiene el permiso. +3. `curl -i http://localhost:8080/harvest` responde 303 hacia `/auth/login?rd=%2Fharvest`. +4. `curl -i -H "HX-Request: true" http://localhost:8080/harvest` responde 200 sin cuerpo y con la + cabecera `HX-Redirect`. + +## Siguiente + +- [Añadir usuarios y permisos](users.md): la extensión `pagetop-user`, con cuentas, sesiones y + roles. +- [Añadir rutas](routes.md): los tres accesos de una ruta. +- [Arquitectura](../explanation/architecture.md#el-acceso-a-cada-ruta): cómo encaja el acceso en el + recorrido de una petición. diff --git a/doc/v0.6/es/src/how-to/components.md b/doc/v0.6/es/src/how-to/components.md index 7d287aa..de772b3 100644 --- a/doc/v0.6/es/src/how-to/components.md +++ b/doc/v0.6/es/src/how-to/components.md @@ -157,8 +157,7 @@ Block::new() # use pagetop::prelude::*; async fn saved(request: HttpRequest) -> Result { let mut page = Page::new(request); - page.context() - .push_message(MessageLevel::Info, Lc::n("Your changes have been saved.")); + page.push_message(MessageLevel::Info, Lc::n("Your changes have been saved.")); page.render().await } ``` diff --git a/doc/v0.6/es/src/how-to/cron.md b/doc/v0.6/es/src/how-to/cron.md index fdf6009..07e08cd 100644 --- a/doc/v0.6/es/src/how-to/cron.md +++ b/doc/v0.6/es/src/how-to/cron.md @@ -255,8 +255,8 @@ impl Extension for Garden { actions![DeclareCronJobs::new(declare_jobs)] } - fn configure_router(&self, router: Router) -> Router { - router.route("/", web::get(home)) + fn configure_router(&self, routes: Routes) -> Routes { + routes.public_route("/", web::get(home)) } } diff --git a/doc/v0.6/es/src/how-to/error-pages.md b/doc/v0.6/es/src/how-to/error-pages.md index 9a44709..325a715 100644 --- a/doc/v0.6/es/src/how-to/error-pages.md +++ b/doc/v0.6/es/src/how-to/error-pages.md @@ -181,11 +181,11 @@ struct Garden; #[async_trait] impl Extension for Garden { - fn configure_router(&self, router: Router) -> Router { - router - .route("/plots/{code}", web::get(plot)) - .route("/report", web::get(report)) - .route("/boom", web::get(boom)) + fn configure_router(&self, routes: Routes) -> Routes { + routes + .public_route("/plots/{code}", web::get(plot)) + .public_route("/report", web::get(report)) + .public_route("/boom", web::get(boom)) } } @@ -247,8 +247,8 @@ También puedes comprobarlo en una prueba (ve [Probar rutas y componentes](testi # struct Garden; # #[async_trait] # impl Extension for Garden { -# fn configure_router(&self, router: Router) -> Router { -# router.route("/plots/{code}", web::get(plot)) +# fn configure_router(&self, routes: Routes) -> Routes { +# routes.public_route("/plots/{code}", web::get(plot)) # } # } # async fn plot( diff --git a/doc/v0.6/es/src/how-to/extensions.md b/doc/v0.6/es/src/how-to/extensions.md index ad3fe29..e954651 100644 --- a/doc/v0.6/es/src/how-to/extensions.md +++ b/doc/v0.6/es/src/how-to/extensions.md @@ -48,10 +48,10 @@ impl Extension for Blog { Ok(()) } - fn configure_router(&self, router: Router) -> Router { - router - .route("/blog", web::get(index)) - .route("/blog/{slug}", web::get(post)) + fn configure_router(&self, routes: Routes) -> Routes { + routes + .public_route("/blog", web::get(index)) + .public_route("/blog/{slug}", web::get(post)) } } @@ -166,15 +166,16 @@ pub struct Headers; #[async_trait] impl Extension for Headers { - fn configure_middleware(&self, router: Router) -> Router { - router.layer(web::middleware::from_fn(custom_header)) + fn configure_middleware(&self, layers: Layers) -> Layers { + layers.layer(web::middleware::from_fn(custom_header)) } } ``` -Para una capa que sólo afecte a tus rutas, crea un `Router` propio en `configure_router()`, aplica -la capa sobre él y únelo con `router.merge(...)`. Compresión, límites, tiempo máximo, CORS y el -orden de las capas, en [Añadir *middleware*](middleware.md). +`configure_middleware()` sólo admite capas: las rutas se registran en `configure_router()`, cada +una con su acceso. Para una capa que sólo afecte a tus rutas, crea un `Router` propio, aplica la +capa sobre él y anídalo con `routes.nest(prefijo, acceso, router)`. Compresión, límites, tiempo +máximo, CORS y el orden de las capas, en [Añadir *middleware*](middleware.md). ## Comprueba diff --git a/doc/v0.6/es/src/how-to/forms.md b/doc/v0.6/es/src/how-to/forms.md index ea388cc..4224600 100644 --- a/doc/v0.6/es/src/how-to/forms.md +++ b/doc/v0.6/es/src/how-to/forms.md @@ -94,8 +94,8 @@ pub struct Contact; #[async_trait] impl Extension for Contact { - fn configure_router(&self, router: Router) -> Router { - router.route("/contact", web::get(show).post(send)) + fn configure_router(&self, routes: Routes) -> Routes { + routes.public_route("/contact", web::get(show).post(send)) } } @@ -121,8 +121,7 @@ async fn send( if data.message.trim().is_empty() { // Shows the form again with a message. let mut page = Page::new(request).with_child(contact_form()); - page.context() - .push_message(MessageLevel::Error, Lc::n("Please write a message.")); + page.push_message(MessageLevel::Error, Lc::n("Please write a message.")); return page.render().await.map(IntoResponse::into_response); } // ... save or send `data` ... diff --git a/doc/v0.6/es/src/how-to/htmx-delete.md b/doc/v0.6/es/src/how-to/htmx-delete.md index 8dfd935..71927d4 100644 --- a/doc/v0.6/es/src/how-to/htmx-delete.md +++ b/doc/v0.6/es/src/how-to/htmx-delete.md @@ -145,10 +145,10 @@ impl Extension for Allotments { vec![&pagetop_htmx::Htmx] } - fn configure_router(&self, router: Router) -> Router { - router - .route("/", web::get(home)) - .route("/plots/{id}", web::delete(delete)) + fn configure_router(&self, routes: Routes) -> Routes { + routes + .public_route("/", web::get(home)) + .public_route("/plots/{id}", web::delete(delete)) } } diff --git a/doc/v0.6/es/src/how-to/htmx-edit.md b/doc/v0.6/es/src/how-to/htmx-edit.md index c1e2a7a..976b933 100644 --- a/doc/v0.6/es/src/how-to/htmx-edit.md +++ b/doc/v0.6/es/src/how-to/htmx-edit.md @@ -161,11 +161,11 @@ impl Extension for Coordinator { vec![&pagetop_htmx::Htmx] } - fn configure_router(&self, router: Router) -> Router { - router - .route("/", web::get(home)) - .route("/contact", web::get(show).put(save)) - .route("/contact/edit", web::get(edit)) + fn configure_router(&self, routes: Routes) -> Routes { + routes + .public_route("/", web::get(home)) + .public_route("/contact", web::get(show).put(save)) + .public_route("/contact/edit", web::get(edit)) } } diff --git a/doc/v0.6/es/src/how-to/htmx-infinite.md b/doc/v0.6/es/src/how-to/htmx-infinite.md index 7801c9f..327413e 100644 --- a/doc/v0.6/es/src/how-to/htmx-infinite.md +++ b/doc/v0.6/es/src/how-to/htmx-infinite.md @@ -98,10 +98,10 @@ impl Extension for Diary { vec![&pagetop_htmx::Htmx] } - fn configure_router(&self, router: Router) -> Router { - router - .route("/", web::get(diary)) - .route("/diary/entries", web::get(more_entries)) + fn configure_router(&self, routes: Routes) -> Routes { + routes + .public_route("/", web::get(diary)) + .public_route("/diary/entries", web::get(more_entries)) } } diff --git a/doc/v0.6/es/src/how-to/htmx-load.md b/doc/v0.6/es/src/how-to/htmx-load.md index 5c87c52..6368630 100644 --- a/doc/v0.6/es/src/how-to/htmx-load.md +++ b/doc/v0.6/es/src/how-to/htmx-load.md @@ -105,11 +105,11 @@ impl Extension for Garden { vec![&pagetop_htmx::Htmx] } - fn configure_router(&self, router: Router) -> Router { - router - .route("/", web::get(home)) - .route("/forecast", web::get(forecast)) - .route("/comments", web::get(comments)) + fn configure_router(&self, routes: Routes) -> Routes { + routes + .public_route("/", web::get(home)) + .public_route("/forecast", web::get(forecast)) + .public_route("/comments", web::get(comments)) } } diff --git a/doc/v0.6/es/src/how-to/htmx-polling.md b/doc/v0.6/es/src/how-to/htmx-polling.md index 20db60b..3fafaaa 100644 --- a/doc/v0.6/es/src/how-to/htmx-polling.md +++ b/doc/v0.6/es/src/how-to/htmx-polling.md @@ -105,10 +105,10 @@ impl Extension for Watering { vec![&pagetop_htmx::Htmx] } - fn configure_router(&self, router: Router) -> Router { - router - .route("/", web::get(home)) - .route("/watering", web::get(status).post(start)) + fn configure_router(&self, routes: Routes) -> Routes { + routes + .public_route("/", web::get(home)) + .public_route("/watering", web::get(status).post(start)) } } diff --git a/doc/v0.6/es/src/how-to/htmx-responses.md b/doc/v0.6/es/src/how-to/htmx-responses.md index f5756e6..beb3e0d 100644 --- a/doc/v0.6/es/src/how-to/htmx-responses.md +++ b/doc/v0.6/es/src/how-to/htmx-responses.md @@ -129,13 +129,13 @@ impl Extension for Newsletter { vec![&pagetop_htmx::Htmx] } - fn configure_router(&self, router: Router) -> Router { - router - .route("/", web::get(home)) - .route("/subscribe", web::post(subscribe)) - .route("/subscribers", web::get(subscribers)) - .route("/season/close", web::post(close_season)) - .route("/season/closed", web::get(season_closed)) + fn configure_router(&self, routes: Routes) -> Routes { + routes + .public_route("/", web::get(home)) + .public_route("/subscribe", web::post(subscribe)) + .public_route("/subscribers", web::get(subscribers)) + .public_route("/season/close", web::post(close_season)) + .public_route("/season/closed", web::get(season_closed)) } } diff --git a/doc/v0.6/es/src/how-to/htmx-search.md b/doc/v0.6/es/src/how-to/htmx-search.md index ab9388f..352859c 100644 --- a/doc/v0.6/es/src/how-to/htmx-search.md +++ b/doc/v0.6/es/src/how-to/htmx-search.md @@ -134,10 +134,10 @@ impl Extension for PlantFinder { vec![&pagetop_htmx::Htmx] } - fn configure_router(&self, router: Router) -> Router { - router - .route("/", web::get(|| async { Redirect::see_other("/plants") })) - .route("/plants", web::get(plants)) + fn configure_router(&self, routes: Routes) -> Routes { + routes + .public_route("/", web::get(|| async { Redirect::see_other("/plants") })) + .public_route("/plants", web::get(plants)) } } diff --git a/doc/v0.6/es/src/how-to/htmx-setup.md b/doc/v0.6/es/src/how-to/htmx-setup.md index ab61fcf..7458d99 100644 --- a/doc/v0.6/es/src/how-to/htmx-setup.md +++ b/doc/v0.6/es/src/how-to/htmx-setup.md @@ -169,10 +169,10 @@ impl Extension for Clock { vec![&pagetop_htmx::Htmx] } - fn configure_router(&self, router: Router) -> Router { - router - .route("/", web::get(home)) - .route("/time", web::get(time)) + fn configure_router(&self, routes: Routes) -> Routes { + routes + .public_route("/", web::get(home)) + .public_route("/time", web::get(time)) } } diff --git a/doc/v0.6/es/src/how-to/htmx-tables.md b/doc/v0.6/es/src/how-to/htmx-tables.md index e0522de..5f321ec 100644 --- a/doc/v0.6/es/src/how-to/htmx-tables.md +++ b/doc/v0.6/es/src/how-to/htmx-tables.md @@ -104,7 +104,7 @@ async fn list(request: HttpRequest, web::Query(query): web::Query) -> let mut table = harvests(&cx, sort, dir, page); return HtmxResponse::new(table.render(&mut cx).await).into_response(); } - let mut full = Page::new(request).with_title(Lc::n("Harvests")); + let full = Page::new(request).with_title(Lc::n("Harvests")); let table = harvests(full.context(), sort, dir, page); full.with_child(table).render().await.into_response() } @@ -148,10 +148,10 @@ impl Extension for HarvestLog { vec![&pagetop_htmx::Htmx] } - fn configure_router(&self, router: Router) -> Router { - router - .route("/", web::get(|| async { Redirect::see_other("/harvests") })) - .route("/harvests", web::get(list)) + fn configure_router(&self, routes: Routes) -> Routes { + routes + .public_route("/", web::get(|| async { Redirect::see_other("/harvests") })) + .public_route("/harvests", web::get(list)) } } @@ -172,7 +172,7 @@ async fn list(request: HttpRequest, web::Query(query): web::Query) -> let mut table = harvests(&cx, sort, dir, page); return HtmxResponse::new(table.render(&mut cx).await).into_response(); } - let mut full = Page::new(request).with_title(Lc::n("Harvests")); + let full = Page::new(request).with_title(Lc::n("Harvests")); let table = harvests(full.context(), sort, dir, page); full.with_child(table).render().await.into_response() } diff --git a/doc/v0.6/es/src/how-to/htmx-validation.md b/doc/v0.6/es/src/how-to/htmx-validation.md index 9887237..589bf0f 100644 --- a/doc/v0.6/es/src/how-to/htmx-validation.md +++ b/doc/v0.6/es/src/how-to/htmx-validation.md @@ -164,7 +164,7 @@ async fn join(request: HttpRequest, web::Form(data): web::Form) -> Res } let mut page = Page::new(request).with_child(content); if let Some(error) = error { - page.context().push_message(MessageLevel::Error, error); + page.push_message(MessageLevel::Error, error); } page.render().await.into_response() } @@ -187,11 +187,11 @@ impl Extension for JoinTheGarden { vec![&pagetop_htmx::Htmx] } - fn configure_router(&self, router: Router) -> Router { - router - .route("/", web::get(home)) - .route("/join", web::post(join)) - .route("/join/check", web::post(check_username)) + fn configure_router(&self, routes: Routes) -> Routes { + routes + .public_route("/", web::get(home)) + .public_route("/join", web::post(join)) + .public_route("/join/check", web::post(check_username)) } } @@ -289,7 +289,7 @@ async fn join(request: HttpRequest, web::Form(data): web::Form) -> Res } let mut page = Page::new(request).with_child(content); if let Some(error) = error { - page.context().push_message(MessageLevel::Error, error); + page.push_message(MessageLevel::Error, error); } page.render().await.into_response() } diff --git a/doc/v0.6/es/src/how-to/mail.md b/doc/v0.6/es/src/how-to/mail.md index 2907a74..4464c8a 100644 --- a/doc/v0.6/es/src/how-to/mail.md +++ b/doc/v0.6/es/src/how-to/mail.md @@ -347,6 +347,19 @@ schedule = "@delay 30s" # 30 s after each batch ends (1 minute by default). La cola guarda los mensajes completos y sin cifrar hasta entregarlos: pueden contener datos personales y enlaces de un solo uso, también en las copias de seguridad de la base de datos. +## 10. Comprueba el envío desde el panel + +Para saber si la configuración funciona en producción no hace falta escribir nada: `pagetop-mail` +añade al [panel de administración](admin.md) la página **Configuración > Correo electrónico** +(`/admin/config/mail`). Muestra el transporte, el remitente y el servidor configurados (nunca las +credenciales) y envía un correo de prueba a la dirección que escribas. Espera al resultado, así que +al volver a la página ves si se ha enviado o el error del servidor. Con `redirect_to`, el correo +llega a esa dirección, como todos. + +La página exige el permiso `mail:send_test`, que aparece en la pantalla de roles de +[`pagetop-user`](users.md) en el grupo «Correo electrónico». Los administradores lo tienen sin +asignarlo. + ## El ejemplo completo Un formulario en `/harvest` donde cada visitante pide el aviso de la cosecha, que recibe por @@ -403,8 +416,8 @@ impl Extension for Garden { actions![DeclareMailPreviews::new(declare_previews)] } - fn configure_router(&self, router: Router) -> Router { - router.route("/harvest", web::get(show).post(notify)) + fn configure_router(&self, routes: Routes) -> Routes { + routes.public_route("/harvest", web::get(show).post(notify)) } } @@ -457,7 +470,7 @@ async fn notify( let mut page = Page::new(request) .with_title(Lc::n("Harvest")) .with_child(notice_form()); - page.context().push_message( + page.push_message( MessageLevel::Error, Lc::n("The notice could not be sent. Check the address and try again."), ); @@ -524,8 +537,8 @@ base_url = "https://garden.example.com" # fn dependencies(&self) -> Vec { # vec![&pagetop_mail::Mail] # } -# fn configure_router(&self, router: Router) -> Router { -# router.route("/harvest", web::post(notify)) +# fn configure_router(&self, routes: Routes) -> Routes { +# routes.public_route("/harvest", web::post(notify)) # } # } # #[derive(Deserialize)] diff --git a/doc/v0.6/es/src/how-to/middleware.md b/doc/v0.6/es/src/how-to/middleware.md index 78ec931..9168bcd 100644 --- a/doc/v0.6/es/src/how-to/middleware.md +++ b/doc/v0.6/es/src/how-to/middleware.md @@ -37,8 +37,8 @@ pub struct Garden; #[async_trait] impl Extension for Garden { - fn configure_middleware(&self, router: Router) -> Router { - router.layer(web::middleware::from_fn(timing)) + fn configure_middleware(&self, layers: Layers) -> Layers { + layers.layer(web::middleware::from_fn(timing)) } } ``` @@ -71,8 +71,8 @@ use tower_http::timeout::TimeoutLayer; # pub struct Garden; # #[async_trait] # impl Extension for Garden { -fn configure_middleware(&self, router: Router) -> Router { - router +fn configure_middleware(&self, layers: Layers) -> Layers { + layers // Requests with a body over 1 MiB get a 413 Payload Too Large. .layer(RequestBodyLimitLayer::new(1024 * 1024)) // Requests that take more than 30 seconds get a 408 Request Timeout. @@ -107,8 +107,8 @@ inicializaron antes. ## 4. Aplica una capa sólo a tus rutas `configure_middleware()` afecta a todo. Para que una capa sólo envuelva unas rutas, crea con ellas -un `Router` propio en `configure_router()`, ponle la capa y únelo al resto con `merge()`. Es lo -natural para CORS, que sólo debe abrirse en la API: +un `Router` propio en `configure_router()`, ponle la capa y anídalo bajo su prefijo con `nest()`, +con el acceso que compartan sus rutas. Es lo natural para CORS, que sólo debe abrirse en la API: ```rust,no_run # use pagetop::prelude::*; @@ -122,16 +122,18 @@ use tower_http::cors::CorsLayer; # pub struct Garden; # #[async_trait] # impl Extension for Garden { -fn configure_router(&self, router: Router) -> Router { +fn configure_router(&self, routes: Routes) -> Routes { let cors = CorsLayer::new() .allow_origin(web::http::HeaderValue::from_static("https://garden.example.org")) .allow_methods([web::http::Method::GET]); let api = Router::new() - .route("/api/plots", web::get(plots)) + .route("/plots", web::get(plots)) .layer(cors); - router.route("/", web::get(home)).merge(api) + routes + .public_route("/", web::get(home)) + .nest("/api", Access::Public, api) } # } ``` @@ -170,8 +172,8 @@ struct Garden; #[async_trait] impl Extension for Garden { - fn configure_middleware(&self, router: Router) -> Router { - router + fn configure_middleware(&self, layers: Layers) -> Layers { + layers .layer(web::middleware::from_fn(timing)) .layer(RequestBodyLimitLayer::new(1024 * 1024)) .layer(TimeoutLayer::with_status_code( @@ -181,19 +183,19 @@ impl Extension for Garden { .layer(CompressionLayer::new()) } - fn configure_router(&self, router: Router) -> Router { + fn configure_router(&self, routes: Routes) -> Routes { let cors = CorsLayer::new() .allow_origin(web::http::HeaderValue::from_static("https://garden.example.org")) .allow_methods([web::http::Method::GET]); let api = Router::new() - .route("/api/plots", web::get(plots)) + .route("/plots", web::get(plots)) .layer(cors); - router - .route("/", web::get(home)) - .route("/notes", web::post(notes)) - .merge(api) + routes + .public_route("/", web::get(home)) + .public_route("/notes", web::post(notes)) + .nest("/api", Access::Public, api) } } diff --git a/doc/v0.6/es/src/how-to/pages.md b/doc/v0.6/es/src/how-to/pages.md index 6d9126e..9eed630 100644 --- a/doc/v0.6/es/src/how-to/pages.md +++ b/doc/v0.6/es/src/how-to/pages.md @@ -76,6 +76,11 @@ Page::new(request) `with_metadata()` genera `` y `with_property()` genera ``, la forma que usa Open Graph. +Título, descripción y metadatos se guardan en el contexto de la página, así que también un +componente puede fijarlos mientras se renderiza (por ejemplo, un artículo con su propia +descripción), con `cx.alter_description()`, `cx.alter_metadata()` o `cx.alter_property()`: el +`` se genera después del ``. + ## 4. Añade estilos y *scripts* Una página puede pedir sus propios recursos. PageTop los ordena, evita duplicados y los añade al diff --git a/doc/v0.6/es/src/how-to/routes.md b/doc/v0.6/es/src/how-to/routes.md index ed4a4be..881cf1b 100644 --- a/doc/v0.6/es/src/how-to/routes.md +++ b/doc/v0.6/es/src/how-to/routes.md @@ -8,8 +8,26 @@ una página, un error, una redirección o JSON. Cada extensión registra sus rutas en `configure_router()`. Recibe las rutas acumuladas por las extensiones anteriores, añade las suyas y las devuelve. +Cada ruta lleva su acceso (`Access`), que PageTop comprueba antes de llegar al *handler*: + +| Acceso | Quién llega al *handler* | +|---|---| +| `Access::Public` | Cualquiera, también un visitante anónimo | +| `Access::Authenticated` | Cualquier usuario con la sesión iniciada | +| `Access::Permission(&P)` | Quien tenga el permiso `P` (ver [Añadir usuarios y permisos](users.md)) | + +No hay forma de registrar una ruta sin indicarlo, así que una página no queda abierta por olvido. +Como casi todas las rutas son públicas, `routes.public_route(path, ...)` equivale a +`routes.route(path, Access::Public, ...)` y se lee mejor. A quien no cumple el acceso se le +responde con un 403, salvo a un visitante anónimo, al que una extensión de autenticación como +`pagetop-user` le ofrece antes iniciar sesión. + ```rust,no_run # use pagetop::prelude::*; +# struct BlogPermission; +# impl Permission for BlogPermission { +# fn key(&self) -> CowStr { "blog:publish".into() } +# } # async fn list() -> &'static str { "" } # async fn view() -> &'static str { "" } # async fn create() -> &'static str { "" } @@ -17,38 +35,48 @@ pub struct Blog; #[async_trait] impl Extension for Blog { - fn configure_router(&self, router: Router) -> Router { - router - .route("/posts", web::get(list)) - .route("/posts/{id}", web::get(view)) - .route("/posts/new", web::get(create).post(create)) + fn configure_router(&self, routes: Routes) -> Routes { + routes + .public_route("/posts", web::get(list)) + .public_route("/posts/{id}", web::get(view)) + .route( + "/posts/new", + Access::Permission(&BlogPermission), + web::get(create).post(create), + ) } } ``` Los métodos disponibles son `web::get`, `web::post`, `web::put`, `web::patch` y `web::delete`, y se -encadenan para atender varios en la misma ruta. +encadenan para atender varios en la misma ruta. Si cada método necesita un acceso distinto (leer +para todos y guardar con un permiso, por ejemplo), registra la misma ruta dos veces, cada una con +su método y su acceso. ## 2. Agrupa rutas bajo un prefijo -Para agrupar rutas bajo un prefijo común, crea un `Router` aparte y anídalo: +Para agrupar rutas bajo un prefijo común, crea un `Router` aparte y anídalo con `nest()`. Todas +sus rutas comparten el acceso que indiques: ```rust,no_run # use pagetop::prelude::*; -# async fn dashboard() -> &'static str { "" } -# async fn users() -> &'static str { "" } -# pub struct Admin; +# async fn beds() -> &'static str { "" } +# async fn crops() -> &'static str { "" } +# pub struct Garden; # #[async_trait] -# impl Extension for Admin { -fn configure_router(&self, router: Router) -> Router { - let admin = Router::new() - .route("/dashboard", web::get(dashboard)) - .route("/users", web::get(users)); - router.nest("/admin", admin) +# impl Extension for Garden { +fn configure_router(&self, routes: Routes) -> Routes { + let garden = Router::new() + .route("/beds", web::get(beds)) + .route("/crops", web::get(crops)); + routes.nest("/garden", Access::Authenticated, garden) } # } ``` +Las rutas del panel de administración no se registran así, sino con `routes.admin_route()`, que +exige el permiso de su página (ver [Añadir páginas al panel de administración](admin.md)). + ## 3. Lee los datos de la petición Un *handler* es una función `async` que recibe lo que necesite de la petición y devuelve algo que diff --git a/doc/v0.6/es/src/how-to/services.md b/doc/v0.6/es/src/how-to/services.md index 45f095f..12dbb8e 100644 --- a/doc/v0.6/es/src/how-to/services.md +++ b/doc/v0.6/es/src/how-to/services.md @@ -262,11 +262,11 @@ impl Extension for Garden { Ok(()) } - fn configure_router(&self, router: Router) -> Router { - router - .route("/", web::get(page)) - .route("/plots", web::get(page)) - .route("/harvest", web::get(page)) + fn configure_router(&self, routes: Routes) -> Routes { + routes + .public_route("/", web::get(page)) + .public_route("/plots", web::get(page)) + .public_route("/harvest", web::get(page)) } } @@ -338,8 +338,8 @@ sola prueba por flujo (ve [Probar rutas y componentes](testing.md)). # fn settings(&self) -> Option<&'static dyn LoadSettings> { # Some(&SETTINGS) # } -# fn configure_router(&self, router: Router) -> Router { -# router.route("/plots", web::get(page)).route("/harvest", web::get(page)) +# fn configure_router(&self, routes: Routes) -> Routes { +# routes.public_route("/plots", web::get(page)).public_route("/harvest", web::get(page)) # } # } # async fn page(request: HttpRequest) -> Result { diff --git a/doc/v0.6/es/src/how-to/testing.md b/doc/v0.6/es/src/how-to/testing.md index 5c1cd01..258d463 100644 --- a/doc/v0.6/es/src/how-to/testing.md +++ b/doc/v0.6/es/src/how-to/testing.md @@ -20,8 +20,8 @@ struct MyApp; #[async_trait] impl Extension for MyApp { - fn configure_router(&self, router: Router) -> Router { - router.route("/hello/{name}", web::get(hello)) + fn configure_router(&self, routes: Routes) -> Routes { + routes.public_route("/hello/{name}", web::get(hello)) } } @@ -76,8 +76,8 @@ struct Contact; #[async_trait] impl Extension for Contact { - fn configure_router(&self, router: Router) -> Router { - router.route("/contact", web::post(send)) + fn configure_router(&self, routes: Routes) -> Routes { + routes.public_route("/contact", web::post(send)) } } @@ -152,8 +152,8 @@ impl Extension for Clock { vec![&pagetop_htmx::Htmx] } - fn configure_router(&self, router: Router) -> Router { - router.route("/time", web::get(time)) + fn configure_router(&self, routes: Routes) -> Routes { + routes.public_route("/time", web::get(time)) } } diff --git a/doc/v0.6/es/src/how-to/uploads.md b/doc/v0.6/es/src/how-to/uploads.md index 853e0a7..6d448a5 100644 --- a/doc/v0.6/es/src/how-to/uploads.md +++ b/doc/v0.6/es/src/how-to/uploads.md @@ -240,10 +240,10 @@ struct Garden; #[async_trait] impl Extension for Garden { - fn configure_router(&self, router: Router) -> Router { - router - .route("/photos", web::get(gallery).post(upload)) - .route("/photos/{index}", web::get(photo)) + fn configure_router(&self, routes: Routes) -> Routes { + routes + .public_route("/photos", web::get(gallery).post(upload)) + .public_route("/photos/{index}", web::get(photo)) } } @@ -288,7 +288,7 @@ async fn gallery(request: HttpRequest) -> Result { async fn show_form(request: HttpRequest, error: Lc) -> Result { let mut page = gallery_page(request); - page.context().push_message(MessageLevel::Error, error); + page.push_message(MessageLevel::Error, error); page.render().await.map(IntoResponse::into_response) } @@ -380,10 +380,10 @@ otro lugar en `config/test.toml` (por ejemplo, `"target/test-uploads"`): # struct Garden; # #[async_trait] # impl Extension for Garden { -# fn configure_router(&self, router: Router) -> Router { -# router -# .route("/photos", web::post(upload)) -# .route("/photos/{index}", web::get(photo)) +# fn configure_router(&self, routes: Routes) -> Routes { +# routes +# .public_route("/photos", web::post(upload)) +# .public_route("/photos/{index}", web::get(photo)) # } # } # #[derive(Deserialize)] @@ -393,7 +393,7 @@ otro lugar en `config/test.toml` (por ejemplo, `"target/test-uploads"`): # } # async fn show_form(request: HttpRequest, error: Lc) -> Result { # let mut page = Page::new(request); -# page.context().push_message(MessageLevel::Error, error); +# page.push_message(MessageLevel::Error, error); # page.render().await.map(IntoResponse::into_response) # } # async fn upload(request: HttpRequest, multipart: web::Multipart) -> Result { diff --git a/doc/v0.6/es/src/how-to/users.md b/doc/v0.6/es/src/how-to/users.md index a38bac6..240477d 100644 --- a/doc/v0.6/es/src/how-to/users.md +++ b/doc/v0.6/es/src/how-to/users.md @@ -28,10 +28,10 @@ impl Extension for Board { } ``` -`User` declara por su cuenta lo que necesita: `pagetop-seaorm`, `pagetop-htmx`, `pagetop-mail` y -el panel `pagetop-admin`. Al arrancar crea sus tablas y registra sus rutas, entre ellas -`/user/login`, `/user/register`, `/user` (el perfil), `/user/email` (cambiar el email) y -`/user/password/reset` (recuperar la contraseña). +`User` declara por su cuenta lo que necesita: `pagetop-seaorm`, `pagetop-htmx` y `pagetop-mail`, y +sus páginas de usuarios, roles y permisos en el panel de administración. Al arrancar crea sus tablas +y registra sus rutas, entre ellas `/user/login`, `/user/register`, `/user` (el perfil), `/user/email` +(cambiar el email) y `/user/password/reset` (recuperar la contraseña). La recuperación de contraseña envía un correo con un enlace, como el cambio de email, que no se aplica hasta que se confirma desde la nueva dirección. Además, la cuenta recibe un aviso cuando @@ -201,7 +201,8 @@ impl Permission for BoardPermission { } ``` -Para que aparezca en la pantalla de roles, regístralo con la acción `DeclarePermissions`: +Para que aparezca en la pantalla de roles, decláralo con la acción `DeclarePermissions` de +PageTop: ```rust,no_run # use pagetop::prelude::*; @@ -210,9 +211,6 @@ Para que aparezca en la pantalla de roles, regístralo con la acción `DeclarePe # impl Permission for BoardPermission { # fn key(&self) -> CowStr { "board:post_notices".into() } # } -use pagetop_user::PermissionRegistry; -use pagetop_user::prelude::*; - fn declare_permissions(registry: &mut PermissionRegistry) { registry.register(&BoardPermission::PostNotices); } @@ -222,17 +220,22 @@ pub struct Board; #[async_trait] impl Extension for Board { fn actions(&self) -> Vec { - actions![DeclarePermissions::new(declare_permissions)] + actions![action::auth::DeclarePermissions::new(declare_permissions)] } // ... dependencies(), initialize() and configure_router() ... } ``` +Si una ruta o una página del panel exige un permiso que no has declarado, PageTop lo avisa en las +trazas al arrancar: nadie podría concederlo, y sólo entrarían los administradores. + ## 5. Protege rutas y adapta la interfaz -`require_permission()` corta la petición con un error 403 si falta el permiso. Va al principio del -*handler*, con `?`: +Cada ruta se registra con su acceso. Con `Access::Permission`, PageTop comprueba el permiso antes de +llegar al *handler*; a quien no lo tiene le responde con un 403 y, si no ha iniciado sesión, +`pagetop-user` le lleva antes al formulario de inicio de sesión y le devuelve después a la ruta que +pedía: ```rust,no_run # use pagetop::prelude::*; @@ -241,15 +244,26 @@ impl Extension for Board { # impl Permission for BoardPermission { # fn key(&self) -> CowStr { "board:post_notices".into() } # } -async fn new_notice(request: HttpRequest) -> Result { - require_permission(&request, &BoardPermission::PostNotices)?; - Page::new(request) - .with_title(Lc::n("New notice")) - .render() - .await +# async fn board() -> &'static str { "" } +# async fn new_notice() -> &'static str { "" } +# pub struct Board; +# #[async_trait] +# 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), + ) } +# } ``` +Para una comprobación más concreta que la de la ruta (que sólo el autor pueda editar su aviso, por +ejemplo), `require_permission()` corta la petición con un 403 desde el propio *handler*. + `has_permission()` devuelve un `bool`, para mostrar u ocultar lo que no se puede usar: ```rust,no_run @@ -305,7 +319,6 @@ Los administradores tienen todos los permisos sin necesidad de asignarlos. ```rust,no_run use pagetop::prelude::*; -use pagetop_user::PermissionRegistry; use pagetop_user::prelude::*; #[derive(Clone, Copy, Debug)] @@ -346,7 +359,7 @@ impl Extension for Board { } fn actions(&self) -> Vec { - actions![DeclarePermissions::new(declare_permissions)] + actions![action::auth::DeclarePermissions::new(declare_permissions)] } async fn initialize(&self) -> Result<(), BoxError> { @@ -354,10 +367,14 @@ impl Extension for Board { Ok(()) } - fn configure_router(&self, router: Router) -> Router { - router - .route("/", web::get(board)) - .route("/notices/new", web::get(new_notice)) + fn configure_router(&self, routes: Routes) -> Routes { + routes + .public_route("/", web::get(board)) + .route( + "/notices/new", + Access::Permission(&BoardPermission::PostNotices), + web::get(new_notice), + ) } } @@ -393,7 +410,6 @@ async fn board(request: HttpRequest) -> Result { } async fn new_notice(request: HttpRequest) -> Result { - require_permission(&request, &BoardPermission::PostNotices)?; Page::new(request) .with_title(Lc::n("New notice")) .with_child(Html::with(|_| html! { p { "Write your notice here." } })) @@ -410,7 +426,7 @@ async fn main() -> std::io::Result<()> { ## Comprueba 1. Sin iniciar sesión, la portada no muestra *Post a notice*, y - responde con la página de acceso denegado (403). + te lleva al formulario de inicio de sesión. 2. Inicia sesión como `admin`: aparece el botón y la página se abre. 3. Crea una cuenta con el enlace «Crear una cuenta» del menú, concede el permiso al rol **authenticated** e inicia sesión con ella: también puede publicar. @@ -420,4 +436,5 @@ async fn main() -> std::io::Result<()> { - [Opciones de configuración](../reference/configuration.md#user): registro, sesiones y contraseñas. - [Extensiones oficiales](../reference/extensions.md): lo que aportan `pagetop-user` y - `pagetop-admin`. + `pagetop-admin`, y el panel de administración. +- [Conectar tu propia autenticación](auth.md): si los usuarios vienen de otro sistema. diff --git a/doc/v0.6/es/src/intro.md b/doc/v0.6/es/src/intro.md index 1c10f60..5b1479a 100644 --- a/doc/v0.6/es/src/intro.md +++ b/doc/v0.6/es/src/intro.md @@ -16,8 +16,8 @@ struct HelloWorld; #[async_trait] impl Extension for HelloWorld { - fn configure_router(&self, router: Router) -> Router { - router.route("/", web::get(home)) + fn configure_router(&self, routes: Routes) -> Routes { + routes.public_route("/", web::get(home)) } } diff --git a/doc/v0.6/es/src/reference/cheatsheet.md b/doc/v0.6/es/src/reference/cheatsheet.md index de34e7d..41f7c1f 100644 --- a/doc/v0.6/es/src/reference/cheatsheet.md +++ b/doc/v0.6/es/src/reference/cheatsheet.md @@ -12,12 +12,12 @@ Lo esencial de PageTop en una página. Cada línea enlaza con la guía que lo ex | [Lanzar una tarea en segundo plano](../how-to/extensions.md#3-inicialízala-al-arrancar) | `async fn start(&self) -> Result<(), BoxError>` (y `shutdown()`) | | [Programar una tarea periódica](../how-to/cron.md) | `Job::new("app.key", Schedule::cron("0 3 * * *"), job_fn)` | | [Ejecutar una tarea programada ya](../how-to/cron.md#comprueba) | `pagetop_cron::run_now("app.key").await` | -| [Añadir rutas](../how-to/routes.md) | `router.route("/path", web::get(handler))` | -| [Servir archivos](../how-to/assets.md) | `serve_static_files!(router, ["./static", app] => "/static")` | +| [Añadir rutas](../how-to/routes.md) | `routes.public_route("/path", web::get(handler))` | +| [Servir archivos](../how-to/assets.md) | `serve_static_files!(files, ["./static", app] => "/static")` | | [Leer un ajuste](../how-to/configuration.md) | `global::SETTINGS.app.name` | | [Escribir una traza](../how-to/logging.md) | `trace::info!("...")` | | [Compartir un servicio](../how-to/services.md) | `static X: LazyLock = LazyLock::new(...)` | -| [Añadir *middleware*](../how-to/middleware.md) | `fn configure_middleware(&self, router: Router) -> Router` | +| [Añadir *middleware*](../how-to/middleware.md) | `fn configure_middleware(&self, layers: Layers) -> Layers` | ## *Handlers* @@ -33,7 +33,11 @@ Lo esencial de PageTop en una página. Cada línea enlaza con la guía que lo ex | [Redirigir](../how-to/routes.md#4-elige-la-respuesta) | `Redirect::see_other("/target")` | | [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](../how-to/users.md) | `require_permission(&request, &MyPermission::X)?` | +| [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))` | +| [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))` | +| [Exigir un permiso en el *handler*](../how-to/users.md#5-protege-rutas-y-adapta-la-interfaz) | `require_permission(&request, &MyPermission::X)?` | ## Páginas @@ -43,7 +47,7 @@ Lo esencial de PageTop en una página. Cada línea enlaza con la guía que lo ex | [Contenido en una región](../how-to/pages.md#2-reparte-el-contenido-en-regiones) | `.with_child_in(&CoreRegions::Aside, component)` | | [Una hoja de estilos](../how-to/pages.md#4-añade-estilos-y-scripts) | `.with_assets(StyleSheet::from("/static/app.css"))` | | [Un *script*](../how-to/pages.md#4-añade-estilos-y-scripts) | `.with_assets(JavaScript::defer("/static/app.js"))` | -| [Un aviso al usuario](../how-to/components.md#mensajes-al-usuario) | `page.context().push_message(MessageLevel::Info, Lc::n("..."))` | +| [Un aviso al usuario](../how-to/components.md#mensajes-al-usuario) | `page.push_message(MessageLevel::Info, Lc::n("..."))` | | [Un aviso tras redirigir](../how-to/forms.md#3-recibe-y-valida-los-datos) | `Redirect::see_other(cx.route("/")).with_message(&cx, MessageLevel::Info, Lc::n("..."))` | | [Algo en todas las páginas](../how-to/extensions.md#4-pon-componentes-en-todas-las-páginas) | `InRegion::Global(&CoreRegions::Footer).add(component)` | @@ -98,7 +102,7 @@ Lo esencial de PageTop en una página. Cada línea enlaza con la guía que lo ex | [SQL a mano](../how-to/database.md#8-escribe-sql-a-mano) | `fetch_all(&stmt).await?` / `execute("...").await?` | | [Saber quién pide la página](../how-to/users.md#5-protege-rutas-y-adapta-la-interfaz) | `cx.current_user()` | | [Comprobar un permiso](../how-to/users.md#5-protege-rutas-y-adapta-la-interfaz) | `has_permission(&request, &MyPermission::X)` | -| [Una página en el panel](../how-to/admin.md) | `DeclareAdminPages::new(declare_pages)` | +| [Una página en el panel](../how-to/admin.md) | `action::admin::DeclareAdminPages::new(declare_pages)` | | [Leer un ajuste del panel](../how-to/admin.md#4-lee-los-ajustes-guardados) | `pagetop_admin::settings::get_or("app.key", default).await` | | [Enviar un correo](../how-to/mail.md#3-envía-un-correo) | `Email::new().with_to(addr).with_subject("...").with_html(markup).send().await` | | [Un correo traducido](../how-to/mail.md#4-escribe-una-plantilla-traducida) | `Email::from_template(&template, &cx)` | diff --git a/doc/v0.6/es/src/reference/configuration.md b/doc/v0.6/es/src/reference/configuration.md index e7f2994..bed7b05 100644 --- a/doc/v0.6/es/src/reference/configuration.md +++ b/doc/v0.6/es/src/reference/configuration.md @@ -72,6 +72,7 @@ startup_banner = "Slant" | `timezone_regions` | Texto | `""` (todas) | Regiones ofrecidas al elegir zona horaria, separadas por comas (`"Europe, America"`) | | `timezone_order` | `Nearest`, `Alphabetical`, `Listed` | `"Nearest"` | Orden de esas regiones en el selector | | `timezone_per_user` | Booleano | `true` | Si cada usuario puede tener su propia zona horaria | +| `admin_path` | Texto | `"/admin"` | Raíz del panel de administración: empieza por `/`, sin `/` final; una no válida impide arrancar | | `startup_banner` | `Off`, `Slant`, `Small`, `Speed`, `Starwars` | `"Slant"` | Banner al arrancar | `lang_negotiation`: diff --git a/doc/v0.6/es/src/reference/extensions.md b/doc/v0.6/es/src/reference/extensions.md index 95eaae6..c8c8aa3 100644 --- a/doc/v0.6/es/src/reference/extensions.md +++ b/doc/v0.6/es/src/reference/extensions.md @@ -11,7 +11,7 @@ con una línea en `dependencies()`. | [`pagetop-mail`](#correo) | Envío de correo con plantillas, HTML y adjuntos | [lettre](https://lettre.rs) | | [`pagetop-cron`](#tareas-programadas) | Tareas periódicas con expresiones cron o intervalos | [croner](https://github.com/hexagon/croner-rust) | | [`pagetop-user`](#usuarios-y-permisos) | Usuarios, sesiones, roles y permisos | [Argon2](https://docs.rs/argon2) para las contraseñas | -| [`pagetop-admin`](#administración) | Panel de administración en `/admin` | Componentes del núcleo | +| [`pagetop-admin`](#administración) | Páginas de ajustes del panel, guardados en la base de datos | [SeaORM](https://www.sea-ql.org/SeaORM) | | [`pagetop-aliner`](../how-to/themes.md) | Tema de pruebas que muestra la estructura de la página | Componentes del núcleo | | [`pagetop-mdbook`](#documentación-con-mdbook) | Libros de mdBook servidos como páginas PageTop | [mdBook](https://rust-lang.github.io/mdBook/) | @@ -57,10 +57,10 @@ impl Extension for Clock { vec![&pagetop_htmx::Htmx] } - fn configure_router(&self, router: Router) -> Router { - router - .route("/", web::get(home)) - .route("/time", web::get(time)) + fn configure_router(&self, routes: Routes) -> Routes { + routes + .public_route("/", web::get(home)) + .public_route("/time", web::get(time)) } } @@ -161,8 +161,9 @@ trazas. Con la *feature* `queue`, `send_later()` guarda antes el correo en una c datos (con `pagetop-seaorm`), que sobrevive a un reinicio y reintenta los fallos temporales, y `queue()` lo deja en la cola para enviarlo por lotes con `pagetop-cron` (ver [`[mail.queue]`](configuration.md#mailqueue)). Los enlaces de un correo se construyen con -`absolute_url()`, sobre `mail.base_url`. Paso a paso en [Enviar correo -electrónico](../how-to/mail.md). +`absolute_url()`, sobre `mail.base_url`. En el panel de administración, la página +**Configuración > Correo electrónico** muestra la configuración y envía un correo de prueba (permiso +`mail:send_test`). Paso a paso en [Enviar correo electrónico](../how-to/mail.md). ## Tareas programadas @@ -233,10 +234,22 @@ impl Permission for BlogPermission { } async fn new_post(request: HttpRequest) -> Result { - // Responds with 403 if the user lacks the permission. - require_permission(&request, &BlogPermission::Publish)?; Page::new(request).with_title(Lc::n("New post")).render().await } + +pub struct Blog; + +#[async_trait] +impl Extension for Blog { + fn configure_router(&self, routes: Routes) -> Routes { + // Without the permission, a 403; without a session, pagetop-user offers to sign in first. + routes.route( + "/posts/new", + Access::Permission(&BlogPermission::Publish), + web::get(new_post), + ) + } +} ``` Dentro de cualquier componente, `cx.current_user()` indica quién hace la petición: @@ -257,24 +270,34 @@ Html::with(|cx| { # } ``` -Con `pagetop-user` activo, la extensión registra sus permisos con la acción `DeclarePermissions` -para que aparezcan en la pantalla de roles y se puedan asignar. Paso a paso en [Añadir usuarios y +La extensión declara sus permisos con la acción `DeclarePermissions` de PageTop; con `pagetop-user` +activo, aparecen en la pantalla de roles y se pueden asignar. Paso a paso en [Añadir usuarios y permisos](../how-to/users.md). +`pagetop-user` es una extensión de autenticación más: cualquier otra se conecta igual, con un +*middleware* que deja el `CurrentUser` en la petición y las acciones `CheckPermission` (concede los +permisos) y `AnonymousDenied` (qué responder a un anónimo sin acceso). Paso a paso en [Conectar tu +propia autenticación](../how-to/auth.md). + ## Administración -`pagetop-admin` monta el panel en `/admin`, con un menú de secciones construido con los -componentes del núcleo (funciona con cualquier tema). Las extensiones registran en él sus páginas -de administración; `pagetop-user` añade, por ejemplo, la gestión de usuarios y roles. Paso a paso -en [Añadir páginas al panel de administración](../how-to/admin.md). +El panel de administración es de PageTop. Las extensiones declaran sus secciones y páginas con +acciones, con rutas relativas a su raíz (`/admin` por defecto, ajuste `admin_path` de `[app]`); +`pagetop-user` declara, por ejemplo, la gestión de usuarios y roles. Si hay alguna página, PageTop +monta la página de inicio del panel y la de cada sección, y la plantilla de administración pinta la +navegación, las migas y el título con los componentes del núcleo (funciona con cualquier tema). +`pagetop-admin` añade los formularios de ajustes que se guardan en la base de datos. Paso a paso en +[Añadir páginas al panel de administración](../how-to/admin.md). | Pieza | Qué hace | |---|---| -| `DeclareAdminSections` | Acción para añadir secciones al panel | -| `DeclareAdminPages` | Acción para añadir páginas a una sección, cada una con su permiso | -| `DeclareAdminTasks`, `DeclareAdminActions` | Acciones para añadir pestañas y botones a una página | -| `AdminPageKind::ConfigForm` | Página de ajustes que el panel pinta y guarda por sí solo | -| `AdminFrame` | Marco de una página propia: migas, título, pestañas y botones | +| `DeclareAdminSections` | Acción de PageTop para añadir secciones al panel | +| `DeclareAdminPages` | Acción de PageTop para añadir páginas a una sección, cada una con su permiso | +| `DeclareAdminTasks`, `DeclareAdminActions` | Acciones de PageTop para añadir pestañas y botones a una página | +| `routes.admin_route()` | Monta una ruta del panel, relativa a su raíz, con el permiso de su página | +| `admin_path()` | Ruta completa de una ruta relativa a la raíz del panel, para enlazar | +| `DeclareConfigForms` | Página de ajustes que `pagetop-admin` pinta y guarda por sí solo | +| `Page::admin()` | Página del panel: la plantilla de administración añade la navegación, las migas, el título, las pestañas y los botones | | `settings::get_or()` | Lee un ajuste guardado (`<ámbito>.`) | ## Documentación con mdBook diff --git a/doc/v0.6/es/src/tutorials/database.md b/doc/v0.6/es/src/tutorials/database.md index fb84e36..ffe02db 100644 --- a/doc/v0.6/es/src/tutorials/database.md +++ b/doc/v0.6/es/src/tutorials/database.md @@ -475,13 +475,13 @@ así que la nueva es la tercera. # } # Ok(()) # } -# fn configure_router(&self, router: Router) -> Router { -# router -# .route("/", web::get(home)) -# .route("/tasks", web::post(create)) -# .route("/tasks/{id}", web::get(show).put(update).delete(remove)) -# .route("/tasks/{id}/edit", web::get(edit)) -# .route("/tasks/{id}/toggle", web::patch(toggle)) +# fn configure_router(&self, routes: Routes) -> Routes { +# routes +# .public_route("/", web::get(home)) +# .public_route("/tasks", web::post(create)) +# .public_route("/tasks/{id}", web::get(show).put(update).delete(remove)) +# .public_route("/tasks/{id}/edit", web::get(edit)) +# .public_route("/tasks/{id}/toggle", web::patch(toggle)) # } # } # async fn all_tasks() -> Result, DbErr> { @@ -771,13 +771,13 @@ impl Extension for GardenTasks { Ok(()) } - fn configure_router(&self, router: Router) -> Router { - router - .route("/", web::get(home)) - .route("/tasks", web::post(create)) - .route("/tasks/{id}", web::get(show).put(update).delete(remove)) - .route("/tasks/{id}/edit", web::get(edit)) - .route("/tasks/{id}/toggle", web::patch(toggle)) + fn configure_router(&self, routes: Routes) -> Routes { + routes + .public_route("/", web::get(home)) + .public_route("/tasks", web::post(create)) + .public_route("/tasks/{id}", web::get(show).put(update).delete(remove)) + .public_route("/tasks/{id}/edit", web::get(edit)) + .public_route("/tasks/{id}/toggle", web::patch(toggle)) } } diff --git a/doc/v0.6/es/src/tutorials/first-app.md b/doc/v0.6/es/src/tutorials/first-app.md index fde9f82..99b25ba 100644 --- a/doc/v0.6/es/src/tutorials/first-app.md +++ b/doc/v0.6/es/src/tutorials/first-app.md @@ -87,8 +87,8 @@ struct HelloPageTop; #[async_trait] impl Extension for HelloPageTop { - fn configure_router(&self, router: Router) -> Router { - router.route("/", web::get(home)) + fn configure_router(&self, routes: Routes) -> Routes { + routes.public_route("/", web::get(home)) } } @@ -133,10 +133,10 @@ struct HelloPageTop; #[async_trait] impl Extension for HelloPageTop { - fn configure_router(&self, router: Router) -> Router { - router - .route("/", web::get(home)) - .route("/hello/{name}", web::get(hello)) + fn configure_router(&self, routes: Routes) -> Routes { + routes + .public_route("/", web::get(home)) + .public_route("/hello/{name}", web::get(hello)) } } diff --git a/doc/v0.6/es/src/tutorials/htmx-tasks.md b/doc/v0.6/es/src/tutorials/htmx-tasks.md index 42b1d6c..5b64799 100644 --- a/doc/v0.6/es/src/tutorials/htmx-tasks.md +++ b/doc/v0.6/es/src/tutorials/htmx-tasks.md @@ -98,8 +98,8 @@ impl Extension for GardenTasks { Ok(()) } - fn configure_router(&self, router: Router) -> Router { - router.route("/", web::get(home)) + fn configure_router(&self, routes: Routes) -> Routes { + routes.public_route("/", web::get(home)) } } @@ -162,10 +162,10 @@ impl Extension for GardenTasks { // ... initialize() as before ... - fn configure_router(&self, router: Router) -> Router { - router - .route("/", web::get(home)) - .route("/tasks", web::post(create)) + fn configure_router(&self, routes: Routes) -> Routes { + routes + .public_route("/", web::get(home)) + .public_route("/tasks", web::post(create)) } } ``` @@ -329,7 +329,8 @@ async fn toggle(web::Path(id): web::Path) -> Response { } ``` -Regístrala con `.route("/tasks/{id}/toggle", web::patch(toggle))`. Marca una tarea: queda tachada. +Regístrala con `.public_route("/tasks/{id}/toggle", web::patch(toggle))`. Marca una tarea: +queda tachada. ## 5. El contador, fuera de banda @@ -413,7 +414,7 @@ async fn remove(web::Path(id): web::Path) -> Response { } ``` -Regístrala en la ruta de cada tarea: `.route("/tasks/{id}", web::delete(remove))`. +Regístrala en la ruta de cada tarea: `.public_route("/tasks/{id}", web::delete(remove))`. ## 7. Editar en línea @@ -500,13 +501,13 @@ Las rutas quedan así: # struct GardenTasks; # #[async_trait] # impl Extension for GardenTasks { -fn configure_router(&self, router: Router) -> Router { - router - .route("/", web::get(home)) - .route("/tasks", web::post(create)) - .route("/tasks/{id}", web::get(show).put(update).delete(remove)) - .route("/tasks/{id}/edit", web::get(edit)) - .route("/tasks/{id}/toggle", web::patch(toggle)) +fn configure_router(&self, routes: Routes) -> Routes { + routes + .public_route("/", web::get(home)) + .public_route("/tasks", web::post(create)) + .public_route("/tasks/{id}", web::get(show).put(update).delete(remove)) + .public_route("/tasks/{id}/edit", web::get(edit)) + .public_route("/tasks/{id}/toggle", web::patch(toggle)) } # } ``` @@ -558,13 +559,13 @@ ciclo completo de una tarea: # store().add("Turn the compost".into()); # Ok(()) # } -# fn configure_router(&self, router: Router) -> Router { -# router -# .route("/", web::get(home)) -# .route("/tasks", web::post(create)) -# .route("/tasks/{id}", web::get(show).put(update).delete(remove)) -# .route("/tasks/{id}/edit", web::get(edit)) -# .route("/tasks/{id}/toggle", web::patch(toggle)) +# fn configure_router(&self, routes: Routes) -> Routes { +# routes +# .public_route("/", web::get(home)) +# .public_route("/tasks", web::post(create)) +# .public_route("/tasks/{id}", web::get(show).put(update).delete(remove)) +# .public_route("/tasks/{id}/edit", web::get(edit)) +# .public_route("/tasks/{id}/toggle", web::patch(toggle)) # } # } # async fn home(request: HttpRequest) -> Result { @@ -821,13 +822,13 @@ impl Extension for GardenTasks { Ok(()) } - fn configure_router(&self, router: Router) -> Router { - router - .route("/", web::get(home)) - .route("/tasks", web::post(create)) - .route("/tasks/{id}", web::get(show).put(update).delete(remove)) - .route("/tasks/{id}/edit", web::get(edit)) - .route("/tasks/{id}/toggle", web::patch(toggle)) + fn configure_router(&self, routes: Routes) -> Routes { + routes + .public_route("/", web::get(home)) + .public_route("/tasks", web::post(create)) + .public_route("/tasks/{id}", web::get(show).put(update).delete(remove)) + .public_route("/tasks/{id}/edit", web::get(edit)) + .public_route("/tasks/{id}/toggle", web::patch(toggle)) } } diff --git a/doc/v0.6/es/src/tutorials/tour.md b/doc/v0.6/es/src/tutorials/tour.md index 679aae4..a29a5de 100644 --- a/doc/v0.6/es/src/tutorials/tour.md +++ b/doc/v0.6/es/src/tutorials/tour.md @@ -167,7 +167,7 @@ async fn list(request: HttpRequest) -> Result { } ``` -Regístrala en la extensión con `router.route("/", web::get(list))`, arranca y abre +Regístrala en la extensión con `routes.public_route("/", web::get(list))`, arranca y abre . Con Bootsier, las tarjetas, las etiquetas y el botón ya tienen el aspecto de Bootstrap. Cambia `theme = "Basic"` en la configuración, reinicia y verás el mismo contenido con otra piel. @@ -224,8 +224,7 @@ async fn receive( let mut page = Page::new(request) .with_title(Lc::n("Propose a garden")) .with_child(proposal_form()); - page.context() - .push_message(MessageLevel::Error, Lc::n("The garden needs a name.")); + page.push_message(MessageLevel::Error, Lc::n("The garden needs a name.")); return page.render().await.map(IntoResponse::into_response); } trace::info!("New garden proposed: {} ({})", proposal.name, proposal.email); @@ -239,7 +238,7 @@ async fn receive( ``` Las dos funciones atienden la misma ruta, una por método: -`router.route("/propose", web::get(propose).post(receive))`. +`routes.public_route("/propose", web::get(propose).post(receive))`. El navegador ya impide enviar el nombre vacío (`required`), pero el servidor lo comprueba igual: cualquiera puede saltarse el navegador. Si falta, la página se repite con un aviso, que aparece al @@ -403,10 +402,10 @@ Las pruebas preparan la aplicación sin abrir ningún puerto y le envían petici # fn settings(&self) -> Option<&'static dyn LoadSettings> { # Some(&SETTINGS) # } -# fn configure_router(&self, router: Router) -> Router { -# router -# .route("/", web::get(list)) -# .route("/propose", web::get(propose).post(receive)) +# fn configure_router(&self, routes: Routes) -> Routes { +# routes +# .public_route("/", web::get(list)) +# .public_route("/propose", web::get(propose).post(receive)) # } # } # async fn list(request: HttpRequest) -> Result { @@ -457,8 +456,7 @@ Las pruebas preparan la aplicación sin abrir ningún puerto y le envían petici # ) -> Result { # if proposal.name.trim().is_empty() { # let mut page = Page::new(request).with_child(proposal_form()); -# page.context() -# .push_message(MessageLevel::Error, Lc::n("The garden needs a name.")); +# page.push_message(MessageLevel::Error, Lc::n("The garden needs a name.")); # return page.render().await.map(IntoResponse::into_response); # } # Ok(Redirect::see_other("/")) diff --git a/src/lib.rs b/src/lib.rs index dd2574e..be9e049 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -44,10 +44,10 @@ impl Extension for Website { Ok(()) } - fn configure_router(&self, router: Router) -> Router { - let router = router.route("/doc/latest/{lang}", web::get(doc_latest)); - pagetop_mdbook::serve_mdbook!(router, [doc] => "/doc"); - router + fn configure_router(&self, routes: Routes) -> Routes { + let routes = routes.public_route("/doc/latest/{lang}", web::get(doc_latest)); + pagetop_mdbook::serve_mdbook!(routes, [doc] => "/doc", Access::Public); + routes } } diff --git a/tools/doccheck/tests/localization.rs b/tools/doccheck/tests/localization.rs index a0fef98..3f2a5f0 100644 --- a/tools/doccheck/tests/localization.rs +++ b/tools/doccheck/tests/localization.rs @@ -7,8 +7,8 @@ struct App; #[async_trait] impl Extension for App { - fn configure_router(&self, router: Router) -> Router { - router.route("/", web::get(home)) + fn configure_router(&self, routes: Routes) -> Routes { + routes.public_route("/", web::get(home)) } }