diff --git a/README.md b/README.md index 955bfd5..f52e389 100644 --- a/README.md +++ b/README.md @@ -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_
__` override individual +keys (e.g. `PAGETOP_SERVER__BIND_PORT=80`). ## Warning diff --git a/config/common.toml b/config/common.toml index 6cbb3b9..62f9bbb 100644 --- a/config/common.toml +++ b/config/common.toml @@ -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_
__ 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 >********************************************************************************* diff --git a/doc/v0.6/es/src/SUMMARY.md b/doc/v0.6/es/src/SUMMARY.md index 6c70c21..9b2856e 100644 --- a/doc/v0.6/es/src/SUMMARY.md +++ b/doc/v0.6/es/src/SUMMARY.md @@ -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) diff --git a/doc/v0.6/es/src/explanation/architecture.md b/doc/v0.6/es/src/explanation/architecture.md index 43a23fa..8e619e7 100644 --- a/doc/v0.6/es/src/explanation/architecture.md +++ b/doc/v0.6/es/src/explanation/architecture.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** diff --git a/doc/v0.6/es/src/explanation/comparison.md b/doc/v0.6/es/src/explanation/comparison.md index 93bd082..b882de1 100644 --- a/doc/v0.6/es/src/explanation/comparison.md +++ b/doc/v0.6/es/src/explanation/comparison.md @@ -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 diff --git a/doc/v0.6/es/src/explanation/rendering.md b/doc/v0.6/es/src/explanation/rendering.md index 77680b5..b05b280 100644 --- a/doc/v0.6/es/src/explanation/rendering.md +++ b/doc/v0.6/es/src/explanation/rendering.md @@ -42,13 +42,21 @@ Page::render() 3. : the theme renders the regions every component, see below 4. theme: after_render_page_body(page) 5. extensions: AfterRenderBody - 6. : title, metadata and every asset collected so far + 6. deferred: postponed components, in place e.g. the messages of Content + 7. : title, metadata and every asset collected so far ``` El `` 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: diff --git a/doc/v0.6/es/src/faq.md b/doc/v0.6/es/src/faq.md index c52cae9..3554692 100644 --- a/doc/v0.6/es/src/faq.md +++ b/doc/v0.6/es/src/faq.md @@ -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 diff --git a/doc/v0.6/es/src/how-to/components.md b/doc/v0.6/es/src/how-to/components.md index 48f25ef..7d287aa 100644 --- a/doc/v0.6/es/src/how-to/components.md +++ b/doc/v0.6/es/src/how-to/components.md @@ -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 { - 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: diff --git a/doc/v0.6/es/src/how-to/configuration.md b/doc/v0.6/es/src/how-to/configuration.md index 8ba7caf..23d9263 100644 --- a/doc/v0.6/es/src/how-to/configuration.md +++ b/doc/v0.6/es/src/how-to/configuration.md @@ -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___`, con cada nivel separado por dos guiones bajos. + +```sh +PAGETOP_DATABASE__DB_PASS=secret ./my-app # db_pass of [database] +``` ## 2. Ajusta PageTop diff --git a/doc/v0.6/es/src/how-to/cron.md b/doc/v0.6/es/src/how-to/cron.md new file mode 100644 index 0000000..fdf6009 --- /dev/null +++ b/doc/v0.6/es/src/how-to/cron.md @@ -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 { + 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 { + vec![&pagetop_cron::Cron] + } + + fn actions(&self) -> Vec { + 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 { + vec![&pagetop_cron::Cron] + } + + fn actions(&self) -> Vec { + actions![DeclareCronJobs::new(declare_jobs)] + } + + fn configure_router(&self, router: Router) -> Router { + router.route("/", web::get(home)) + } +} + +async fn home(request: HttpRequest) -> Result { + 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 { +# vec![&pagetop_cron::Cron] +# } +# fn actions(&self) -> Vec { +# 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. diff --git a/doc/v0.6/es/src/how-to/deployment.md b/doc/v0.6/es/src/how-to/deployment.md index aa0fcfa..c37196d 100644 --- a/doc/v0.6/es/src/how-to/deployment.md +++ b/doc/v0.6/es/src/how-to/deployment.md @@ -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___` (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). diff --git a/doc/v0.6/es/src/how-to/extensions.md b/doc/v0.6/es/src/how-to/extensions.md index db94b38..ad3fe29 100644 --- a/doc/v0.6/es/src/how-to/extensions.md +++ b/doc/v0.6/es/src/how-to/extensions.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: diff --git a/doc/v0.6/es/src/how-to/forms.md b/doc/v0.6/es/src/how-to/forms.md index acbfbfb..ea388cc 100644 --- a/doc/v0.6/es/src/how-to/forms.md +++ b/doc/v0.6/es/src/how-to/forms.md @@ -109,7 +109,6 @@ struct ContactData { async fn show(request: HttpRequest) -> Result { 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 { 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 diff --git a/doc/v0.6/es/src/how-to/htmx-responses.md b/doc/v0.6/es/src/how-to/htmx-responses.md index eebe819..f5756e6 100644 --- a/doc/v0.6/es/src/how-to/htmx-responses.md +++ b/doc/v0.6/es/src/how-to/htmx-responses.md @@ -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 | diff --git a/doc/v0.6/es/src/how-to/pages.md b/doc/v0.6/es/src/how-to/pages.md index 170004f..6d9126e 100644 --- a/doc/v0.6/es/src/how-to/pages.md +++ b/doc/v0.6/es/src/how-to/pages.md @@ -52,6 +52,9 @@ async fn news(request: HttpRequest) -> Result { } ``` +`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). diff --git a/doc/v0.6/es/src/how-to/themes.md b/doc/v0.6/es/src/how-to/themes.md index 531456c..4d3c7b9 100644 --- a/doc/v0.6/es/src/how-to/themes.md +++ b/doc/v0.6/es/src/how-to/themes.md @@ -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 diff --git a/doc/v0.6/es/src/how-to/users.md b/doc/v0.6/es/src/how-to/users.md index 5d72cac..a38bac6 100644 --- a/doc/v0.6/es/src/how-to/users.md +++ b/doc/v0.6/es/src/how-to/users.md @@ -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 " +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 { require_permission(&request, &BoardPermission::PostNotices)?; @@ -185,7 +257,7 @@ async fn new_notice(request: HttpRequest) -> Result { # #[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 { 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(), } } diff --git a/doc/v0.6/es/src/reference/cheatsheet.md b/doc/v0.6/es/src/reference/cheatsheet.md index c1f4c42..1cb5ce5 100644 --- a/doc/v0.6/es/src/reference/cheatsheet.md +++ b/doc/v0.6/es/src/reference/cheatsheet.md @@ -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 { 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 diff --git a/doc/v0.6/es/src/reference/components.md b/doc/v0.6/es/src/reference/components.md index 8389418..dcf3373 100644 --- a/doc/v0.6/es/src/reference/components.md +++ b/doc/v0.6/es/src/reference/components.md @@ -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()` | diff --git a/doc/v0.6/es/src/reference/configuration.md b/doc/v0.6/es/src/reference/configuration.md index 44cfe59..dc1d726 100644 --- a/doc/v0.6/es/src/reference/configuration.md +++ b/doc/v0.6/es/src/reference/configuration.md @@ -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___` 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 " +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 `: 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]` diff --git a/doc/v0.6/es/src/reference/extensions.md b/doc/v0.6/es/src/reference/extensions.md index 2116160..a3fd737 100644 --- a/doc/v0.6/es/src/reference/extensions.md +++ b/doc/v0.6/es/src/reference/extensions.md @@ -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 ") + .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 { + vec![&pagetop_cron::Cron] + } + + fn actions(&self) -> Vec { + 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: diff --git a/doc/v0.6/es/src/tutorials/tour.md b/doc/v0.6/es/src/tutorials/tour.md index 331c16f..679aae4 100644 --- a/doc/v0.6/es/src/tutorials/tour.md +++ b/doc/v0.6/es/src/tutorials/tour.md @@ -211,7 +211,6 @@ struct Proposal { async fn propose(request: HttpRequest) -> Result { 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 { -# 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, # ) -> Result { # 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); diff --git a/tools/doccheck/Cargo.toml b/tools/doccheck/Cargo.toml index 9b4217c..e361c5b 100644 --- a/tools/doccheck/Cargo.toml +++ b/tools/doccheck/Cargo.toml @@ -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]