📝 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:
parent
1a41a456d4
commit
4e007feec8
23 changed files with 946 additions and 125 deletions
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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**
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
339
doc/v0.6/es/src/how-to/cron.md
Normal file
339
doc/v0.6/es/src/how-to/cron.md
Normal 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.
|
||||
|
|
@ -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).
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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 |
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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(),
|
||||
}
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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()` |
|
||||
|
||||
|
|
|
|||
|
|
@ -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]`
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
|
|
@ -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);
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue