pagetop/src/core/extension/definition.rs
Manuel Cillero ab2677be44 ✨ (web): Exige el acceso de cada ruta al montarla
`configure_router()` recibe Routes, que no monta ninguna ruta sin su
Access: `route()`, `public_route()` y `admin_route()`, que toma el
permiso de la página del panel de la que cuelga.

Una ruta del panel montada de otra forma impide arrancar.

`configure_middleware()` recibe Layers y `configure_static_files()`
recibe StaticFiles, siempre públicos.
2026-11-07 13:52:04 +01:00

397 lines
16 KiB
Rust

use crate::BoxError;
use crate::actions;
use crate::async_trait;
use crate::config::LoadSettings;
use crate::core::AnyInfo;
use crate::core::action::ActionBox;
use crate::core::theme::ThemeRef;
use crate::locale::Lc;
use crate::web::{Layers, Routes, StaticFiles};
/// Interfaz común que debe implementar cualquier extensión de PageTop.
///
/// Este trait es fácil de implementar, basta con declarar una estructura sin campos para la
/// extensión y sobrescribir los métodos que sean necesarios. Por ejemplo:
///
/// ```rust,no_run
/// # use pagetop::prelude::*;
/// pub struct MyExtension;
///
/// #[async_trait]
/// impl Extension for MyExtension {
/// fn name(&self) -> Lc {
/// Lc::n("My Extension")
/// }
///
/// fn description(&self) -> Lc {
/// Lc::n("Does something useful")
/// }
/// }
/// ```
#[async_trait]
pub trait Extension: AnyInfo + Send + Sync {
/// Nombre de la extensión como *texto localizado* legible para el usuario.
///
/// Predeterminado por el [`short_name()`](AnyInfo::short_name) del tipo asociado a la
/// extensión.
fn name(&self) -> Lc {
Lc::n(self.short_name())
}
/// Descripción corta de la extensión como *texto localizado* para paneles, listados, etc.
///
/// Por defecto devuelve un valor vacío (`Lc::default()`).
fn description(&self) -> Lc {
Lc::default()
}
/// Devuelve una referencia a esta misma extensión cuando actúa como un tema.
///
/// Para ello, la implementación concreta debe ser una extensión que también implemente
/// [`Theme`](crate::core::theme::Theme). Por defecto, asume que la extensión no es un tema y
/// devuelve `None`.
///
/// # Ejemplo
///
/// ```rust,no_run
/// # use pagetop::prelude::*;
/// pub struct MyTheme;
///
/// #[async_trait]
/// impl Extension for MyTheme {
/// fn theme(&self) -> Option<ThemeRef> {
/// Some(&Self)
/// }
/// }
///
/// #[async_trait]
/// impl Theme for MyTheme {}
/// ```
fn theme(&self) -> Option<ThemeRef> {
None
}
/// Extensiones que deben inicializarse **antes** de esta.
///
/// PageTop usa este método para construir un grafo de dependencias en tiempo de ejecución entre
/// extensiones. Garantiza que todas las extensiones requeridas están presentes y se inicializan
/// en el orden apropiado, es decir, las dependencias siempre antes que la extensión que las
/// declara.
///
/// Esta declaración es independiente de las dependencias en `Cargo.toml`, donde Rust gestiona
/// las dependencias de los *crates* en tiempo de compilación.
///
/// # Ejemplo
///
/// ```rust,no_run
/// # use pagetop::prelude::*;
/// # pub struct Database;
/// # #[async_trait]
/// # impl Extension for Database {}
/// pub struct MyApp;
///
/// #[async_trait]
/// impl Extension for MyApp {
/// fn dependencies(&self) -> Vec<ExtensionRef> {
/// vec![&Database]
/// }
/// }
/// ```
fn dependencies(&self) -> Vec<ExtensionRef> {
vec![]
}
/// Devuelve la lista de acciones que la extensión registra.
///
/// Estas [acciones] se despachan por orden de registro o por [peso] (ver [`actions!`]),
/// permitiendo personalizar el comportamiento de la aplicación en puntos específicos.
///
/// PageTop lo invoca una sola vez por proceso, al registrar las extensiones y antes de
/// [`initialize()`]. La lista queda fija a partir de ahí y no es posible añadir acciones más
/// tarde.
///
/// [acciones]: crate::core::action
/// [peso]: crate::Weight
/// [`actions!`]: crate::actions
/// [`initialize()`]: Self::initialize
fn actions(&self) -> Vec<ActionBox> {
actions![]
}
/// Inicializa la extensión durante la fase de arranque de la aplicación.
///
/// La firma extendida que muestra este método es el resultado de aplicar la macro
/// [`pagetop::async_trait`] a la declaración:
///
/// ```text
/// async fn initialize(&self) -> Result<(), BoxError> { Ok(()) }
/// ```
///
/// Solo es necesario sobrescribir este método **cuando la extensión necesita ejecutar alguna
/// lógica de inicialización**. PageTop lo invoca después de que todas las dependencias se han
/// inicializado y antes de aceptar cualquier petición HTTP.
///
/// Si devuelve un error, el arranque se detiene: PageTop lo registra en las trazas junto con
/// sus causas, lo muestra en la salida de errores y termina el proceso con el código de salida
/// `1`. El tipo [`BoxError`] permite propagar con `?` cualquier tipo de error.
///
/// ```rust,no_run
/// use pagetop::prelude::*;
///
/// pub struct MyExtension;
///
/// #[async_trait]
/// impl Extension for MyExtension {
/// async fn initialize(&self) -> Result<(), BoxError> {
/// // lógica de inicialización...
/// Ok(())
/// }
/// }
/// ```
///
/// [`pagetop::async_trait`]: pagetop::async_trait
/// [`BoxError`]: crate::BoxError
async fn initialize(&self) -> Result<(), BoxError> {
Ok(())
}
/// Arranca los servicios propios de la extensión cuando el servidor web empieza a atender
/// peticiones.
///
/// La firma extendida, como en [`initialize()`], es el resultado de aplicar la macro
/// [`pagetop::async_trait`] a la declaración:
///
/// ```text
/// async fn start(&self) -> Result<(), BoxError> { Ok(()) }
/// ```
///
/// A diferencia de [`initialize()`], que prepara los recursos de la extensión y se ejecuta
/// cada vez que se prepara la aplicación (también en las pruebas), este método sólo lo invoca
/// [`Application::run()`], una vez enlazado el puerto del servidor y antes de atender la
/// primera petición, en el orden en que se inicializaron las extensiones. Es el lugar para
/// lanzar tareas que deben vivir mientras la aplicación está en marcha, como un planificador
/// de tareas o un proceso que vacía una cola; así no se lanzan en las pruebas, que obtienen el
/// servidor con [`Application::test()`] sin ejecutarlo.
///
/// Las tareas deben lanzarse con `tokio::spawn()` para que el método termine enseguida: el
/// servidor no atiende peticiones hasta que vuelven todas las extensiones. Si devuelve un
/// error, la aplicación se detiene igual que con un error en [`initialize()`], pero antes
/// llama a [`shutdown()`] de las extensiones que ya arrancaron, en orden inverso. No lo llama
/// en la extensión que falla: si había lanzado algo antes del error, debe detenerlo ella misma
/// antes de devolverlo.
///
/// [`initialize()`]: Self::initialize
/// [`shutdown()`]: Self::shutdown
/// [`pagetop::async_trait`]: pagetop::async_trait
/// [`Application::run()`]: crate::app::Application::run
/// [`Application::test()`]: crate::app::Application::test
async fn start(&self) -> Result<(), BoxError> {
Ok(())
}
/// Detiene de forma ordenada los servicios que la extensión lanzó en [`start()`].
///
/// La firma extendida, como en [`initialize()`], es el resultado de aplicar la macro
/// [`pagetop::async_trait`] a la declaración:
///
/// ```text
/// async fn shutdown(&self) {}
/// ```
///
/// [`Application::run()`] lo invoca cuando el servidor se detiene (con Ctrl+C o la señal
/// `SIGTERM`), una vez terminadas las peticiones en curso y antes de volcar las trazas
/// pendientes, en orden inverso al de inicialización: una extensión se detiene antes que las
/// extensiones de las que depende. También lo invoca, en las extensiones que ya arrancaron, si
/// falla el [`start()`] de otra posterior.
///
/// Es el momento de avisar a las tareas en segundo plano y de esperar, con un tiempo máximo, a
/// que terminen su trabajo. No devuelve errores: si algo falla, la extensión lo registra en las
/// trazas.
///
/// [`start()`]: Self::start
/// [`initialize()`]: Self::initialize
/// [`pagetop::async_trait`]: pagetop::async_trait
/// [`Application::run()`]: crate::app::Application::run
async fn shutdown(&self) {}
/// Devuelve los ajustes de configuración de la extensión, para cargarlos en el arranque de la
/// aplicación.
///
/// Se cargan en el orden en que se registran las extensiones y antes de llamar a
/// [`initialize()`]. Así, un error de la configuración (como un valor no válido o una clave
/// desconocida) detiene el arranque, igual que un error en [`initialize()`]. Cada extensión
/// debe usar una sección propia: si dos extensiones reclaman la misma, el arranque también se
/// detiene. Ver [`pagetop::config`] para saber cómo declarar los ajustes usando
/// [`#[settings]`](crate::settings). La implementación por defecto devuelve `None`.
///
/// # Ejemplo
///
/// ```rust,ignore
/// # use pagetop::prelude::*;
/// pub mod config;
///
/// pub struct Blog;
///
/// #[async_trait]
/// impl Extension for Blog {
/// fn settings(&self) -> Option<&'static dyn LoadSettings> {
/// Some(&config::SETTINGS)
/// }
/// }
/// ```
///
/// [`initialize()`]: Self::initialize
/// [`pagetop::config`]: crate::config
fn settings(&self) -> Option<&'static dyn LoadSettings> {
None
}
/// Registra las rutas de la extensión en el servidor web de la aplicación.
///
/// Recibe las rutas acumuladas hasta ese momento, añade las de la extensión y las devuelve. La
/// implementación por defecto las devuelve sin cambios.
///
/// Cada ruta se monta con su acceso ([`Access`]): quién puede llegar a su *handler*, que
/// PageTop comprueba antes. No hay forma de montar una sin indicarlo; una ruta pública se
/// monta con [`Routes::public_route()`], que equivale a [`Access::Public`]. Ver [`Routes`] para
/// las operaciones disponibles.
///
/// Los archivos estáticos se registran en [`configure_static_files`], donde no pasan por el
/// middleware de las extensiones.
///
/// # Ejemplos
///
/// ## Rutas con su acceso
///
/// ```rust,no_run
/// # use pagetop::prelude::*;
/// # #[derive(Clone, Copy, Debug)]
/// # enum BlogPermission { Publish }
/// # impl Permission for BlogPermission {
/// # fn key(&self) -> CowStr { "blog:publish".into() }
/// # }
/// # async fn list_posts() -> &'static str { "" }
/// # async fn view_post() -> &'static str { "" }
/// # async fn create_post() -> &'static str { "" }
/// pub struct Blog;
///
/// #[async_trait]
/// impl Extension for Blog {
/// fn configure_router(&self, routes: Routes) -> Routes {
/// let publish = Access::Permission(&BlogPermission::Publish);
/// routes
/// .public_route("/posts", web::get(list_posts))
/// .public_route("/posts/{id}", web::get(view_post))
/// .route("/posts/new", publish, web::post(create_post))
/// }
/// }
/// ```
///
/// ## Rutas agrupadas con su propio middleware
///
/// Un `Router::new()` aparte, con sus capas, se añade bajo un prefijo con
/// [`Routes::nest()`]: sus capas sólo envuelven sus rutas, y todas comparten el mismo acceso.
///
/// ```rust,ignore
/// # use pagetop::prelude::*;
/// pub struct Api;
///
/// #[async_trait]
/// impl Extension for Api {
/// fn configure_router(&self, routes: Routes) -> Routes {
/// let api = Router::new()
/// .route("/data", web::get(get_data))
/// .layer(api_key_layer());
/// routes.nest("/api", Access::Public, api)
/// }
/// }
/// ```
///
/// Para el middleware que deba cubrir las rutas de **todas** las extensiones, usar
/// [`configure_middleware`].
///
/// [`Access`]: crate::auth::Access
/// [`Access::Public`]: crate::auth::Access::Public
/// [`Routes`]: crate::web::Routes
/// [`Routes::public_route()`]: crate::web::Routes::public_route
/// [`Routes::nest()`]: crate::web::Routes::nest
/// [`configure_static_files`]: Self::configure_static_files
/// [`configure_middleware`]: Self::configure_middleware
fn configure_router(&self, routes: Routes) -> Routes {
routes
}
/// Añade capas de middleware globales a las rutas de la aplicación.
///
/// Se invoca **después** de que todas las extensiones hayan registrado sus rutas con
/// [`configure_router`](Self::configure_router), de modo que las capas añadidas aquí se aplican
/// a **todas** esas rutas, independientemente del orden de las extensiones. **No** se aplican a
/// los archivos estáticos de [`configure_static_files`](Self::configure_static_files), que se
/// registran después.
///
/// Usar este método cuando el middleware deba interceptar todas las peticiones a rutas de la
/// aplicación (p. ej. resolución de sesión, autenticación, etc.). Una capa que deba cubrir
/// también los archivos estáticos (p. ej. ciertas cabeceras de seguridad) no puede añadirse
/// aquí; una alternativa es aplicarla en el proxy inverso.
///
/// # Ejemplo
///
/// ```rust,no_run
/// # use pagetop::prelude::*;
/// # async fn session_middleware(req: web::Request, next: web::middleware::Next) -> Response {
/// # next.run(req).await
/// # }
/// pub struct MyAuth;
///
/// #[async_trait]
/// impl Extension for MyAuth {
/// fn configure_middleware(&self, layers: Layers) -> Layers {
/// layers.layer(web::middleware::from_fn(session_middleware))
/// }
/// }
/// ```
///
/// Sólo admite capas ([`Layers`](crate::web::Layers)): las rutas se registran en
/// [`configure_router`](Self::configure_router), con su acceso.
fn configure_middleware(&self, layers: Layers) -> Layers {
layers
}
/// Registra los archivos estáticos de la extensión (hojas de estilo, *scripts*, fuentes,
/// imágenes, etc.) en el servidor web de la aplicación.
///
/// Es un paso aparte de [`configure_router`](Self::configure_router) porque las capas de
/// middleware sólo envuelven las rutas registradas antes de añadirlas. Este método se invoca
/// **después** de [`configure_middleware`](Self::configure_middleware), así que estas rutas
/// **no** pasan por las capas de middleware de las extensiones (p. ej. la resolución de
/// sesión). Una página carga muchos recursos; sin esta separación, cada uno repetiría ese
/// trabajo, que no necesita. Por eso son siempre públicos. La implementación por defecto los
/// devuelve sin cambios.
///
/// Si algún archivo debe pasar por el middleware o exigir un acceso (p. ej. descargas que
/// requieran una sesión iniciada), se registra en [`configure_router`](Self::configure_router).
///
/// La macro [`serve_static_files!`](crate::serve_static_files) sombrea `files` internamente,
/// por lo que el parámetro no necesita `mut`. Sí es necesario devolverlo al final.
///
/// # Ejemplo
///
/// ```rust,ignore
/// # use pagetop::prelude::*;
/// pub struct MyExtension;
///
/// #[async_trait]
/// impl Extension for MyExtension {
/// fn configure_static_files(&self, files: StaticFiles) -> StaticFiles {
/// serve_static_files!(files, [assets] => "/static");
/// files
/// }
/// }
/// ```
fn configure_static_files(&self, files: StaticFiles) -> StaticFiles {
files
}
}
/// Representa una referencia a una extensión.
pub type ExtensionRef = &'static dyn Extension;