`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.
397 lines
16 KiB
Rust
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;
|