♻️ (pagetop): initialize() devuelve Result sin panic

`Extension::initialize()` devuelve `Result<(), BoxError>`; `BoxError` es
un nuevo alias. Si una extensión falla, `prepare()` registra el error
con sus causas, vuelca las trazas, lo repite en stderr y termina con
código 1, sin panic! ni cambiar su firma.
This commit is contained in:
Manuel Cillero 2026-10-13 00:04:04 +02:00
parent 728a5c83dc
commit d3a9be7550
14 changed files with 199 additions and 110 deletions

View file

@ -7,7 +7,7 @@ use crate::datetime::Timezone;
use crate::locale::Locale;
use crate::response::{render_error_pages, response_for_panic, route_not_found};
use crate::web::Router;
use crate::{PAGETOP_VERSION, global, trace};
use crate::{BoxError, PAGETOP_VERSION, global, trace};
use tower_http::catch_panic::CatchPanicLayer;
use tracing_appender::non_blocking::WorkerGuard;
@ -54,9 +54,13 @@ impl Application {
/// que no dependen de ninguna otra, luego las que dependen de extensiones ya habilitadas, y así
/// hasta habilitar la extensión raíz.
///
/// Es `async` porque cada extensión puede realizar operaciones asíncronas en su
/// [`initialize()`](crate::core::extension::Extension::initialize) (conexión a base de datos,
/// migraciones, semillas de datos...).
/// Es `async` porque cada extensión puede realizar operaciones asíncronas en su `initialize()`
/// (conexión a base de datos, migraciones, semillas de datos, etc.).
///
/// Si alguna extensión devuelve un error al inicializarse, detiene el arranque y termina el
/// proceso con el código de salida `1` (ver [`Extension::initialize()`]).
///
/// [`Extension::initialize()`]: crate::core::extension::Extension::initialize
pub async fn prepare(root_extension: ExtensionRef) -> Self {
Self::internal_prepare(Some(root_extension)).await
}
@ -87,12 +91,38 @@ impl Application {
// Registra las acciones de las extensiones.
extension::all::register_actions();
// Inicializa las extensiones.
extension::all::initialize_extensions().await;
// Inicializa las extensiones. Si alguna falla, detiene aquí el arranque.
if let Err((name, err)) = extension::all::initialize_extensions().await {
Self::abort_startup(tracing, name, err);
}
Self { tracing }
}
// Detiene el arranque cuando una extensión falla al inicializarse. Escribe el error, con todas
// sus causas, en las trazas y en la salida de errores, que es lo único que ve quien arranca la
// aplicación si las trazas se escriben en archivos. Vuelca las trazas antes de terminar,
// porque `process::exit()` no ejecuta los destructores.
//
// Muchos errores terminan ya con el texto de su causa (p. ej. los de SeaORM), así que se omite
// cada causa con la que ya termina el mensaje.
fn abort_startup(tracing: Option<WorkerGuard>, name: &str, err: BoxError) -> ! {
let mut message = format!("Extension \"{name}\" failed to initialize: {err}");
let mut source = err.source();
while let Some(cause) = source {
let cause_text = cause.to_string();
if !message.ends_with(&cause_text) {
message.push_str(": ");
message.push_str(&cause_text);
}
source = cause.source();
}
trace::error!("{message}");
drop(tracing);
eprintln!("{message}");
std::process::exit(1);
}
// Muestra la cabecera de arranque si está habilitada en la configuración.
fn show_banner() {
use colored::Colorize;

View file

@ -3,7 +3,7 @@ use crate::core::extension::ExtensionRef;
use crate::core::theme::ThemeRef;
use crate::core::theme::all::register_theme;
use crate::web::Router;
use crate::{config, global, serve_static_files, trace, web};
use crate::{BoxError, config, global, serve_static_files, trace, web};
use std::sync::OnceLock;
@ -131,11 +131,15 @@ pub fn load_settings() {
// **< INICIALIZA LAS EXTENSIONES >*****************************************************************
pub async fn initialize_extensions() {
/// Inicializa las extensiones en el orden en que se registraron.
///
/// Se detiene en la primera que falle y devuelve su nombre corto junto con el error.
pub async fn initialize_extensions() -> Result<(), (&'static str, BoxError)> {
trace::info!("Calling application bootstrap");
for e in EXTENSIONS.get().into_iter().flatten() {
e.initialize().await;
e.initialize().await.map_err(|err| (e.short_name(), err))?;
}
Ok(())
}
// **< CONFIGURA LAS RUTAS >************************************************************************

View file

@ -1,3 +1,4 @@
use crate::BoxError;
use crate::actions;
use crate::async_trait;
use crate::config::LoadSettings;
@ -119,16 +120,20 @@ pub trait Extension: AnyInfo + Send + Sync {
/// Inicializa la extensión durante la fase de arranque de la aplicación.
///
/// La firma extendida que se muestra es el resultado de aplicar la macro
/// [`pagetop::async_trait`](pagetop::async_trait) a la declaración del método:
/// 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) {}
/// 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 una sola vez, después de que todas las
/// dependencias se han inicializado y antes de aceptar cualquier petición HTTP.
/// 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::*;
@ -137,12 +142,18 @@ pub trait Extension: AnyInfo + Send + Sync {
///
/// #[async_trait]
/// impl Extension for MyExtension {
/// async fn initialize(&self) {
/// async fn initialize(&self) -> Result<(), BoxError> {
/// // lógica de inicialización...
/// Ok(())
/// }
/// }
/// ```
async fn initialize(&self) {}
///
/// [`pagetop::async_trait`]: pagetop::async_trait
/// [`BoxError`]: crate::BoxError
async fn initialize(&self) -> Result<(), BoxError> {
Ok(())
}
/// Devuelve los ajustes de configuración de la extensión, para cargarlos en el arranque de la
/// aplicación.

View file

@ -170,6 +170,12 @@ impl Deref for StaticResources {
}
}
/// Alias para un error cualquiera, `Box<dyn std::error::Error + Send + Sync>`.
///
/// Lo devuelve [`Extension::initialize()`](crate::core::extension::Extension::initialize) para que
/// cada extensión pueda propagar con `?` sus propios tipos de error sin convertirlos.
pub type BoxError = Box<dyn std::error::Error + Send + Sync>;
/// Alias para `Cow<'static, str>`.
///
/// Es un puntero inteligente con semántica *copy-on-write* para cadenas. Permite reutilizar

View file

@ -6,7 +6,7 @@ pub use crate::PAGETOP_VERSION;
pub use crate::{async_trait, builder_fn, builder_impl, html, main, settings, test};
pub use crate::{AutoDefault, CowStr, Getters, StaticResources, UniqueId, Weight};
pub use crate::{AutoDefault, BoxError, CowStr, Getters, StaticResources, UniqueId, Weight};
// MACROS.