# 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: ```text 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: ```text 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: ```text 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()`: ```text 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](../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** 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](rendering.md). ## 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`: ```rust 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](rendering.md). - [Si vienes de Axum](coming-from-axum.md): qué es igual y qué cambia.