From fd6030ee7d15b73c34314192613189ff4001b2a1 Mon Sep 17 00:00:00 2001 From: Manuel Cillero Date: Tue, 13 Oct 2026 01:21:34 +0200 Subject: [PATCH] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20(config):=20Ajustes=20no?= =?UTF-8?q?=20v=C3=A1lidos=20sin=20panic=20al=20arrancar?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/app.rs | 35 ++++--- src/config.rs | 50 ++++++---- src/core/extension/all.rs | 159 +++++++++++++++++++++++++----- src/core/extension/definition.rs | 8 +- tests/config.rs | 26 ++++- tests/config_duplicate_section.rs | 25 ----- 6 files changed, 217 insertions(+), 86 deletions(-) delete mode 100644 tests/config_duplicate_section.rs diff --git a/src/app.rs b/src/app.rs index 00c39ac7..ebd1cb22 100644 --- a/src/app.rs +++ b/src/app.rs @@ -2,12 +2,15 @@ mod figfont; -use crate::core::{extension, extension::ExtensionRef, theme}; +use crate::core::extension; +use crate::core::extension::ExtensionRef; +use crate::core::extension::all::StartupError; +use crate::core::theme; 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::{BoxError, PAGETOP_VERSION, global, trace}; +use crate::{PAGETOP_VERSION, global, trace}; use tower_http::catch_panic::CatchPanicLayer; use tracing_appender::non_blocking::WorkerGuard; @@ -57,9 +60,11 @@ impl Application { /// 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()`]). + /// Si los ajustes de alguna extensión no se pueden cargar o alguna extensión devuelve un error + /// al inicializarse, detiene el arranque y termina el proceso con el código de salida `1` (ver + /// [`Extension::settings()`] y [`Extension::initialize()`]). /// + /// [`Extension::settings()`]: crate::core::extension::Extension::settings /// [`Extension::initialize()`]: crate::core::extension::Extension::initialize pub async fn prepare(root_extension: ExtensionRef) -> Self { Self::internal_prepare(Some(root_extension)).await @@ -83,7 +88,9 @@ impl Application { extension::all::register_extensions(root_extension); // Carga los ajustes de las extensiones. Un error de configuración detiene aquí el arranque. - extension::all::load_settings(); + if let Err(err) = extension::all::load_settings() { + Self::abort_startup(tracing, err); + } // Inicializa el tema predeterminado, que ya puede ser el de una extensión. theme::all::init_default_theme(); @@ -92,23 +99,23 @@ impl Application { extension::all::register_actions(); // 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); + if let Err(err) = extension::all::initialize_extensions().await { + Self::abort_startup(tracing, 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. + // Detiene el arranque cuando falla la carga de los ajustes o la inicialización de una + // extensión. 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(); + fn abort_startup(tracing: Option, err: StartupError) -> ! { + let mut message = err.to_string(); + let mut source = std::error::Error::source(&err); while let Some(cause) = source { let cause_text = cause.to_string(); if !message.ends_with(&cause_text) { diff --git a/src/config.rs b/src/config.rs index 674c413d..b311a653 100644 --- a/src/config.rs +++ b/src/config.rs @@ -126,7 +126,7 @@ //! //! Los ajustes globales de PageTop están en [`global::SETTINGS`](crate::global::SETTINGS). -use crate::{trace, util}; +use crate::{AutoDefault, BoxError, trace, util}; use config::{Config, ConfigError, File, FileFormat}; use serde::de::{DeserializeOwned, IgnoredAny}; @@ -135,7 +135,7 @@ use std::collections::HashMap; use std::env; use std::ops::Deref; use std::path::PathBuf; -use std::sync::LazyLock; +use std::sync::{LazyLock, OnceLock}; // Nombre del directorio de configuración por defecto. const DEFAULT_CONFIG_DIR: &str = "config"; @@ -246,8 +246,7 @@ fn section_from(config: &Config) -> Result { /// Variable con los ajustes de una sección de la configuración. /// -/// Se declara como `static` y los ajustes se cargan al arrancar la aplicación (o, fuera de ella, en -/// el primer acceso). Como buena práctica, se declara en el módulo `config` de la extensión +/// Se declara como `static`. Como buena práctica, se declara en el módulo `config` de la extensión /// (archivo `config.rs`), junto a las estructuras de sus ajustes: /// /// ```rust,ignore @@ -264,32 +263,34 @@ fn section_from(config: &Config) -> Result { /// Las claves ausentes toman su valor por defecto, y si falta la sección entera se usan los valores /// por defecto de todos los campos. /// +/// Si la extensión devuelve la variable en [`Extension::settings()`], los ajustes se cargan al +/// arrancar y una sección que no puede deserializarse (un valor no válido o una clave desconocida) +/// detiene el arranque. Si no, se cargan en el primer acceso. +/// /// # Panics /// -/// Al cargarse, si la sección no puede deserializarse (un valor no válido o una clave desconocida), -/// con un mensaje que indica la sección y el problema. -pub struct LazySettings(LazyLock); +/// En el primer acceso a unos ajustes aún no cargados, si la sección no puede deserializarse, con +/// un mensaje que indica la sección y el problema. Ocurre si la extensión no los devuelve en +/// `Extension::settings()`, si se accede a ellos antes de cargarlos al arrancar (p. ej. desde +/// `Extension::dependencies()`) o si se usan fuera de una aplicación (p. ej. en una prueba). +/// +/// [`Extension::settings()`]: crate::core::extension::Extension::settings +#[derive(AutoDefault)] +pub struct LazySettings(OnceLock); impl LazySettings { /// Crea la variable de ajustes de la sección [`SettingsSection::SECTION`] de `T`. pub const fn new() -> Self { - Self(LazyLock::new(load::)) - } -} - -// A mano y no derivado: el `Default` de `LazyLock` usaría `T::default()` en lugar de cargar los -// ajustes de la configuración. -impl Default for LazySettings { - fn default() -> Self { - Self::new() + Self(OnceLock::new()) } } impl Deref for LazySettings { type Target = T; + #[inline] fn deref(&self) -> &T { - &self.0 + self.0.get_or_init(load::) } } @@ -302,15 +303,24 @@ impl Deref for LazySettings { /// [`Extension::settings()`](crate::core::extension::Extension::settings). pub trait LoadSettings: Sync { /// Carga los ajustes si aún no se han cargado. - fn load(&self); + /// + /// Devuelve un error si los ajustes no se pueden cargar, lo que detiene el arranque de la + /// aplicación. + fn load(&self) -> Result<(), BoxError>; /// Sección de la configuración a la que corresponden los ajustes. fn section(&self) -> &'static str; } impl LoadSettings for LazySettings { - fn load(&self) { - LazyLock::force(&self.0); + // Devuelve el error en lugar del `panic!` del primer acceso. Si otro hilo guarda antes los + // ajustes (las pruebas preparan aplicaciones en paralelo), se conservan los suyos, que son los + // mismos. + fn load(&self) -> Result<(), BoxError> { + if self.0.get().is_none() { + let _ = self.0.set(section_from::(&CONFIG_VALUES)?); + } + Ok(()) } fn section(&self) -> &'static str { diff --git a/src/core/extension/all.rs b/src/core/extension/all.rs index d34cd14f..a2f7b958 100644 --- a/src/core/extension/all.rs +++ b/src/core/extension/all.rs @@ -9,6 +9,30 @@ use std::sync::OnceLock; static EXTENSIONS: OnceLock> = OnceLock::new(); +/// Errores de las extensiones que detienen el arranque de la aplicación. +#[derive(Debug, thiserror::Error)] +pub enum StartupError { + /// Dos extensiones, o una extensión y PageTop, reclaman la misma sección de la configuración: + /// cada una la leería con su propia estructura de ajustes. + #[error("Settings section [{0}] is already claimed by PageTop or another extension")] + DuplicateSection(&'static str), + /// Los ajustes de una sección no se pueden cargar (p. ej. por un valor no válido o una clave + /// desconocida). + #[error("Invalid settings in section [{section}]")] + InvalidSettings { + section: &'static str, + #[source] + source: BoxError, + }, + /// Una extensión ha devuelto un error en su `initialize()`. + #[error("Extension \"{name}\" failed to initialize")] + Initialize { + name: &'static str, + #[source] + source: BoxError, + }, +} + // **< REGISTRO DE LAS EXTENSIONES >**************************************************************** pub fn register_extensions(root_extension: Option) { @@ -98,28 +122,25 @@ pub fn register_actions() { /// Carga los ajustes de configuración de todas las extensiones, en el orden en que se registraron. /// -/// Avisa además de las secciones de los archivos de configuración que no corresponden a PageTop ni -/// a ninguna extensión, que suelen ser erratas. -/// -/// # Panics -/// -/// Si dos extensiones, o una extensión y PageTop, reclaman la misma sección: cada una la leería con -/// su propia estructura de ajustes. -pub fn load_settings() { +/// Se detiene en el primer error: una sección reclamada por más de una extensión o unos ajustes que +/// no se pueden cargar. Si todo va bien, avisa de las secciones de los archivos de configuración +/// que no corresponden a PageTop ni a ninguna extensión, que suelen ser erratas. +pub fn load_settings() -> Result<(), StartupError> { + load_settings_of(EXTENSIONS.get().map(Vec::as_slice).unwrap_or_default()) +} + +// Separada de `load_settings()` para poder probarla sin el registro global de extensiones. +fn load_settings_of(extensions: &[ExtensionRef]) -> Result<(), StartupError> { trace::info!("Loading settings for all extensions"); let mut known: Vec<&str> = global::SECTIONS.to_vec(); - for settings in EXTENSIONS - .get() - .into_iter() - .flatten() - .filter_map(|e| e.settings()) - { + for settings in extensions.iter().filter_map(|e| e.settings()) { let section = settings.section(); - assert!( - !known.contains(§ion), - "Settings section [{section}] is claimed by more than one extension" - ); - settings.load(); + if known.contains(§ion) { + return Err(StartupError::DuplicateSection(section)); + } + settings + .load() + .map_err(|source| StartupError::InvalidSettings { section, source })?; known.push(section); } for section in config::sections() { @@ -127,17 +148,23 @@ pub fn load_settings() { trace::warn!("Unknown settings section [{section}], ignored. Check settings"); } } + Ok(()) } // **< INICIALIZA LAS EXTENSIONES >***************************************************************** /// 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)> { +/// Se detiene en la primera que falle. +pub async fn initialize_extensions() -> Result<(), StartupError> { trace::info!("Calling application bootstrap"); for e in EXTENSIONS.get().into_iter().flatten() { - e.initialize().await.map_err(|err| (e.short_name(), err))?; + e.initialize() + .await + .map_err(|source| StartupError::Initialize { + name: e.short_name(), + source, + })?; } Ok(()) } @@ -191,3 +218,91 @@ pub fn configure_static_files(router: Router) -> Router { router } + +#[cfg(test)] +mod tests { + use super::{StartupError, load_settings_of}; + use crate::config::LoadSettings; + use crate::core::extension::Extension; + use crate::{BoxError, async_trait}; + + // Settings for a given section that load fine or fail, without touching the configuration. + struct FakeSettings { + section: &'static str, + fails: bool, + } + + impl LoadSettings for FakeSettings { + fn load(&self) -> Result<(), BoxError> { + if self.fails { + Err("bad value".into()) + } else { + Ok(()) + } + } + + fn section(&self) -> &'static str { + self.section + } + } + + struct Claims(&'static FakeSettings); + + #[async_trait] + impl Extension for Claims { + fn settings(&self) -> Option<&'static dyn LoadSettings> { + Some(self.0) + } + } + + static APP: Claims = Claims(&FakeSettings { + section: "app", + fails: false, + }); + static FIRST: Claims = Claims(&FakeSettings { + section: "fake", + fails: false, + }); + static SECOND: Claims = Claims(&FakeSettings { + section: "fake", + fails: false, + }); + static BROKEN: Claims = Claims(&FakeSettings { + section: "broken", + fails: true, + }); + + #[test] + fn valid_settings_load() { + assert!(load_settings_of(&[&FIRST]).is_ok()); + } + + #[test] + fn a_section_of_pagetop_cannot_be_claimed() { + let err = load_settings_of(&[&APP]).unwrap_err(); + assert!(matches!(err, StartupError::DuplicateSection("app"))); + } + + #[test] + fn a_section_cannot_be_claimed_twice() { + let err = load_settings_of(&[&FIRST, &SECOND]).unwrap_err(); + assert!(matches!(err, StartupError::DuplicateSection("fake"))); + } + + #[test] + fn invalid_settings_stop_with_their_section_and_cause() { + let err = load_settings_of(&[&FIRST, &BROKEN]).unwrap_err(); + assert!(matches!( + err, + StartupError::InvalidSettings { + section: "broken", + .. + } + )); + assert_eq!(err.to_string(), "Invalid settings in section [broken]"); + assert_eq!( + std::error::Error::source(&err).unwrap().to_string(), + "bad value" + ); + } +} diff --git a/src/core/extension/definition.rs b/src/core/extension/definition.rs index d543693e..bc1c67dc 100644 --- a/src/core/extension/definition.rs +++ b/src/core/extension/definition.rs @@ -160,10 +160,10 @@ pub trait Extension: AnyInfo + Send + Sync { /// /// 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. 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`. + /// 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 /// diff --git a/tests/config.rs b/tests/config.rs index 9c6ab273..9013e178 100644 --- a/tests/config.rs +++ b/tests/config.rs @@ -32,8 +32,9 @@ static STARTUP_LOADED: AtomicBool = AtomicBool::new(false); struct StartupSettings; impl LoadSettings for StartupSettings { - fn load(&self) { + fn load(&self) -> Result<(), BoxError> { STARTUP_LOADED.store(true, Ordering::SeqCst); + Ok(()) } fn section(&self) -> &'static str { @@ -48,6 +49,12 @@ pub struct AbsentSettings { pub value: u8, } +// Only one of the keys of `[test]` in `config/test.toml`: the other one is unknown. +#[settings(section = "test")] +pub struct PartialTestSettings { + pub float_value: f32, +} + // `EXTENSIONS` is a global `OnceLock`: all tests in this file share the same root extension. struct SettingsExtension; @@ -113,3 +120,20 @@ async fn load_from_str_rejects_unknown_keys() { .to_string(); assert!(error.contains("string_valu")); } + +#[pagetop::test] +async fn load_reports_invalid_settings_instead_of_panicking() { + let settings = LazySettings::::new(); + let error = settings + .load() + .expect_err("unknown key accepted") + .to_string(); + assert!(error.contains("string_value"), "{error}"); +} + +#[pagetop::test] +async fn load_keeps_the_settings_it_reads() { + let settings = LazySettings::::new(); + settings.load().expect("valid settings rejected"); + assert_eq!(settings.string_value, "Modified value"); +} diff --git a/tests/config_duplicate_section.rs b/tests/config_duplicate_section.rs deleted file mode 100644 index b38ccb02..00000000 --- a/tests/config_duplicate_section.rs +++ /dev/null @@ -1,25 +0,0 @@ -use pagetop::prelude::*; - -// Settings that claim `[app]`, a section that already belongs to the global settings. -#[settings(section = "app")] -pub struct ClashingSettings { - pub name: String, -} - -static SETTINGS: LazySettings = LazySettings::new(); - -// `EXTENSIONS` is a global `OnceLock`, so this test needs its own test binary. -struct ClashingExtension; - -#[async_trait] -impl Extension for ClashingExtension { - fn settings(&self) -> Option<&'static dyn LoadSettings> { - Some(&SETTINGS) - } -} - -#[pagetop::test] -#[should_panic(expected = "Settings section [app] is claimed by more than one extension")] -async fn a_section_claimed_twice_stops_the_startup() { - let _ = Application::prepare(&ClashingExtension).await; -}