♻️ (config): Ajustes no válidos sin panic al arrancar
This commit is contained in:
parent
79655932d0
commit
fd6030ee7d
6 changed files with 217 additions and 86 deletions
35
src/app.rs
35
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<WorkerGuard>, name: &str, err: BoxError) -> ! {
|
||||
let mut message = format!("Extension \"{name}\" failed to initialize: {err}");
|
||||
let mut source = err.source();
|
||||
fn abort_startup(tracing: Option<WorkerGuard>, 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) {
|
||||
|
|
|
|||
|
|
@ -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<T: SettingsSection>(config: &Config) -> Result<T, ConfigError> {
|
|||
|
||||
/// 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<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
|
||||
/// 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<T: SettingsSection>(LazyLock<T>);
|
||||
/// 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<T: SettingsSection>(OnceLock<T>);
|
||||
|
||||
impl<T: SettingsSection> LazySettings<T> {
|
||||
/// Crea la variable de ajustes de la sección [`SettingsSection::SECTION`] de `T`.
|
||||
pub const fn new() -> Self {
|
||||
Self(LazyLock::new(load::<T>))
|
||||
}
|
||||
}
|
||||
|
||||
// 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()
|
||||
Self(OnceLock::new())
|
||||
}
|
||||
}
|
||||
|
||||
impl<T: SettingsSection> Deref for LazySettings<T> {
|
||||
type Target = T;
|
||||
|
||||
#[inline]
|
||||
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).
|
||||
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<T: SettingsSection> LoadSettings for LazySettings<T> {
|
||||
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::<T>(&CONFIG_VALUES)?);
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn section(&self) -> &'static str {
|
||||
|
|
|
|||
|
|
@ -9,6 +9,30 @@ use std::sync::OnceLock;
|
|||
|
||||
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 >****************************************************************
|
||||
|
||||
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.
|
||||
///
|
||||
/// 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"
|
||||
);
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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
|
||||
///
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue