From 728a5c83dc2d8bd4cfbef9c4bb4955e5ca93d391 Mon Sep 17 00:00:00 2001 From: Manuel Cillero Date: Mon, 12 Oct 2026 21:41:01 +0200 Subject: [PATCH] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20(config):=20Ajustes=20con?= =?UTF-8?q?=20#[settings]=20al=20arrancar?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Nuevo atributo `#[settings]`: valores por defecto en los campos (tipos comprobados al compilar y documentados); claves desconocidas y valores no válidos rechazados. Sustituye a `include_config!`, que se elimina. - `LazySettings::new()` declara los ajustes de una sección, y `Extension::settings()` los carga al arrancar, en orden; un error de configuración o una sección reclamada dos veces detiene el arranque. - Aviso de secciones que no corresponden a ninguna extensión. - Bootsier: [dev] bootsier_static_dir pasa a [bootsier] static_dir. --- config/reference.toml | 18 +- extensions/pagetop-bootsier/src/config.rs | 58 +-- extensions/pagetop-bootsier/src/lib.rs | 6 +- .../src/theme/bs/layout/template.rs | 4 +- extensions/pagetop-seaorm/src/config.rs | 53 +-- extensions/pagetop-seaorm/src/lib.rs | 26 +- extensions/pagetop-user/src/config.rs | 180 +++++---- extensions/pagetop-user/src/lib.rs | 4 + helpers/pagetop-macros/src/lib.rs | 44 +++ helpers/pagetop-macros/src/settings.rs | 114 ++++++ helpers/pagetop-minimal/src/lib.rs | 8 +- src/app.rs | 3 + src/auth.rs | 2 +- src/base/component/brand.rs | 2 +- src/base/component/form/select_timezone.rs | 6 +- src/config.rs | 351 +++++++++--------- src/core/component/context.rs | 2 +- src/core/extension/all.rs | 37 +- src/core/extension/definition.rs | 33 ++ src/datetime.rs | 2 +- src/datetime/definition.rs | 6 +- src/global.rs | 132 ++++--- src/global/lang_negotiation.rs | 32 +- src/global/log_format.rs | 27 +- src/global/log_rolling.rs | 29 +- src/global/startup_banner.rs | 29 +- src/global/timezone_order.rs | 37 +- src/lib.rs | 7 +- src/prelude.rs | 7 +- src/util.rs | 5 +- tests/config.rs | 117 ++++-- tests/config_duplicate_section.rs | 25 ++ 32 files changed, 918 insertions(+), 488 deletions(-) create mode 100644 helpers/pagetop-macros/src/settings.rs create mode 100644 tests/config_duplicate_section.rs diff --git a/config/reference.toml b/config/reference.toml index 86f5d693..f1d5536d 100644 --- a/config/reference.toml +++ b/config/reference.toml @@ -18,8 +18,11 @@ # Las opciones comentadas no tienen valor por defecto; se muestran con un valor de ejemplo. # # En las opciones del núcleo con valores fijos ("Full", "Nearest"...) da igual escribir el valor en -# mayúsculas o minúsculas; uno no válido se sustituye por el valor por defecto, con un aviso al -# arrancar. +# mayúsculas o minúsculas. +# +# Una clave desconocida dentro de una sección (p. ej. una errata) o un valor no válido impiden +# arrancar la aplicación, con un mensaje que indica el problema. Una sección que no corresponde a +# PageTop ni a ninguna extensión habilitada se ignora, con un aviso al arrancar. # ================================================================================================== @@ -73,10 +76,9 @@ startup_banner = "Slant" # Banner ASCII al arrancar: "Off", "Slant", [dev] pagetop_static_dir = "" # Directorio static/ de PageTop para servir sus archivos # estáticos desde disco (editables sin recompilar). Ruta - # absoluta o relativa al proyecto o al binario. Vacío -> se - # sirven los incluidos en el binario. -bootsier_static_dir = "" # Igual que el anterior, para los archivos estáticos de - # pagetop-bootsier. + # absoluta o relativa al proyecto (o, al ejecutar el binario, + # al directorio de trabajo). Vacío -> se sirven los incluidos + # en el binario. [log] enabled = true # Activa (true) o desactiva (false) las trazas. @@ -163,4 +165,6 @@ list_page_size = 20 # Filas por página en los listados de admin # **< pagetop-bootsier >**************************************************************************** [bootsier] -max_width = "1440px" # Ancho máximo de la página ("100%", "90rem", "1440px"...). +max_width = "1440px" # Ancho máximo de la página ("100%", "90rem", "1440px"...). +static_dir = "" # Directorio static/ de pagetop-bootsier para servir sus + # archivos estáticos desde disco, como pagetop_static_dir. diff --git a/extensions/pagetop-bootsier/src/config.rs b/extensions/pagetop-bootsier/src/config.rs index dede3c4c..202ec9f8 100644 --- a/extensions/pagetop-bootsier/src/config.rs +++ b/extensions/pagetop-bootsier/src/config.rs @@ -1,4 +1,4 @@ -//! Opciones de configuración del tema. +//! Ajustes de configuración de `pagetop-bootsier`. //! //! Ejemplo: //! @@ -13,46 +13,46 @@ //! # use pagetop::prelude::*; //! use pagetop_bootsier::config; //! -//! assert_eq!(config::SETTINGS.bootsier.max_width, UnitValue::Px(1440)); +//! assert_eq!(config::SETTINGS.max_width, UnitValue::RelRem(90.0)); //! ``` //! +//! Todas las opciones, con su valor por defecto, se documentan en [`BootsierSettings`]. +//! //! Consulta [`pagetop::config`] para ver cómo PageTop lee los archivos de configuración y aplica //! los valores a los ajustes. use pagetop::prelude::*; -use serde::Deserialize; +/// Ajustes de la sección `[bootsier]`, cargados al arrancar la aplicación. +pub static SETTINGS: LazySettings = LazySettings::new(); -include_config!(SETTINGS: Settings => [ - // [bootsier] - "bootsier.max_width" => "1440px", - // [dev] - "dev.bootsier_static_dir" => "", -]); - -/// Ajustes para la sección [`Bootsier`] de [`SETTINGS`]. -#[derive(Debug, Deserialize)] -pub struct Settings { - pub bootsier: Bootsier, - pub dev: Dev, -} - -/// Sección **`[bootsier]`** de la configuración. Forma parte de [`Settings`]. -#[derive(Debug, Deserialize)] -pub struct Bootsier { +/// Sección **`[bootsier]`** de la configuración. +#[settings(section = "bootsier")] +pub struct BootsierSettings { /// Ancho máximo predeterminado para la página, por ejemplo "100%" o "90rem". + #[default(UnitValue::Px(1440))] pub max_width: UnitValue, -} - -/// Sección **`[dev]`** de la configuración. Forma parte de [`Settings`]. -#[derive(Debug, Deserialize)] -pub struct Dev { /// Directorio raíz de `static/` para servir los archivos estáticos propios de Bootsier. /// - /// Si se indica una ruta válida, absoluta o relativa al directorio del proyecto o del binario - /// en ejecución, los archivos estáticos se servirán desde disco. Útil para poder modificar los - /// archivos estáticos mientras la aplicación está en ejecución, sin necesidad de recompilar. + /// Si se indica una ruta válida, absoluta o relativa al directorio del proyecto (o, al ejecutar + /// el binario, al directorio de trabajo actual), los archivos estáticos se servirán desde + /// disco. Útil durante el desarrollo para poder modificar los archivos estáticos mientras la + /// aplicación está en ejecución, sin necesidad de recompilar. /// /// Si la cadena está vacía, se ignora este ajuste. - pub bootsier_static_dir: String, + pub static_dir: String, +} + +#[cfg(test)] +mod tests { + use super::{BootsierSettings, config}; + + // `reference.toml` documents every option; with unknown keys rejected, loading it proves that + // it only documents keys that exist, with values of the right type. + const REFERENCE: &str = include_str!("../../../config/reference.toml"); + + #[test] + fn reference_toml_documents_only_existing_keys() { + config::load_from_str::(REFERENCE).unwrap(); + } } diff --git a/extensions/pagetop-bootsier/src/lib.rs b/extensions/pagetop-bootsier/src/lib.rs index 69d739f8..d5dbb656 100644 --- a/extensions/pagetop-bootsier/src/lib.rs +++ b/extensions/pagetop-bootsier/src/lib.rs @@ -106,8 +106,12 @@ impl Extension for Bootsier { Some(&Self) } + fn settings(&self) -> Option<&'static dyn LoadSettings> { + Some(&config::SETTINGS) + } + fn configure_static_files(&self, router: Router) -> Router { - let base = &config::SETTINGS.dev.bootsier_static_dir; + let base = &config::SETTINGS.static_dir; let subdir = |s: &str| { if base.is_empty() { String::new() diff --git a/extensions/pagetop-bootsier/src/theme/bs/layout/template.rs b/extensions/pagetop-bootsier/src/theme/bs/layout/template.rs index 75fb6426..8a4f7295 100644 --- a/extensions/pagetop-bootsier/src/theme/bs/layout/template.rs +++ b/extensions/pagetop-bootsier/src/theme/bs/layout/template.rs @@ -29,9 +29,7 @@ pub(crate) async fn render( async fn render_standard(cx: &mut Context) -> Markup { bs::Container::new() .with_prop(PropsOp::add_classes("container-wrapper")) - .with_width(bs::container::Width::FluidMax( - config::SETTINGS.bootsier.max_width, - )) + .with_width(bs::container::Width::FluidMax(config::SETTINGS.max_width)) .with_child(layout::Region::header()) .with_child(layout::Region::aside()) .with_child(layout::Region::default()) diff --git a/extensions/pagetop-seaorm/src/config.rs b/extensions/pagetop-seaorm/src/config.rs index e8b119fa..0dbde0de 100644 --- a/extensions/pagetop-seaorm/src/config.rs +++ b/extensions/pagetop-seaorm/src/config.rs @@ -1,4 +1,4 @@ -//! Opciones de configuración de la extensión. +//! Ajustes de configuración de `pagetop-seaorm`. //! //! Ejemplo: //! @@ -16,10 +16,13 @@ //! Uso: //! //! ```rust -//! # use pagetop_seaorm::config; -//! assert_eq!(config::SETTINGS.database.db_host, "localhost"); +//! use pagetop_seaorm::config; +//! +//! assert_eq!(config::SETTINGS.db_host, "localhost"); //! ``` //! +//! Todas las opciones, con su valor por defecto, se documentan en [`DatabaseSettings`]. +//! //! Consulta [`pagetop::config`] para ver cómo PageTop lee los archivos de configuración y aplica //! los valores a los ajustes. @@ -27,25 +30,12 @@ use pagetop::prelude::*; use serde::Deserialize; -include_config!(SETTINGS: Settings => [ - // [database] - "database.db_type" => "", - "database.db_name" => "", - "database.db_user" => "", - "database.db_pass" => "", - "database.db_host" => "localhost", - "database.max_pool_size" => 5, -]); +/// Ajustes de la sección `[database]`, cargados al arrancar la aplicación. +pub static SETTINGS: LazySettings = LazySettings::new(); -/// Ajustes para la sección [`Database`] de [`SETTINGS`]. -#[derive(Debug, Deserialize)] -pub struct Settings { - pub database: Database, -} - -/// Sección **`[database]`** de la configuración. Forma parte de [`Settings`]. -#[derive(Debug, Deserialize)] -pub struct Database { +/// Sección **`[database]`** de la configuración. +#[settings(section = "database")] +pub struct DatabaseSettings { /// Motor de base de datos. /// /// Valores aceptados: `"mysql"` (también `"mariadb"`), `"postgres"` (también `"postgresql"`) y @@ -58,20 +48,23 @@ pub struct Database { /// Contraseña para la conexión a la base de datos (para mysql/postgres). pub db_pass: String, /// Servidor de conexión a la base de datos (para mysql/postgres). + #[default = "localhost"] pub db_host: String, /// Puerto de conexión a la base de datos (para mysql/postgres). Si se omite, se usa el puerto /// predeterminado para el motor: 3306 para MySQL y 5432 para PostgreSQL. pub db_port: Option, /// Número máximo de conexiones habilitadas. + #[default = 5] pub max_pool_size: u32, } -/// Motor de base de datos. Usado en el campo [`Database::db_type`] de [`SETTINGS`]. -#[derive(Clone, Copy, Debug, Deserialize)] +/// Motor de base de datos. Usado en [`DatabaseSettings::db_type`]. +#[derive(AutoDefault, Clone, Copy, Debug, Deserialize)] #[serde(rename_all = "lowercase")] pub enum DbType { /// Valor por defecto cuando `db_type` no está configurado. En este caso la aplicación terminará /// con un error al arrancar. + #[default] #[serde(rename = "")] Unset, /// Usa el motor MySQL. Acepta también el alias `"mariadb"`. @@ -83,3 +76,17 @@ pub enum DbType { /// Usa el motor SQLite. Sqlite, } + +#[cfg(test)] +mod tests { + use super::{DatabaseSettings, config}; + + // `reference.toml` documents every option; with unknown keys rejected, loading it proves that + // it only documents keys that exist, with values of the right type. + const REFERENCE: &str = include_str!("../../../config/reference.toml"); + + #[test] + fn reference_toml_documents_only_existing_keys() { + config::load_from_str::(REFERENCE).unwrap(); + } +} diff --git a/extensions/pagetop-seaorm/src/lib.rs b/extensions/pagetop-seaorm/src/lib.rs index b0129172..70d05ff7 100644 --- a/extensions/pagetop-seaorm/src/lib.rs +++ b/extensions/pagetop-seaorm/src/lib.rs @@ -202,19 +202,23 @@ impl Extension for SeaORM { Lc::t("extension_description", &LOCALES_SEAORM) } + fn settings(&self) -> Option<&'static dyn LoadSettings> { + Some(&config::SETTINGS) + } + async fn initialize(&self) { trace::info!( "Connecting to database \"{}\" using a pool of {} connections", - &config::SETTINGS.database.db_name, - &config::SETTINGS.database.max_pool_size + &config::SETTINGS.db_name, + &config::SETTINGS.max_pool_size ); - let db_uri: String = match config::SETTINGS.database.db_type { + 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.database.db_type, config::DbType::Mysql) { + let scheme = if matches!(config::SETTINGS.db_type, config::DbType::Mysql) { "mysql" } else { "postgres" @@ -222,18 +226,18 @@ impl Extension for SeaORM { let mut tmp_uri = Url::parse(&format!( "{}://{}/{}", scheme, - &config::SETTINGS.database.db_host, - &config::SETTINGS.database.db_name + &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.database.db_user.as_str()) + .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.database.db_pass.as_str())) + .set_password(Some(config::SETTINGS.db_pass.as_str())) .expect("Failed to set db_pass in connection URL"); - if let Some(port) = config::SETTINGS.database.db_port { + if let Some(port) = config::SETTINGS.db_port { tmp_uri .set_port(Some(port)) .expect("Failed to set db_port in connection URL"); @@ -241,13 +245,13 @@ impl Extension for SeaORM { tmp_uri.to_string() } config::DbType::Sqlite => { - format!("sqlite://{}", &config::SETTINGS.database.db_name) + format!("sqlite://{}", &config::SETTINGS.db_name) } }; let conn = Database::connect::({ let mut db_opt = ConnectOptions::new(db_uri); - db_opt.max_connections(config::SETTINGS.database.max_pool_size); + db_opt.max_connections(config::SETTINGS.max_pool_size); db_opt }) .await diff --git a/extensions/pagetop-user/src/config.rs b/extensions/pagetop-user/src/config.rs index f36d987c..62b9928f 100644 --- a/extensions/pagetop-user/src/config.rs +++ b/extensions/pagetop-user/src/config.rs @@ -1,111 +1,94 @@ -//! Configuración de `pagetop-user`. +//! Ajustes de configuración de `pagetop-user`. //! -//! Todos los valores pueden sobreescribirse en los ficheros TOML de la aplicación: +//! Ejemplo: //! //! ```toml +//! [user] +//! allow_registration = false +//! +//! [user.session] +//! secure_cookie = true +//! //! [user.password] //! min_length = 10 //! ``` +//! +//! Uso: +//! +//! ```rust,no_run +//! use pagetop_user::config; +//! +//! assert_eq!(config::SETTINGS.password.min_length, 10); +//! ``` +//! +//! Todas las opciones, con su valor por defecto, se documentan en [`UserSettings`] y sus +//! subsecciones ([`SessionSettings`], [`PasswordSettings`], [`SeedSettings`] y [`AdminSettings`]). +//! +//! Consulta [`pagetop::config`] para ver cómo PageTop lee los archivos de configuración y aplica +//! los valores a los ajustes. use pagetop::prelude::*; -use serde::Deserialize; -use std::sync::LazyLock; +/// Ajustes de la sección `[user]`, cargados al arrancar la aplicación. +pub static SETTINGS: LazySettings = LazySettings::new(); -// **< CONFIG_USER >******************************************************************************** - -include_config!(CONFIG_USER: UserTopConfig => [ - // Política de registro y verificación. - "user.allow_registration" => true, - "user.require_email_verification" => false, - - // Sesiones. - "user.session.cookie_name" => "pagetop", - "user.session.secure_cookie" => false, - "user.session.idle_secs" => 7_200_i64, // 2 horas - "user.session.remember_idle_secs" => 1_209_600_i64, // 14 días - "user.session.write_interval_secs" => 60_i64, // 1 minuto - - // Anti-fuerza-bruta. - "user.max_failed_logins" => 5_i32, - "user.failed_login_window_secs" => 900_i64, // 15 min - "user.locked_for_secs" => 600_i64, // 10 min - - // Contraseñas (Argon2id). - "user.password.argon2_m_cost" => 19456_u32, - "user.password.argon2_t_cost" => 2_u32, - "user.password.argon2_p_cost" => 1_u32, - "user.password.min_length" => 8_u64, - - // Semilla del primer administrador. - "user.seed.admin_username" => "admin", - "user.seed.admin_email" => "admin@example.com", - - // Listados de administración (usuarios, roles...). - "user.admin.list_page_size" => 20_u64, - - // Modo de login. - "user.login_strict" => false, -]); - -// **< UserTopConfig >****************************************************************************** - -/// Estructura raíz para la sección `[user]` del fichero de configuración. -#[derive(Clone, Debug, Deserialize)] -pub struct UserTopConfig { - pub user: Settings, -} - -// **< SETTINGS >*********************************************************************************** - -/// Acceso directo a los ajustes de `pagetop-user` (alias de `CONFIG_USER.user`). -pub static SETTINGS: LazyLock = LazyLock::new(|| CONFIG_USER.user.clone()); - -// **< Settings >*********************************************************************************** - -/// Ajustes de la extensión `pagetop-user`, accesibles en la sección `[user]` del TOML. -#[derive(Clone, Debug, Deserialize)] -pub struct Settings { - // Política de registro y verificación. +/// Sección **`[user]`** de la configuración. +#[settings(section = "user")] +pub struct UserSettings { + /// Permite que los visitantes creen su propia cuenta. + #[default = true] pub allow_registration: bool, + /// Las cuentas nuevas quedan pendientes (*"Pending"*) en lugar de activas hasta verificar el + /// correo. + #[default = false] pub require_email_verification: bool, - // Anti-fuerza-bruta. + /// Intentos fallidos de acceso antes de bloquear la cuenta. + #[default = 5] pub max_failed_logins: i32, + /// Ventana de recuento de intentos fallidos, en segundos. Reservada: todavía no tiene efecto. + #[default = 900] pub failed_login_window_secs: i64, + /// Duración del bloqueo de la cuenta, en segundos. + #[default = 600] pub locked_for_secs: i64, - // Sesiones. - pub session: SessionConfig, + /// Sesiones, en la subsección `[user.session]`. + pub session: SessionSettings, - // Contraseñas. - pub password: PasswordConfig, + /// Contraseñas, en la subsección `[user.password]`. + pub password: PasswordSettings, - // Semilla del primer administrador. - pub seed: SeedConfig, + /// Primer administrador, en la subsección `[user.seed]`. + pub seed: SeedSettings, - // Listados de administración. - pub admin: AdminConfig, + /// Listados de administración, en la subsección `[user.admin]`. + pub admin: AdminSettings, /// Activa las medidas para dificultar que el navegador recuerde o autorrellene las /// credenciales en la pantalla de login (gestor de contraseñas, autocompletado agresivo...). + #[default = false] pub login_strict: bool, } -/// Ajustes de la sección `[user.session]`. -#[derive(Clone, Debug, Deserialize)] -pub struct SessionConfig { +/// Subsección **`[user.session]`** de la configuración. +#[settings] +pub struct SessionSettings { /// Nombre de la cookie de sesión. + #[default = "pagetop"] pub cookie_name: String, /// Marca la cookie de sesión como `Secure` (sólo HTTPS). Debe activarse en producción. + #[default = false] pub secure_cookie: bool, /// Segundos sin uso tras los que caduca una sesión iniciada sin "recordarme". El tiempo se /// cuenta desde la última petición, con la precisión que fija /// [`write_interval_secs`](Self::write_interval_secs). + #[default = 7_200] pub idle_secs: i64, /// Segundos sin uso tras los que caduca una sesión iniciada con "recordarme". El tiempo se /// cuenta desde la última petición, con la precisión que fija /// [`write_interval_secs`](Self::write_interval_secs). + #[default = 1_209_600] pub remember_idle_secs: i64, /// Segundos mínimos entre dos actualizaciones de la misma sesión en la base de datos. /// @@ -115,7 +98,7 @@ pub struct SessionConfig { /// en [`idle_secs`](Self::idle_secs) y [`remember_idle_secs`](Self::remember_idle_secs). Con /// `0` se escribe en cada petición. /// - /// El valor por defecto (60) sirve para la mayoría de aplicaciones. Conviene cambiarlo: + /// El valor por defecto sirve para la mayoría de aplicaciones. Conviene cambiarlo: /// /// - **Al alza** (p. ej. 180, como Drupal) si hay muchos usuarios simultáneos o la base de /// datos es remota o lenta, para reducir las escrituras. @@ -123,30 +106,51 @@ pub struct SessionConfig { /// adelanto no es aceptable. /// /// Debe ser siempre muy inferior a `idle_secs`. + #[default = 60] pub write_interval_secs: i64, } -/// Ajustes de la sección `[user.password]`. -#[derive(Clone, Debug, Deserialize)] -pub struct PasswordConfig { +/// Subsección **`[user.password]`** de la configuración. +/// +/// Las contraseñas se cifran con Argon2id. +#[settings] +pub struct PasswordSettings { + /// Coste de memoria de Argon2id, en KiB. Si cambia, las contraseñas se vuelven a cifrar en el + /// siguiente acceso de cada usuario. + #[default = 19_456] pub argon2_m_cost: u32, + /// Coste de tiempo de Argon2id (número de iteraciones). + #[default = 2] pub argon2_t_cost: u32, + /// Grado de paralelismo de Argon2id (número de hilos). + #[default = 1] pub argon2_p_cost: u32, + /// Longitud mínima de las contraseñas. + #[default = 8] pub min_length: usize, } -/// Ajustes de la sección `[user.seed]`. -#[derive(Clone, Debug, Deserialize)] -pub struct SeedConfig { +/// Subsección **`[user.seed]`** de la configuración. +/// +/// El primer administrador, que se crea si no existe ningún usuario. +#[settings] +pub struct SeedSettings { + /// Nombre de usuario del primer administrador. + #[default = "admin"] pub admin_username: String, + /// Correo electrónico del primer administrador. + #[default = "admin@example.com"] pub admin_email: String, + /// Contraseña del primer administrador. Sin valor, se genera una aleatoria y se muestra una + /// sola vez por la salida estándar al crearlo. pub admin_password: Option, } -/// Ajustes de la sección `[user.admin]`. -#[derive(Clone, Debug, Deserialize)] -pub struct AdminConfig { +/// Subsección **`[user.admin]`** de la configuración. +#[settings] +pub struct AdminSettings { /// Número de filas por página en los listados de administración (usuarios, roles...). + #[default = 20] pub list_page_size: u64, } @@ -163,3 +167,17 @@ pub(crate) fn user_language_applies() -> bool { pub(crate) fn user_timezone_applies() -> bool { global::SETTINGS.app.timezone_per_user } + +#[cfg(test)] +mod tests { + use super::{UserSettings, config}; + + // `reference.toml` documents every option; with unknown keys rejected, loading it proves that + // it only documents keys that exist, with values of the right type. + const REFERENCE: &str = include_str!("../../../config/reference.toml"); + + #[test] + fn reference_toml_documents_only_existing_keys() { + config::load_from_str::(REFERENCE).unwrap(); + } +} diff --git a/extensions/pagetop-user/src/lib.rs b/extensions/pagetop-user/src/lib.rs index 2069839e..1357fbaa 100644 --- a/extensions/pagetop-user/src/lib.rs +++ b/extensions/pagetop-user/src/lib.rs @@ -216,6 +216,10 @@ impl Extension for User { Lc::t("extension_description", &LOCALES_USER) } + fn settings(&self) -> Option<&'static dyn LoadSettings> { + Some(&config::SETTINGS) + } + fn dependencies(&self) -> Vec { vec![ &pagetop_admin::Admin, diff --git a/helpers/pagetop-macros/src/lib.rs b/helpers/pagetop-macros/src/lib.rs index 70c97e1a..d9f39e86 100644 --- a/helpers/pagetop-macros/src/lib.rs +++ b/helpers/pagetop-macros/src/lib.rs @@ -36,6 +36,7 @@ cada proyecto PageTop. mod builder; mod maud; +mod settings; mod smart_default; use proc_macro::TokenStream; @@ -114,6 +115,49 @@ pub fn derive_auto_default(input: TokenStream) -> TokenStream { } } +/// Macro (*attribute*) que convierte una estructura en ajustes de configuración. +/// +/// Los valores por defecto se declaran en los propios campos, con `#[default = valor]` o +/// `#[default(expresión)]`, igual que en [`AutoDefault`](macro@AutoDefault). Los campos sin valor +/// por defecto toman el de su tipo (`None` en un `Option`, o los de otra estructura de ajustes +/// anidada). +/// +/// La macro añade a la estructura: +/// +/// - `#[derive(AutoDefault, Debug, Deserialize)]`, por lo que no hay que derivarlos de nuevo +/// (hacerlo daría un error de implementación duplicada). +/// - `#[serde(default, deny_unknown_fields)]`: las claves ausentes toman su valor por defecto y una +/// clave desconocida (p. ej. una errata) es un error al cargar la configuración. +/// - Una línea con el valor por defecto en la documentación de cada campo que lo declare. +/// +/// Con `section = "nombre"` la estructura corresponde a esa sección del archivo de configuración y +/// sus ajustes se declaran con `pagetop::config::LazySettings`. Sin ella, es una subsección que +/// forma parte de otra estructura de ajustes. +/// +/// # Ejemplo +/// +/// ```rust,ignore +/// #[settings(section = "blog")] +/// pub struct BlogSettings { +/// /// Título del blog. +/// #[default = "Mi Blog"] +/// pub title: String, +/// /// Comentarios, en la subsección `[blog.comments]`. +/// pub comments: CommentsSettings, +/// } +/// +/// #[settings] +/// pub struct CommentsSettings { +/// /// Si se admiten comentarios. +/// #[default = true] +/// pub enabled: bool, +/// } +/// ``` +#[proc_macro_attribute] +pub fn settings(attr: TokenStream, item: TokenStream) -> TokenStream { + settings::expand(attr.into(), item.into()).into() +} + /// Macro (*attribute*) que asocia un método *builder* `with_` con un método `alter_`. /// /// La macro añade automáticamente un método `alter_` que permite modificar la instancia actual diff --git a/helpers/pagetop-macros/src/settings.rs b/helpers/pagetop-macros/src/settings.rs new file mode 100644 index 00000000..2c635697 --- /dev/null +++ b/helpers/pagetop-macros/src/settings.rs @@ -0,0 +1,114 @@ +use proc_macro2::TokenStream; +use quote::{ToTokens, quote}; +use syn::{Attribute, Expr, Fields, ItemStruct, LitStr, Meta}; + +pub fn expand(attr: TokenStream, item: TokenStream) -> TokenStream { + match try_expand(attr, item) { + Ok(output) => output, + Err(error) => error.to_compile_error(), + } +} + +fn try_expand(attr: TokenStream, item: TokenStream) -> syn::Result { + let mut section: Option = None; + let parser = syn::meta::parser(|meta| { + if meta.path.is_ident("section") { + let name: LitStr = meta.value()?.parse()?; + if name.value().trim().is_empty() { + return Err(syn::Error::new_spanned( + &name, + "the section name cannot be empty", + )); + } + section = Some(name); + Ok(()) + } else { + Err(meta.error("expected `section = \"...\"`")) + } + }); + syn::parse::Parser::parse2(parser, attr)?; + + let mut item: ItemStruct = syn::parse2(item)?; + if !item.generics.params.is_empty() { + return Err(syn::Error::new_spanned( + &item.generics, + "`#[settings]` does not support generic structs", + )); + } + let Fields::Named(fields) = &mut item.fields else { + return Err(syn::Error::new_spanned( + &item.ident, + "`#[settings]` requires a struct with named fields", + )); + }; + + for field in &mut fields.named { + if let Some(shown) = default_value_doc(&field.attrs)? { + let has_doc = field.attrs.iter().any(|a| a.path().is_ident("doc")); + let line = format!(" Por defecto: `{shown}`."); + if has_doc { + field.attrs.push(syn::parse_quote!(#[doc = ""])); + } + field.attrs.push(syn::parse_quote!(#[doc = #line])); + } + } + + let ident = &item.ident; + let section_impl = section.map(|section| { + quote! { + impl ::pagetop::config::SettingsSection for #ident { + const SECTION: &'static str = #section; + } + } + }); + + Ok(quote! { + #[derive(::pagetop::AutoDefault, ::core::fmt::Debug, ::pagetop::serde::Deserialize)] + #[serde(crate = "::pagetop::serde", default, deny_unknown_fields)] + #item + #section_impl + }) +} + +// Texto con el valor por defecto de un campo para su documentación, si tiene `#[default = ...]` o +// `#[default(...)]`. De una ruta (p. ej. `LogRolling::Stdout`) se muestra sólo el último segmento, +// que es el valor que se escribe en el archivo de configuración. +fn default_value_doc(attrs: &[Attribute]) -> syn::Result> { + let Some(attr) = attrs.iter().find(|a| a.path().is_ident("default")) else { + return Ok(None); + }; + let expr: Expr = match &attr.meta { + Meta::NameValue(name_value) => name_value.value.clone(), + Meta::List(list) => match list.parse_args::() { + Ok(expr) => expr, + // Formas que `AutoDefault` admite pero que no son una expresión (p. ej. `_code = ...`). + Err(_) => return Ok(None), + }, + Meta::Path(_) => return Ok(None), + }; + let shown = match &expr { + Expr::Path(path) => path + .path + .segments + .last() + .map(|segment| segment.ident.to_string()) + .unwrap_or_default(), + other => compact(&other.to_token_stream().to_string()), + }; + Ok(Some(shown)) +} + +// Quita los espacios que `quote` deja entre los elementos de una expresión (p. ej. +// `UnitValue :: Px (1440)` -> `UnitValue::Px(1440)`, o `- 1` -> `-1`). +fn compact(tokens: &str) -> String { + let compacted = tokens + .replace(" :: ", "::") + .replace(" (", "(") + .replace("( ", "(") + .replace(" )", ")") + .replace(" ,", ","); + match compacted.strip_prefix("- ") { + Some(rest) => format!("-{rest}"), + None => compacted, + } +} diff --git a/helpers/pagetop-minimal/src/lib.rs b/helpers/pagetop-minimal/src/lib.rs index 14bd4211..1d2f40bd 100644 --- a/helpers/pagetop-minimal/src/lib.rs +++ b/helpers/pagetop-minimal/src/lib.rs @@ -52,12 +52,12 @@ pub use pastey::paste; // La documentación anterior se copia en `pagetop::util::paste!` porque el *crate* original no la // define y `pagetop` no la hereda automáticamente. -/// Concatena varios fragmentos en un [`String`] reservando una sola vez la memoria del resultado. +/// Concatena varios fragmentos en un [`String`]. /// /// Acepta uno o más fragmentos que implementen [`AsRef`] (literales, `&str`, [`String`], -/// `Cow`...) y construye el resultado con la capacidad exacta, sin pasar por el formateo. Es -/// la forma preferida de componer texto a partir de fragmentos, y suele ser más rápida que -/// `format!`. +/// `Cow`...) y construye el resultado reservando la memoria una sola vez, con la capacidad +/// exacta, sin pasar por el formateo. Es la forma preferida de componer texto a partir de +/// fragmentos, y suele ser más rápida que `format!`. /// /// Cada expresión se evalúa **una sola vez**, por lo que admite llamadas como `n.to_string()` o /// cierres con efectos secundarios. Los valores que no son cadenas (números, tipos `Display`) se diff --git a/src/app.rs b/src/app.rs index f133e316..f52f3933 100644 --- a/src/app.rs +++ b/src/app.rs @@ -78,6 +78,9 @@ impl Application { // Registra las extensiones de la aplicación. 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(); + // Inicializa el tema predeterminado, que ya puede ser el de una extensión. theme::all::init_default_theme(); diff --git a/src/auth.rs b/src/auth.rs index 30161f02..6016f584 100644 --- a/src/auth.rs +++ b/src/auth.rs @@ -156,7 +156,7 @@ impl CurrentUser { /// de ese momento el renderizado del documento no vuelve a llamarlo porque usa el valor ya /// resuelto vía [`Contextual::timezone()`]. /// - /// [`global::SETTINGS.app.timezone_per_user`]: crate::global::App::timezone_per_user + /// [`global::SETTINGS.app.timezone_per_user`]: crate::global::AppSettings::timezone_per_user /// [`Context`]: crate::core::component::Context /// [`Contextual::timezone()`]: crate::core::component::Contextual::timezone pub fn timezone(&self) -> Tz { diff --git a/src/base/component/brand.rs b/src/base/component/brand.rs index 4775a80f..907a24be 100644 --- a/src/base/component/brand.rs +++ b/src/base/component/brand.rs @@ -23,7 +23,7 @@ use crate::prelude::*; /// ``` /// /// [`with_route()`]: Self::with_route -/// [`global::SETTINGS.app.name`]: crate::global::App::name +/// [`global::SETTINGS.app.name`]: crate::global::AppSettings::name #[derive(AutoDefault, Clone, Debug, Getters)] pub struct Brand { /// Devuelve identificador, clases CSS, atributos HTML y valores extra del componente. diff --git a/src/base/component/form/select_timezone.rs b/src/base/component/form/select_timezone.rs index 3a75a3ce..d3d54890 100644 --- a/src/base/component/form/select_timezone.rs +++ b/src/base/component/form/select_timezone.rs @@ -53,7 +53,7 @@ use chrono::Offset; /// /// [`TimezoneOrder::Alphabetical`]: crate::global::TimezoneOrder::Alphabetical /// [`TimezoneOrder::Listed`]: crate::global::TimezoneOrder::Listed -/// [`global::SETTINGS.app.timezone_per_user`]: crate::global::App::timezone_per_user +/// [`global::SETTINGS.app.timezone_per_user`]: crate::global::AppSettings::timezone_per_user /// [`with_utc_offset(true)`]: Self::with_utc_offset /// [`with_required(true)`]: Self::with_required /// [`with_regions()`]: Self::with_regions @@ -68,11 +68,11 @@ pub struct SelectTimezone { /// Devuelve si las etiquetas muestran el desfase actual respecto a UTC. utc_offset: bool, /// Devuelve las regiones que se ofrecen, junto a `Etc`, que se ofrece siempre; por defecto, las - /// de [`global::SETTINGS.app.timezone_regions`](crate::global::App::timezone_regions). + /// de [`global::SETTINGS.app.timezone_regions`](crate::global::AppSettings::timezone_regions). #[default(_code = "Timezone::configured_regions()")] regions: Vec, /// Devuelve el orden de las regiones; por defecto, el de - /// [`global::SETTINGS.app.timezone_order`](crate::global::App::timezone_order). + /// [`global::SETTINGS.app.timezone_order`](crate::global::AppSettings::timezone_order). #[default(_code = "global::SETTINGS.app.timezone_order")] order: global::TimezoneOrder, } diff --git a/src/config.rs b/src/config.rs index b3c66350..674c413d 100644 --- a/src/config.rs +++ b/src/config.rs @@ -54,90 +54,86 @@ //! Los archivos se combinan clave a clave en el orden anterior. Cada archivo sobrescribe a los //! anteriores sólo en las claves que define. //! -//! # Cómo añadir opciones de configuración a tu código +//! # Cómo declarar ajustes //! -//! Añade [*serde*](https://docs.rs/serde) en tu archivo *Cargo.toml* con la *feature* `derive`: +//! Cada extensión declara sus ajustes en una estructura con el atributo +//! [`#[settings]`](crate::settings), que corresponde a una sección propia del archivo de +//! configuración. Los valores por defecto se escriben en los propios campos con `#[default = ...]`, +//! así que el compilador comprueba sus tipos, y la documentación de cada campo muestra el suyo. //! -//! ```toml -//! [dependencies] -//! serde = { version = "1.0", features = ["derive"] } -//! ``` -//! -//! Y usa la macro [`include_config!`](crate::include_config) para inicializar tus ajustes en una -//! estructura con tipos seguros. Por ejemplo: +//! Lo habitual es definirlos en un archivo `config.rs` de la extensión con algo como esto: //! //! ```rust,no_run //! use pagetop::prelude::*; -//! use serde::Deserialize; //! -//! include_config!(SETTINGS: Settings => [ -//! // [myapp] -//! "myapp.name" => "Value Name", -//! "myapp.width" => 900, -//! "myapp.height" => 320, -//! ]); +//! /// Ajustes de la sección `[blog]`, cargados al arrancar la aplicación. +//! pub static SETTINGS: LazySettings = LazySettings::new(); //! -//! #[derive(Debug, Deserialize)] -//! pub struct Settings { -//! pub myapp: MyApp, +//! /// Sección **`[blog]`** de la configuración. +//! #[settings(section = "blog")] +//! pub struct BlogSettings { +//! /// Título del blog. +//! #[default = "Mi Blog"] +//! pub title: String, +//! /// Descripción opcional (sin valor por defecto: `None`). +//! pub description: Option, +//! /// Comentarios, en la subsección `[blog.comments]`. +//! pub comments: CommentsSettings, //! } //! -//! #[derive(Debug, Deserialize)] -//! pub struct MyApp { -//! pub name: String, -//! pub description: Option, -//! pub width: u16, -//! pub height: u16, +//! /// Subsección **`[blog.comments]`** de la configuración. +//! #[settings] +//! pub struct CommentsSettings { +//! /// Si se admiten comentarios. +//! #[default = true] +//! pub enabled: bool, +//! /// Número máximo de comentarios por página. +//! #[default = 20] +//! pub page_size: u32, //! } //! ``` //! -//! De esta forma estás añadiendo una nueva sección `[myapp]` a la configuración, igual que existen -//! `[app]` o `[server]` en las opciones globales de [`Settings`](crate::global::Settings). +//! [`LazySettings`] lee la sección indicada en `section`; las claves que falten toman su valor por +//! defecto, y si falta la sección entera se usan los valores por defecto de todos los campos. //! -//! Se recomienda proporcionar siempre valores por defecto o usar `Option` para los ajustes -//! opcionales. -//! -//! Los valores por defecto se declaran **sólo** en [`include_config!`](crate::include_config). -//! -//! Las estructuras de configuración no necesitan implementar `Default` (ni derivar `AutoDefault`). -//! La deserialización nunca lo usa, y declararlo duplicaría los valores en un segundo sitio que -//! puede quedar desincronizado sin que nada lo detecte. -//! -//! Los ajustes se cargan la primera vez que se accede a la variable generada. Si no pueden cargarse -//! (un archivo TOML mal formado, una clave obligatoria sin valor o un valor de tipo incorrecto), -//! ese primer acceso lanza *panic*: si ocurre al arrancar, detiene la aplicación; si ocurre dentro -//! de una petición, ésta responde con un error y cada acceso posterior vuelve a fallar. -//! -//! Las estructuras de configuración son de **sólo lectura** durante la ejecución. -//! -//! # Usando tus opciones de configuración -//! -//! Los ajustes de cada extensión y los globales de PageTop -//! ([`global::SETTINGS`](crate::global::SETTINGS)) conviven sin conflicto: cada cual vive en su -//! propia sección del TOML y pueden combinarse libremente cuando se necesiten. +//! Para que los ajustes se carguen al arrancar, la extensión los devuelve en +//! [`Extension::settings()`](crate::core::extension::Extension::settings): //! //! ```rust,ignore -//! use pagetop::prelude::*; -//! use crate::config; +//! pub mod config; //! -//! fn global_settings() { -//! println!("Nombre de la app: {}", &global::SETTINGS.app.name); -//! println!("Run mode: {}", &global::SETTINGS.app.run_mode); -//! } -//! -//! fn extension_settings() { -//! println!("{}", &config::SETTINGS.myapp.name); -//! println!("{}", &config::SETTINGS.myapp.width); +//! impl Extension for Blog { +//! fn settings(&self) -> Option<&'static dyn LoadSettings> { +//! Some(&config::SETTINGS) +//! } //! } //! ``` +//! +//! Desde cualquier parte del código se leen como `config::SETTINGS.title` o +//! `config::SETTINGS.comments.enabled`. Son de **sólo lectura** durante la ejecución. +//! +//! # Carga y errores +//! +//! PageTop carga los ajustes de todas las extensiones durante el arranque, en el orden en que se +//! registran y antes de inicializarlas. Si unos ajustes no pueden cargarse, la aplicación se +//! detiene con un mensaje que indica el problema: el archivo y la línea si un TOML está mal +//! formado, o la sección y el valor no válido o la **clave desconocida** (típicamente una errata). +//! También avisa al arrancar de las secciones de los archivos que no corresponden a PageTop ni a +//! ninguna extensión. +//! +//! Fuera de una aplicación en marcha (p. ej. en pruebas unitarias) los ajustes se cargan en el +//! primer acceso a la variable, con las mismas reglas. +//! +//! Los ajustes globales de PageTop están en [`global::SETTINGS`](crate::global::SETTINGS). use crate::{trace, util}; -use config::builder::DefaultState; -use config::{Config, ConfigBuilder, File}; +use config::{Config, ConfigError, File, FileFormat}; +use serde::de::{DeserializeOwned, IgnoredAny}; +use std::collections::HashMap; use std::env; -use std::fmt; +use std::ops::Deref; use std::path::PathBuf; use std::sync::LazyLock; @@ -147,13 +143,10 @@ const DEFAULT_CONFIG_DIR: &str = "config"; // Modo de ejecución por defecto. const DEFAULT_RUN_MODE: &str = "default"; -/// Fuentes comunes de la configuración. -/// -/// Se obtienen de los archivos TOML en el orden de carga y el modo de ejecución (`app.run_mode`). -/// -/// Es la base sobre la que [`include_config!`](crate::include_config) aplica sus valores por -/// defecto antes de deserializar. Los archivos se leen cada vez que se construye la configuración. -pub static CONFIG_VALUES: LazyLock> = LazyLock::new(|| { +// Configuración combinada de los archivos TOML en el orden de carga, más el modo de ejecución +// (`app.run_mode`). Se construye una sola vez, en el primer acceso, y sólo la leen las funciones de +// este módulo: así ningún ajuste se salta las comprobaciones de `#[settings]`. +static CONFIG_VALUES: LazyLock = LazyLock::new(|| { // CONFIG_DIR (si existe) o DEFAULT_CONFIG_DIR. Si no se puede resolver, se usa tal cual. Sólo // se avisa si CONFIG_DIR está definida: que falte el directorio predeterminado es normal en una // aplicación sin configuración propia, pero un CONFIG_DIR erróneo podría dejar la aplicación @@ -195,132 +188,132 @@ pub static CONFIG_VALUES: LazyLock> = LazyLock::new( .add_source(File::from(config_dir.join("local.toml")).required(false)) // Guarda el modo de ejecución explícitamente. .set_override("app.run_mode", rm) - .expect("Failed to set application run mode") + .and_then(|builder| builder.build()) + .unwrap_or_else(|err| panic!("Failed to read the configuration files: {err}")) }); -// Guarda el aviso de un valor no válido para la opción `key` y devuelve `default`, el valor que se -// usa en su lugar. Lo usan las opciones enumeradas de la configuración al leerse. -pub(crate) fn invalid_setting(key: &str, raw: &str, default: T) -> T { - trace::defer_warning(format!( - "Invalid value \"{raw}\" for {key}, using \"{default:?}\". Check settings" - )); - default +// Secciones del primer nivel de la configuración. +pub(crate) fn sections() -> Vec { + CONFIG_VALUES + .clone() + .try_deserialize::>() + .map(|sections| sections.into_keys().collect()) + .unwrap_or_default() } -// **< include_config! >**************************************************************************** +// **< Ajustes >************************************************************************************ -/// Declara una variable global con los ajustes de configuración. +/// Estructura de ajustes asociada a una sección del archivo de configuración. /// -/// Incluye los ajustes necesarios de la configuración, aplicando valores por defecto a las claves -/// que no definan los archivos TOML. +/// La implementa el atributo [`#[settings(section = "...")]`](crate::settings); no es necesario +/// implementarla a mano. +pub trait SettingsSection: DeserializeOwned + Default + Send + Sync + 'static { + /// Nombre de la sección en el archivo de configuración (p. ej. `"blog"` para `[blog]`). + const SECTION: &'static str; +} + +// Carga los ajustes de la sección `T::SECTION` de la configuración. Las claves ausentes toman su +// valor por defecto, y si falta la sección entera se usan los de todos los campos. Si la sección no +// puede deserializarse (un valor no válido o una clave desconocida), lanza `panic!` con un mensaje +// que indica la sección y el problema. +pub(crate) fn load() -> T { + section_from(&CONFIG_VALUES) + .unwrap_or_else(|err| panic!("Invalid settings in section [{}]: {err}", T::SECTION)) +} + +/// Carga los ajustes de la sección [`SettingsSection::SECTION`] a partir de un texto TOML, con las +/// mismas reglas que [`LazySettings`]. /// -/// # Sintaxis +/// Pensada para pruebas, p. ej. para comprobar que un archivo de configuración de referencia sólo +/// documenta claves que existen. No forma parte de la API pública. +#[doc(hidden)] +pub fn load_from_str(toml: &str) -> Result { + let config = Config::builder() + .add_source(File::from_str(toml, FileFormat::Toml)) + .build()?; + section_from(&config) +} + +// Lee la sección de `T` de una configuración; si falta entera, usa los valores por defecto. +fn section_from(config: &Config) -> Result { + match config.get::(T::SECTION) { + Err(ConfigError::NotFound(_)) => Ok(T::default()), + result => result, + } +} + +// **< LazySettings >******************************************************************************* + +/// Variable con los ajustes de una sección de la configuración. /// -/// Se declara en el código de la extensión o de la aplicación así: +/// 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 +/// (archivo `config.rs`), junto a las estructuras de sus ajustes: /// /// ```rust,ignore -/// include_config!(SETTINGS_NAME: SettingsType => [ -/// "ruta.clave" => valor, -/// // ... -/// ]); +/// pub static SETTINGS: LazySettings = LazySettings::new(); /// ``` /// -/// donde: +/// Y desde el resto del código se accede a los ajustes a través de la variable, cualificada con el +/// módulo: /// -/// * **`SETTINGS_NAME`** es el nombre de la variable global que se usará para referenciar los -/// ajustes. Se recomienda usar `SETTINGS`, aunque no es obligatorio. -/// * **`SettingsType`** es la estructura que define los tipos para deserializar la configuración. -/// Debe implementar `Deserialize` (derivable con `#[derive(Deserialize)]`). -/// * **Lista de pares** con las claves TOML que requieran valores por defecto. Siguen la notación -/// del árbol TOML, con un punto por nivel (`"blog.title"`, `"blog.comments.enabled"`...). La -/// lista se muestra además en la documentación generada de la variable, con todos los valores -/// por defecto de un vistazo. -/// -/// # Ejemplo básico -/// -/// ```rust,no_run -/// use pagetop::prelude::*; -/// use serde::Deserialize; -/// -/// include_config!(SETTINGS: BlogSettings => [ -/// // [blog] -/// "blog.title" => "Mi Blog", -/// "blog.port" => 8080, -/// ]); -/// -/// #[derive(Debug, Deserialize)] -/// pub struct BlogSettings { -/// pub blog: Blog, -/// } -/// -/// #[derive(Debug, Deserialize)] -/// pub struct Blog { -/// pub title: String, -/// pub description: Option, -/// pub port: u16, -/// } -/// -/// fn print_title() { -/// // Lectura en tiempo de ejecución. -/// println!("Título: {}", SETTINGS.blog.title); -/// } +/// ```rust,ignore +/// let title = &config::SETTINGS.title; /// ``` /// -/// # Buenas prácticas +/// 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. /// -/// * **Valores por defecto**. Declara un valor por defecto para cada clave obligatoria. Las claves -/// opcionales pueden ser `Option`. Los valores de esta lista se aplican con `set_default()` -/// antes de deserializar, y sólo en las claves que no defina ningún TOML, así que las estructuras -/// de ajustes no necesitan implementar `Default` ni derivar `AutoDefault`. Si falta una clave -/// obligatoria en los TOML y en la lista, la deserialización falla. +/// # Panics /// -/// * **Secciones únicas**. Agrupa tus claves dentro de una sección exclusiva (p. ej. `[blog]`) para -/// evitar colisiones con otras extensiones. -/// -/// * **Sólo lectura**. La variable generada es inmutable durante toda la vida del programa. Para -/// configurar distintos entornos (*dev*, *staging*, *production*) usa los archivos TOML descritos -/// en la documentación de [`config`](crate::config). -/// -/// * **Errores explícitos**. Si la configuración no puede cargarse, el primer acceso a la variable -/// lanza un `panic!` con un mensaje que nombra la estructura de ajustes y el error de origen -/// (normalmente la clave problemática). -/// -/// # Requisitos -/// -/// * Cada nivel de las claves debe coincidir con un campo (*snake case*) de la estructura de -/// ajustes o de sus estructuras anidadas. -/// * Añade `serde` con la *feature* `derive` en *Cargo.toml*: -/// -/// ```toml -/// [dependencies] -/// serde = { version = "1.0", features = ["derive"] } -/// ``` -#[macro_export] -macro_rules! include_config { - ( $SETTINGS_NAME:ident : $settings_type:ty => [ $( $k:literal => $v:expr ),* $(,)? ] ) => { - #[doc = concat!( - "Carga [`", stringify!($settings_type), "`] ", - "(y aplica **valores por defecto** en claves no definidas)." - )] - #[doc = ""] - #[doc = "Valores predeterminados que se aplican en ausencia de configuración:"] - #[doc = "```text"] - $( - #[doc = concat!($k, " = ", stringify!($v))] - )* - #[doc = "```"] - pub static $SETTINGS_NAME: std::sync::LazyLock<$settings_type> = - std::sync::LazyLock::new(|| { - let mut settings = $crate::config::CONFIG_VALUES.clone(); - $( - settings = settings.set_default($k, $v) - .expect(concat!("Failed to set default for key ", $k)); - )* - settings - .build() - .expect(concat!("Failed to build config for ", stringify!($settings_type))) - .try_deserialize::<$settings_type>() - .expect(concat!("Error parsing settings for ", stringify!($settings_type))) - }); - }; +/// 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); + +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() + } +} + +impl Deref for LazySettings { + type Target = T; + + fn deref(&self) -> &T { + &self.0 + } +} + +// **< LoadSettings >******************************************************************************* + +/// Ajustes que PageTop carga durante el arranque. +/// +/// Lo implementa [`LazySettings`] con `T` declarado con +/// [`#[settings(section = "...")]`](crate::settings), y las extensiones devuelven esa variable en +/// [`Extension::settings()`](crate::core::extension::Extension::settings). +pub trait LoadSettings: Sync { + /// Carga los ajustes si aún no se han cargado. + fn load(&self); + + /// 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); + } + + fn section(&self) -> &'static str { + T::SECTION + } } diff --git a/src/core/component/context.rs b/src/core/component/context.rs index 81259720..45ab618a 100644 --- a/src/core/component/context.rs +++ b/src/core/component/context.rs @@ -336,7 +336,7 @@ impl Context { /// [`Lc::using()`]. /// /// [`Context`]: crate::core::component::Context -/// [`global::SETTINGS.app.lang_negotiation`]: crate::global::App::lang_negotiation +/// [`global::SETTINGS.app.lang_negotiation`]: crate::global::AppSettings::lang_negotiation /// [`Lc::lookup()`]: crate::locale::Lc::lookup /// [`Lc::using()`]: crate::locale::Lc::using impl LangId for Context { diff --git a/src/core/extension/all.rs b/src/core/extension/all.rs index d98baa04..35e309a4 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::{global, serve_static_files, trace, web}; +use crate::{config, global, serve_static_files, trace, web}; use std::sync::OnceLock; @@ -94,6 +94,41 @@ pub fn register_actions() { }); } +// **< CARGA LOS AJUSTES >************************************************************************** + +/// 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() { + 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()) + { + let section = settings.section(); + assert!( + !known.contains(§ion), + "Settings section [{section}] is claimed by more than one extension" + ); + settings.load(); + known.push(section); + } + for section in config::sections() { + if !known.contains(§ion.as_str()) { + trace::warn!("Unknown settings section [{section}], ignored. Check settings"); + } + } +} + // **< INICIALIZA LAS EXTENSIONES >***************************************************************** pub async fn initialize_extensions() { diff --git a/src/core/extension/definition.rs b/src/core/extension/definition.rs index a5b43db7..c9a25513 100644 --- a/src/core/extension/definition.rs +++ b/src/core/extension/definition.rs @@ -1,5 +1,6 @@ use crate::actions; use crate::async_trait; +use crate::config::LoadSettings; use crate::core::AnyInfo; use crate::core::action::ActionBox; use crate::core::theme::ThemeRef; @@ -143,6 +144,38 @@ pub trait Extension: AnyInfo + Send + Sync { /// ``` async fn initialize(&self) {} + /// Devuelve los ajustes de configuración de la extensión, para cargarlos en el arranque de la + /// aplicación. + /// + /// 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`. + /// + /// # Ejemplo + /// + /// ```rust,ignore + /// # use pagetop::prelude::*; + /// pub mod config; + /// + /// pub struct Blog; + /// + /// #[async_trait] + /// impl Extension for Blog { + /// fn settings(&self) -> Option<&'static dyn LoadSettings> { + /// Some(&config::SETTINGS) + /// } + /// } + /// ``` + /// + /// [`initialize()`]: Self::initialize + /// [`pagetop::config`]: crate::config + fn settings(&self) -> Option<&'static dyn LoadSettings> { + None + } + /// Registra rutas, servicios y capas de la extensión en el servidor web de la aplicación. /// /// Recibe las rutas acumuladas hasta ese momento, añade lo que la extensión necesite y retorna diff --git a/src/datetime.rs b/src/datetime.rs index 7940ceb3..18526d87 100644 --- a/src/datetime.rs +++ b/src/datetime.rs @@ -39,7 +39,7 @@ //! [ISO 8601]: https://en.wikipedia.org/wiki/ISO_8601 //! [chrono]: https://docs.rs/chrono //! [chrono-tz]: https://docs.rs/chrono-tz -//! [`timezone_per_user`]: crate::global::App::timezone_per_user +//! [`timezone_per_user`]: crate::global::AppSettings::timezone_per_user //! [`CurrentUser::timezone()`]: crate::auth::CurrentUser::timezone //! [`form::date::Field`]: crate::base::component::form::date::Field //! [`Contextual::format_datetime()`]: crate::core::component::Contextual::format_datetime diff --git a/src/datetime/definition.rs b/src/datetime/definition.rs index bf9688b4..d9870314 100644 --- a/src/datetime/definition.rs +++ b/src/datetime/definition.rs @@ -252,7 +252,7 @@ fn regions_by(order: TimezoneOrder, list: &[TzRegion], site: Tz) -> Vec<&'static /// además las zonas horarias que se pueden elegir ([`supported_by_region()`], /// [`is_supported_in()`]). /// -/// [`global::SETTINGS.app.timezone`]: crate::global::App::timezone +/// [`global::SETTINGS.app.timezone`]: crate::global::AppSettings::timezone /// [`supported_by_region()`]: Self::supported_by_region /// [`is_supported_in()`]: Self::is_supported_in pub struct Timezone; @@ -375,8 +375,8 @@ impl Timezone { /// assert!(!is_supported("US/Eastern")); /// ``` /// - /// [`global::SETTINGS.app.timezone_order`]: crate::global::App::timezone_order - /// [`global::SETTINGS.app.timezone_regions`]: crate::global::App::timezone_regions + /// [`global::SETTINGS.app.timezone_order`]: crate::global::AppSettings::timezone_order + /// [`global::SETTINGS.app.timezone_regions`]: crate::global::AppSettings::timezone_regions /// [`form::SelectTimezone`]: crate::base::component::form::SelectTimezone pub fn supported_by_region() -> &'static [(TzRegion, &'static [&'static str])] { &TZ_BY_REGION diff --git a/src/global.rs b/src/global.rs index ff64a7b3..a1f21d38 100644 --- a/src/global.rs +++ b/src/global.rs @@ -1,8 +1,8 @@ -//! Opciones de configuración globales. +//! Ajustes de configuración globales de PageTop. -use crate::include_config; +use crate::{config, settings}; -use serde::Deserialize; +use std::sync::LazyLock; mod lang_negotiation; pub use lang_negotiation::LangNegotiation; @@ -21,52 +21,47 @@ pub use log_format::LogFormat; // **< SETTINGS >*********************************************************************************** -include_config!(SETTINGS: Settings => [ - // [app] - "app.name" => "PageTop App", - "app.theme" => "Basic", - "app.lang_negotiation" => "Full", - "app.timezone" => "UTC", - "app.timezone_regions" => "", - "app.timezone_order" => "Nearest", - "app.timezone_per_user" => true, - "app.startup_banner" => "Slant", - - // [dev] - "dev.pagetop_static_dir" => "", - - // [log] - "log.enabled" => true, - "log.tracing" => "Info", - "log.rolling" => "Stdout", - "log.path" => "log", - "log.prefix" => "tracing.log", - "log.format" => "Full", - - // [server] - "server.bind_address" => "localhost", - "server.bind_port" => 8080, -]); +/// Ajustes de las secciones `[app]`, `[dev]`, `[log]` y `[server]`. +/// +/// Se cargan al arrancar la aplicación, antes que los ajustes de las extensiones. +pub static SETTINGS: LazyLock = LazyLock::new(|| Settings { + app: config::load(), + dev: config::load(), + log: config::load(), + server: config::load(), +}); // **< Settings >*********************************************************************************** -/// Ajustes para las secciones globales [`App`], [`Dev`], [`Log`] y [`Server`] de [`SETTINGS`]. -#[derive(Debug, Deserialize)] +/// Ajustes globales de [`SETTINGS`]. +/// +/// Secciones [`AppSettings`], [`DevSettings`], [`LogSettings`] y [`ServerSettings`]. +#[derive(Debug)] pub struct Settings { - pub app: App, - pub dev: Dev, - pub log: Log, - pub server: Server, + pub app: AppSettings, + pub dev: DevSettings, + pub log: LogSettings, + pub server: ServerSettings, } +// Secciones de los ajustes globales, para reconocerlas en los archivos de configuración. +pub(crate) const SECTIONS: [&str; 4] = [ + ::SECTION, + ::SECTION, + ::SECTION, + ::SECTION, +]; + /// Sección **`[app]`** de la configuración. Forma parte de [`Settings`]. -#[derive(Debug, Deserialize)] -pub struct App { +#[settings(section = "app")] +pub struct AppSettings { /// Nombre de la aplicación. + #[default = "PageTop App"] pub name: String, /// Tema predeterminado: *"Basic"* o el de una extensión enlazada por la aplicación, sin /// distinguir mayúsculas y minúsculas. Si no está habilitado se usa *"Basic"*, con un aviso al /// arrancar. Ver [`default_theme()`](crate::core::theme::default_theme). + #[default = "Basic"] pub theme: String, /// Idioma predeterminado de la aplicación (p. ej., *"es-ES"* o *"en-US"*). /// @@ -84,6 +79,7 @@ pub struct App { /// /// Define las fuentes que intervienen en la negociación del idioma para el renderizado de los /// documentos y la generación de URLs. Ver [`LangNegotiation`] para los modos disponibles. + #[default(LangNegotiation::Full)] pub lang_negotiation: LangNegotiation, /// Zona horaria predeterminada de la aplicación (p. ej. *"UTC"* o *"Europe/Madrid"*). /// @@ -133,6 +129,7 @@ pub struct App { /// `with_order()`. /// /// [`form::SelectTimezone`]: crate::base::component::form::SelectTimezone + #[default(TimezoneOrder::Nearest)] pub timezone_order: TimezoneOrder, /// Si cada usuario puede tener su propia zona horaria (*true*) o se usa siempre la de la /// aplicación (*false*). @@ -143,9 +140,11 @@ pub struct App { /// a activar. Es el equivalente de [`LangNegotiation::ConfigOnly`] para el idioma. /// /// [`CurrentUser::timezone()`]: crate::auth::CurrentUser::timezone + #[default = true] pub timezone_per_user: bool, /// Banner ASCII mostrado al inicio: *"Off"* (desactivado), *"Slant"*, *"Small"*, *"Speed"* o /// *"Starwars"*. + #[default(StartupBanner::Slant)] pub startup_banner: StartupBanner, /// Modo de ejecución, dado por la variable de entorno `PAGETOP_RUN_MODE`, o *"default"* si no /// está definida o está vacía. Con la *feature* `testing` activa es siempre *"test"*. @@ -153,44 +152,85 @@ pub struct App { } /// Sección **`[dev]`** de la configuración. Forma parte de [`Settings`]. -#[derive(Debug, Deserialize)] -pub struct Dev { +#[settings(section = "dev")] +pub struct DevSettings { /// Directorio raíz de `static/` para servir los archivos estáticos propios de PageTop. /// - /// Si se indica una ruta válida, absoluta o relativa al directorio del proyecto o del binario - /// en ejecución, los archivos estáticos se servirán desde disco. Útil para poder modificar los - /// archivos estáticos mientras la aplicación está en ejecución, sin necesidad de recompilar. + /// Si se indica una ruta válida, absoluta o relativa al directorio del proyecto (o, al ejecutar + /// el binario, al directorio de trabajo actual), los archivos estáticos se servirán desde + /// disco. Útil para poder modificar los archivos estáticos mientras la aplicación está en + /// ejecución, sin necesidad de recompilar. /// /// Si la cadena está vacía, se ignora este ajuste. pub pagetop_static_dir: String, } /// Sección **`[log]`** de la configuración. Forma parte de [`Settings`]. -#[derive(Debug, Deserialize)] -pub struct Log { +#[settings(section = "log")] +pub struct LogSettings { /// Gestión de trazas y registro de eventos activada (*true*) o desactivada (*false*). + #[default = true] pub enabled: bool, /// Opciones, o combinación de opciones separadas por comas, para filtrar las trazas: *"Error"*, /// *"Warn"*, *"Info"*, *"Debug"* o *"Trace"*. /// Ejemplo: *"Error,tower_http=Debug,axum::rejection=trace"*. Si no es válido se usa *"Info"*, /// con un aviso al arrancar. + #[default = "Info"] pub tracing: String, /// Muestra los mensajes de traza en el terminal (*"Stdout"*) o los vuelca en archivos con /// rotación: *"Daily"*, *"Hourly"*, *"Minutely"* o *"Endless"*. + #[default(LogRolling::Stdout)] pub rolling: LogRolling, /// Directorio para los archivos de traza (si [`rolling`](Self::rolling) ≠ *"Stdout"*). + #[default = "log"] pub path: String, /// Prefijo para los archivos de traza (si [`rolling`](Self::rolling) ≠ *"Stdout"*). + #[default = "tracing.log"] pub prefix: String, /// Formato de salida de las trazas. Opciones: *"Full"*, *"Compact"*, *"Pretty"* o *"Json"*. + #[default(LogFormat::Full)] pub format: LogFormat, } /// Sección **`[server]`** de la configuración. Forma parte de [`Settings`]. -#[derive(Debug, Deserialize)] -pub struct Server { +#[settings(section = "server")] +pub struct ServerSettings { /// Dirección de enlace para el servidor web. + #[default = "localhost"] pub bind_address: String, /// Puerto de escucha del servidor web. + #[default = 8080] pub bind_port: u16, } + +#[cfg(test)] +mod tests { + use super::{AppSettings, DevSettings, LogSettings, ServerSettings, config}; + + // `reference.toml` documents every option; with unknown keys rejected, loading it proves that + // it only documents keys that exist, with values of the right type. + const REFERENCE: &str = include_str!("../config/reference.toml"); + + #[test] + fn reference_toml_documents_only_existing_keys() { + config::load_from_str::(REFERENCE).unwrap(); + config::load_from_str::(REFERENCE).unwrap(); + config::load_from_str::(REFERENCE).unwrap(); + config::load_from_str::(REFERENCE).unwrap(); + } + + #[test] + fn enum_values_are_case_insensitive() { + let log = config::load_from_str::("[log]\nrolling = \"daily\"\n").unwrap(); + assert_eq!(log.rolling, super::LogRolling::Daily); + } + + #[test] + fn invalid_enum_values_are_rejected() { + let error = config::load_from_str::("[log]\nrolling = \"Daly\"\n") + .expect_err("invalid value accepted") + .to_string(); + assert!(error.contains("Daly")); + assert!(error.contains("Daily")); + } +} diff --git a/src/global/lang_negotiation.rs b/src/global/lang_negotiation.rs index ed30344f..6ab4de40 100644 --- a/src/global/lang_negotiation.rs +++ b/src/global/lang_negotiation.rs @@ -1,13 +1,17 @@ -use crate::{AutoDefault, config}; +use crate::AutoDefault; +use serde::de::Error; use serde::{Deserialize, Deserializer}; /// Modos disponibles para negociar el idioma de una petición HTTP. /// -/// El ajuste [`global::SETTINGS.app.lang_negotiation`](crate::global::App::lang_negotiation) -/// determina qué fuentes intervienen en la resolución del idioma efectivo utilizado por -/// [`RequestLocale`](crate::locale::RequestLocale) y en la generación de URLs mediante -/// [`Context::route()`](crate::core::component::Context::route). +/// El ajuste [`global::SETTINGS.app.lang_negotiation`] determina qué fuentes intervienen en la +/// resolución del idioma efectivo utilizado por [`RequestLocale`] y en la generación de URLs +/// mediante [`Context::route()`]. +/// +/// [`global::SETTINGS.app.lang_negotiation`]: crate::global::AppSettings::lang_negotiation +/// [`RequestLocale`]: crate::locale::RequestLocale +/// [`Context::route()`]: crate::core::component::Context::route #[derive(AutoDefault, Clone, Copy, Debug, Eq, PartialEq)] pub enum LangNegotiation { /// Usa todas las fuentes disponibles para determinar el idioma, en este orden: comprueba el @@ -18,7 +22,7 @@ pub enum LangNegotiation { /// comportamiento por defecto. /// /// [`CurrentUser::language()`]: crate::auth::CurrentUser::language - /// [`global::SETTINGS.app.language`]: crate::global::App::language + /// [`global::SETTINGS.app.language`]: crate::global::AppSettings::language #[default] Full, @@ -42,12 +46,14 @@ impl<'de> Deserialize<'de> for LangNegotiation { D: Deserializer<'de>, { let raw = String::deserialize(deserializer)?; - let result = match raw.trim().to_ascii_lowercase().as_str() { - "full" => Self::Full, - "noquery" => Self::NoQuery, - "configonly" => Self::ConfigOnly, - _ => config::invalid_setting("[app].lang_negotiation", &raw, Self::default()), - }; - Ok(result) + match raw.trim().to_ascii_lowercase().as_str() { + "full" => Ok(Self::Full), + "noquery" => Ok(Self::NoQuery), + "configonly" => Ok(Self::ConfigOnly), + _ => Err(D::Error::unknown_variant( + &raw, + &["Full", "NoQuery", "ConfigOnly"], + )), + } } } diff --git a/src/global/log_format.rs b/src/global/log_format.rs index 75cb3362..726d2d53 100644 --- a/src/global/log_format.rs +++ b/src/global/log_format.rs @@ -1,12 +1,13 @@ -use crate::{AutoDefault, config}; +use crate::AutoDefault; +use serde::de::Error; use serde::{Deserialize, Deserializer}; /// Formatos disponibles para mostrar las trazas. /// -/// El valor se obtiene de [`global::SETTINGS.log.format`](crate::global::Log::format) y determina -/// la representación textual de los eventos registrados por `tracing`. -/// El valor configurado no distingue entre mayúsculas y minúsculas. +/// El valor se obtiene de [`global::SETTINGS.log.format`](crate::global::LogSettings::format) y +/// determina la representación textual de los eventos registrados por `tracing`. El valor +/// configurado no distingue entre mayúsculas y minúsculas. #[derive(AutoDefault, Clone, Copy, Debug, Eq, PartialEq)] pub enum LogFormat { /// Formato JSON estructurado. @@ -29,13 +30,15 @@ impl<'de> Deserialize<'de> for LogFormat { D: Deserializer<'de>, { let raw = String::deserialize(deserializer)?; - let result = match raw.trim().to_ascii_lowercase().as_str() { - "json" => Self::Json, - "full" => Self::Full, - "compact" => Self::Compact, - "pretty" => Self::Pretty, - _ => config::invalid_setting("[log].format", &raw, Self::default()), - }; - Ok(result) + match raw.trim().to_ascii_lowercase().as_str() { + "json" => Ok(Self::Json), + "full" => Ok(Self::Full), + "compact" => Ok(Self::Compact), + "pretty" => Ok(Self::Pretty), + _ => Err(D::Error::unknown_variant( + &raw, + &["Json", "Full", "Compact", "Pretty"], + )), + } } } diff --git a/src/global/log_rolling.rs b/src/global/log_rolling.rs index a641d088..75e6b176 100644 --- a/src/global/log_rolling.rs +++ b/src/global/log_rolling.rs @@ -1,12 +1,13 @@ -use crate::{AutoDefault, config}; +use crate::AutoDefault; +use serde::de::Error; use serde::{Deserialize, Deserializer}; /// Modos de salida y rotación para el registro de trazas. /// -/// El valor se obtiene de [`global::SETTINGS.log.rolling`](crate::global::Log::rolling) y -/// determina si las trazas se muestran por pantalla o se vuelcan en archivos con rotación. -/// El valor configurado no distingue entre mayúsculas y minúsculas. +/// El valor se obtiene de [`global::SETTINGS.log.rolling`](crate::global::LogSettings::rolling) y +/// determina si las trazas se muestran por pantalla o se vuelcan en archivos con rotación. El valor +/// configurado no distingue entre mayúsculas y minúsculas. #[derive(AutoDefault, Clone, Copy, Debug, Eq, PartialEq)] pub enum LogRolling { /// Escribe las trazas en la salida estándar (sin rotación de archivos). Es el valor por @@ -29,14 +30,16 @@ impl<'de> Deserialize<'de> for LogRolling { D: Deserializer<'de>, { let raw = String::deserialize(deserializer)?; - let result = match raw.trim().to_ascii_lowercase().as_str() { - "stdout" => Self::Stdout, - "daily" => Self::Daily, - "hourly" => Self::Hourly, - "minutely" => Self::Minutely, - "endless" => Self::Endless, - _ => config::invalid_setting("[log].rolling", &raw, Self::default()), - }; - Ok(result) + match raw.trim().to_ascii_lowercase().as_str() { + "stdout" => Ok(Self::Stdout), + "daily" => Ok(Self::Daily), + "hourly" => Ok(Self::Hourly), + "minutely" => Ok(Self::Minutely), + "endless" => Ok(Self::Endless), + _ => Err(D::Error::unknown_variant( + &raw, + &["Stdout", "Daily", "Hourly", "Minutely", "Endless"], + )), + } } } diff --git a/src/global/startup_banner.rs b/src/global/startup_banner.rs index 3b3f61f9..a30ef239 100644 --- a/src/global/startup_banner.rs +++ b/src/global/startup_banner.rs @@ -1,11 +1,14 @@ -use crate::{AutoDefault, config}; +use crate::AutoDefault; +use serde::de::Error; use serde::{Deserialize, Deserializer}; /// Opciones para el *banner* ASCII mostrado al arrancar la aplicación. /// -/// Se obtiene de [`global::SETTINGS.app.startup_banner`](crate::global::App::startup_banner) y -/// controla si se muestra un *banner* en la salida estándar al arrancar la aplicación. +/// Se obtiene de [`global::SETTINGS.app.startup_banner`] y controla si se muestra un *banner* en la +/// salida estándar al arrancar la aplicación. +/// +/// [`global::SETTINGS.app.startup_banner`]: crate::global::AppSettings::startup_banner #[derive(AutoDefault, Clone, Copy, Debug, Eq, PartialEq)] pub enum StartupBanner { /// No muestra ningún banner de inicio. @@ -27,14 +30,16 @@ impl<'de> Deserialize<'de> for StartupBanner { D: Deserializer<'de>, { let raw = String::deserialize(deserializer)?; - let result = match raw.trim().to_ascii_lowercase().as_str() { - "off" => Self::Off, - "slant" => Self::Slant, - "small" => Self::Small, - "speed" => Self::Speed, - "starwars" => Self::Starwars, - _ => config::invalid_setting("[app].startup_banner", &raw, Self::default()), - }; - Ok(result) + match raw.trim().to_ascii_lowercase().as_str() { + "off" => Ok(Self::Off), + "slant" => Ok(Self::Slant), + "small" => Ok(Self::Small), + "speed" => Ok(Self::Speed), + "starwars" => Ok(Self::Starwars), + _ => Err(D::Error::unknown_variant( + &raw, + &["Off", "Slant", "Small", "Speed", "Starwars"], + )), + } } } diff --git a/src/global/timezone_order.rs b/src/global/timezone_order.rs index 2b5e6b6c..9c2e0039 100644 --- a/src/global/timezone_order.rs +++ b/src/global/timezone_order.rs @@ -1,14 +1,16 @@ -use crate::{AutoDefault, config}; +use crate::AutoDefault; +use serde::de::Error; use serde::{Deserialize, Deserializer}; /// Criterios para ordenar las regiones de zonas horarias que se ofrecen para elegir. /// -/// Se obtiene de [`global::SETTINGS.app.timezone_order`](crate::global::App::timezone_order) y -/// determina el orden de los grupos de [`Timezone::supported_by_region()`]. Es también el orden -/// por defecto de [`form::SelectTimezone`], que puede cambiarse con `with_order()`. En todos los -/// casos el grupo *"Etc"* (`Etc/UTC`) va siempre al final. +/// Se obtiene de [`global::SETTINGS.app.timezone_order`] y determina el orden de los grupos de +/// [`Timezone::supported_by_region()`]. Es también el orden por defecto de +/// [`form::SelectTimezone`], que puede cambiarse con `with_order()`. En todos los casos el grupo +/// *"Etc"* (`Etc/UTC`) va siempre al final. /// +/// [`global::SETTINGS.app.timezone_order`]: crate::global::AppSettings::timezone_order /// [`Timezone::supported_by_region()`]: crate::datetime::Timezone::supported_by_region /// [`form::SelectTimezone`]: crate::base::component::form::SelectTimezone #[derive(AutoDefault, Clone, Copy, Debug, Eq, PartialEq)] @@ -23,10 +25,11 @@ pub enum TimezoneOrder { /// /// [`form::SelectTimezone`]: crate::base::component::form::SelectTimezone Alphabetical, - /// En el orden en que se indican las regiones, en - /// [`global::SETTINGS.app.timezone_regions`](crate::global::App::timezone_regions) o con - /// `SelectTimezone::with_regions()`; si no se indica ninguna región válida, por nombre, como - /// `TimezoneOrder::Alphabetical`. + /// En el orden en que se indican las regiones, en [`global::SETTINGS.app.timezone_regions`] o + /// con `SelectTimezone::with_regions()`; si no se indica ninguna región válida, por nombre, + /// como `TimezoneOrder::Alphabetical`. + /// + /// [`global::SETTINGS.app.timezone_regions`]: crate::global::AppSettings::timezone_regions Listed, } @@ -36,12 +39,14 @@ impl<'de> Deserialize<'de> for TimezoneOrder { D: Deserializer<'de>, { let raw = String::deserialize(deserializer)?; - let result = match raw.trim().to_ascii_lowercase().as_str() { - "nearest" => Self::Nearest, - "alphabetical" => Self::Alphabetical, - "listed" => Self::Listed, - _ => config::invalid_setting("[app].timezone_order", &raw, Self::default()), - }; - Ok(result) + match raw.trim().to_ascii_lowercase().as_str() { + "nearest" => Ok(Self::Nearest), + "alphabetical" => Ok(Self::Alphabetical), + "listed" => Ok(Self::Listed), + _ => Err(D::Error::unknown_variant( + &raw, + &["Nearest", "Alphabetical", "Listed"], + )), + } } } diff --git a/src/lib.rs b/src/lib.rs index d022eb37..5fbb2e31 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -137,7 +137,12 @@ pub const PAGETOP_VERSION: &str = env!("CARGO_PKG_VERSION"); /// [`impl Extension`](crate::core::extension::Extension). pub use async_trait::async_trait; -pub use pagetop_macros::{AutoDefault, builder_fn, builder_impl, html, main, test}; +pub use pagetop_macros::{AutoDefault, builder_fn, builder_impl, html, main, settings, test}; + +// Lo usa el código que genera `#[settings]`, para que las extensiones no necesiten declarar `serde` +// como dependencia sólo para sus ajustes. +#[doc(hidden)] +pub use serde; pub use pagetop_statics::{StaticFile, resource}; diff --git a/src/prelude.rs b/src/prelude.rs index 9d8e570e..393a4349 100644 --- a/src/prelude.rs +++ b/src/prelude.rs @@ -4,14 +4,12 @@ pub use crate::PAGETOP_VERSION; -pub use crate::{async_trait, builder_fn, builder_impl, html, main, test}; +pub use crate::{async_trait, builder_fn, builder_impl, html, main, settings, test}; pub use crate::{AutoDefault, CowStr, Getters, StaticResources, UniqueId, Weight}; // MACROS. -// crate::config -pub use crate::include_config; // crate::locale pub use crate::include_locales; // crate::web @@ -25,6 +23,9 @@ pub use crate::{render_component, setup_component}; pub use crate::util; +pub use crate::config; +pub use crate::config::{LazySettings, LoadSettings}; + pub use crate::global; pub use crate::trace; diff --git a/src/util.rs b/src/util.rs index c6539ce4..9155a55f 100644 --- a/src/util.rs +++ b/src/util.rs @@ -212,8 +212,9 @@ pub fn normalize_ascii(input: &str) -> Option> { } } -/// Recorta espacios y pasa a minúsculas el nombre de una propiedad, tratando el resultado vacío -/// como ausencia. +/// Recorta espacios y pasa a minúsculas el nombre de una propiedad. +/// +/// Si el resultado queda vacío, devuelve `None`. /// /// # Ejemplo /// diff --git a/tests/config.rs b/tests/config.rs index 38ebb01b..9c6ab273 100644 --- a/tests/config.rs +++ b/tests/config.rs @@ -1,40 +1,115 @@ use pagetop::prelude::*; -use serde::Deserialize; +use std::sync::atomic::{AtomicBool, Ordering}; -include_config!(SETTINGS: Settings => [ - "test.string_value" => "Test String", - "test.int_value" => -321, - "test.float_value" => 2.3456, -]); +// The `testing` *feature* (active with `cargo ts` / `cargo tw`) fixes the "test" run mode at +// compile time, so that `global::SETTINGS` and any other settings automatically load the "test" +// mode configuration from `config/test.toml` (versioned, unlike the `local.*.toml` files). -#[derive(Debug, Deserialize)] -pub struct Settings { - pub test: Test, -} - -#[derive(Debug, Deserialize)] -pub struct Test { +#[settings(section = "test")] +pub struct TestSettings { + #[default = "Test String"] pub string_value: String, + #[default(-321)] pub int_value: i32, + #[default = 2.3456] pub float_value: f32, + pub nested: NestedSettings, } -// The `testing` *feature* (active with `cargo ts` / `cargo tw`) fixes the "test" mode at compile -// time inside `config::CONFIG_VALUES`, so that `global::SETTINGS` and any local `include_config!` -// automatically load the "test" mode configuration from `config/test.toml` (versioned, unlike the -// `local.*.toml` files). +#[settings] +pub struct NestedSettings { + #[default = true] + pub enabled: bool, +} + +static SETTINGS: LazySettings = LazySettings::new(); + +// Settings only reachable through `Extension::settings()`: `STARTUP_LOADED` can only be set by the +// application loading them at startup. +static STARTUP_LOADED: AtomicBool = AtomicBool::new(false); + +struct StartupSettings; + +impl LoadSettings for StartupSettings { + fn load(&self) { + STARTUP_LOADED.store(true, Ordering::SeqCst); + } + + fn section(&self) -> &'static str { + "test" + } +} + +// A section that no configuration file defines. +#[settings(section = "absent")] +pub struct AbsentSettings { + #[default = 7] + pub value: u8, +} + +// `EXTENSIONS` is a global `OnceLock`: all tests in this file share the same root extension. +struct SettingsExtension; + +#[async_trait] +impl Extension for SettingsExtension { + fn settings(&self) -> Option<&'static dyn LoadSettings> { + Some(&StartupSettings) + } +} #[pagetop::test] async fn check_global_config() { assert_eq!(global::SETTINGS.app.run_mode, "test"); assert_eq!(global::SETTINGS.app.name, "Testing"); assert_eq!(global::SETTINGS.server.bind_port, 9000); + // Not defined in `config/test.toml`: default value. + assert_eq!(global::SETTINGS.server.bind_address, "localhost"); } #[pagetop::test] -async fn check_local_config() { - assert_eq!(SETTINGS.test.string_value, "Modified value"); - assert_eq!(SETTINGS.test.int_value, -321); - assert_eq!(SETTINGS.test.float_value, 8.7654); +async fn files_override_defaults_key_by_key() { + assert_eq!(SETTINGS.string_value, "Modified value"); + assert_eq!(SETTINGS.int_value, -321); + assert_eq!(SETTINGS.float_value, 8.7654); + assert!(SETTINGS.nested.enabled); +} + +#[pagetop::test] +async fn absent_section_uses_all_defaults() { + static ABSENT: LazySettings = LazySettings::new(); + assert_eq!(ABSENT.value, 7); +} + +#[pagetop::test] +async fn defaults_come_from_the_fields() { + let defaults = TestSettings::default(); + assert_eq!(defaults.string_value, "Test String"); + assert_eq!(defaults.int_value, -321); + assert!(defaults.nested.enabled); +} + +#[pagetop::test] +async fn unknown_keys_are_rejected() { + // A typo in a key must not be silently ignored. + let result = serde_json::from_str::(r#"{ "string_valu": "typo" }"#); + let error = result.expect_err("unknown key accepted").to_string(); + assert!(error.contains("string_valu")); + + let result = serde_json::from_str::(r#"{ "nested": { "enable": false } }"#); + assert!(result.is_err()); +} + +#[pagetop::test] +async fn application_loads_settings_at_startup() { + let _ = Application::prepare(&SettingsExtension).await.test(); + assert!(STARTUP_LOADED.load(Ordering::SeqCst)); +} + +#[pagetop::test] +async fn load_from_str_rejects_unknown_keys() { + let error = config::load_from_str::("[test]\nstring_valu = \"typo\"\n") + .expect_err("unknown key accepted") + .to_string(); + assert!(error.contains("string_valu")); } diff --git a/tests/config_duplicate_section.rs b/tests/config_duplicate_section.rs new file mode 100644 index 00000000..b38ccb02 --- /dev/null +++ b/tests/config_duplicate_section.rs @@ -0,0 +1,25 @@ +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; +}