📝 Document route access and custom authentication

Adapt the guides to the current PageTop API: Routes with the access of
each route, Layers, StaticFiles and the administration panel in the
core, with pagetop-admin reduced to the settings forms.

Add the "Connect your own authentication" guide, the mail test page and
the admin_path setting, and explain route access in the architecture
page.

Mount the books with their access through pagetop-mdbook.
This commit is contained in:
Manuel Cillero 2026-11-07 17:24:26 +01:00
parent f42f5e9b89
commit 345bd26974
41 changed files with 869 additions and 368 deletions

63
Cargo.lock generated
View file

@ -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"

View file

@ -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)

View file

@ -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

View file

@ -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 |

View file

@ -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).

View file

@ -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,38 +149,35 @@ 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<Markup, ErrorPage> {
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 |_| {
.with_child(Html::with(move |_| {
html! {
ul {
@for (crop, kilos) in rows {
@ -180,15 +185,22 @@ async fn harvest(request: HttpRequest) -> Result<Markup, ErrorPage> {
}
}
}
})),
)
}))
.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<ExtensionRef> {
vec![&pagetop_user::User]
vec![&pagetop_user::User, &pagetop_admin::Admin]
}
fn actions(&self) -> Vec<ActionBox> {
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,13 +363,10 @@ async fn home(request: HttpRequest) -> Result<Markup, ErrorPage> {
}
async fn harvest(request: HttpRequest) -> Result<Markup, ErrorPage> {
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 |_| {
.with_child(Html::with(move |_| {
html! {
ul {
@for (crop, kilos) in rows {
@ -366,8 +374,7 @@ async fn harvest(request: HttpRequest) -> Result<Markup, ErrorPage> {
}
}
}
})),
)
}))
.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, <http://localhost:8080/admin/reports/harvest> responde con la página de
acceso denegado (403).
1. Sin iniciar sesión, <http://localhost:8080/admin/reports/harvest> 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.

View file

@ -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
}
}
```

View file

@ -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::<CurrentUser>().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<Response> {
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<ActionBox> {
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::<CurrentUser>().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<Response> {
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<ExtensionRef> {
vec![&ProxyAuth]
}
fn actions(&self) -> Vec<ActionBox> {
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<Markup, ErrorPage> {
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<Markup, ErrorPage> {
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.

View file

@ -157,8 +157,7 @@ Block::new()
# use pagetop::prelude::*;
async fn saved(request: HttpRequest) -> Result<Markup, ErrorPage> {
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
}
```

View file

@ -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))
}
}

View file

@ -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(

View file

@ -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

View file

@ -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` ...

View file

@ -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))
}
}

View file

@ -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))
}
}

View file

@ -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))
}
}

View file

@ -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))
}
}

View file

@ -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))
}
}

View file

@ -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))
}
}

View file

@ -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))
}
}

View file

@ -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))
}
}

View file

@ -104,7 +104,7 @@ async fn list(request: HttpRequest, web::Query(query): web::Query<ListQuery>) ->
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<ListQuery>) ->
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()
}

View file

@ -164,7 +164,7 @@ async fn join(request: HttpRequest, web::Form(data): web::Form<JoinData>) -> 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<JoinData>) -> 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()
}

View file

@ -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<ExtensionRef> {
# 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)]

View file

@ -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)
}
}

View file

@ -76,6 +76,11 @@ Page::new(request)
`with_metadata()` genera `<meta name="..." content="...">` y `with_property()` genera
`<meta property="...">`, 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
`<head>` se genera después del `<body>`.
## 4. Añade estilos y *scripts*
Una página puede pedir sus propios recursos. PageTop los ordena, evita duplicados y los añade al

View file

@ -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

View file

@ -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<Markup, ErrorPage> {

View file

@ -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))
}
}

View file

@ -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<Markup, ErrorPage> {
async fn show_form(request: HttpRequest, error: Lc) -> Result<Response, ErrorPage> {
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<Response, ErrorPage> {
# 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<Response, ErrorPage> {

View file

@ -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<ActionBox> {
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<Markup, ErrorPage> {
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<ActionBox> {
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<Markup, ErrorPage> {
}
async fn new_notice(request: HttpRequest) -> Result<Markup, ErrorPage> {
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 <http://localhost:8080/notices/new>
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.

View file

@ -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))
}
}

View file

@ -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<Service> = 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<Response>` |
| [Montar una página del panel](../how-to/admin.md#5-añade-una-página-con-tu-propio-contenido) | `routes.admin_route("reports/harvest", web::get(handler))` |
| [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)` |

View file

@ -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`:

View file

@ -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<Markup, ErrorPage> {
// 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>.<campo>`) |
## Documentación con mdBook

View file

@ -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<Vec<task::Model>, 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))
}
}

View file

@ -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))
}
}

View file

@ -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<u32>) -> 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<u32>) -> 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<Markup, ErrorPage> {
@ -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))
}
}

View file

@ -167,7 +167,7 @@ async fn list(request: HttpRequest) -> Result<Markup, ErrorPage> {
}
```
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
<http://localhost:8080>. 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<Markup, ErrorPage> {
@ -457,8 +456,7 @@ Las pruebas preparan la aplicación sin abrir ningún puerto y le envían petici
# ) -> Result<Response, ErrorPage> {
# 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("/"))

View file

@ -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
}
}

View file

@ -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))
}
}