♻️ (config): Ajustes no válidos sin panic al arrancar

This commit is contained in:
Manuel Cillero 2026-10-13 01:21:34 +02:00
parent 79655932d0
commit fd6030ee7d
6 changed files with 217 additions and 86 deletions

View file

@ -2,12 +2,15 @@
mod figfont; 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::datetime::Timezone;
use crate::locale::Locale; use crate::locale::Locale;
use crate::response::{render_error_pages, response_for_panic, route_not_found}; use crate::response::{render_error_pages, response_for_panic, route_not_found};
use crate::web::Router; use crate::web::Router;
use crate::{BoxError, PAGETOP_VERSION, global, trace}; use crate::{PAGETOP_VERSION, global, trace};
use tower_http::catch_panic::CatchPanicLayer; use tower_http::catch_panic::CatchPanicLayer;
use tracing_appender::non_blocking::WorkerGuard; 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()` /// 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.). /// (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 /// Si los ajustes de alguna extensión no se pueden cargar o alguna extensión devuelve un error
/// proceso con el código de salida `1` (ver [`Extension::initialize()`]). /// 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 /// [`Extension::initialize()`]: crate::core::extension::Extension::initialize
pub async fn prepare(root_extension: ExtensionRef) -> Self { pub async fn prepare(root_extension: ExtensionRef) -> Self {
Self::internal_prepare(Some(root_extension)).await Self::internal_prepare(Some(root_extension)).await
@ -83,7 +88,9 @@ impl Application {
extension::all::register_extensions(root_extension); extension::all::register_extensions(root_extension);
// Carga los ajustes de las extensiones. Un error de configuración detiene aquí el arranque. // 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. // Inicializa el tema predeterminado, que ya puede ser el de una extensión.
theme::all::init_default_theme(); theme::all::init_default_theme();
@ -92,23 +99,23 @@ impl Application {
extension::all::register_actions(); extension::all::register_actions();
// Inicializa las extensiones. Si alguna falla, detiene aquí el arranque. // Inicializa las extensiones. Si alguna falla, detiene aquí el arranque.
if let Err((name, err)) = extension::all::initialize_extensions().await { if let Err(err) = extension::all::initialize_extensions().await {
Self::abort_startup(tracing, name, err); Self::abort_startup(tracing, err);
} }
Self { tracing } Self { tracing }
} }
// Detiene el arranque cuando una extensión falla al inicializarse. Escribe el error, con todas // Detiene el arranque cuando falla la carga de los ajustes o la inicialización de una
// sus causas, en las trazas y en la salida de errores, que es lo único que ve quien arranca la // extensión. Escribe el error, con todas sus causas, en las trazas y en la salida de errores,
// aplicación si las trazas se escriben en archivos. Vuelca las trazas antes de terminar, // que es lo único que ve quien arranca la aplicación si las trazas se escriben en archivos.
// porque `process::exit()` no ejecuta los destructores. // 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 // 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. // cada causa con la que ya termina el mensaje.
fn abort_startup(tracing: Option<WorkerGuard>, name: &str, err: BoxError) -> ! { fn abort_startup(tracing: Option<WorkerGuard>, err: StartupError) -> ! {
let mut message = format!("Extension \"{name}\" failed to initialize: {err}"); let mut message = err.to_string();
let mut source = err.source(); let mut source = std::error::Error::source(&err);
while let Some(cause) = source { while let Some(cause) = source {
let cause_text = cause.to_string(); let cause_text = cause.to_string();
if !message.ends_with(&cause_text) { if !message.ends_with(&cause_text) {

View file

@ -126,7 +126,7 @@
//! //!
//! Los ajustes globales de PageTop están en [`global::SETTINGS`](crate::global::SETTINGS). //! 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 config::{Config, ConfigError, File, FileFormat};
use serde::de::{DeserializeOwned, IgnoredAny}; use serde::de::{DeserializeOwned, IgnoredAny};
@ -135,7 +135,7 @@ use std::collections::HashMap;
use std::env; use std::env;
use std::ops::Deref; use std::ops::Deref;
use std::path::PathBuf; use std::path::PathBuf;
use std::sync::LazyLock; use std::sync::{LazyLock, OnceLock};
// Nombre del directorio de configuración por defecto. // Nombre del directorio de configuración por defecto.
const DEFAULT_CONFIG_DIR: &str = "config"; const DEFAULT_CONFIG_DIR: &str = "config";
@ -246,8 +246,7 @@ fn section_from<T: SettingsSection>(config: &Config) -> Result<T, ConfigError> {
/// Variable con los ajustes de una sección de la configuración. /// 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 /// Se declara como `static`. Como buena práctica, se declara en el módulo `config` de la extensión
/// el primer acceso). 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: /// (archivo `config.rs`), junto a las estructuras de sus ajustes:
/// ///
/// ```rust,ignore /// ```rust,ignore
@ -264,32 +263,34 @@ fn section_from<T: SettingsSection>(config: &Config) -> Result<T, ConfigError> {
/// Las claves ausentes toman su valor por defecto, y si falta la sección entera se usan los valores /// 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. /// 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 /// # Panics
/// ///
/// Al cargarse, si la sección no puede deserializarse (un valor no válido o una clave desconocida), /// En el primer acceso a unos ajustes aún no cargados, si la sección no puede deserializarse, con
/// con un mensaje que indica la sección y el problema. /// un mensaje que indica la sección y el problema. Ocurre si la extensión no los devuelve en
pub struct LazySettings<T: SettingsSection>(LazyLock<T>); /// `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<T: SettingsSection>(OnceLock<T>);
impl<T: SettingsSection> LazySettings<T> { impl<T: SettingsSection> LazySettings<T> {
/// Crea la variable de ajustes de la sección [`SettingsSection::SECTION`] de `T`. /// Crea la variable de ajustes de la sección [`SettingsSection::SECTION`] de `T`.
pub const fn new() -> Self { pub const fn new() -> Self {
Self(LazyLock::new(load::<T>)) Self(OnceLock::new())
}
}
// A mano y no derivado: el `Default` de `LazyLock` usaría `T::default()` en lugar de cargar los
// ajustes de la configuración.
impl<T: SettingsSection> Default for LazySettings<T> {
fn default() -> Self {
Self::new()
} }
} }
impl<T: SettingsSection> Deref for LazySettings<T> { impl<T: SettingsSection> Deref for LazySettings<T> {
type Target = T; type Target = T;
#[inline]
fn deref(&self) -> &T { fn deref(&self) -> &T {
&self.0 self.0.get_or_init(load::<T>)
} }
} }
@ -302,15 +303,24 @@ impl<T: SettingsSection> Deref for LazySettings<T> {
/// [`Extension::settings()`](crate::core::extension::Extension::settings). /// [`Extension::settings()`](crate::core::extension::Extension::settings).
pub trait LoadSettings: Sync { pub trait LoadSettings: Sync {
/// Carga los ajustes si aún no se han cargado. /// 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. /// Sección de la configuración a la que corresponden los ajustes.
fn section(&self) -> &'static str; fn section(&self) -> &'static str;
} }
impl<T: SettingsSection> LoadSettings for LazySettings<T> { impl<T: SettingsSection> LoadSettings for LazySettings<T> {
fn load(&self) { // Devuelve el error en lugar del `panic!` del primer acceso. Si otro hilo guarda antes los
LazyLock::force(&self.0); // 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::<T>(&CONFIG_VALUES)?);
}
Ok(())
} }
fn section(&self) -> &'static str { fn section(&self) -> &'static str {

View file

@ -9,6 +9,30 @@ use std::sync::OnceLock;
static EXTENSIONS: OnceLock<Vec<ExtensionRef>> = OnceLock::new(); static EXTENSIONS: OnceLock<Vec<ExtensionRef>> = 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 >**************************************************************** // **< REGISTRO DE LAS EXTENSIONES >****************************************************************
pub fn register_extensions(root_extension: Option<ExtensionRef>) { pub fn register_extensions(root_extension: Option<ExtensionRef>) {
@ -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. /// 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 /// Se detiene en el primer error: una sección reclamada por más de una extensión o unos ajustes que
/// a ninguna extensión, que suelen ser erratas. /// 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.
/// # Panics pub fn load_settings() -> Result<(), StartupError> {
/// load_settings_of(EXTENSIONS.get().map(Vec::as_slice).unwrap_or_default())
/// 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() { // 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"); trace::info!("Loading settings for all extensions");
let mut known: Vec<&str> = global::SECTIONS.to_vec(); let mut known: Vec<&str> = global::SECTIONS.to_vec();
for settings in EXTENSIONS for settings in extensions.iter().filter_map(|e| e.settings()) {
.get()
.into_iter()
.flatten()
.filter_map(|e| e.settings())
{
let section = settings.section(); let section = settings.section();
assert!( if known.contains(&section) {
!known.contains(&section), return Err(StartupError::DuplicateSection(section));
"Settings section [{section}] is claimed by more than one extension" }
); settings
settings.load(); .load()
.map_err(|source| StartupError::InvalidSettings { section, source })?;
known.push(section); known.push(section);
} }
for section in config::sections() { for section in config::sections() {
@ -127,17 +148,23 @@ pub fn load_settings() {
trace::warn!("Unknown settings section [{section}], ignored. Check settings"); trace::warn!("Unknown settings section [{section}], ignored. Check settings");
} }
} }
Ok(())
} }
// **< INICIALIZA LAS EXTENSIONES >***************************************************************** // **< INICIALIZA LAS EXTENSIONES >*****************************************************************
/// Inicializa las extensiones en el orden en que se registraron. /// 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. /// Se detiene en la primera que falle.
pub async fn initialize_extensions() -> Result<(), (&'static str, BoxError)> { pub async fn initialize_extensions() -> Result<(), StartupError> {
trace::info!("Calling application bootstrap"); trace::info!("Calling application bootstrap");
for e in EXTENSIONS.get().into_iter().flatten() { 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(()) Ok(())
} }
@ -191,3 +218,91 @@ pub fn configure_static_files(router: 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"
);
}
}

View file

@ -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 /// 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 /// [`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 /// desconocida) detiene el arranque, igual que un error en [`initialize()`]. Cada extensión
/// extensiones reclaman la misma, el arranque también se detiene. Ver [`pagetop::config`] para /// debe usar una sección propia: si dos extensiones reclaman la misma, el arranque también se
/// saber cómo declarar los ajustes usando [`#[settings]`](crate::settings). La implementación /// detiene. Ver [`pagetop::config`] para saber cómo declarar los ajustes usando
/// por defecto devuelve `None`. /// [`#[settings]`](crate::settings). La implementación por defecto devuelve `None`.
/// ///
/// # Ejemplo /// # Ejemplo
/// ///

View file

@ -32,8 +32,9 @@ static STARTUP_LOADED: AtomicBool = AtomicBool::new(false);
struct StartupSettings; struct StartupSettings;
impl LoadSettings for StartupSettings { impl LoadSettings for StartupSettings {
fn load(&self) { fn load(&self) -> Result<(), BoxError> {
STARTUP_LOADED.store(true, Ordering::SeqCst); STARTUP_LOADED.store(true, Ordering::SeqCst);
Ok(())
} }
fn section(&self) -> &'static str { fn section(&self) -> &'static str {
@ -48,6 +49,12 @@ pub struct AbsentSettings {
pub value: u8, 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. // `EXTENSIONS` is a global `OnceLock`: all tests in this file share the same root extension.
struct SettingsExtension; struct SettingsExtension;
@ -113,3 +120,20 @@ async fn load_from_str_rejects_unknown_keys() {
.to_string(); .to_string();
assert!(error.contains("string_valu")); assert!(error.contains("string_valu"));
} }
#[pagetop::test]
async fn load_reports_invalid_settings_instead_of_panicking() {
let settings = LazySettings::<PartialTestSettings>::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::<TestSettings>::new();
settings.load().expect("valid settings rejected");
assert_eq!(settings.string_value, "Modified value");
}

View file

@ -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<ClashingSettings> = 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;
}