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.
6.4 KiB
Arquitectura: del arranque a la respuesta
Una aplicación PageTop vive dos momentos distintos: el arranque, que ocurre una vez y prepara todo, y la petición, que ocurre miles de veces y debe ser rápida. Entender qué pasa en cada uno explica casi todas las decisiones de diseño de PageTop.
Un árbol de extensiones
Una aplicación es un árbol de extensiones. En la raíz está la tuya; de ella cuelgan las que declara como dependencias, y de esas, las suyas:
MyApp <- root extension
├── Bootsier <- theme
├── User <- accounts and permissions
│ ├── Admin
│ ├── SeaORM <- database
│ └── Htmx
└── Blog <- your feature
└── SeaORM <- the same one: each extension is registered once
Este árbol es independiente de las dependencias de Cargo.toml: Cargo decide qué se compila;
dependencies() decide qué se activa y en qué orden. Una extensión compilada pero que nadie
declara no registra rutas ni ajustes.
Separar la extensión raíz en src/lib.rs y dejar src/main.rs con lo mínimo permite usar la
aplicación como biblioteca, por ejemplo desde las pruebas:
my-app/
├── Cargo.toml
├── config/
│ ├── common.toml <- common settings
│ └── local.toml <- local settings (not versioned)
└── src/
├── lib.rs <- root extension
├── main.rs <- startup
└── locale/ <- translations
├── en-US/
└── es-ES/
El arranque
Application::prepare() sigue siempre los mismos pasos:
Application::prepare(&MyApp)
1. banner and traces [log] settles how much is traced and where
2. language and time zone the defaults of [app]
3. register extensions walks the tree: dependencies first, each one once
4. load settings every settings() section, validated
5. default theme the one in [app] theme, or Basic with a warning
6. register actions every actions(), sorted by weight
7. initialize extensions every initialize(), dependencies first
|
v
.run()
8. build the server routes + middleware + static files
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
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 contest(), sin llamar arun(): hace los pasos 1 a 8, pero ni arranca los servicios de las extensiones ni ejecuta tareas programadas por su cuenta.
La petición
Cuando llega una petición, recorre las capas que construyó run():
request
|
v
+------------------------------------------------------------+
| cross-origin check (CSRF) -> 403 for a POST, PUT... |
| from another origin |
+------------------------------------------------------------+
| static files (/static, /htmx...) -> served directly, |
| without middleware |
+------------------------------------------------------------+
| middleware of the extensions (session, current user...) |
| +------------------------------------------------------+ |
| | router -> your handler | |
| | Page::new(request) builds the Context: | |
| | language, theme, user, zone | |
| | .with_child(...) adds components, not HTML | |
| | .render() the theme lays out the page | |
| +------------------------------------------------------+ |
+------------------------------------------------------------+
|
v
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. - 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 las extensiones. Así,pagetop-userresuelve la sesión una vez y cualquier ruta sabe quién pide. - El handler es un handler de Axum normal.
Page::new(request)crea el contexto de la petición, que viajará por todos los componentes: el idioma negociado, el tema, el usuario, la zona horaria, los recursos y los mensajes.
Qué pasa dentro de render() se explica en Componentes, temas y renderizado.
Sin estado mutable compartido
Los ajustes son de sólo lectura, las acciones se registran una vez y los componentes globales
(InRegion) se clonan para cada página. Cada petición trabaja con su propio contexto y sus
propias copias: lo que un componente cambia al renderizarse no afecta a otras peticiones. El estado
que debe compartirse entre peticiones (datos, sesiones) vive en la base de datos o, si es tuyo, en
tus propias estructuras.
El preludio
Casi todo lo que necesitas está en un solo use:
use pagetop::prelude::*;
Trae los tipos principales (Extension, Page, Component, Lc...), los componentes base, las
macros (html!, include_locales!...) y accesos directos a módulos como web, trace, util o
global. Las extensiones tienen el suyo: pagetop_htmx::prelude::*, pagetop_user::prelude::*...
Siguiente
- Componentes, temas y renderizado.
- Si vienes de Axum: qué es igual y qué cambia.