pagetop-website/doc/v0.6/es/src/explanation/architecture.md
Manuel Cillero 4e007feec8 📝 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.
2026-11-02 14:46:28 +01:00

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

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-user resuelve 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