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 { /// Some(&Self) /// } /// } /// /// #[async_trait] /// impl Theme for MyTheme {} /// ``` fn theme(&self) -> Option { 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 { /// vec![&Database] /// } /// } /// ``` fn dependencies(&self) -> Vec { 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 { 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;