📝 Doc cron, mail queue, CSRF and flash messages

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

View file

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