📝 Doc cron, mail queue, CSRF and flash messages

Add the scheduled tasks guide, environment variable overrides, the
[mail] and [cron] references, CSRF protection without tokens, flash
messages after redirects and the username policies of pagetop-user.
Update the framework comparison with Poem and Topcoat.
This commit is contained in:
Manuel Cillero 2026-11-02 14:46:28 +01:00
parent 1a41a456d4
commit 4e007feec8
23 changed files with 946 additions and 125 deletions

View file

@ -94,11 +94,11 @@ When writing a chapter:
- Use ```` ```rust ```` only for examples that can run with no server (with `assert!`),
```` ```rust,no_run ```` for the rest, and ```` ```rust,ignore ```` only for loose fragments
that are not valid on their own.
- Examples can use `pagetop`, `pagetop-admin`, `pagetop-bootsier`, `pagetop-htmx`,
`pagetop-seaorm` (with SQLite), `pagetop-user`, `pagetop-build`, `serde`, `thiserror` and
`tower-http` (with the `compression-gzip`, `cors`, `limit` and `timeout` features); the
translations in `tools/doccheck/src/locale/` (`LOCALES_APP`), and a static files bundle named
`app`. If a chapter needs anything else, add it to `tools/doccheck`.
- Examples can use `pagetop`, `pagetop-admin`, `pagetop-bootsier`, `pagetop-cron`,
`pagetop-htmx`, `pagetop-mail`, `pagetop-seaorm` (with SQLite), `pagetop-user`, `pagetop-build`,
`serde`, `thiserror`, `tokio` and `tower-http` (with the `compression-gzip`, `cors`, `limit` and
`timeout` features); the translations in `tools/doccheck/src/locale/` (`LOCALES_APP`), and a
static files bundle named `app`. If a chapter needs anything else, add it to `tools/doccheck`.
- Examples and tests that start an application read `tools/doccheck/config/`: those with a database
get a new in-memory SQLite one on every run.
- Tests that share state (a static store, a database) run in the same process: write one test per
@ -111,7 +111,8 @@ The first run compiles PageTop and takes a few minutes; the next ones only compi
Settings are loaded in cascade from the `config/` directory (or the one in the `CONFIG_DIR`
environment variable): `common.toml`, then `{run_mode}.toml` according to `PAGETOP_RUN_MODE`
(`default` by default), `local.{run_mode}.toml` and `local.toml`. The local files are not
versioned. There are no environment variables that override individual keys.
versioned. Finally, environment variables named `PAGETOP_<SECTION>__<KEY>` override individual
keys (e.g. `PAGETOP_SERVER__BIND_PORT=80`).
## Warning

View file

@ -6,9 +6,10 @@
# 3. config/local.{run_mode}.toml
# 4. config/local.toml <- local overrides, do not track in git
#
# Configuration is only read from these files: there are no environment variables that override
# individual keys. The only variables that are consulted are PAGETOP_RUN_MODE (see above) and
# CONFIG_DIR (an alternative to the "config" directory).
# Finally, environment variables named PAGETOP_<SECTION>__<KEY> override any key of these files,
# with each level separated by a double underscore (e.g. PAGETOP_SERVER__BIND_PORT=80). Besides,
# PAGETOP_RUN_MODE (see above) and CONFIG_DIR (an alternative to the "config" directory) choose
# which files are loaded.
# **< Application >*********************************************************************************

View file

@ -40,6 +40,7 @@
- [La aplicación]()
- [Configurar la aplicación](how-to/configuration.md)
- [Compartir un servicio entre rutas](how-to/services.md)
- [Programar tareas periódicas](how-to/cron.md)
- [Añadir *middleware*](how-to/middleware.md)
- [Traducir la aplicación](how-to/localization.md)
- [Servir recursos estáticos](how-to/assets.md)

View file

@ -58,16 +58,21 @@ Application::prepare(&MyApp)
v
.run()
8. build the server routes + middleware + static files
9. serve requests until Ctrl+C or SIGTERM
9. start extensions every start(): background services, such as pagetop-cron
10. serve requests until Ctrl+C or SIGTERM
11. shut down extensions every shutdown(), in reverse order
```
Dos consecuencias importantes:
Tres consecuencias importantes:
- **Lo que falla, falla al arrancar.** Una clave mal escrita, un valor no válido, una base de datos
que no responde o una migración rota detienen la aplicación antes de servir una sola petición,
con un mensaje que explica la causa. Nunca hay una aplicación a medias en producción.
- **Lo costoso se hace una vez.** Las traducciones, los ajustes, las acciones y los recursos
estáticos se cargan o se registran al arrancar; en cada petición sólo se consultan.
- **Las pruebas no lanzan nada en segundo plano.** Una prueba prepara la aplicación con
`prepare()` y obtiene su servidor con `test()`, sin llamar a `run()`: hace los pasos 1 a 8, pero
ni arranca los servicios de las extensiones ni ejecuta tareas programadas por su cuenta.
## La petición
@ -78,6 +83,9 @@ request
|
v
+------------------------------------------------------------+
| cross-origin check (CSRF) -> 403 for a POST, PUT... |
| from another origin |
+------------------------------------------------------------+
| static files (/static, /htmx...) -> served directly, |
| without middleware |
+------------------------------------------------------------+
@ -95,6 +103,10 @@ request
response (complete HTML, or a fragment for HTMX)
```
- La **comprobación de origen** rechaza con `403`, antes de llegar al *middleware* de las
extensiones, las peticiones que pueden cambiar algo (`POST`, `PUT`...) y que el navegador indica
que vienen de otro origen: es la protección contra CSRF, sin *tokens* en los formularios. Ver
[Sin *tokens* contra CSRF](../how-to/forms.md#6-sin-tokens-contra-csrf).
- Los **archivos estáticos** se registran después del *middleware*, así que no pasan por él:
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**

View file

@ -4,68 +4,80 @@ Rust tiene muy buenos *frameworks* web, y es justo preguntarse por qué elegir u
página compara PageTop con los más conocidos, con sus puntos fuertes y también con lo que a PageTop
todavía le falta.
A grandes rasgos hay dos familias. Los **modulares** (Axum, Actix Web) te dan las piezas básicas
para atender peticiones y te dejan elegir el resto: base de datos, plantillas, usuarios. Los
**completos** (Rocket en parte, Loco, Cot) traen de serie muchas de esas piezas y unas convenciones
para encajarlas. PageTop está en la segunda familia, con un matiz: lo que trae lo organiza en
**extensiones**, **componentes** y **temas**, y casi todo es opcional.
A grandes rasgos hay dos familias. Los **modulares** (Actix Web, Axum, Poem) te dan las piezas
básicas para atender peticiones y te dejan elegir el resto: base de datos, plantillas, usuarios. Los
**completos** (Rocket en parte, Loco, Cot, Topcoat) traen de serie muchas de esas piezas y unas
convenciones para encajarlas. PageTop está en la segunda familia, con un matiz: lo que trae lo
organiza en **extensiones**, **componentes** y **temas**, y casi todo es opcional.
Ten en cuenta también la madurez: PageTop sigue en versiones 0.x, su API todavía cambia entre
versiones y su comunidad es más pequeña que la de la mayoría de los *frameworks* de esta página.
## Tabla comparativa
| | PageTop | Axum | Actix Web | Rocket | Loco | Cot |
| | PageTop | Rocket | Poem | Loco | Cot | Topcoat |
|:--|:--|:--|:--|:--|:--|:--|
| **Enfoque** | Completo, por extensiones | Modular | Modular | Completo en parte | Completo (como Rails) | Completo (como Django) |
| **Base** | Axum | Hyper y Tokio | Actix | Hyper y Tokio | Axum | Axum |
| **HTML** | `html!` con componentes y temas | A tu elección | A tu elección | Tera o Handlebars | Tera | Askama |
| **Interactividad** | HTMX (extensión) | A tu elección | A tu elección | A tu elección | A tu elección | A tu elección |
| **Base de datos** | SeaORM (extensión) | A tu elección | A tu elección | Varias, con su integración | SeaORM | ORM propio |
| **Migraciones** | Escritas en Rust, aplicadas al arrancar | Herramientas externas | Herramientas externas | Herramientas externas | Generadas con su CLI | Generadas a partir de los modelos |
| **Usuarios y permisos** | Extensión (roles y permisos) | No | No | No | Autenticación con JWT | Autenticación |
| **Panel de administración** | Extensible, con formularios de ajustes | No | No | No | No | Generado a partir de los modelos |
| **Traducciones** | Fluent, de serie | No | No | No | Fluent, en su plantilla de proyecto | No |
| **Tareas en segundo plano y correo** | Todavía no | No | No | No | Sí | Correo y caché |
## PageTop frente a Axum
PageTop **está construido sobre Axum**, así que comparten rutas, extractores y respuestas. Lo que
sabes de Axum lo puedes usar en PageTop (lo cuenta [Si vienes de Axum](coming-from-axum.md)).
- **Elige Axum si** quieres controlar cada pieza, construyes una API o un microservicio sin
interfaz, o prefieres montar tu propia pila.
- **Elige PageTop si** vas a generar páginas: te ahorra el trabajo de juntar plantillas,
traducciones, recursos estáticos, configuración y extensiones, y sigues teniendo Axum debajo
cuando lo necesites.
## PageTop frente a Actix Web
Actix Web es maduro y uno de los más rápidos que existen.
- **Elige Actix Web si** el rendimiento bruto por petición es lo que más pesa, o ya tienes código
sobre su ecosistema.
- **Elige PageTop si** te importa más avanzar rápido en una aplicación con interfaz. Rust y Axum ya
dan un rendimiento de sobra para la inmensa mayoría de aplicaciones de gestión.
| **Enfoque** | Completo, por extensiones | Completo en parte | Modular, con OpenAPI | Completo (como Rails) | Completo (como Django) | Completo, interfaz reactiva |
| **Base** | Axum | Hyper y Tokio | Hyper y Tokio | Axum | Axum | Hyper y Tokio |
| **HTML** | `html!` con componentes y temas | Tera, Handlebars o MiniJinja | A tu elección | Tera (u otro motor) | Askama (u otro motor) | `view!` con componentes |
| **Interactividad** | HTMX (extensión) | A tu elección | A tu elección | HTMX en sus generadores | A tu elección | Reactividad propia; también HTMX, Alpine AJAX o Datastar |
| **Base de datos** | SeaORM (extensión) | Varias, con su integración | A tu elección | SeaORM | ORM propio | Toasty, recomendado |
| **Migraciones** | Escritas en Rust, aplicadas al arrancar | Herramientas externas | Herramientas externas | Generadas con su CLI | Generadas a partir de los modelos | Generadas a partir de los modelos (Toasty) |
| **Usuarios y permisos** | Extensión (roles y permisos); CSRF en el núcleo | No | No (sesiones y CSRF) | Autenticación (JWT y claves de API) | Autenticación | Sesiones; autenticación prevista |
| **Panel de administración** | Extensible, con formularios de ajustes | No | No | No | Generado a partir de los modelos | No |
| **Traducciones** | Fluent, de serie | No | Fluent, opcional | Fluent, en su plantilla de proyecto | No | Fluent |
| **Tareas en segundo plano y correo** | Tareas programadas y correo con cola persistente (extensiones); sin cola de trabajos genérica | No | No | Colas, tareas programadas y correo | Correo y caché | Correo; tareas en segundo plano previstas |
## PageTop frente a Rocket
Rocket es conocido por lo agradable que resulta escribir rutas con sus macros y por sus guardas de
petición.
Rocket es conocido por lo agradable que resulta escribir rutas con sus macros, por sus guardas de
petición y por llevar la seguridad de tipos muy lejos. Trae de serie plantillas, *cookies* privadas,
WebSocket, perfiles de configuración, pruebas e integración con varias bases de datos.
- **Elige Rocket si** te gusta su estilo de API y no te importa elegir tú la capa de datos, los
usuarios y la interfaz.
- **Elige Rocket si** te gusta su estilo de API y prefieres montar tú los usuarios, los permisos y
la interfaz sobre esas piezas.
- **Elige PageTop si** quieres que esas piezas vengan resueltas: usuarios y permisos, panel de
administración, temas y traducciones.
## PageTop frente a Poem
[Poem](https://github.com/poem-web/poem) es un *framework* modular, como Axum o Actix Web, pero con
muchas piezas opcionales que se activan por *features* (sesiones, CSRF, WebSocket, traducciones con
Fluent...). Destaca por `poem-openapi`, que genera la especificación OpenAPI a partir de los tipos
de la API, y por su soporte para gRPC.
- **Elige Poem si** construyes una API y quieres la documentación OpenAPI generada de serie, con
Swagger UI u otros visores, o quieres servir también gRPC con el mismo *framework*.
- **Elige PageTop si** vas a generar páginas: Poem no trae componentes, temas, usuarios ni panel de
administración, y la interfaz queda en tus manos.
## PageTop frente a Loco
Loco se presenta como «el Rails de Rust»: convenciones fuertes, una CLI que genera código y muchas
piezas incluidas, también sobre Axum y SeaORM.
Loco se presenta como «Rust on Rails» y como el *framework* para quien trabaja en solitario:
convenciones fuertes, una CLI que genera código y muchas piezas incluidas, también sobre Axum y
SeaORM.
- **Elige Loco si** te gusta la filosofía de Rails, quieres generadores de código, o necesitas ya
**tareas en segundo plano**, **tareas programadas** o **envío de correo**, que PageTop todavía no
tiene.
- **Elige PageTop si** tu aplicación es sobre todo interfaz: los componentes tipados, los temas que
pueden cambiar cualquier componente y HTMX integrado no tienen equivalente en Loco, que deja la
interfaz en manos de las plantillas.
**colas de trabajos** genéricas que sobrevivan a un reinicio (en la base de datos o en Redis), que
PageTop todavía no tiene. Las tareas programadas y el correo sí los tiene PageTop, con sus
extensiones, y el correo puede guardarse en una cola persistente.
- **Elige PageTop si** tu aplicación es sobre todo interfaz: los componentes tipados y los temas
que pueden cambiar cualquier componente no tienen equivalente en Loco, que construye la interfaz
con plantillas (sus generadores sí pueden crear vistas con HTMX).
## PageTop frente a summer-rs
[summer-rs](https://summer-rs.github.io) (antes spring-rs) se inspira en Spring Boot: un núcleo
pequeño de *plugins* que integran piezas del ecosistema (Axum, SQLx, SeaORM, Redis, correo con
lettre, tareas programadas, autenticación con Sa-Token, OpenTelemetry, gRPC...), configurados en
TOML y con inyección de dependencias en tiempo de compilación.
- **Elige summer-rs si** construyes servicios o APIs y quieres tener ya integrados la caché, las
colas o la observabilidad.
- **Elige PageTop si** lo que construyes son páginas: summer-rs no trae plantillas, componentes,
temas ni traducciones. La idea de los *plugins* es muy parecida a la de las extensiones; donde
summer-rs inyecta componentes, PageTop guarda los servicios en estáticos (ve [Compartir un
servicio entre rutas](../how-to/services.md)).
## PageTop frente a Cot
@ -73,33 +85,50 @@ Cot toma la filosofía de Django: un ORM propio que genera las migraciones a par
un panel de administración que se construye solo.
- **Elige Cot si** te gusta Django y quieres un panel de administración con altas, bajas y
modificaciones de tus modelos sin escribir nada.
modificaciones de tus modelos sin escribir nada, o una API JSON con su documentación OpenAPI y
Swagger UI generadas.
- **Elige PageTop si** prefieres SeaORM, quieres construir la interfaz con componentes y temas en
lugar de plantillas, o necesitas traducciones. El panel de PageTop no genera páginas a partir de
los modelos, pero cada extensión le añade las suyas, con sus permisos (ve [Añadir páginas al panel
de administración](../how-to/admin.md)).
## PageTop frente a summer-rs
## PageTop frente a Topcoat
[summer-rs](https://summer-rs.github.io) (antes spring-rs) se inspira en Spring Boot: un núcleo
pequeño de *plugins* que integran piezas del ecosistema (Axum, SQLx, SeaORM, Redis, correo con
lettre, tareas programadas, OpenTelemetry, gRPC...), configurados en TOML y con inyección de
dependencias en tiempo de compilación.
[Topcoat](https://tokio.rs/blog/2026-07-22-announcing-topcoat), del proyecto Tokio (lo firman Carl
Lerche, creador de Tokio, y Julien Scholz), es el más parecido a PageTop en la forma de construir la
interfaz: todo se renderiza en el servidor, con páginas y componentes escritos en Rust (`#[page]`,
`#[component]` y la macro `view!`). Añade su propio sistema de reactividad, con señales cuyo código
se compila a JavaScript y fragmentos de la página que se vuelven a renderizar en el servidor, y
también se integra con HTMX, Alpine AJAX o Datastar. Es muy reciente: se presentó en julio de 2026
y, como PageTop, avisa de que su API cambiará.
- **Elige summer-rs si** construyes servicios o APIs y quieres tener ya integrados la caché, las
colas, el correo, las tareas programadas o la observabilidad.
- **Elige PageTop si** lo que construyes son páginas: summer-rs no trae plantillas, componentes,
temas ni traducciones. La idea de los *plugins* es muy parecida a la de las extensiones; donde
summer-rs inyecta componentes, PageTop guarda los servicios en estáticos (ve [Compartir un
servicio entre rutas](../how-to/services.md)).
- **Elige Topcoat si** quieres reactividad en el navegador sin escribir JavaScript ni compilar a
WebAssembly, o su biblioteca de componentes con Tailwind.
- **Elige PageTop si** necesitas ya usuarios y permisos, panel de administración o tareas
programadas, que en Topcoat todavía no existen o están en su hoja de ruta, o temas capaces de
cambiar el aspecto de cualquier componente sin tocar la aplicación.
## ¿Y Axum o Actix Web?
No están en la tabla porque casi todas sus filas dirían «A tu elección» o «No»: son la base sobre
la que se construye una aplicación, no la aplicación hecha. PageTop **está construido sobre Axum**,
así que comparten rutas, extractores y respuestas, y lo que sabes de Axum lo puedes usar en PageTop
(lo cuenta [Si vienes de Axum](coming-from-axum.md)). Actix Web es maduro y uno de los más rápidos
que existen, aunque Rust y Axum ya dan un rendimiento de sobra para la inmensa mayoría de
aplicaciones de gestión. Son buena elección si quieres controlar cada pieza, construyes una API o un
microservicio sin interfaz, o ya tienes código sobre alguno de ellos. Si vas a generar páginas,
PageTop te ahorra juntar plantillas, traducciones, recursos estáticos, configuración y extensiones,
y sigues teniendo Axum debajo cuando lo necesites.
## ¿Y Leptos o Dioxus?
Leptos y Dioxus son *frameworks* **de pila completa** que compilan la interfaz a WebAssembly y la
ejecutan en el navegador, con renderizado en el servidor como punto de partida. Es el modelo
contrario al de PageTop: aquí la interfaz vive en el servidor y HTMX sólo intercambia fragmentos
de HTML. Si tu aplicación necesita mucha lógica en el navegador o funcionar sin conexión, mira hacia
ellos (lo explica también [Por qué PageTop](why.md#cuándo-no-es-la-mejor-opción)).
Leptos y Dioxus son *frameworks* **de pila completa** con reactividad fina: la interfaz se compila a
WebAssembly y se ejecuta en el navegador, y puede renderizarse antes en el servidor e hidratarse
después. Dioxus, además, lleva la misma aplicación al escritorio y al móvil. Es el modelo contrario
al de PageTop: aquí la interfaz vive en el servidor y HTMX sólo intercambia fragmentos de HTML. Si
tu aplicación necesita mucha lógica en el navegador, funcionar sin conexión o ejecutarse también
fuera de él, mira hacia ellos (lo explica también
[Por qué PageTop](why.md#cuándo-no-es-la-mejor-opción)).
## Siguiente

View file

@ -42,13 +42,21 @@ Page::render()
3. <body>: the theme renders the regions every component, see below
4. theme: after_render_page_body(page)
5. extensions: AfterRenderBody
6. <head>: title, metadata and every asset collected so far
6. deferred: postponed components, in place e.g. the messages of Content
7. <head>: title, metadata and every asset collected so far
```
El `<head>` se genera **al final**: así recoge los estilos y *scripts* que los componentes
añadieron al contexto mientras se renderizaban. Un componente que sólo aparece en algunas páginas
sólo carga sus recursos en esas páginas, y una vez aunque aparezca muchas veces.
Un componente puede pedir que se le **aplace** (`is_deferred()` devuelve `true`): en el paso 3 deja
una marca en su sitio y se renderiza en el 6, cuando ya está hecho el resto. Se aplaza el momento,
no la posición: se muestra donde estaba. Así funciona el `Messages` con el que empieza la región
`Content`: aunque aparece al principio, recoge los avisos que añadan los componentes de toda la
página. Si un componente aplazado no genera nada, la marca, un comentario HTML, se queda en su
sitio; por eso los temas ocultan las regiones vacías con el selector `.region:empty`.
## El renderizado de un componente
Cada componente, en cada región, pasa por estos pasos:

View file

@ -104,8 +104,12 @@ Con las capas de `tower-http` en `configure_middleware()`. Ver [Añadir
**¿Puedo programar tareas periódicas o enviar correos?**
Todavía no: PageTop no tiene aún tareas en segundo plano ni envío de correo (ve la [comparación
con otros *frameworks*](explanation/comparison.md)).
Sí, con dos extensiones oficiales: `pagetop-cron` ejecuta trabajos en segundo plano según una
expresión cron o a intervalos (ve [Programar tareas periódicas](how-to/cron.md)), y `pagetop-mail`
envía correo (ve [Extensiones oficiales](reference/extensions.md#correo)), con una cola opcional
que guarda los correos en la base de datos y reintenta los que fallan. Lo que todavía no tiene
PageTop es una cola de trabajos genérica que sobreviva a un reinicio, como las de Loco (ve la
[comparación con otros *frameworks*](explanation/comparison.md)).
**¿Tengo que usar una base de datos?**
@ -126,6 +130,27 @@ PageTop está en desarrollo activo y su API puede cambiar entre versiones hasta
piezas maduras del ecosistema (Axum, Tokio, SeaORM, Fluent), pero conviene evaluarlo con tus
propios requisitos antes de llevarlo a un sistema crítico.
**¿Necesito *tokens* CSRF en los formularios?**
No. PageTop rechaza con `403` las peticiones que pueden cambiar algo (`POST`, `PUT`...) cuando el
navegador indica que vienen de otro origen, sin campos ocultos ni *cookies* adicionales. Sólo debes
cuidar que ningún `GET` cambie nada. Ver [Sin *tokens* contra
CSRF](how-to/forms.md#6-sin-tokens-contra-csrf).
**Un formulario responde con 403 en producción.**
Las causas habituales, en este orden:
1. El formulario está en **otro origen** (otro dominio, subdominio o puerto). Si es una aplicación
tuya, añade su origen a `trusted_origins` de `[server]`.
2. El **proxy inverso** cambia la cabecera `Host`. Conserva la original (`proxy_set_header Host
$host;` en nginx). Ver [Detrás de un proxy
inverso](how-to/deployment.md#5-detrás-de-un-proxy-inverso).
3. Falta un **permiso**: el 403 es de la aplicación, no de la protección contra CSRF.
Las trazas lo distinguen: cada petición rechazada por venir de otro origen deja un aviso con la
ruta y las cabeceras `Sec-Fetch-Site` y `Origin` recibidas.
**¿Cómo se detiene sin perder peticiones?**
Con `Ctrl+C` o con `SIGTERM` (lo que envían `systemd` y Docker), PageTop deja de aceptar

View file

@ -150,18 +150,27 @@ Block::new()
## Mensajes al usuario
`Page` acumula avisos en su contexto y el componente `Messages` los muestra:
`Page` acumula avisos en su contexto, y la región de contenido empieza siempre por un componente
`Messages` que los muestra. Basta con añadirlos:
```rust,no_run
# use pagetop::prelude::*;
async fn saved(request: HttpRequest) -> Result<Markup, ErrorPage> {
let mut page = Page::new(request).with_child(Messages::new());
let mut page = Page::new(request);
page.context()
.push_message(MessageLevel::Info, Lc::n("Your changes have been saved."));
page.render().await
}
```
Ese `Messages` se renderiza el último, cuando ya está hecho el resto de la página, así que recoge
también los avisos que añadan los componentes al renderizarse, aunque se muestre al principio. Cada
aviso aparece una sola vez: añade tu propio `Messages::new()` sólo para mostrarlos en otro lugar,
por ejemplo justo antes de un formulario, o en un fragmento de HTMX, que no tiene página.
Para avisar en la página a la que rediriges, añade el mensaje a la respuesta con `with_message()`
(ver [Crear y procesar formularios](forms.md#3-recibe-y-valida-los-datos)).
## Una portada en un minuto
`Intro` monta una página de presentación con un solo componente:

View file

@ -24,9 +24,13 @@ El modo lo da la variable de entorno `PAGETOP_RUN_MODE` (`default` si no se defi
PAGETOP_RUN_MODE=production ./my-app # reads common.toml, production.toml, ...
```
Las variables de entorno **no** sobrescriben ajustes sueltos. Las únicas que se leen son
`PAGETOP_RUN_MODE` y `CONFIG_DIR`, que cambia el directorio `config/`. Las contraseñas y demás
secretos van en un `local.toml` que no se sube al repositorio.
`CONFIG_DIR` cambia el directorio `config/`. Las contraseñas y demás secretos van en un
`local.toml` que no se sube al repositorio, o en variables de entorno: cualquier clave se
sobrescribe con `PAGETOP_<SECCIÓN>__<CLAVE>`, con cada nivel separado por dos guiones bajos.
```sh
PAGETOP_DATABASE__DB_PASS=secret ./my-app # db_pass of [database]
```
## 2. Ajusta PageTop

View file

@ -0,0 +1,339 @@
# Programar tareas periódicas
**Objetivo:** ejecutar código en segundo plano mientras la aplicación está en marcha, según un
calendario (cada noche a las 4:30, cada lunes) o a intervalos (cada diez minutos), y dejar que
quien administra la aplicación lo cambie o lo desactive sin recompilar.
Lo aporta la extensión `pagetop-cron`. Cada extensión **declara** sus trabajos con una acción, y el
planificador los ejecuta cuando toca. El planificador sólo se pone en marcha con
`Application::run()`: en las pruebas no se ejecuta nada por sí solo, y cada prueba ejecuta el
trabajo que quiere cuando quiere.
## 1. Añade la dependencia
```toml
[dependencies]
pagetop-cron = { git = "https://git.cillero.es/manuelcillero/pagetop" }
```
Y declara `pagetop_cron::Cron` en `dependencies()` de la extensión que aporta los trabajos:
```rust,no_run
# use pagetop::prelude::*;
pub struct Garden;
#[async_trait]
impl Extension for Garden {
fn dependencies(&self) -> Vec<ExtensionRef> {
vec![&pagetop_cron::Cron]
}
}
```
## 2. Escribe el trabajo
Un trabajo es una función asíncrona que recibe un `JobContext` y devuelve un `JobResult`. Lee los
ajustes y los servicios de la aplicación igual que un *handler* (ve [Compartir un servicio entre
rutas](services.md)), y con `?` propaga cualquier error, que queda registrado en las trazas:
```rust,no_run
# use pagetop::prelude::*;
# use pagetop_cron::prelude::*;
async fn water_plots(cx: JobContext) -> JobResult {
let plan = std::fs::read_to_string("watering-plan.txt")?;
trace::info!("Watering {} plots ({:?})", plan.lines().count(), cx.trigger());
Ok(())
}
```
Si el trabajo devuelve un error o provoca un `panic!`, la aplicación sigue en marcha y el trabajo
vuelve a ejecutarse cuando le toque.
## 3. Declara cuándo se ejecuta
Los trabajos se declaran con la acción `DeclareCronJobs`. Cada uno tiene una **clave** única, que
conviene empezar por el nombre de la extensión, y una programación (`Schedule`):
```rust,no_run
# use pagetop::prelude::*;
# use pagetop_cron::prelude::*;
# async fn water_plots(_cx: JobContext) -> JobResult { Ok(()) }
fn declare_jobs(jobs: &mut CronJobs) {
jobs.add(
Job::new("garden.water", Schedule::cron("30 6 * * *"), water_plots)
.with_title(Lc::n("Water the plots")),
);
}
pub struct Garden;
#[async_trait]
impl Extension for Garden {
fn dependencies(&self) -> Vec<ExtensionRef> {
vec![&pagetop_cron::Cron]
}
fn actions(&self) -> Vec<ActionBox> {
actions![DeclareCronJobs::new(declare_jobs)]
}
}
```
Hay tres formas de programarlo:
| Programación | Se ejecuta... |
|---|---|
| `Schedule::cron("30 6 * * *")` | Según una expresión cron: cada día a las 6:30 |
| `Schedule::fixed_rate(Duration::minutes(10))` | Cada 10 minutos desde que **empieza** la ejecución anterior |
| `Schedule::fixed_delay(Duration::seconds(30))` | 30 segundos después de que **termina** la ejecución anterior |
Las expresiones cron tienen los cinco campos clásicos (minuto, hora, día del mes, mes y día de la
semana), con un sexto campo opcional al principio para los segundos. Algunos ejemplos:
| Expresión | Se ejecuta... |
|---|---|
| `*/10 * * * *` | Cada diez minutos |
| `0 8-18 * * MON-FRI` | A cada hora en punto, de 8 a 18, de lunes a viernes |
| `0 0 L * *` | A medianoche del último día de cada mes |
| `0 9 * * MON#1` | A las 9:00 del primer lunes de cada mes |
| `*/30 * * * * *` | Cada treinta segundos |
| `@daily`, `@hourly`... | Al principio de cada día, de cada hora... |
Se interpretan en la zona horaria de la aplicación (`[app] timezone`) y respetan los cambios de
hora: una ejecución en una hora que no existe se hace al empezar la siguiente, y una en una hora
que se repite, una sola vez. La sintaxis completa está en la documentación de `Schedule`.
Para procesar algo pendiente (una cola, una lista de avisos), `fixed_delay()` suele ser la mejor
opción: dos ejecuciones nunca coinciden, y cada una empieza con lo que dejó la anterior.
## 4. Ajusta cómo se ejecuta
`Job` admite además:
| Método | Para qué |
|---|---|
| `with_timeout(Duration::minutes(5))` | Cancela la ejecución si dura más |
| `with_overlap(Overlap::Allow)` | Ejecuta aunque siga en curso la anterior; por defecto se omite (`Overlap::Skip`) |
| `with_run_on_start()` | Ejecuta también al arrancar, sin esperar a la primera hora programada |
| `with_timezone(Tz::Europe__Madrid)` | Interpreta su expresión cron en otra zona horaria |
```rust,no_run
# use pagetop::prelude::*;
# use pagetop_cron::prelude::*;
# async fn check_sensors(_cx: JobContext) -> JobResult { Ok(()) }
# fn f() -> Job {
Job::new("garden.sensors", Schedule::fixed_delay(Duration::seconds(30)), check_sensors)
.with_timeout(Duration::seconds(20))
.with_run_on_start()
# }
```
La función también puede ser un cierre, útil para trabajos cortos:
```rust,no_run
# use pagetop::prelude::*;
# use pagetop_cron::prelude::*;
# fn f() -> Job {
Job::new("garden.heartbeat", Schedule::fixed_rate(Duration::minutes(1)), |cx| async move {
trace::debug!("Still alive ({})", cx.key());
Ok(())
})
# }
```
## 5. Cámbialo desde la configuración
Quien administra la aplicación puede cambiar cada trabajo por su clave, sin tocar el código, en la
subsección `[cron.jobs."clave"]`. La clave va entre comillas porque lleva un punto:
```toml
[cron.jobs."garden.water"]
schedule = "0 7 * * *" # Water at 7:00 instead.
timeout_secs = 600 # At most 10 minutes (0 = no limit).
[cron.jobs."garden.heartbeat"]
enabled = false # Never runs on its own.
```
`schedule` admite una expresión cron y también `"@every 10m"` (como `fixed_rate()`) y
`"@delay 30s"` (como `fixed_delay()`). Si una programación no es válida, la aplicación no arranca e
indica el trabajo; una clave que no corresponde a ningún trabajo sólo produce un aviso en las
trazas.
## 6. Con varias instancias, elige el modo
Por defecto (`mode = "internal"`) cada instancia de la aplicación ejecuta todos los trabajos. Si
despliegas varias (por ejemplo, detrás de un balanceador), cada trabajo se ejecutaría una vez por
instancia. Tienes dos opciones:
- **Uno solo ejecuta los trabajos:** deja `"internal"` en una instancia y pon `"off"` en las demás.
- **Un programa externo marca el ritmo:** pon `"external"` en todas y programa una sola llamada
cada minuto. Cada llamada llega a una instancia, que ejecuta lo programado en el último minuto:
```toml
[cron]
mode = "external"
trigger_token = "a-long-and-secret-token" # Better in config/local.toml.
```
```text
# System crontab: checks the jobs every minute. The file holds the line
# "Authorization: Bearer a-long-and-secret-token".
* * * * * curl -fsS -X POST -H @/etc/garden/cron-header https://garden.example.com/cron > /dev/null
```
La clave viaja en la cabecera `Authorization` y no en la ruta, que suelen registrar los *proxies*;
necesita al menos 16 letras, dígitos, `-` o `_`. Sin la clave correcta, la ruta responde `404`. La
llamada responde `200 OK` cuando terminan los trabajos, con una línea por trabajo y su resultado,
así que el programa externo debe esperar más de lo que tarde el más largo.
Como ninguna instancia recuerda lo que hicieron las demás, el programa externo debe llamar una vez,
y sólo una, cada minuto: si falta una llamada se pierden sus ejecuciones, y si sobra, pueden
repetirse. Para llamar con otra frecuencia, indícala en `trigger_interval_secs`. En este modo, un
trabajo no se ejecuta más a menudo que las llamadas.
Una llamada de más suele ser un reintento tras un error de red, que puede llegar a otra instancia.
Desactiva los reintentos del programa externo (p. ej. `backoffLimit: 0` en un *CronJob* de
Kubernetes) y, si un trabajo no debe repetirse nunca, haz que lo compruebe él mismo en la base de
datos antes de hacer nada.
Con `"off"`, los trabajos sólo se ejecutan si alguien lo pide con `pagetop_cron::run_now()`.
## 7. Termina a tiempo al detener la aplicación
Al detener la aplicación (Ctrl+C o `SIGTERM`), el planificador deja de lanzar ejecuciones y espera
hasta `shutdown_timeout_secs` (30 segundos por defecto) a que terminen las que están en curso. Un
trabajo largo puede preguntar por `is_stopping()` y dejar su trabajo en un punto seguro:
```rust,no_run
# use pagetop::prelude::*;
# use pagetop_cron::prelude::*;
# async fn send_reminder(_n: usize) {}
async fn send_reminders(cx: JobContext) -> JobResult {
for n in 0..500 {
if cx.is_stopping() {
trace::info!("Stopping at reminder {n}; the rest go in the next run");
break;
}
send_reminder(n).await;
}
Ok(())
}
```
## El ejemplo completo
Riega el huerto según su programación y muestra en la portada cuántas veces se ha regado y cuándo
fue la última, a partir del estado del trabajo (`pagetop_cron::job()`):
```rust,no_run
use pagetop::prelude::*;
use pagetop_cron::prelude::*;
async fn water_plots(cx: JobContext) -> JobResult {
trace::info!("Watering the plots ({:?})", cx.trigger());
Ok(())
}
fn declare_jobs(jobs: &mut CronJobs) {
jobs.add(
Job::new("garden.water", Schedule::cron("30 6 * * *"), water_plots)
.with_title(Lc::n("Water the plots"))
.with_timeout(Duration::minutes(5)),
);
}
struct Garden;
#[async_trait]
impl Extension for Garden {
fn dependencies(&self) -> Vec<ExtensionRef> {
vec![&pagetop_cron::Cron]
}
fn actions(&self) -> Vec<ActionBox> {
actions![DeclareCronJobs::new(declare_jobs)]
}
fn configure_router(&self, router: Router) -> Router {
router.route("/", web::get(home))
}
}
async fn home(request: HttpRequest) -> Result<Markup, ErrorPage> {
let status = pagetop_cron::job("garden.water");
Page::new(request)
.with_title(Lc::n("Garden"))
.with_child(Html::with(move |_| match &status {
Some(status) => html! {
p { "Watered " (status.runs()) " times." }
@if let Some(last) = status.last_run() {
p { "Last time: " (last.started_at().format("%H:%M:%S UTC")) "." }
}
@if let Some(next) = status.next_run() {
p { "Next time: " (next.format("%Y-%m-%d %H:%M UTC")) "." }
}
},
None => html! { p { "No watering job." } },
}))
.render()
.await
}
#[pagetop::main]
async fn main() -> std::io::Result<()> {
Application::prepare(&Garden).await.run().await
}
```
## Comprueba
Para no esperar a las 6:30, programa el riego cada diez segundos en `config/local.toml`:
```toml
[cron.jobs."garden.water"]
schedule = "@every 10s"
```
Arranca con `cargo run`: el terminal anuncia `Cron scheduler started with 1 of 1 jobs` y, cada diez
segundos, `Watering the plots (Schedule)`. Recarga `/` y verás crecer el número de riegos.
En las pruebas el planificador no arranca: ejecuta el trabajo con `run_now()`, que espera a que
termine y devuelve cómo fue:
```rust
# use pagetop::prelude::*;
# use pagetop_cron::prelude::*;
# async fn water_plots(_cx: JobContext) -> JobResult { Ok(()) }
# fn declare_jobs(jobs: &mut CronJobs) {
# jobs.add(Job::new("garden.water", Schedule::cron("30 6 * * *"), water_plots));
# }
# struct Garden;
# #[async_trait]
# impl Extension for Garden {
# fn dependencies(&self) -> Vec<ExtensionRef> {
# vec![&pagetop_cron::Cron]
# }
# fn actions(&self) -> Vec<ActionBox> {
# actions![DeclareCronJobs::new(declare_jobs)]
# }
# }
#[pagetop::test]
async fn watering_succeeds() {
Application::prepare(&Garden).await;
let run = pagetop_cron::run_now("garden.water").await.unwrap();
assert!(run.outcome().is_success(), "{}", run.outcome());
assert_eq!(pagetop_cron::job("garden.water").unwrap().runs(), 1);
}
```
Para vigilar todos los trabajos (registrar sus ejecuciones, avisar cuando uno falla), registra la
acción `AfterJobRun`, que recibe el informe de cada ejecución terminada.
## Siguiente
- [Opciones de configuración](../reference/configuration.md#cron): todas las claves de `[cron]`.
- [Compartir un servicio entre rutas](services.md): los servicios que usan los trabajos.
- [Desplegar en producción](deployment.md): la aplicación como servicio, que se detiene de forma
ordenada.

View file

@ -44,14 +44,19 @@ O, desde cualquier directorio, indicando dónde está la configuración:
CONFIG_DIR=/opt/my-app/config PAGETOP_RUN_MODE=production /opt/my-app/my-app
```
Los secretos pueden ir también en variables de entorno en lugar de `local.production.toml`:
cualquier clave se sobrescribe con `PAGETOP_<SECCIÓN>__<CLAVE>` (p. ej.
`PAGETOP_DATABASE__DB_PASS`), como explica la
[referencia de la configuración](../reference/configuration.md).
Recuerda que, por defecto, el servidor sólo escucha en `localhost`. Para aceptar conexiones de
fuera, o de un proxy en otro equipo, fija `bind_address = "0.0.0.0"` en `[server]`.
## 3. Como servicio del sistema
PageTop se detiene de forma ordenada con `SIGTERM`, la señal que envían `systemd` o Docker: deja de
aceptar conexiones, termina las peticiones en curso y vuelca las trazas pendientes. Una unidad de
`systemd` sencilla:
aceptar conexiones, termina las peticiones en curso, espera a las tareas de `pagetop-cron` que estén
en marcha y vuelca las trazas pendientes. Una unidad de `systemd` sencilla:
```ini
[Unit]
@ -61,6 +66,7 @@ After=network.target
[Service]
WorkingDirectory=/opt/my-app
Environment=PAGETOP_RUN_MODE=production
EnvironmentFile=-/etc/my-app/secrets.env
ExecStart=/opt/my-app/my-app
Restart=on-failure
User=my-app
@ -69,6 +75,9 @@ User=my-app
WantedBy=multi-user.target
```
`EnvironmentFile` es opcional (el `-` lo admite ausente): un archivo legible sólo por `root`, con
una variable por línea, como `PAGETOP_DATABASE__DB_PASS=secret`.
## 4. En un contenedor
El binario no necesita nada a su lado salvo `config/`, así que la imagen final puede ser mínima. Un
@ -91,7 +100,8 @@ CMD ["/app/my-app"]
Dentro del contenedor, el servidor debe escuchar en todas las interfaces: pon
`bind_address = "0.0.0.0"` en `config/production.toml`. Docker detiene los contenedores con
`SIGTERM`, que PageTop atiende cerrando de forma ordenada.
`SIGTERM`, que PageTop atiende cerrando de forma ordenada. Los secretos no van en la imagen: se
pasan al arrancar el contenedor, por ejemplo con `docker run --env-file secrets.env`.
## 5. Detrás de un proxy inverso
@ -117,6 +127,24 @@ server {
Con el proxy delante, deja `bind_address = "localhost"` (el valor por defecto): así sólo el proxy
llega a la aplicación.
Todas las conexiones llegan entonces desde el proxy. Para que la aplicación conozca la dirección de
cada visitante, que usan por ejemplo los límites por IP de `pagetop-user`, indica la cabecera en
la que el proxy la escribe:
```toml
[server]
client_ip_header = "X-Forwarded-For"
```
Si la cabecera trae varias direcciones, vale la última, la que añade el proxy: las anteriores las
envía el navegador y podrían ser falsas. Configúrala sólo si todas las peticiones pasan por el
proxy y éste escribe siempre la cabecera, como hace `$proxy_add_x_forwarded_for` en el ejemplo.
Conserva la línea `proxy_set_header Host $host;`. La protección contra CSRF compara la cabecera
`Origin` del navegador con `Host` cuando el navegador no envía `Sec-Fetch-Site` (los antiguos, o
cualquiera en una conexión HTTP sin cifrar fuera de `localhost`). Si el proxy cambia `Host` por
`127.0.0.1:8080`, esos navegadores reciben un `403` al enviar cualquier formulario.
## Comprueba
```sh
@ -130,4 +158,6 @@ peticiones en curso.
## Siguiente
- [Registrar trazas](logging.md): trazas en archivos con rotación.
- [Programar tareas periódicas](cron.md#6-con-varias-instancias-elige-el-modo): con varias
instancias, quién ejecuta las tareas.
- [Opciones de configuración](../reference/configuration.md).

View file

@ -104,6 +104,38 @@ impl Extension for Catalog {
}
```
`initialize()` se ejecuta cada vez que se prepara la aplicación, también en las pruebas. Lo que
debe funcionar sólo mientras la aplicación está **en marcha**, como una tarea en segundo plano que
vacía una cola, se lanza en `start()`: sólo lo llama `run()`, una vez enlazado el puerto y antes
de la primera petición, y nunca las pruebas. Su pareja, `shutdown()`, se llama al detener la
aplicación, cuando ya han terminado las peticiones en curso. El ejemplo lanza la tarea con
[Tokio](https://tokio.rs), que debes añadir a tu `Cargo.toml`:
```rust,no_run
# use pagetop::prelude::*;
pub struct Outbox;
#[async_trait]
impl Extension for Outbox {
async fn start(&self) -> Result<(), BoxError> {
tokio::spawn(async {
loop {
tokio::time::sleep(std::time::Duration::from_secs(60)).await;
trace::info!("Flushing the outbox");
}
});
Ok(())
}
async fn shutdown(&self) {
trace::info!("Outbox stopped");
}
}
```
Para tareas periódicas no hace falta escribir el bucle: [Programar tareas periódicas](cron.md)
lo resuelve con una extensión.
## 4. Pon componentes en todas las páginas
`InRegion` registra un componente una sola vez para que aparezca en todas las páginas:

View file

@ -109,7 +109,6 @@ struct ContactData {
async fn show(request: HttpRequest) -> Result<Markup, ErrorPage> {
Page::new(request)
.with_title(Lc::n("Contact"))
.with_child(Messages::new())
.with_child(contact_form())
.render()
.await
@ -121,20 +120,30 @@ async fn send(
) -> Result<Response, ErrorPage> {
if data.message.trim().is_empty() {
// Shows the form again with a message.
let mut page = Page::new(request)
.with_child(Messages::new())
.with_child(contact_form());
let mut page = Page::new(request).with_child(contact_form());
page.context()
.push_message(MessageLevel::Error, Lc::n("Please write a message."));
return page.render().await.map(IntoResponse::into_response);
}
// ... save or send `data` ...
Ok(Redirect::see_other("/contact/thanks"))
let cx = Context::new(request);
Ok(Redirect::see_other(cx.route("/contact")).with_message(
&cx,
MessageLevel::Info,
Lc::n("Thank you, we will reply soon."),
))
}
```
Si el mensaje está en blanco, la página se repite con un aviso. No hace falta añadir el componente
`Messages`: la región de contenido ya empieza por uno que muestra los avisos acumulados con
`push_message()`.
Tras guardar, redirige con `see_other()` (patrón *Post/Redirect/Get*): así, si el usuario recarga
la página, no reenvía el formulario.
la página, no reenvía el formulario. Para avisar del resultado en la página a la que rediriges,
añade el mensaje a la respuesta con `with_message()`: viaja en una *cookie* de vida corta, ya
traducido, y la página siguiente lo muestra como si se hubiera añadido con `push_message()`. Si esa
página vuelve a redirigir, el mensaje espera a la siguiente.
## 4. Campos con varios valores
@ -172,13 +181,38 @@ fn read_date(cx: &Context, text: &str) {
}
```
## 6. Sin *tokens* contra CSRF
Los formularios no necesitan ningún campo oculto contra CSRF (*Cross-Site Request Forgery*), el
ataque en el que otra web hace que el navegador de tus usuarios envíe peticiones a tu aplicación
con su sesión abierta. PageTop rechaza con `403` cualquier petición que pueda cambiar algo (todos
los métodos salvo `GET`, `HEAD` y `OPTIONS`) si el navegador indica, con las cabeceras
`Sec-Fetch-Site` y `Origin`, que llega desde otro origen, también desde otro subdominio del mismo
sitio. Vale igual para formularios, HTMX y `fetch`, y no afecta a `curl`, a otros servidores ni a
las pruebas, que no envían esas cabeceras.
A cambio, dos reglas:
- **Un `GET` nunca cambia nada.** Borrar, cerrar sesión o confirmar van siempre con `POST` (o
`PUT`, `PATCH`, `DELETE`), aunque el formulario sea sólo un botón.
- **Otra aplicación tuya, servida desde otro origen,** que envíe formularios o peticiones a ésta
debe figurar en `trusted_origins`:
```toml
[server]
trusted_origins = ["https://shop.example.com"]
```
Ninguna protección contra CSRF resiste un fallo de XSS en la propia aplicación: por eso `html!`
escapa siempre el texto que insertas.
## Comprueba
1. Envía el formulario vacío: el navegador lo impide, porque `name` es obligatorio.
2. Envía un mensaje en blanco (sólo espacios): el servidor lo rechaza y el formulario vuelve con el
aviso.
3. Envía uno correcto y recarga la página de destino: el navegador no ofrece reenviar el
formulario.
3. Envía uno correcto: vuelves al formulario con el aviso de agradecimiento. Recarga la página: el
aviso ya no aparece y el navegador no ofrece reenviar el formulario.
## Siguiente

View file

@ -90,6 +90,9 @@ async fn close_season() -> HtmxResponse {
`location()` es la alternativa suave: navega con HTMX, sin recargar los estilos y *scripts* de la
página.
Con las dos, los avisos que añadas con `with_message()` esperan a la página de destino, como tras
una redirección normal: convierte antes la respuesta con `.into_response()`.
## Las cabeceras disponibles
| Método | Cabecera | Efecto |

View file

@ -52,6 +52,9 @@ async fn news(request: HttpRequest) -> Result<Markup, ErrorPage> {
}
```
`Content` empieza siempre por los avisos al usuario (ver [Mensajes al
usuario](components.md#mensajes-al-usuario)): no hace falta añadir el componente `Messages`.
Los componentes añadidos así sólo existen en esa página. Para que algo aparezca en **todas** (un
menú, un pie...), regístralo una vez con `InRegion`, como se explica en [Crear una
extensión](extensions.md#4-pon-componentes-en-todas-las-páginas).

View file

@ -151,6 +151,11 @@ impl Theme for Earth {
Como el componente expone sus datos con *getters* (`badge.label()`), el tema no depende de sus
detalles internos.
Si capturas `layout::Region` para maquetar la región de contenido a tu manera, incluye al
principio `Messages::new().with_deferred(true)`, que es lo que pone PageTop: sin él, los avisos al
usuario no se ven. Es también la forma de llevarlos a otro lugar de la página, por ejemplo a la
cabecera.
## 6. Cambia las páginas de error
Las páginas 403, 404 y de error grave se pintan con la plantilla activa, para no perder la

View file

@ -28,9 +28,27 @@ impl Extension for Board {
}
```
`User` declara por su cuenta lo que necesita: `pagetop-seaorm`, `pagetop-htmx` y el panel
`pagetop-admin`. Al arrancar crea sus tablas y registra sus rutas, entre ellas `/user/login`,
`/user/register` y `/user` (el perfil).
`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).
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
cambia su contraseña o se pide cambiar su dirección. Mientras no configures la sección
`[mail]`, los correos se escriben en las trazas en lugar de enviarse; para enviarlos, indica al menos
el transporte, el remitente y la URL pública de la aplicación, que forma los enlaces:
```toml
# config/production.toml
[mail]
transport = "smtp"
from = "Garden board <no-reply@example.com>"
base_url = "https://board.example.com"
[mail.smtp]
host = "smtp.example.com"
```
## 2. Configura la base de datos y el primer administrador
@ -56,8 +74,62 @@ pagetop-user: admin account created.
password: ...
```
Las demás opciones (registro abierto, bloqueo tras intentos fallidos, duración de las sesiones...)
están en la [referencia de configuración](../reference/configuration.md#user).
Las demás opciones (registro abierto, bloqueo tras intentos fallidos, límites por IP, duración de
las sesiones...) están en la [referencia de configuración](../reference/configuration.md#user).
### Elige qué nombres de usuario se aceptan
Cada cuenta tiene un nombre de usuario y un email, los dos obligatorios y únicos, y se puede
iniciar sesión con cualquiera de ellos. Qué nombres de usuario se admiten lo decide
`identity_policy`:
```toml
# config/common.toml
[user]
identity_policy = "unicode"
```
| Valor | Caracteres | Longitud |
|---|---|---|
| `"strict"` (por defecto) | Letras ASCII sin tildes, dígitos, `.`, `_` y `-` | 3 a 32 |
| `"unicode"` | Letras y dígitos de cualquier alfabeto, sin mezclarlos, `.`, `_` y `-` | 3 a 32 |
| `"permissive"` | Los de `"unicode"`, más espacios simples, `'` y `+` | 3 a 60 |
Cada nivel admite todo lo del anterior, y los tres comparten tres reglas:
- **Nunca se admite `@`**, así que un nombre de usuario no puede coincidir con el email de otra
cuenta, que también sirve para entrar.
- **No se distinguen mayúsculas**: `Ana` y `ana` son el mismo usuario. El nombre se muestra tal
como se escribió.
- **No se admiten nombres que se confunden a simple vista con otro existente**: si existe `maria`,
no se puede crear `rnaria`, ni `сосо` (escrito con letras cirílicas) si existe `coco`. Se
comprueba con la tabla de caracteres confusables de Unicode.
Para elegir, piensa en quién crea los nombres más que en dónde se publica la aplicación. Con el
registro abierto, cualquiera escoge un nombre que verán los demás y que aparecerá en el saludo de
sus correos en cuanto verifique su dirección; si las cuentas sólo las crea un administrador, el
riesgo es mucho menor.
| Situación | Política |
|---|---|
| Aplicación en Internet con registro abierto | `"strict"` |
| Comunidad en Internet cuyos usuarios escriben su nombre en su alfabeto | `"unicode"` |
| Aplicación interna con cuentas creadas por administradores | `"strict"` o `"unicode"` |
| Importar cuentas de un sistema con espacios en los nombres (Drupal...) | `"permissive"` |
`"strict"` basta casi siempre: los nombres con tildes o en otros alfabetos tienen su sitio en el
nombre visible de la cuenta. Evita `"permissive"` con el registro abierto, porque los espacios
permiten escribir frases («Soporte técnico», «Llama al 900...») que luego se muestran como nombre.
Puedes cambiar de política cuando quieras, y nadie pierde el acceso:
- **A una más abierta**, las cuentas existentes no cambian.
- **A una más estricta**, los nombres que ya no la cumplen se conservan y sus titulares pueden
seguir entrando y guardando su perfil; sólo un nombre nuevo, o uno que se cambia, debe cumplirla.
Nada se renombra automáticamente.
- **El administrador inicial** (`[user.seed] admin_username`) se comprueba en cada arranque: si no
cumple la política nueva, la aplicación no arranca hasta que pongas uno válido. Cambiarlo no
renombra al administrador que ya existe, y con el valor por defecto, `admin`, no ocurre nunca.
## 3. Pon el menú de cuenta en la cabecera
@ -111,7 +183,7 @@ enum BoardPermission {
impl Permission for BoardPermission {
fn key(&self) -> CowStr {
match self {
Self::PostNotices => "board.post_notices".into(),
Self::PostNotices => "board:post_notices".into(),
}
}
@ -136,7 +208,7 @@ Para que aparezca en la pantalla de roles, regístralo con la acción `DeclarePe
# #[derive(Clone, Copy, Debug)]
# enum BoardPermission { PostNotices }
# impl Permission for BoardPermission {
# fn key(&self) -> CowStr { "board.post_notices".into() }
# fn key(&self) -> CowStr { "board:post_notices".into() }
# }
use pagetop_user::PermissionRegistry;
use pagetop_user::prelude::*;
@ -167,7 +239,7 @@ impl Extension for Board {
# #[derive(Clone, Copy, Debug)]
# enum BoardPermission { PostNotices }
# impl Permission for BoardPermission {
# fn key(&self) -> CowStr { "board.post_notices".into() }
# fn key(&self) -> CowStr { "board:post_notices".into() }
# }
async fn new_notice(request: HttpRequest) -> Result<Markup, ErrorPage> {
require_permission(&request, &BoardPermission::PostNotices)?;
@ -185,7 +257,7 @@ async fn new_notice(request: HttpRequest) -> Result<Markup, ErrorPage> {
# #[derive(Clone, Copy, Debug)]
# enum BoardPermission { PostNotices }
# impl Permission for BoardPermission {
# fn key(&self) -> CowStr { "board.post_notices".into() }
# fn key(&self) -> CowStr { "board:post_notices".into() }
# }
async fn board(request: HttpRequest) -> Result<Markup, ErrorPage> {
let can_post = has_permission(&request, &BoardPermission::PostNotices);
@ -244,7 +316,7 @@ enum BoardPermission {
impl Permission for BoardPermission {
fn key(&self) -> CowStr {
match self {
Self::PostNotices => "board.post_notices".into(),
Self::PostNotices => "board:post_notices".into(),
}
}

View file

@ -9,6 +9,9 @@ Lo esencial de PageTop en una página. Cada línea enlaza con la guía que lo ex
| [Arrancar](../tutorials/first-app.md) | `Application::prepare(&MyApp).await.run().await` |
| [Declarar dependencias](../how-to/extensions.md) | `fn dependencies(&self) -> Vec<ExtensionRef> { vec![&Other] }` |
| [Ejecutar código al arrancar](../how-to/extensions.md#3-inicialízala-al-arrancar) | `async fn initialize(&self) -> Result<(), BoxError>` |
| [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")` |
| [Leer un ajuste](../how-to/configuration.md) | `global::SETTINGS.app.name` |
@ -39,6 +42,7 @@ Lo esencial de PageTop en una página. Cada línea enlaza con la guía que lo ex
| [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 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)` |
## Textos

View file

@ -25,7 +25,7 @@ el idioma del visitante.
| `Image` | Imagen, a su tamaño, adaptable o en miniatura | `Image::with(image::Source::plain(..))`, `responsive(..)`, `thumbnail(..)` |
| `Badge` | Etiqueta pequeña de estado | `Badge::labeled()`, `primary()`, `neutral()`, `success()`, `info()`, `warning()`, `severe()` |
| `Button` | Botón o enlace con aspecto de botón | `Button::submit()`, `reset()`, `plain()`, `anchor(label, ruta)` |
| `Messages` | Avisos acumulados en el contexto | `Messages::new()` |
| `Messages` | Avisos acumulados en el contexto; la región de contenido ya empieza por uno | `Messages::new()`, `.with_deferred(true)` |
| `Dialog` | Ventana modal con título, cuerpo y pie | `Dialog::new()` |
| `PoweredBy` | Pie con el crédito de PageTop | `PoweredBy::new()` |

View file

@ -15,17 +15,36 @@ sólo en las claves que define:
| 3 | `config/local.{modo}.toml` | Ajustes locales de ese modo (no se versiona) |
| 4 | `config/local.toml` | Ajustes locales para cualquier modo (no se versiona) |
Todos son opcionales. Sólo se leen dos variables de entorno, y ninguna sobrescribe claves sueltas:
Todos son opcionales. Dos variables de entorno eligen qué archivos se cargan:
| Variable | Efecto |
|---|---|
| `PAGETOP_RUN_MODE` | El modo de ejecución, `{modo}` en la tabla anterior. Por defecto, `default` |
| `CONFIG_DIR` | Otro directorio de configuración en lugar de `config/` |
Por último, las variables `PAGETOP_<SECCIÓN>__<CLAVE>` sobrescriben cualquier clave de los
archivos. La sección y la clave van en mayúsculas, con cada nivel separado por dos guiones bajos:
| Variable | Clave |
|---|---|
| `PAGETOP_SERVER__BIND_PORT=80` | `bind_port` de `[server]` |
| `PAGETOP_DATABASE__DB_PASS=secret` | `db_pass` de `[database]` |
| `PAGETOP_MAIL__SMTP__PASSWORD=secret` | `password` de `[mail.smtp]` |
- El valor se escribe sin comillas: los números en decimal (`80`) y los booleanos como `true` o
`false`.
- Una variable vacía equivale a no definirla, así que no sirve para vaciar un valor de los archivos.
- No sirven para listas ni para claves con punto, como la del trabajo `mail.queue` en
`[cron.jobs."mail.queue"]`. Un trabajo sin punto en la clave sí:
`PAGETOP_CRON__JOBS__CLEANUP__ENABLED=false`.
- Con la *feature* `testing` se ignoran, para que no cambien el resultado de las pruebas.
- Al arrancar, las trazas indican qué claves vienen del entorno (nunca sus valores).
Reglas comunes a todas las secciones:
- Una **clave desconocida** o un **valor no válido** impiden arrancar, con un mensaje que indica la
sección y la clave.
sección y la clave. También si vienen de una variable de entorno: el mensaje nombra entonces las
variables de esa sección.
- Una **sección** que no corresponde a PageTop ni a ninguna extensión habilitada se ignora, con un
aviso al arrancar.
- En los valores fijos del núcleo (`"Full"`, `"Daily"`...) da igual escribir mayúsculas o
@ -75,6 +94,8 @@ bind_port = 8080
|---|---|---|---|
| `bind_address` | Texto | `"localhost"` | Dirección en la que escucha. `"0.0.0.0"` acepta conexiones de fuera |
| `bind_port` | Entero | `8080` | Puerto |
| `client_ip_header` | Texto | `""` | Cabecera con la IP del cliente detrás de un proxy inverso (`"X-Forwarded-For"`, `"X-Real-IP"`...); con varias direcciones vale la última; `"Forwarded"` no se admite. Vacía, la de la conexión. Un nombre no válido impide arrancar. Ver [Detrás de un proxy inverso](../how-to/deployment.md#5-detrás-de-un-proxy-inverso) |
| `trusted_origins` | Lista | `[]` | Orígenes de otras aplicaciones (`"https://shop.example.com"`) desde los que un navegador puede enviar peticiones que cambian estado (`POST`, `PUT`...); las demás que lleguen de otro origen se rechazan con `403` (protección CSRF). Formato `esquema://servidor[:puerto]`; uno no válido impide arrancar. Ver [Sin *tokens* contra CSRF](../how-to/forms.md#6-sin-tokens-contra-csrf) |
## `[log]`
@ -123,6 +144,103 @@ db_host = "localhost"
| `db_port` | Entero | 3306 / 5432 | Puerto, si no es el del motor |
| `max_pool_size` | Entero | `5` | Conexiones simultáneas como máximo |
## `[mail]`
De [`pagetop-mail`](extensions.md#correo). Sin configurar, los correos se escriben en las trazas en
lugar de enviarse, así que una aplicación en desarrollo nunca envía correo real por error.
```toml
[mail]
transport = "smtp"
from = "Garden board <no-reply@example.com>"
base_url = "https://board.example.com"
[mail.smtp]
host = "smtp.example.com"
username = "no-reply@example.com"
password = "secret" # Better in config/local.toml.
```
| Clave | Tipo | Por defecto | Notas |
|---|---|---|---|
| `transport` | `smtp`, `sendmail`, `file`, `log`, `memory` | `log` | Cómo se entregan: servidor SMTP, programa *sendmail*, un `.eml` por correo, en las trazas, o en memoria (pruebas) |
| `from` | Texto | Ninguno | Remitente por defecto, con o sin nombre. Necesario para enviar los correos de `pagetop-user` |
| `reply_to` | Texto | Ninguno | Dirección de respuesta por defecto |
| `redirect_to` | Texto | Ninguno | Entrega todos los correos sólo a esta dirección (entornos de pruebas) |
| `base_url` | Texto | `http://{bind_address}:{bind_port}` | URL pública para los enlaces de los correos. **Indícala en producción** |
| `previews` | Booleano | `false` | Vistas previas de los correos en `/mail/preview`. Sólo en desarrollo |
| `delivery_timeout_secs` | Entero | `300` | Tiempo máximo de cada entrega completa, incluida la espera de su turno (1 a 86400). Se recomienda el valor por defecto |
| `max_waiting` | Entero | `100` | Correos que pueden esperar turno por cada envío simultáneo; con más, la entrega falla enseguida en lugar de acumularlos en memoria. No se recomiendan valores mayores |
### `[mail.smtp]`
| Clave | Tipo | Por defecto | Notas |
|---|---|---|---|
| `host` | Texto | `"localhost"` | Servidor SMTP |
| `port` | Entero | Según `security` | 465 con `tls`, 587 con `starttls` y 25 con los demás |
| `security` | `none`, `opportunistic`, `starttls`, `tls` | `starttls` | Cifrado de la conexión |
| `username`, `password` | Texto | Ninguno | Credenciales. Sin usuario, no se autentica |
| `hello_name` | Texto | Nombre del equipo | Nombre para `EHLO` |
| `timeout_secs` | Entero | `60` | Espera máxima de cada orden al servidor |
| `pool_max_size` | Entero | `10` | Conexiones abiertas como máximo, reutilizadas entre envíos |
| `accept_invalid_certs` | Booleano | `false` | Acepta certificados no válidos. **Sólo para pruebas** |
Con `transport = "sendmail"`, `[mail.sendmail] command` indica el programa (por defecto,
`sendmail` del `PATH`); con `transport = "file"`, `[mail.file] dir` el directorio de los `.eml`
(por defecto, `"mail"`). En las dos subsecciones, `max_concurrent` (por defecto, `10`) limita los
correos que se entregan a la vez; no se recomiendan valores mayores.
### `[mail.queue]`
Sólo con la *feature* `queue` de `pagetop-mail`, que guarda los correos en la base de datos y
reintenta los que fallan. La envía el trabajo `mail.queue` de `pagetop-cron`, un minuto después de
terminar la ejecución anterior; su ritmo se cambia en `[cron.jobs."mail.queue"]`.
| Clave | Tipo | Por defecto | Notas |
|---|---|---|---|
| `batch_size` | Entero | `50` | Correos que envía cada ejecución del trabajo, uno tras otro |
| `max_attempts` | Entero | `5` | Intentos de cada correo, contando el primero; agotados, o ante un rechazo definitivo del servidor (SMTP 5xx), queda como fallido |
| `retry_base_secs` | Entero | `60` | Espera tras el primer fallo temporal; se duplica en cada intento |
| `max_retry_secs` | Entero | `86400` | Espera máxima entre dos intentos (1 a un año) |
| `keep_failed_days` | Entero | `30` | Días que se conservan los correos fallidos; `0`, siempre. Los enviados se borran al entregarse |
## `[cron]`
De [`pagetop-cron`](extensions.md#tareas-programadas). Decide cómo se ejecutan los trabajos
programados y permite ajustar cada uno por su clave.
```toml
[cron]
mode = "internal"
[cron.jobs."garden.water"]
schedule = "0 7 * * *"
timeout_secs = 600
```
| Clave | Tipo | Por defecto | Notas |
|---|---|---|---|
| `mode` | `internal`, `external`, `off` | `internal` | Quién ejecuta los trabajos: la propia aplicación, una llamada externa a `POST /cron`, o nadie (sólo bajo demanda) |
| `trigger_token` | Texto | Ninguno | Clave secreta del modo `external`, en la cabecera `Authorization: Bearer <clave>`: 16 o más letras, dígitos, `-` o `_`. Obligatoria en ese modo |
| `trigger_interval_secs` | Entero | `60` | Cada cuántos segundos llama el programa externo en el modo `external`; cada llamada ejecuta lo programado en el último intervalo |
| `shutdown_timeout_secs` | Entero | `30` | Espera máxima, al detener la aplicación, a que terminen los trabajos en curso |
Con varias instancias de la aplicación, usa `internal` en una sola y `off` en las demás, o
`external` en todas (ve [Con varias instancias, elige el
modo](../how-to/cron.md#6-con-varias-instancias-elige-el-modo)).
### `[cron.jobs."clave"]`
Ajustes de un trabajo, por su clave (entre comillas, porque suele llevar un punto). Lo que no se
indica mantiene lo declarado en el código; una clave que no corresponde a ningún trabajo sólo
produce un aviso.
| Clave | Tipo | Por defecto | Notas |
|---|---|---|---|
| `enabled` | Booleano | `true` | Con `false`, el trabajo sólo se ejecuta bajo demanda |
| `schedule` | Texto | La del código | Expresión cron, `"@daily"`, `"@every 10m"` (cada 10 min desde que empieza) o `"@delay 30s"` (30 s después de terminar) |
| `timeout_secs` | Entero | El del código | Tiempo máximo de cada ejecución; `0` quita el límite |
## `[user]`
De [`pagetop-user`](extensions.md#usuarios-y-permisos). Ver [Añadir usuarios y
@ -131,10 +249,19 @@ permisos](../how-to/users.md).
| Clave | Tipo | Por defecto | Notas |
|---|---|---|---|
| `allow_registration` | Booleano | `true` | Los visitantes pueden crear su propia cuenta |
| `require_email_verification` | Booleano | `false` | Las cuentas nuevas quedan pendientes hasta verificar el correo |
| `max_failed_logins` | Entero | `5` | Intentos fallidos antes de bloquear la cuenta |
| `failed_login_window_secs` | Entero | `900` | Reservada; todavía no tiene efecto |
| `require_email_verification` | Booleano | `false` | Las cuentas nuevas quedan pendientes hasta confirmar su dirección desde el enlace del correo de verificación que reciben al registrarse |
| `identity_policy` | Texto | `"strict"` | Nombres de usuario que se aceptan: `"strict"`, `"unicode"` o `"permissive"`. Ver [Elige qué nombres de usuario se aceptan](../how-to/users.md#elige-qué-nombres-de-usuario-se-aceptan) |
| `max_failed_logins` | Entero | `5` | Intentos fallidos seguidos que bloquean la cuenta, también los de la contraseña actual al cambiar la contraseña o el email; `0`, nunca |
| `failed_login_window_secs` | Entero | `900` | Segundos desde el último fallo en los que el siguiente se suma al recuento |
| `locked_for_secs` | Entero | `600` | Segundos que dura el bloqueo |
| `max_password_resets` | Entero | `3` | Máximo de solicitudes de recuperación de contraseña de una misma cuenta en un periodo de `password_reset_window_secs` segundos; las siguientes no envían correo; `0`, sin límite |
| `password_reset_window_secs` | Entero | `3600` | Duración del periodo |
| `max_email_changes` | Entero | `3` | Máximo de cambios de email que puede pedir una misma cuenta en un periodo de `email_change_window_secs` segundos; `0`, sin límite |
| `email_change_window_secs` | Entero | `3600` | Duración del periodo |
| `max_ip_requests` | Entero | `20` | Máximo de registros, recuperaciones de contraseña y cambios de email desde una misma IP en un periodo de `ip_request_window_secs` segundos; `0`, sin límite. Tras un proxy inverso requiere `client_ip_header` de `[server]` |
| `ip_request_window_secs` | Entero | `3600` | Duración del periodo |
| `max_ip_failed_logins` | Entero | `30` | Máximo de inicios de sesión fallidos desde una misma IP en un periodo de `ip_failed_login_window_secs` segundos; los siguientes se rechazan sin comprobar la contraseña. Frena probar unas pocas contraseñas en muchas cuentas. `0`, sin límite. Tras un proxy inverso requiere `client_ip_header` de `[server]` |
| `ip_failed_login_window_secs` | Entero | `900` | Duración del periodo |
| `login_strict` | Booleano | `false` | Dificulta que el navegador recuerde las credenciales |
### `[user.session]`
@ -151,10 +278,13 @@ permisos](../how-to/users.md).
| Clave | Tipo | Por defecto | Notas |
|---|---|---|---|
| `argon2_m_cost` | Entero | `19456` | Memoria de Argon2id, en KiB. Si cambia, las contraseñas se recifran en el siguiente acceso |
| `argon2_m_cost` | Entero | `19456` | Memoria de Argon2id, en KiB |
| `argon2_t_cost` | Entero | `2` | Iteraciones |
| `argon2_p_cost` | Entero | `1` | Hilos |
| `min_length` | Entero | `8` | Longitud mínima de una contraseña |
| `min_length` | Entero | `8` | Longitud mínima de una contraseña, en caracteres |
Si cambia cualquiera de los tres costes, cada contraseña se vuelve a cifrar con los nuevos en el
siguiente acceso de su usuario.
### `[user.seed]`
@ -162,8 +292,8 @@ El primer administrador, que se crea si no existe ningún usuario.
| Clave | Tipo | Por defecto | Notas |
|---|---|---|---|
| `admin_username` | Texto | `"admin"` | Nombre de usuario |
| `admin_email` | Texto | `"admin@example.com"` | Correo |
| `admin_username` | Texto | `"admin"` | Nombre de usuario. Si no cumple `identity_policy`, la aplicación no arranca |
| `admin_email` | Texto | `"admin@example.com"` | Correo. Si no es válido, la aplicación no arranca |
| `admin_password` | Texto | Ninguno | Sin valor, se genera una y se muestra una sola vez en el terminal |
### `[user.admin]`

View file

@ -8,6 +8,8 @@ con una línea en `dependencies()`.
| [`pagetop-bootsier`](#bootsier) | Tema completo para cualquier aplicación | [Bootstrap 5](https://getbootstrap.com) |
| [`pagetop-htmx`](#htmx) | Interactividad sin escribir JavaScript | [HTMX 2](https://htmx.org) |
| [`pagetop-seaorm`](#seaorm) | Bases de datos PostgreSQL, MySQL y SQLite | [SeaORM](https://www.sea-ql.org/SeaORM) |
| [`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-aliner`](../how-to/themes.md) | Tema de pruebas que muestra la estructura de la página | Componentes del núcleo |
@ -133,11 +135,83 @@ impl Extension for MyApp {
Si la base de datos no responde o una migración falla, la aplicación no arranca y lo explica. Más
en [Conectar una base de datos](../how-to/database.md).
## Correo
`pagetop-mail` envía correos en texto y HTML, con adjuntos, por SMTP, con *sendmail* o a archivos
`.eml`, según la sección [`[mail]`](configuration.md#mail). Sin configurar, los escribe en las
trazas. Un correo se compone con `Email`, o con una plantilla (`MailTemplate`) que traduce sus
textos al idioma del destinatario:
```rust,no_run
use pagetop::prelude::*;
use pagetop_mail::prelude::*;
async fn notify() -> Result<(), MailError> {
Email::new()
.with_to("Ana Pérez <ana@example.com>")
.with_subject("Your order has shipped")
.with_html(html! { p { "Order " strong { "1234" } " left today." } })
.send()
.await
}
```
`send()` espera a la entrega; `send_later()` envía en segundo plano y registra los fallos en las
trazas. Con la *feature* `queue`, `send_later()` guarda antes el correo en una cola en la base de
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`.
## Tareas programadas
`pagetop-cron` ejecuta trabajos en segundo plano mientras la aplicación está en marcha, según una
expresión cron o a intervalos. Cada extensión los declara con la acción `DeclareCronJobs`:
```rust,no_run
use pagetop::prelude::*;
use pagetop_cron::prelude::*;
async fn purge_old_tasks(_cx: JobContext) -> JobResult {
// Deletes the tasks completed more than a year ago...
Ok(())
}
fn declare_jobs(jobs: &mut CronJobs) {
jobs.add(Job::new("garden.purge", Schedule::cron("0 3 * * SUN"), purge_old_tasks));
}
pub struct Garden;
#[async_trait]
impl Extension for Garden {
fn dependencies(&self) -> Vec<ExtensionRef> {
vec![&pagetop_cron::Cron]
}
fn actions(&self) -> Vec<ActionBox> {
actions![DeclareCronJobs::new(declare_jobs)]
}
}
```
La sección [`[cron]`](configuration.md#cron) elige si los ejecuta la propia aplicación, una llamada
externa (para varias instancias) o nadie, y permite cambiar o desactivar cada trabajo por su clave.
`pagetop_cron::run_now()` ejecuta un trabajo bajo demanda, también en las pruebas, donde el
planificador no arranca. Paso a paso en [Programar tareas periódicas](../how-to/cron.md).
## Usuarios y permisos
`pagetop-user` aporta inicio de sesión, perfiles, sesiones guardadas en la base de datos,
contraseñas con Argon2 y control de acceso por roles (RBAC), con su interfaz de administración. Se
apoya en `pagetop-seaorm`.
apoya en `pagetop-seaorm`, y en `pagetop-mail` para los correos de recuperación de contraseña y de
verificación de las cuentas nuevas.
Frena los ataques a las cuentas sin configurar nada: bloquea una cuenta tras varios intentos
fallidos y limita por dirección IP los inicios de sesión fallidos y las solicitudes que envían
correo (registros, recuperaciones de contraseña, cambios de email). Detrás de un proxy inverso,
los límites por IP necesitan `client_ip_header` de `[server]`. Tras sus acciones (cuenta creada,
contraseña cambiada...) deja un aviso para la página siguiente.
El núcleo de PageTop define cómo se **expresa** un permiso; la extensión decide quién lo tiene:

View file

@ -211,7 +211,6 @@ struct Proposal {
async fn propose(request: HttpRequest) -> Result<Markup, ErrorPage> {
Page::new(request)
.with_title(Lc::n("Propose a garden"))
.with_child(Messages::new())
.with_child(proposal_form())
.render()
.await
@ -224,14 +223,18 @@ async fn receive(
if proposal.name.trim().is_empty() {
let mut page = Page::new(request)
.with_title(Lc::n("Propose a garden"))
.with_child(Messages::new())
.with_child(proposal_form());
page.context()
.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);
Ok(Redirect::see_other("/"))
let cx = Context::new(request);
Ok(Redirect::see_other(cx.route("/")).with_message(
&cx,
MessageLevel::Info,
Lc::n("Thank you! We will review your proposal."),
))
}
```
@ -239,9 +242,10 @@ Las dos funciones atienden la misma ruta, una por método:
`router.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 en `Messages`. Si
todo va bien, redirige con `see_other()`, para que recargar no reenvíe el formulario. La propuesta
queda en las trazas del terminal.
cualquiera puede saltarse el navegador. Si falta, la página se repite con un aviso, que aparece al
principio del contenido sin hacer nada más. Si todo va bien, redirige con `see_other()`, para que
recargar no reenvíe el formulario, y `with_message()` deja un aviso de agradecimiento para la
portada. La propuesta queda en las trazas del terminal.
Más en [Crear y procesar formularios](../how-to/forms.md).
@ -445,16 +449,14 @@ Las pruebas preparan la aplicación sin abrir ningún puerto y le envían petici
# name: String,
# }
# async fn propose(request: HttpRequest) -> Result<Markup, ErrorPage> {
# Page::new(request).with_child(Messages::new()).with_child(proposal_form()).render().await
# Page::new(request).with_child(proposal_form()).render().await
# }
# async fn receive(
# request: HttpRequest,
# web::Form(proposal): web::Form<Proposal>,
# ) -> Result<Response, ErrorPage> {
# if proposal.name.trim().is_empty() {
# let mut page = Page::new(request)
# .with_child(Messages::new())
# .with_child(proposal_form());
# let mut page = Page::new(request).with_child(proposal_form());
# page.context()
# .push_message(MessageLevel::Error, Lc::n("The garden needs a name."));
# return page.render().await.map(IntoResponse::into_response);

View file

@ -12,12 +12,15 @@ publish = false
pagetop = { path = "../../../pagetop" }
pagetop-bootsier = { path = "../../../pagetop/extensions/pagetop-bootsier" }
pagetop-build = { path = "../../../pagetop/helpers/pagetop-build" }
pagetop-cron = { path = "../../../pagetop/extensions/pagetop-cron" }
pagetop-htmx = { path = "../../../pagetop/extensions/pagetop-htmx" }
pagetop-mail = { path = "../../../pagetop/extensions/pagetop-mail" }
pagetop-seaorm = { path = "../../../pagetop/extensions/pagetop-seaorm", features = ["sqlite"] }
pagetop-admin = { path = "../../../pagetop/extensions/pagetop-admin" }
pagetop-user = { path = "../../../pagetop/extensions/pagetop-user" }
serde = { version = "1", features = ["derive"] }
thiserror = "2"
tokio = { version = "1", features = ["full"] }
tower-http = { version = "0.7", features = ["compression-gzip", "cors", "limit", "timeout"] }
[build-dependencies]