From d3a9be75506115e1a253c5493004af00900c903e Mon Sep 17 00:00:00 2001 From: Manuel Cillero Date: Tue, 13 Oct 2026 00:04:04 +0200 Subject: [PATCH] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20(pagetop):=20initialize()?= =?UTF-8?q?=20devuelve=20Result=20sin=20panic?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `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. --- Cargo.lock | 1 + examples/basic-nav.rs | 3 +- examples/basic-navbar.rs | 3 +- extensions/pagetop-admin/src/lib.rs | 5 +- extensions/pagetop-seaorm/Cargo.toml | 1 + extensions/pagetop-seaorm/README.md | 5 +- extensions/pagetop-seaorm/src/lib.rs | 138 +++++++++++++-------- extensions/pagetop-seaorm/src/migration.rs | 63 +++++----- extensions/pagetop-user/src/lib.rs | 5 +- src/app.rs | 42 ++++++- src/core/extension/all.rs | 10 +- src/core/extension/definition.rs | 25 ++-- src/lib.rs | 6 + src/prelude.rs | 2 +- 14 files changed, 199 insertions(+), 110 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 9326263b..d69da3a1 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1898,6 +1898,7 @@ dependencies = [ "sea-orm", "sea-schema", "serde", + "thiserror", "tokio", "url", ] diff --git a/examples/basic-nav.rs b/examples/basic-nav.rs index 8fc37f94..ba875b57 100644 --- a/examples/basic-nav.rs +++ b/examples/basic-nav.rs @@ -8,7 +8,7 @@ impl Extension for NavDemo { vec![&pagetop::base::extension::Welcome] } - async fn initialize(&self) { + async fn initialize(&self) -> Result<(), BoxError> { let main_nav = Nav::new() .with_item(nav::Item::link(Lc::n("Home"), "/")) .with_item(nav::Item::link_blank( @@ -37,6 +37,7 @@ impl Extension for NavDemo { InRegion::Global(&CoreRegions::Header).add(main_nav); InRegion::Global(&CoreRegions::Aside).add(user_menu); + Ok(()) } } diff --git a/examples/basic-navbar.rs b/examples/basic-navbar.rs index ef4813aa..544d3d44 100644 --- a/examples/basic-navbar.rs +++ b/examples/basic-navbar.rs @@ -13,7 +13,7 @@ impl Extension for NavbarDemo { ] } - async fn initialize(&self) { + async fn initialize(&self) -> Result<(), BoxError> { let brand = Brand::new() .with_image(image::Source::logo(PageTopSvg::Color)) .with_title(Lc::n("PageTop")) @@ -46,6 +46,7 @@ impl Extension for NavbarDemo { let navbar = Navbar::brand_left(brand).with_item(navbar::Item::nav(main_nav)); InRegion::Global(&CoreRegions::Header).add(navbar); + Ok(()) } } diff --git a/extensions/pagetop-admin/src/lib.rs b/extensions/pagetop-admin/src/lib.rs index e2ed8718..1c868c6a 100644 --- a/extensions/pagetop-admin/src/lib.rs +++ b/extensions/pagetop-admin/src/lib.rs @@ -158,13 +158,14 @@ impl Extension for Admin { actions![action::DeclareAdminSections::new(seed::declare_default_sections).with_weight(-99),] } - async fn initialize(&self) { - install_migrations!(m20260629_000001_create_settings); + async fn initialize(&self) -> Result<(), BoxError> { + install_migrations!(m20260629_000001_create_settings)?; registry::build(); // Región neutra del core: cualquier tema puede decidir renderizarla (o no) sin que // `pagetop-admin` dependa de ninguno en concreto (ver `CoreRegions::Aside`). InRegion::Global(&CoreRegions::Aside).add(component::AdminMenu::new()); + Ok(()) } fn configure_router(&self, router: Router) -> Router { diff --git a/extensions/pagetop-seaorm/Cargo.toml b/extensions/pagetop-seaorm/Cargo.toml index e0a32977..26016a76 100644 --- a/extensions/pagetop-seaorm/Cargo.toml +++ b/extensions/pagetop-seaorm/Cargo.toml @@ -24,5 +24,6 @@ pagetop.workspace = true sea-orm.workspace = true sea-schema.workspace = true serde.workspace = true +thiserror.workspace = true tokio.workspace = true url.workspace = true diff --git a/extensions/pagetop-seaorm/README.md b/extensions/pagetop-seaorm/README.md index 1f846891..f247a084 100644 --- a/extensions/pagetop-seaorm/README.md +++ b/extensions/pagetop-seaorm/README.md @@ -78,8 +78,9 @@ impl Extension for MyApp { ] } - async fn initialize(&self) { - install_migrations!(m20240101_000001_create_users); + async fn initialize(&self) -> Result<(), BoxError> { + install_migrations!(m20240101_000001_create_users)?; + Ok(()) } } diff --git a/extensions/pagetop-seaorm/src/lib.rs b/extensions/pagetop-seaorm/src/lib.rs index 70d05ff7..7a6ec261 100644 --- a/extensions/pagetop-seaorm/src/lib.rs +++ b/extensions/pagetop-seaorm/src/lib.rs @@ -79,8 +79,9 @@ impl Extension for MyApp { ] } - async fn initialize(&self) { - install_migrations!(m20240101_000001_create_users); + async fn initialize(&self) -> Result<(), BoxError> { + install_migrations!(m20240101_000001_create_users)?; + Ok(()) } } @@ -176,7 +177,7 @@ use pagetop::prelude::*; include_locales!(LOCALES_SEAORM); -use sea_orm::{ConnectOptions, Database, DatabaseConnection}; +use sea_orm::{ConnectOptions, Database, DatabaseConnection, DbErr}; use url::Url; use std::sync::OnceLock; @@ -189,6 +190,30 @@ pub mod migration; static DBCONN: OnceLock = OnceLock::new(); +/// Errores que detienen el arranque de la aplicación al conectar con la base de datos o al aplicar +/// las migraciones. +#[derive(Debug, thiserror::Error)] +pub enum DbError { + /// No se ha configurado el motor de base de datos (`database.db_type`). + #[error("database.db_type is not configured: use \"mysql\", \"postgres\" or \"sqlite\"")] + TypeNotConfigured, + /// No se puede construir la URL de conexión con los ajustes de la sección `[database]`. + #[error("invalid database URL: check db_host and db_name in config")] + InvalidUrl, + /// No se puede conectar con la base de datos. + #[error("cannot connect to database \"{name}\"")] + Connection { + /// Nombre de la base de datos (`database.db_name`). + name: String, + /// Error devuelto al conectar. + #[source] + source: DbErr, + }, + /// Una migración, o su reversión, ha fallado. + #[error("migration failed")] + Migration(#[source] DbErr), +} + /// Implementa la extensión. pub struct SeaORM; @@ -206,57 +231,60 @@ impl Extension for SeaORM { Some(&config::SETTINGS) } - async fn initialize(&self) { - trace::info!( - "Connecting to database \"{}\" using a pool of {} connections", - &config::SETTINGS.db_name, - &config::SETTINGS.max_pool_size - ); - - let db_uri: String = match config::SETTINGS.db_type { - config::DbType::Unset => panic!( - "database.db_type is not configured: use \"mysql\", \"postgres\" or \"sqlite\"" - ), - config::DbType::Mysql | config::DbType::Postgres => { - let scheme = if matches!(config::SETTINGS.db_type, config::DbType::Mysql) { - "mysql" - } else { - "postgres" - }; - let mut tmp_uri = Url::parse(&format!( - "{}://{}/{}", - scheme, - &config::SETTINGS.db_host, - &config::SETTINGS.db_name - )) - .expect("Invalid database URL: check db_host and db_name in config"); - tmp_uri - .set_username(config::SETTINGS.db_user.as_str()) - .expect("Failed to set db_user in connection URL"); - tmp_uri - // https://github.com/launchbadge/sqlx/issues/1624 - .set_password(Some(config::SETTINGS.db_pass.as_str())) - .expect("Failed to set db_pass in connection URL"); - if let Some(port) = config::SETTINGS.db_port { - tmp_uri - .set_port(Some(port)) - .expect("Failed to set db_port in connection URL"); - } - tmp_uri.to_string() - } - config::DbType::Sqlite => { - format!("sqlite://{}", &config::SETTINGS.db_name) - } - }; - - let conn = Database::connect::({ - let mut db_opt = ConnectOptions::new(db_uri); - db_opt.max_connections(config::SETTINGS.max_pool_size); - db_opt - }) - .await - .expect("Failed to connect to database"); - - DBCONN.set(conn).expect("DBCONN already initialized"); + async fn initialize(&self) -> Result<(), BoxError> { + // Preparar la aplicación varias veces en el mismo proceso (las pruebas lo hacen) reutiliza + // la conexión ya abierta. + if DBCONN.get().is_none() { + let conn = connect().await?; + // Si otra preparación simultánea se adelanta, se queda la suya y se descarta ésta. + let _ = DBCONN.set(conn); + } + Ok(()) } } + +// Abre el pool de conexiones con los ajustes de la sección `[database]`. +async fn connect() -> Result { + let settings = &*config::SETTINGS; + let db_uri: String = match settings.db_type { + config::DbType::Unset => return Err(DbError::TypeNotConfigured), + config::DbType::Mysql | config::DbType::Postgres => { + let scheme = if matches!(settings.db_type, config::DbType::Mysql) { + "mysql" + } else { + "postgres" + }; + let mut uri = Url::parse(&format!( + "{}://{}/{}", + scheme, settings.db_host, settings.db_name + )) + .map_err(|_| DbError::InvalidUrl)?; + // Sin servidor en la URL (p. ej. con `db_host` vacío) no se pueden fijar el usuario, + // la contraseña ni el puerto. + uri.set_username(&settings.db_user) + .map_err(|()| DbError::InvalidUrl)?; + // https://github.com/launchbadge/sqlx/issues/1624 + uri.set_password(Some(&settings.db_pass)) + .map_err(|()| DbError::InvalidUrl)?; + if let Some(port) = settings.db_port { + uri.set_port(Some(port)).map_err(|()| DbError::InvalidUrl)?; + } + uri.to_string() + } + config::DbType::Sqlite => format!("sqlite://{}", settings.db_name), + }; + + trace::info!( + "Connecting to database \"{}\" using a pool of {} connections", + settings.db_name, + settings.max_pool_size + ); + let mut options = ConnectOptions::new(db_uri); + options.max_connections(settings.max_pool_size); + Database::connect(options) + .await + .map_err(|source| DbError::Connection { + name: settings.db_name.clone(), + source, + }) +} diff --git a/extensions/pagetop-seaorm/src/migration.rs b/extensions/pagetop-seaorm/src/migration.rs index 412426aa..2ce8f649 100644 --- a/extensions/pagetop-seaorm/src/migration.rs +++ b/extensions/pagetop-seaorm/src/migration.rs @@ -162,6 +162,8 @@ pub use sea_orm::sea_query::*; use pagetop::core::TypeInfo; +use crate::DbError; + impl MigrationName for M { fn name(&self) -> &str { // Extrae el módulo contenedor, descartando el segmento final "Migration". @@ -181,30 +183,27 @@ pub type MigrationItem = Box; pub trait MigratorBase { /// Ejecuta las migraciones pendientes en orden ascendente. /// - /// Provoca un `panic!` si alguna migración falla, evitando que la aplicación arranque con un - /// esquema de base de datos inconsistente. - async fn run_up(); + /// Devuelve [`DbError::Migration`] si alguna migración falla. Propagado desde + /// [`Extension::initialize()`](pagetop::core::extension::Extension::initialize), detiene el + /// arranque y evita que la aplicación funcione con un esquema de base de datos inconsistente. + async fn run_up() -> Result<(), DbError>; /// Revierte todas las migraciones en orden descendente. /// - /// Provoca un `panic!` si alguna reversión falla. - async fn run_down(); + /// Devuelve [`DbError::Migration`] si alguna reversión falla. + async fn run_down() -> Result<(), DbError>; } #[pagetop::async_trait] impl MigratorBase for M { - async fn run_up() { + async fn run_up() -> Result<(), DbError> { let conn = SchemaManagerConnection::Connection(super::db::dbconn()); - if let Err(e) = Self::up(conn, None).await { - panic!("Migration upgrade failed: {e}"); - } + Self::up(conn, None).await.map_err(DbError::Migration) } - async fn run_down() { + async fn run_down() -> Result<(), DbError> { let conn = SchemaManagerConnection::Connection(super::db::dbconn()); - if let Err(e) = Self::down(conn, None).await { - panic!("Migration downgrade failed: {e}"); - } + Self::down(conn, None).await.map_err(DbError::Migration) } } @@ -214,6 +213,9 @@ impl MigratorBase for M { /// registrados en la tabla `seaql_migrations`. Se invoca habitualmente desde /// [`Extension::initialize`](pagetop::core::extension::Extension::initialize). /// +/// Devuelve `Result<(), DbError>`: con `?`, una migración que falla ([`DbError::Migration`]) +/// detiene el arranque de la aplicación. +/// /// **Requisito:** cada módulo de migración debe declararse como submódulo público bajo un módulo /// `migration` accesible desde el punto de llamada, y exportar `pub struct Migration` que /// implemente [`MigrationTrait`]. El macro genera rutas de la forma @@ -231,11 +233,12 @@ impl MigratorBase for M { /// /// #[async_trait] /// impl Extension for MyExt { -/// async fn initialize(&self) { +/// async fn initialize(&self) -> Result<(), BoxError> { /// install_migrations!( /// m20240101_000001_create_users, /// m20240115_000002_add_email_index, -/// ); +/// )?; +/// Ok(()) /// } /// } /// ``` @@ -254,31 +257,31 @@ macro_rules! install_migrations { m } } - Migrator::run_up().await; + Migrator::run_up().await }}; } /// Revierte las migraciones de una extensión en orden inverso al de su aplicación. /// -/// Ejecuta el método `down` de cada migración indicada. Si el método `down` de alguna migración -/// devuelve un error, provoca un `panic!`. Complementario a -/// [`install_migrations!`](crate::install_migrations). +/// Ejecuta el método `down` de cada migración indicada y devuelve `Result<(), DbError>`. Si el +/// método `down` de alguna migración devuelve un error, devuelve [`DbError::Migration`]. +/// Complementario a [`install_migrations!`](crate::install_migrations). /// /// **Requisito:** los módulos de migración deben declararse como en /// [`install_migrations!`](crate::install_migrations). Todos los módulos indicados **deben -/// implementar `down`**; la implementación por defecto devuelve error, lo que provoca un pánico en -/// `run_down`. +/// implementar `down`**; la implementación por defecto devuelve un error. /// /// En `src/lib.rs`: /// ```rust,ignore -/// #[async_trait] -/// impl Extension for MyExt { -/// async fn uninitialize(&self) { -/// uninstall_migrations!( -/// m20240101_000001_create_users, -/// m20240115_000002_add_email_index, -/// ); -/// } +/// use pagetop_seaorm::DbError; +/// +/// mod migration; +/// +/// async fn reset_schema() -> Result<(), DbError> { +/// uninstall_migrations!( +/// m20240101_000001_create_users, +/// m20240115_000002_add_email_index, +/// ) /// } /// ``` #[macro_export] @@ -296,6 +299,6 @@ macro_rules! uninstall_migrations { m } } - Migrator::run_down().await; + Migrator::run_down().await }}; } diff --git a/extensions/pagetop-user/src/lib.rs b/extensions/pagetop-user/src/lib.rs index 1357fbaa..4a487bbf 100644 --- a/extensions/pagetop-user/src/lib.rs +++ b/extensions/pagetop-user/src/lib.rs @@ -239,7 +239,7 @@ impl Extension for User { ] } - async fn initialize(&self) { + async fn initialize(&self) -> Result<(), BoxError> { install_migrations!( m20260629_000001_create_users, m20260629_000002_create_roles, @@ -247,11 +247,12 @@ impl Extension for User { m20260629_000004_create_role_permissions, m20260629_000005_create_sessions, m20260629_000006_create_user_tokens, - ); + )?; permission::build_registry(); auth::seed_initial_data().await; #[cfg(feature = "demo-data")] demo::seed_demo_data().await; + Ok(()) } fn configure_router(&self, router: Router) -> Router { diff --git a/src/app.rs b/src/app.rs index f52f3933..00c39ac7 100644 --- a/src/app.rs +++ b/src/app.rs @@ -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, 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; diff --git a/src/core/extension/all.rs b/src/core/extension/all.rs index 35e309a4..d34cd14f 100644 --- a/src/core/extension/all.rs +++ b/src/core/extension/all.rs @@ -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 >************************************************************************ diff --git a/src/core/extension/definition.rs b/src/core/extension/definition.rs index c9a25513..d543693e 100644 --- a/src/core/extension/definition.rs +++ b/src/core/extension/definition.rs @@ -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. diff --git a/src/lib.rs b/src/lib.rs index 5fbb2e31..798152fa 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -170,6 +170,12 @@ impl Deref for StaticResources { } } +/// Alias para un error cualquiera, `Box`. +/// +/// 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; + /// Alias para `Cow<'static, str>`. /// /// Es un puntero inteligente con semántica *copy-on-write* para cadenas. Permite reutilizar diff --git a/src/prelude.rs b/src/prelude.rs index 393a4349..e7c7a152 100644 --- a/src/prelude.rs +++ b/src/prelude.rs @@ -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.