♻️ (config): Ajustes con #[settings] al arrancar

- 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<T>::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.
This commit is contained in:
Manuel Cillero 2026-10-12 21:41:01 +02:00
parent 8a7a827259
commit 728a5c83dc
32 changed files with 918 additions and 488 deletions

View file

@ -18,8 +18,11 @@
# Las opciones comentadas no tienen valor por defecto; se muestran con un valor de ejemplo. # 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 # 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 # mayúsculas o minúsculas.
# arrancar. #
# 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] [dev]
pagetop_static_dir = "" # Directorio static/ de PageTop para servir sus archivos pagetop_static_dir = "" # Directorio static/ de PageTop para servir sus archivos
# estáticos desde disco (editables sin recompilar). Ruta # estáticos desde disco (editables sin recompilar). Ruta
# absoluta o relativa al proyecto o al binario. Vacío -> se # absoluta o relativa al proyecto (o, al ejecutar el binario,
# sirven los incluidos en el binario. # al directorio de trabajo). Vacío -> se sirven los incluidos
bootsier_static_dir = "" # Igual que el anterior, para los archivos estáticos de # en el binario.
# pagetop-bootsier.
[log] [log]
enabled = true # Activa (true) o desactiva (false) las trazas. enabled = true # Activa (true) o desactiva (false) las trazas.
@ -164,3 +166,5 @@ list_page_size = 20 # Filas por página en los listados de admin
[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.

View file

@ -1,4 +1,4 @@
//! Opciones de configuración del tema. //! Ajustes de configuración de `pagetop-bootsier`.
//! //!
//! Ejemplo: //! Ejemplo:
//! //!
@ -13,46 +13,46 @@
//! # use pagetop::prelude::*; //! # use pagetop::prelude::*;
//! use pagetop_bootsier::config; //! 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 //! Consulta [`pagetop::config`] para ver cómo PageTop lee los archivos de configuración y aplica
//! los valores a los ajustes. //! los valores a los ajustes.
use pagetop::prelude::*; use pagetop::prelude::*;
use serde::Deserialize; /// Ajustes de la sección `[bootsier]`, cargados al arrancar la aplicación.
pub static SETTINGS: LazySettings<BootsierSettings> = LazySettings::new();
include_config!(SETTINGS: Settings => [ /// Sección **`[bootsier]`** de la configuración.
// [bootsier] #[settings(section = "bootsier")]
"bootsier.max_width" => "1440px", pub struct BootsierSettings {
// [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 {
/// Ancho máximo predeterminado para la página, por ejemplo "100%" o "90rem". /// Ancho máximo predeterminado para la página, por ejemplo "100%" o "90rem".
#[default(UnitValue::Px(1440))]
pub max_width: UnitValue, 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. /// 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 /// Si se indica una ruta válida, absoluta o relativa al directorio del proyecto (o, al ejecutar
/// en ejecución, los archivos estáticos se servirán desde disco. Útil para poder modificar los /// el binario, al directorio de trabajo actual), los archivos estáticos se servirán desde
/// archivos estáticos mientras la aplicación está en ejecución, sin necesidad de recompilar. /// 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. /// 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::<BootsierSettings>(REFERENCE).unwrap();
}
} }

View file

@ -106,8 +106,12 @@ impl Extension for Bootsier {
Some(&Self) Some(&Self)
} }
fn settings(&self) -> Option<&'static dyn LoadSettings> {
Some(&config::SETTINGS)
}
fn configure_static_files(&self, router: Router) -> Router { 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| { let subdir = |s: &str| {
if base.is_empty() { if base.is_empty() {
String::new() String::new()

View file

@ -29,9 +29,7 @@ pub(crate) async fn render(
async fn render_standard(cx: &mut Context) -> Markup { async fn render_standard(cx: &mut Context) -> Markup {
bs::Container::new() bs::Container::new()
.with_prop(PropsOp::add_classes("container-wrapper")) .with_prop(PropsOp::add_classes("container-wrapper"))
.with_width(bs::container::Width::FluidMax( .with_width(bs::container::Width::FluidMax(config::SETTINGS.max_width))
config::SETTINGS.bootsier.max_width,
))
.with_child(layout::Region::header()) .with_child(layout::Region::header())
.with_child(layout::Region::aside()) .with_child(layout::Region::aside())
.with_child(layout::Region::default()) .with_child(layout::Region::default())

View file

@ -1,4 +1,4 @@
//! Opciones de configuración de la extensión. //! Ajustes de configuración de `pagetop-seaorm`.
//! //!
//! Ejemplo: //! Ejemplo:
//! //!
@ -16,10 +16,13 @@
//! Uso: //! Uso:
//! //!
//! ```rust //! ```rust
//! # use pagetop_seaorm::config; //! use pagetop_seaorm::config;
//! assert_eq!(config::SETTINGS.database.db_host, "localhost"); //!
//! 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 //! Consulta [`pagetop::config`] para ver cómo PageTop lee los archivos de configuración y aplica
//! los valores a los ajustes. //! los valores a los ajustes.
@ -27,25 +30,12 @@ use pagetop::prelude::*;
use serde::Deserialize; use serde::Deserialize;
include_config!(SETTINGS: Settings => [ /// Ajustes de la sección `[database]`, cargados al arrancar la aplicación.
// [database] pub static SETTINGS: LazySettings<DatabaseSettings> = LazySettings::new();
"database.db_type" => "",
"database.db_name" => "",
"database.db_user" => "",
"database.db_pass" => "",
"database.db_host" => "localhost",
"database.max_pool_size" => 5,
]);
/// Ajustes para la sección [`Database`] de [`SETTINGS`]. /// Sección **`[database]`** de la configuración.
#[derive(Debug, Deserialize)] #[settings(section = "database")]
pub struct Settings { pub struct DatabaseSettings {
pub database: Database,
}
/// Sección **`[database]`** de la configuración. Forma parte de [`Settings`].
#[derive(Debug, Deserialize)]
pub struct Database {
/// Motor de base de datos. /// Motor de base de datos.
/// ///
/// Valores aceptados: `"mysql"` (también `"mariadb"`), `"postgres"` (también `"postgresql"`) y /// 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). /// Contraseña para la conexión a la base de datos (para mysql/postgres).
pub db_pass: String, pub db_pass: String,
/// Servidor de conexión a la base de datos (para mysql/postgres). /// Servidor de conexión a la base de datos (para mysql/postgres).
#[default = "localhost"]
pub db_host: String, pub db_host: String,
/// Puerto de conexión a la base de datos (para mysql/postgres). Si se omite, se usa el puerto /// 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. /// predeterminado para el motor: 3306 para MySQL y 5432 para PostgreSQL.
pub db_port: Option<u16>, pub db_port: Option<u16>,
/// Número máximo de conexiones habilitadas. /// Número máximo de conexiones habilitadas.
#[default = 5]
pub max_pool_size: u32, pub max_pool_size: u32,
} }
/// Motor de base de datos. Usado en el campo [`Database::db_type`] de [`SETTINGS`]. /// Motor de base de datos. Usado en [`DatabaseSettings::db_type`].
#[derive(Clone, Copy, Debug, Deserialize)] #[derive(AutoDefault, Clone, Copy, Debug, Deserialize)]
#[serde(rename_all = "lowercase")] #[serde(rename_all = "lowercase")]
pub enum DbType { pub enum DbType {
/// Valor por defecto cuando `db_type` no está configurado. En este caso la aplicación terminará /// Valor por defecto cuando `db_type` no está configurado. En este caso la aplicación terminará
/// con un error al arrancar. /// con un error al arrancar.
#[default]
#[serde(rename = "")] #[serde(rename = "")]
Unset, Unset,
/// Usa el motor MySQL. Acepta también el alias `"mariadb"`. /// Usa el motor MySQL. Acepta también el alias `"mariadb"`.
@ -83,3 +76,17 @@ pub enum DbType {
/// Usa el motor SQLite. /// Usa el motor SQLite.
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::<DatabaseSettings>(REFERENCE).unwrap();
}
}

View file

@ -202,19 +202,23 @@ impl Extension for SeaORM {
Lc::t("extension_description", &LOCALES_SEAORM) Lc::t("extension_description", &LOCALES_SEAORM)
} }
fn settings(&self) -> Option<&'static dyn LoadSettings> {
Some(&config::SETTINGS)
}
async fn initialize(&self) { async fn initialize(&self) {
trace::info!( trace::info!(
"Connecting to database \"{}\" using a pool of {} connections", "Connecting to database \"{}\" using a pool of {} connections",
&config::SETTINGS.database.db_name, &config::SETTINGS.db_name,
&config::SETTINGS.database.max_pool_size &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!( config::DbType::Unset => panic!(
"database.db_type is not configured: use \"mysql\", \"postgres\" or \"sqlite\"" "database.db_type is not configured: use \"mysql\", \"postgres\" or \"sqlite\""
), ),
config::DbType::Mysql | config::DbType::Postgres => { 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" "mysql"
} else { } else {
"postgres" "postgres"
@ -222,18 +226,18 @@ impl Extension for SeaORM {
let mut tmp_uri = Url::parse(&format!( let mut tmp_uri = Url::parse(&format!(
"{}://{}/{}", "{}://{}/{}",
scheme, scheme,
&config::SETTINGS.database.db_host, &config::SETTINGS.db_host,
&config::SETTINGS.database.db_name &config::SETTINGS.db_name
)) ))
.expect("Invalid database URL: check db_host and db_name in config"); .expect("Invalid database URL: check db_host and db_name in config");
tmp_uri 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"); .expect("Failed to set db_user in connection URL");
tmp_uri tmp_uri
// https://github.com/launchbadge/sqlx/issues/1624 // 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"); .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 tmp_uri
.set_port(Some(port)) .set_port(Some(port))
.expect("Failed to set db_port in connection URL"); .expect("Failed to set db_port in connection URL");
@ -241,13 +245,13 @@ impl Extension for SeaORM {
tmp_uri.to_string() tmp_uri.to_string()
} }
config::DbType::Sqlite => { config::DbType::Sqlite => {
format!("sqlite://{}", &config::SETTINGS.database.db_name) format!("sqlite://{}", &config::SETTINGS.db_name)
} }
}; };
let conn = Database::connect::<ConnectOptions>({ let conn = Database::connect::<ConnectOptions>({
let mut db_opt = ConnectOptions::new(db_uri); 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 db_opt
}) })
.await .await

View file

@ -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 //! ```toml
//! [user]
//! allow_registration = false
//!
//! [user.session]
//! secure_cookie = true
//!
//! [user.password] //! [user.password]
//! min_length = 10 //! 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 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<UserSettings> = LazySettings::new();
// **< CONFIG_USER >******************************************************************************** /// Sección **`[user]`** de la configuración.
#[settings(section = "user")]
include_config!(CONFIG_USER: UserTopConfig => [ pub struct UserSettings {
// Política de registro y verificación. /// Permite que los visitantes creen su propia cuenta.
"user.allow_registration" => true, #[default = 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<Settings> = 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.
pub allow_registration: bool, 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, pub require_email_verification: bool,
// Anti-fuerza-bruta. /// Intentos fallidos de acceso antes de bloquear la cuenta.
#[default = 5]
pub max_failed_logins: i32, 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, pub failed_login_window_secs: i64,
/// Duración del bloqueo de la cuenta, en segundos.
#[default = 600]
pub locked_for_secs: i64, pub locked_for_secs: i64,
// Sesiones. /// Sesiones, en la subsección `[user.session]`.
pub session: SessionConfig, pub session: SessionSettings,
// Contraseñas. /// Contraseñas, en la subsección `[user.password]`.
pub password: PasswordConfig, pub password: PasswordSettings,
// Semilla del primer administrador. /// Primer administrador, en la subsección `[user.seed]`.
pub seed: SeedConfig, pub seed: SeedSettings,
// Listados de administración. /// Listados de administración, en la subsección `[user.admin]`.
pub admin: AdminConfig, pub admin: AdminSettings,
/// Activa las medidas para dificultar que el navegador recuerde o autorrellene las /// Activa las medidas para dificultar que el navegador recuerde o autorrellene las
/// credenciales en la pantalla de login (gestor de contraseñas, autocompletado agresivo...). /// credenciales en la pantalla de login (gestor de contraseñas, autocompletado agresivo...).
#[default = false]
pub login_strict: bool, pub login_strict: bool,
} }
/// Ajustes de la sección `[user.session]`. /// Subsección **`[user.session]`** de la configuración.
#[derive(Clone, Debug, Deserialize)] #[settings]
pub struct SessionConfig { pub struct SessionSettings {
/// Nombre de la cookie de sesión. /// Nombre de la cookie de sesión.
#[default = "pagetop"]
pub cookie_name: String, pub cookie_name: String,
/// Marca la cookie de sesión como `Secure` (sólo HTTPS). Debe activarse en producción. /// Marca la cookie de sesión como `Secure` (sólo HTTPS). Debe activarse en producción.
#[default = false]
pub secure_cookie: bool, pub secure_cookie: bool,
/// Segundos sin uso tras los que caduca una sesión iniciada sin "recordarme". El tiempo se /// 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 /// cuenta desde la última petición, con la precisión que fija
/// [`write_interval_secs`](Self::write_interval_secs). /// [`write_interval_secs`](Self::write_interval_secs).
#[default = 7_200]
pub idle_secs: i64, pub idle_secs: i64,
/// Segundos sin uso tras los que caduca una sesión iniciada con "recordarme". El tiempo se /// 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 /// cuenta desde la última petición, con la precisión que fija
/// [`write_interval_secs`](Self::write_interval_secs). /// [`write_interval_secs`](Self::write_interval_secs).
#[default = 1_209_600]
pub remember_idle_secs: i64, pub remember_idle_secs: i64,
/// Segundos mínimos entre dos actualizaciones de la misma sesión en la base de datos. /// 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 /// en [`idle_secs`](Self::idle_secs) y [`remember_idle_secs`](Self::remember_idle_secs). Con
/// `0` se escribe en cada petición. /// `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 /// - **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. /// datos es remota o lenta, para reducir las escrituras.
@ -123,30 +106,51 @@ pub struct SessionConfig {
/// adelanto no es aceptable. /// adelanto no es aceptable.
/// ///
/// Debe ser siempre muy inferior a `idle_secs`. /// Debe ser siempre muy inferior a `idle_secs`.
#[default = 60]
pub write_interval_secs: i64, pub write_interval_secs: i64,
} }
/// Ajustes de la sección `[user.password]`. /// Subsección **`[user.password]`** de la configuración.
#[derive(Clone, Debug, Deserialize)] ///
pub struct PasswordConfig { /// 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, pub argon2_m_cost: u32,
/// Coste de tiempo de Argon2id (número de iteraciones).
#[default = 2]
pub argon2_t_cost: u32, pub argon2_t_cost: u32,
/// Grado de paralelismo de Argon2id (número de hilos).
#[default = 1]
pub argon2_p_cost: u32, pub argon2_p_cost: u32,
/// Longitud mínima de las contraseñas.
#[default = 8]
pub min_length: usize, pub min_length: usize,
} }
/// Ajustes de la sección `[user.seed]`. /// Subsección **`[user.seed]`** de la configuración.
#[derive(Clone, Debug, Deserialize)] ///
pub struct SeedConfig { /// 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, pub admin_username: String,
/// Correo electrónico del primer administrador.
#[default = "admin@example.com"]
pub admin_email: String, 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<String>, pub admin_password: Option<String>,
} }
/// Ajustes de la sección `[user.admin]`. /// Subsección **`[user.admin]`** de la configuración.
#[derive(Clone, Debug, Deserialize)] #[settings]
pub struct AdminConfig { pub struct AdminSettings {
/// Número de filas por página en los listados de administración (usuarios, roles...). /// Número de filas por página en los listados de administración (usuarios, roles...).
#[default = 20]
pub list_page_size: u64, pub list_page_size: u64,
} }
@ -163,3 +167,17 @@ pub(crate) fn user_language_applies() -> bool {
pub(crate) fn user_timezone_applies() -> bool { pub(crate) fn user_timezone_applies() -> bool {
global::SETTINGS.app.timezone_per_user 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::<UserSettings>(REFERENCE).unwrap();
}
}

View file

@ -216,6 +216,10 @@ impl Extension for User {
Lc::t("extension_description", &LOCALES_USER) Lc::t("extension_description", &LOCALES_USER)
} }
fn settings(&self) -> Option<&'static dyn LoadSettings> {
Some(&config::SETTINGS)
}
fn dependencies(&self) -> Vec<ExtensionRef> { fn dependencies(&self) -> Vec<ExtensionRef> {
vec![ vec![
&pagetop_admin::Admin, &pagetop_admin::Admin,

View file

@ -36,6 +36,7 @@ cada proyecto PageTop.
mod builder; mod builder;
mod maud; mod maud;
mod settings;
mod smart_default; mod smart_default;
use proc_macro::TokenStream; 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<T>`, 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_`. /// 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 /// La macro añade automáticamente un método `alter_` que permite modificar la instancia actual

View file

@ -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<TokenStream> {
let mut section: Option<LitStr> = 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<Option<String>> {
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::<Expr>() {
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,
}
}

View file

@ -52,12 +52,12 @@ pub use pastey::paste;
// La documentación anterior se copia en `pagetop::util::paste!` porque el *crate* original no la // La documentación anterior se copia en `pagetop::util::paste!` porque el *crate* original no la
// define y `pagetop` no la hereda automáticamente. // 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<str>`] (literales, `&str`, [`String`], /// Acepta uno o más fragmentos que implementen [`AsRef<str>`] (literales, `&str`, [`String`],
/// `Cow<str>`...) y construye el resultado con la capacidad exacta, sin pasar por el formateo. Es /// `Cow<str>`...) y construye el resultado reservando la memoria una sola vez, con la capacidad
/// la forma preferida de componer texto a partir de fragmentos, y suele ser más rápida que /// exacta, sin pasar por el formateo. Es la forma preferida de componer texto a partir de
/// `format!`. /// 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 /// 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 /// cierres con efectos secundarios. Los valores que no son cadenas (números, tipos `Display`) se

View file

@ -78,6 +78,9 @@ impl Application {
// Registra las extensiones de la aplicación. // Registra las extensiones de la aplicación.
extension::all::register_extensions(root_extension); extension::all::register_extensions(root_extension);
// Carga los ajustes de las extensiones. Un error de configuración detiene aquí el arranque.
extension::all::load_settings();
// Inicializa el tema predeterminado, que ya puede ser el de una extensión. // Inicializa el tema predeterminado, que ya puede ser el de una extensión.
theme::all::init_default_theme(); theme::all::init_default_theme();

View file

@ -156,7 +156,7 @@ impl CurrentUser {
/// de ese momento el renderizado del documento no vuelve a llamarlo porque usa el valor ya /// de ese momento el renderizado del documento no vuelve a llamarlo porque usa el valor ya
/// resuelto vía [`Contextual::timezone()`]. /// 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 /// [`Context`]: crate::core::component::Context
/// [`Contextual::timezone()`]: crate::core::component::Contextual::timezone /// [`Contextual::timezone()`]: crate::core::component::Contextual::timezone
pub fn timezone(&self) -> Tz { pub fn timezone(&self) -> Tz {

View file

@ -23,7 +23,7 @@ use crate::prelude::*;
/// ``` /// ```
/// ///
/// [`with_route()`]: Self::with_route /// [`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)] #[derive(AutoDefault, Clone, Debug, Getters)]
pub struct Brand { pub struct Brand {
/// Devuelve identificador, clases CSS, atributos HTML y valores extra del componente. /// Devuelve identificador, clases CSS, atributos HTML y valores extra del componente.

View file

@ -53,7 +53,7 @@ use chrono::Offset;
/// ///
/// [`TimezoneOrder::Alphabetical`]: crate::global::TimezoneOrder::Alphabetical /// [`TimezoneOrder::Alphabetical`]: crate::global::TimezoneOrder::Alphabetical
/// [`TimezoneOrder::Listed`]: crate::global::TimezoneOrder::Listed /// [`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_utc_offset(true)`]: Self::with_utc_offset
/// [`with_required(true)`]: Self::with_required /// [`with_required(true)`]: Self::with_required
/// [`with_regions()`]: Self::with_regions /// [`with_regions()`]: Self::with_regions
@ -68,11 +68,11 @@ pub struct SelectTimezone {
/// Devuelve si las etiquetas muestran el desfase actual respecto a UTC. /// Devuelve si las etiquetas muestran el desfase actual respecto a UTC.
utc_offset: bool, utc_offset: bool,
/// Devuelve las regiones que se ofrecen, junto a `Etc`, que se ofrece siempre; por defecto, las /// 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()")] #[default(_code = "Timezone::configured_regions()")]
regions: Vec<TzRegion>, regions: Vec<TzRegion>,
/// Devuelve el orden de las regiones; por defecto, el de /// 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")] #[default(_code = "global::SETTINGS.app.timezone_order")]
order: global::TimezoneOrder, order: global::TimezoneOrder,
} }

View file

@ -54,90 +54,86 @@
//! Los archivos se combinan clave a clave en el orden anterior. Cada archivo sobrescribe a los //! Los archivos se combinan clave a clave en el orden anterior. Cada archivo sobrescribe a los
//! anteriores sólo en las claves que define. //! 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 //! Lo habitual es definirlos en un archivo `config.rs` de la extensión con algo como esto:
//! [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:
//! //!
//! ```rust,no_run //! ```rust,no_run
//! use pagetop::prelude::*; //! use pagetop::prelude::*;
//! use serde::Deserialize;
//! //!
//! include_config!(SETTINGS: Settings => [ //! /// Ajustes de la sección `[blog]`, cargados al arrancar la aplicación.
//! // [myapp] //! pub static SETTINGS: LazySettings<BlogSettings> = LazySettings::new();
//! "myapp.name" => "Value Name",
//! "myapp.width" => 900,
//! "myapp.height" => 320,
//! ]);
//! //!
//! #[derive(Debug, Deserialize)] //! /// Sección **`[blog]`** de la configuración.
//! pub struct Settings { //! #[settings(section = "blog")]
//! pub myapp: MyApp, //! pub struct BlogSettings {
//! /// Título del blog.
//! #[default = "Mi Blog"]
//! pub title: String,
//! /// Descripción opcional (sin valor por defecto: `None`).
//! pub description: Option<String>,
//! /// Comentarios, en la subsección `[blog.comments]`.
//! pub comments: CommentsSettings,
//! } //! }
//! //!
//! #[derive(Debug, Deserialize)] //! /// Subsección **`[blog.comments]`** de la configuración.
//! pub struct MyApp { //! #[settings]
//! pub name: String, //! pub struct CommentsSettings {
//! pub description: Option<String>, //! /// Si se admiten comentarios.
//! pub width: u16, //! #[default = true]
//! pub height: u16, //! 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 //! [`LazySettings`] lee la sección indicada en `section`; las claves que falten toman su valor por
//! `[app]` o `[server]` en las opciones globales de [`Settings`](crate::global::Settings). //! 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<T>` para los ajustes //! Para que los ajustes se carguen al arrancar, la extensión los devuelve en
//! opcionales. //! [`Extension::settings()`](crate::core::extension::Extension::settings):
//!
//! 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.
//! //!
//! ```rust,ignore //! ```rust,ignore
//! use pagetop::prelude::*; //! pub mod config;
//! use crate::config;
//! //!
//! fn global_settings() { //! impl Extension for Blog {
//! println!("Nombre de la app: {}", &global::SETTINGS.app.name); //! fn settings(&self) -> Option<&'static dyn LoadSettings> {
//! println!("Run mode: {}", &global::SETTINGS.app.run_mode); //! Some(&config::SETTINGS)
//! } //! }
//!
//! fn extension_settings() {
//! println!("{}", &config::SETTINGS.myapp.name);
//! println!("{}", &config::SETTINGS.myapp.width);
//! } //! }
//! ``` //! ```
//!
//! 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 crate::{trace, util};
use config::builder::DefaultState; use config::{Config, ConfigError, File, FileFormat};
use config::{Config, ConfigBuilder, File}; use serde::de::{DeserializeOwned, IgnoredAny};
use std::collections::HashMap;
use std::env; use std::env;
use std::fmt; use std::ops::Deref;
use std::path::PathBuf; use std::path::PathBuf;
use std::sync::LazyLock; use std::sync::LazyLock;
@ -147,13 +143,10 @@ const DEFAULT_CONFIG_DIR: &str = "config";
// Modo de ejecución por defecto. // Modo de ejecución por defecto.
const DEFAULT_RUN_MODE: &str = "default"; const DEFAULT_RUN_MODE: &str = "default";
/// Fuentes comunes de la configuración. // 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
/// Se obtienen de los archivos TOML en el orden de carga y el modo de ejecución (`app.run_mode`). // este módulo: así ningún ajuste se salta las comprobaciones de `#[settings]`.
/// static CONFIG_VALUES: LazyLock<Config> = LazyLock::new(|| {
/// 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<ConfigBuilder<DefaultState>> = LazyLock::new(|| {
// CONFIG_DIR (si existe) o DEFAULT_CONFIG_DIR. Si no se puede resolver, se usa tal cual. Sólo // 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 // 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 // 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<ConfigBuilder<DefaultState>> = LazyLock::new(
.add_source(File::from(config_dir.join("local.toml")).required(false)) .add_source(File::from(config_dir.join("local.toml")).required(false))
// Guarda el modo de ejecución explícitamente. // Guarda el modo de ejecución explícitamente.
.set_override("app.run_mode", rm) .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 // Secciones del primer nivel de la configuración.
// usa en su lugar. Lo usan las opciones enumeradas de la configuración al leerse. pub(crate) fn sections() -> Vec<String> {
pub(crate) fn invalid_setting<T: fmt::Debug>(key: &str, raw: &str, default: T) -> T { CONFIG_VALUES
trace::defer_warning(format!( .clone()
"Invalid value \"{raw}\" for {key}, using \"{default:?}\". Check settings" .try_deserialize::<HashMap<String, IgnoredAny>>()
)); .map(|sections| sections.into_keys().collect())
default .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 /// La implementa el atributo [`#[settings(section = "...")]`](crate::settings); no es necesario
/// que no definan los archivos TOML. /// 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: SettingsSection>() -> 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<T: SettingsSection>(toml: &str) -> Result<T, ConfigError> {
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<T: SettingsSection>(config: &Config) -> Result<T, ConfigError> {
match config.get::<T>(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 /// ```rust,ignore
/// include_config!(SETTINGS_NAME: SettingsType => [ /// pub static SETTINGS: LazySettings<BlogSettings> = LazySettings::new();
/// "ruta.clave" => valor,
/// // ...
/// ]);
/// ``` /// ```
/// ///
/// 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 /// ```rust,ignore
/// ajustes. Se recomienda usar `SETTINGS`, aunque no es obligatorio. /// let title = &config::SETTINGS.title;
/// * **`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<String>,
/// pub port: u16,
/// }
///
/// fn print_title() {
/// // Lectura en tiempo de ejecución.
/// println!("Título: {}", SETTINGS.blog.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 /// # Panics
/// opcionales pueden ser `Option<T>`. 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.
/// ///
/// * **Secciones únicas**. Agrupa tus claves dentro de una sección exclusiva (p. ej. `[blog]`) para /// Al cargarse, si la sección no puede deserializarse (un valor no válido o una clave desconocida),
/// evitar colisiones con otras extensiones. /// con un mensaje que indica la sección y el problema.
/// pub struct LazySettings<T: SettingsSection>(LazyLock<T>);
/// * **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 impl<T: SettingsSection> LazySettings<T> {
/// en la documentación de [`config`](crate::config). /// Crea la variable de ajustes de la sección [`SettingsSection::SECTION`] de `T`.
/// pub const fn new() -> Self {
/// * **Errores explícitos**. Si la configuración no puede cargarse, el primer acceso a la variable Self(LazyLock::new(load::<T>))
/// lanza un `panic!` con un mensaje que nombra la estructura de ajustes y el error de origen }
/// (normalmente la clave problemática). }
///
/// # Requisitos // A mano y no derivado: el `Default` de `LazyLock` usaría `T::default()` en lugar de cargar los
/// // ajustes de la configuración.
/// * Cada nivel de las claves debe coincidir con un campo (*snake case*) de la estructura de impl<T: SettingsSection> Default for LazySettings<T> {
/// ajustes o de sus estructuras anidadas. fn default() -> Self {
/// * Añade `serde` con la *feature* `derive` en *Cargo.toml*: Self::new()
/// }
/// ```toml }
/// [dependencies]
/// serde = { version = "1.0", features = ["derive"] } impl<T: SettingsSection> Deref for LazySettings<T> {
/// ``` type Target = T;
#[macro_export]
macro_rules! include_config { fn deref(&self) -> &T {
( $SETTINGS_NAME:ident : $settings_type:ty => [ $( $k:literal => $v:expr ),* $(,)? ] ) => { &self.0
#[doc = concat!( }
"Carga [`", stringify!($settings_type), "`] ", }
"(y aplica **valores por defecto** en claves no definidas)."
)] // **< LoadSettings >*******************************************************************************
#[doc = ""]
#[doc = "Valores predeterminados que se aplican en ausencia de configuración:"] /// Ajustes que PageTop carga durante el arranque.
#[doc = "```text"] ///
$( /// Lo implementa [`LazySettings<T>`] con `T` declarado con
#[doc = concat!($k, " = ", stringify!($v))] /// [`#[settings(section = "...")]`](crate::settings), y las extensiones devuelven esa variable en
)* /// [`Extension::settings()`](crate::core::extension::Extension::settings).
#[doc = "```"] pub trait LoadSettings: Sync {
pub static $SETTINGS_NAME: std::sync::LazyLock<$settings_type> = /// Carga los ajustes si aún no se han cargado.
std::sync::LazyLock::new(|| { fn load(&self);
let mut settings = $crate::config::CONFIG_VALUES.clone();
$( /// Sección de la configuración a la que corresponden los ajustes.
settings = settings.set_default($k, $v) fn section(&self) -> &'static str;
.expect(concat!("Failed to set default for key ", $k)); }
)*
settings impl<T: SettingsSection> LoadSettings for LazySettings<T> {
.build() fn load(&self) {
.expect(concat!("Failed to build config for ", stringify!($settings_type))) LazyLock::force(&self.0);
.try_deserialize::<$settings_type>() }
.expect(concat!("Error parsing settings for ", stringify!($settings_type)))
}); fn section(&self) -> &'static str {
}; T::SECTION
}
} }

View file

@ -336,7 +336,7 @@ impl Context {
/// [`Lc::using()`]. /// [`Lc::using()`].
/// ///
/// [`Context`]: crate::core::component::Context /// [`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::lookup()`]: crate::locale::Lc::lookup
/// [`Lc::using()`]: crate::locale::Lc::using /// [`Lc::using()`]: crate::locale::Lc::using
impl LangId for Context { impl LangId for Context {

View file

@ -3,7 +3,7 @@ use crate::core::extension::ExtensionRef;
use crate::core::theme::ThemeRef; use crate::core::theme::ThemeRef;
use crate::core::theme::all::register_theme; use crate::core::theme::all::register_theme;
use crate::web::Router; 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; 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(&section),
"Settings section [{section}] is claimed by more than one extension"
);
settings.load();
known.push(section);
}
for section in config::sections() {
if !known.contains(&section.as_str()) {
trace::warn!("Unknown settings section [{section}], ignored. Check settings");
}
}
}
// **< INICIALIZA LAS EXTENSIONES >***************************************************************** // **< INICIALIZA LAS EXTENSIONES >*****************************************************************
pub async fn initialize_extensions() { pub async fn initialize_extensions() {

View file

@ -1,5 +1,6 @@
use crate::actions; use crate::actions;
use crate::async_trait; use crate::async_trait;
use crate::config::LoadSettings;
use crate::core::AnyInfo; use crate::core::AnyInfo;
use crate::core::action::ActionBox; use crate::core::action::ActionBox;
use crate::core::theme::ThemeRef; use crate::core::theme::ThemeRef;
@ -143,6 +144,38 @@ pub trait Extension: AnyInfo + Send + Sync {
/// ``` /// ```
async fn initialize(&self) {} 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. /// 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 /// Recibe las rutas acumuladas hasta ese momento, añade lo que la extensión necesite y retorna

View file

@ -39,7 +39,7 @@
//! [ISO 8601]: https://en.wikipedia.org/wiki/ISO_8601 //! [ISO 8601]: https://en.wikipedia.org/wiki/ISO_8601
//! [chrono]: https://docs.rs/chrono //! [chrono]: https://docs.rs/chrono
//! [chrono-tz]: https://docs.rs/chrono-tz //! [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 //! [`CurrentUser::timezone()`]: crate::auth::CurrentUser::timezone
//! [`form::date::Field`]: crate::base::component::form::date::Field //! [`form::date::Field`]: crate::base::component::form::date::Field
//! [`Contextual::format_datetime()`]: crate::core::component::Contextual::format_datetime //! [`Contextual::format_datetime()`]: crate::core::component::Contextual::format_datetime

View file

@ -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()`], /// además las zonas horarias que se pueden elegir ([`supported_by_region()`],
/// [`is_supported_in()`]). /// [`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 /// [`supported_by_region()`]: Self::supported_by_region
/// [`is_supported_in()`]: Self::is_supported_in /// [`is_supported_in()`]: Self::is_supported_in
pub struct Timezone; pub struct Timezone;
@ -375,8 +375,8 @@ impl Timezone {
/// assert!(!is_supported("US/Eastern")); /// assert!(!is_supported("US/Eastern"));
/// ``` /// ```
/// ///
/// [`global::SETTINGS.app.timezone_order`]: crate::global::App::timezone_order /// [`global::SETTINGS.app.timezone_order`]: crate::global::AppSettings::timezone_order
/// [`global::SETTINGS.app.timezone_regions`]: crate::global::App::timezone_regions /// [`global::SETTINGS.app.timezone_regions`]: crate::global::AppSettings::timezone_regions
/// [`form::SelectTimezone`]: crate::base::component::form::SelectTimezone /// [`form::SelectTimezone`]: crate::base::component::form::SelectTimezone
pub fn supported_by_region() -> &'static [(TzRegion, &'static [&'static str])] { pub fn supported_by_region() -> &'static [(TzRegion, &'static [&'static str])] {
&TZ_BY_REGION &TZ_BY_REGION

View file

@ -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; mod lang_negotiation;
pub use lang_negotiation::LangNegotiation; pub use lang_negotiation::LangNegotiation;
@ -21,52 +21,47 @@ pub use log_format::LogFormat;
// **< SETTINGS >*********************************************************************************** // **< SETTINGS >***********************************************************************************
include_config!(SETTINGS: Settings => [ /// Ajustes de las secciones `[app]`, `[dev]`, `[log]` y `[server]`.
// [app] ///
"app.name" => "PageTop App", /// Se cargan al arrancar la aplicación, antes que los ajustes de las extensiones.
"app.theme" => "Basic", pub static SETTINGS: LazyLock<Settings> = LazyLock::new(|| Settings {
"app.lang_negotiation" => "Full", app: config::load(),
"app.timezone" => "UTC", dev: config::load(),
"app.timezone_regions" => "", log: config::load(),
"app.timezone_order" => "Nearest", server: config::load(),
"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,
]);
// **< Settings >*********************************************************************************** // **< Settings >***********************************************************************************
/// Ajustes para las secciones globales [`App`], [`Dev`], [`Log`] y [`Server`] de [`SETTINGS`]. /// Ajustes globales de [`SETTINGS`].
#[derive(Debug, Deserialize)] ///
/// Secciones [`AppSettings`], [`DevSettings`], [`LogSettings`] y [`ServerSettings`].
#[derive(Debug)]
pub struct Settings { pub struct Settings {
pub app: App, pub app: AppSettings,
pub dev: Dev, pub dev: DevSettings,
pub log: Log, pub log: LogSettings,
pub server: Server, pub server: ServerSettings,
} }
// Secciones de los ajustes globales, para reconocerlas en los archivos de configuración.
pub(crate) const SECTIONS: [&str; 4] = [
<AppSettings as config::SettingsSection>::SECTION,
<DevSettings as config::SettingsSection>::SECTION,
<LogSettings as config::SettingsSection>::SECTION,
<ServerSettings as config::SettingsSection>::SECTION,
];
/// Sección **`[app]`** de la configuración. Forma parte de [`Settings`]. /// Sección **`[app]`** de la configuración. Forma parte de [`Settings`].
#[derive(Debug, Deserialize)] #[settings(section = "app")]
pub struct App { pub struct AppSettings {
/// Nombre de la aplicación. /// Nombre de la aplicación.
#[default = "PageTop App"]
pub name: String, pub name: String,
/// Tema predeterminado: *"Basic"* o el de una extensión enlazada por la aplicación, sin /// 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 /// 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). /// arrancar. Ver [`default_theme()`](crate::core::theme::default_theme).
#[default = "Basic"]
pub theme: String, pub theme: String,
/// Idioma predeterminado de la aplicación (p. ej., *"es-ES"* o *"en-US"*). /// 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 /// 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. /// documentos y la generación de URLs. Ver [`LangNegotiation`] para los modos disponibles.
#[default(LangNegotiation::Full)]
pub lang_negotiation: LangNegotiation, pub lang_negotiation: LangNegotiation,
/// Zona horaria predeterminada de la aplicación (p. ej. *"UTC"* o *"Europe/Madrid"*). /// Zona horaria predeterminada de la aplicación (p. ej. *"UTC"* o *"Europe/Madrid"*).
/// ///
@ -133,6 +129,7 @@ pub struct App {
/// `with_order()`. /// `with_order()`.
/// ///
/// [`form::SelectTimezone`]: crate::base::component::form::SelectTimezone /// [`form::SelectTimezone`]: crate::base::component::form::SelectTimezone
#[default(TimezoneOrder::Nearest)]
pub timezone_order: TimezoneOrder, pub timezone_order: TimezoneOrder,
/// Si cada usuario puede tener su propia zona horaria (*true*) o se usa siempre la de la /// Si cada usuario puede tener su propia zona horaria (*true*) o se usa siempre la de la
/// aplicación (*false*). /// aplicación (*false*).
@ -143,9 +140,11 @@ pub struct App {
/// a activar. Es el equivalente de [`LangNegotiation::ConfigOnly`] para el idioma. /// a activar. Es el equivalente de [`LangNegotiation::ConfigOnly`] para el idioma.
/// ///
/// [`CurrentUser::timezone()`]: crate::auth::CurrentUser::timezone /// [`CurrentUser::timezone()`]: crate::auth::CurrentUser::timezone
#[default = true]
pub timezone_per_user: bool, pub timezone_per_user: bool,
/// Banner ASCII mostrado al inicio: *"Off"* (desactivado), *"Slant"*, *"Small"*, *"Speed"* o /// Banner ASCII mostrado al inicio: *"Off"* (desactivado), *"Slant"*, *"Small"*, *"Speed"* o
/// *"Starwars"*. /// *"Starwars"*.
#[default(StartupBanner::Slant)]
pub startup_banner: StartupBanner, pub startup_banner: StartupBanner,
/// Modo de ejecución, dado por la variable de entorno `PAGETOP_RUN_MODE`, o *"default"* si no /// 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"*. /// 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`]. /// Sección **`[dev]`** de la configuración. Forma parte de [`Settings`].
#[derive(Debug, Deserialize)] #[settings(section = "dev")]
pub struct Dev { pub struct DevSettings {
/// Directorio raíz de `static/` para servir los archivos estáticos propios de PageTop. /// 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 /// Si se indica una ruta válida, absoluta o relativa al directorio del proyecto (o, al ejecutar
/// en ejecución, los archivos estáticos se servirán desde disco. Útil para poder modificar los /// el binario, al directorio de trabajo actual), los archivos estáticos se servirán desde
/// archivos estáticos mientras la aplicación está en ejecución, sin necesidad de recompilar. /// 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. /// Si la cadena está vacía, se ignora este ajuste.
pub pagetop_static_dir: String, pub pagetop_static_dir: String,
} }
/// Sección **`[log]`** de la configuración. Forma parte de [`Settings`]. /// Sección **`[log]`** de la configuración. Forma parte de [`Settings`].
#[derive(Debug, Deserialize)] #[settings(section = "log")]
pub struct Log { pub struct LogSettings {
/// Gestión de trazas y registro de eventos activada (*true*) o desactivada (*false*). /// Gestión de trazas y registro de eventos activada (*true*) o desactivada (*false*).
#[default = true]
pub enabled: bool, pub enabled: bool,
/// Opciones, o combinación de opciones separadas por comas, para filtrar las trazas: *"Error"*, /// Opciones, o combinación de opciones separadas por comas, para filtrar las trazas: *"Error"*,
/// *"Warn"*, *"Info"*, *"Debug"* o *"Trace"*. /// *"Warn"*, *"Info"*, *"Debug"* o *"Trace"*.
/// Ejemplo: *"Error,tower_http=Debug,axum::rejection=trace"*. Si no es válido se usa *"Info"*, /// Ejemplo: *"Error,tower_http=Debug,axum::rejection=trace"*. Si no es válido se usa *"Info"*,
/// con un aviso al arrancar. /// con un aviso al arrancar.
#[default = "Info"]
pub tracing: String, pub tracing: String,
/// Muestra los mensajes de traza en el terminal (*"Stdout"*) o los vuelca en archivos con /// Muestra los mensajes de traza en el terminal (*"Stdout"*) o los vuelca en archivos con
/// rotación: *"Daily"*, *"Hourly"*, *"Minutely"* o *"Endless"*. /// rotación: *"Daily"*, *"Hourly"*, *"Minutely"* o *"Endless"*.
#[default(LogRolling::Stdout)]
pub rolling: LogRolling, pub rolling: LogRolling,
/// Directorio para los archivos de traza (si [`rolling`](Self::rolling) ≠ *"Stdout"*). /// Directorio para los archivos de traza (si [`rolling`](Self::rolling) ≠ *"Stdout"*).
#[default = "log"]
pub path: String, pub path: String,
/// Prefijo para los archivos de traza (si [`rolling`](Self::rolling) ≠ *"Stdout"*). /// Prefijo para los archivos de traza (si [`rolling`](Self::rolling) ≠ *"Stdout"*).
#[default = "tracing.log"]
pub prefix: String, pub prefix: String,
/// Formato de salida de las trazas. Opciones: *"Full"*, *"Compact"*, *"Pretty"* o *"Json"*. /// Formato de salida de las trazas. Opciones: *"Full"*, *"Compact"*, *"Pretty"* o *"Json"*.
#[default(LogFormat::Full)]
pub format: LogFormat, pub format: LogFormat,
} }
/// Sección **`[server]`** de la configuración. Forma parte de [`Settings`]. /// Sección **`[server]`** de la configuración. Forma parte de [`Settings`].
#[derive(Debug, Deserialize)] #[settings(section = "server")]
pub struct Server { pub struct ServerSettings {
/// Dirección de enlace para el servidor web. /// Dirección de enlace para el servidor web.
#[default = "localhost"]
pub bind_address: String, pub bind_address: String,
/// Puerto de escucha del servidor web. /// Puerto de escucha del servidor web.
#[default = 8080]
pub bind_port: u16, 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::<AppSettings>(REFERENCE).unwrap();
config::load_from_str::<DevSettings>(REFERENCE).unwrap();
config::load_from_str::<LogSettings>(REFERENCE).unwrap();
config::load_from_str::<ServerSettings>(REFERENCE).unwrap();
}
#[test]
fn enum_values_are_case_insensitive() {
let log = config::load_from_str::<LogSettings>("[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::<LogSettings>("[log]\nrolling = \"Daly\"\n")
.expect_err("invalid value accepted")
.to_string();
assert!(error.contains("Daly"));
assert!(error.contains("Daily"));
}
}

View file

@ -1,13 +1,17 @@
use crate::{AutoDefault, config}; use crate::AutoDefault;
use serde::de::Error;
use serde::{Deserialize, Deserializer}; use serde::{Deserialize, Deserializer};
/// Modos disponibles para negociar el idioma de una petición HTTP. /// Modos disponibles para negociar el idioma de una petición HTTP.
/// ///
/// El ajuste [`global::SETTINGS.app.lang_negotiation`](crate::global::App::lang_negotiation) /// El ajuste [`global::SETTINGS.app.lang_negotiation`] determina qué fuentes intervienen en la
/// determina qué fuentes intervienen en la resolución del idioma efectivo utilizado por /// resolución del idioma efectivo utilizado por [`RequestLocale`] y en la generación de URLs
/// [`RequestLocale`](crate::locale::RequestLocale) y en la generación de URLs mediante /// mediante [`Context::route()`].
/// [`Context::route()`](crate::core::component::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)] #[derive(AutoDefault, Clone, Copy, Debug, Eq, PartialEq)]
pub enum LangNegotiation { pub enum LangNegotiation {
/// Usa todas las fuentes disponibles para determinar el idioma, en este orden: comprueba el /// Usa todas las fuentes disponibles para determinar el idioma, en este orden: comprueba el
@ -18,7 +22,7 @@ pub enum LangNegotiation {
/// comportamiento por defecto. /// comportamiento por defecto.
/// ///
/// [`CurrentUser::language()`]: crate::auth::CurrentUser::language /// [`CurrentUser::language()`]: crate::auth::CurrentUser::language
/// [`global::SETTINGS.app.language`]: crate::global::App::language /// [`global::SETTINGS.app.language`]: crate::global::AppSettings::language
#[default] #[default]
Full, Full,
@ -42,12 +46,14 @@ impl<'de> Deserialize<'de> for LangNegotiation {
D: Deserializer<'de>, D: Deserializer<'de>,
{ {
let raw = String::deserialize(deserializer)?; let raw = String::deserialize(deserializer)?;
let result = match raw.trim().to_ascii_lowercase().as_str() { match raw.trim().to_ascii_lowercase().as_str() {
"full" => Self::Full, "full" => Ok(Self::Full),
"noquery" => Self::NoQuery, "noquery" => Ok(Self::NoQuery),
"configonly" => Self::ConfigOnly, "configonly" => Ok(Self::ConfigOnly),
_ => config::invalid_setting("[app].lang_negotiation", &raw, Self::default()), _ => Err(D::Error::unknown_variant(
}; &raw,
Ok(result) &["Full", "NoQuery", "ConfigOnly"],
)),
}
} }
} }

View file

@ -1,12 +1,13 @@
use crate::{AutoDefault, config}; use crate::AutoDefault;
use serde::de::Error;
use serde::{Deserialize, Deserializer}; use serde::{Deserialize, Deserializer};
/// Formatos disponibles para mostrar las trazas. /// Formatos disponibles para mostrar las trazas.
/// ///
/// El valor se obtiene de [`global::SETTINGS.log.format`](crate::global::Log::format) y determina /// El valor se obtiene de [`global::SETTINGS.log.format`](crate::global::LogSettings::format) y
/// la representación textual de los eventos registrados por `tracing`. /// determina la representación textual de los eventos registrados por `tracing`. El valor
/// El valor configurado no distingue entre mayúsculas y minúsculas. /// configurado no distingue entre mayúsculas y minúsculas.
#[derive(AutoDefault, Clone, Copy, Debug, Eq, PartialEq)] #[derive(AutoDefault, Clone, Copy, Debug, Eq, PartialEq)]
pub enum LogFormat { pub enum LogFormat {
/// Formato JSON estructurado. /// Formato JSON estructurado.
@ -29,13 +30,15 @@ impl<'de> Deserialize<'de> for LogFormat {
D: Deserializer<'de>, D: Deserializer<'de>,
{ {
let raw = String::deserialize(deserializer)?; let raw = String::deserialize(deserializer)?;
let result = match raw.trim().to_ascii_lowercase().as_str() { match raw.trim().to_ascii_lowercase().as_str() {
"json" => Self::Json, "json" => Ok(Self::Json),
"full" => Self::Full, "full" => Ok(Self::Full),
"compact" => Self::Compact, "compact" => Ok(Self::Compact),
"pretty" => Self::Pretty, "pretty" => Ok(Self::Pretty),
_ => config::invalid_setting("[log].format", &raw, Self::default()), _ => Err(D::Error::unknown_variant(
}; &raw,
Ok(result) &["Json", "Full", "Compact", "Pretty"],
)),
}
} }
} }

View file

@ -1,12 +1,13 @@
use crate::{AutoDefault, config}; use crate::AutoDefault;
use serde::de::Error;
use serde::{Deserialize, Deserializer}; use serde::{Deserialize, Deserializer};
/// Modos de salida y rotación para el registro de trazas. /// 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 /// 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. /// determina si las trazas se muestran por pantalla o se vuelcan en archivos con rotación. El valor
/// El valor configurado no distingue entre mayúsculas y minúsculas. /// configurado no distingue entre mayúsculas y minúsculas.
#[derive(AutoDefault, Clone, Copy, Debug, Eq, PartialEq)] #[derive(AutoDefault, Clone, Copy, Debug, Eq, PartialEq)]
pub enum LogRolling { pub enum LogRolling {
/// Escribe las trazas en la salida estándar (sin rotación de archivos). Es el valor por /// 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>, D: Deserializer<'de>,
{ {
let raw = String::deserialize(deserializer)?; let raw = String::deserialize(deserializer)?;
let result = match raw.trim().to_ascii_lowercase().as_str() { match raw.trim().to_ascii_lowercase().as_str() {
"stdout" => Self::Stdout, "stdout" => Ok(Self::Stdout),
"daily" => Self::Daily, "daily" => Ok(Self::Daily),
"hourly" => Self::Hourly, "hourly" => Ok(Self::Hourly),
"minutely" => Self::Minutely, "minutely" => Ok(Self::Minutely),
"endless" => Self::Endless, "endless" => Ok(Self::Endless),
_ => config::invalid_setting("[log].rolling", &raw, Self::default()), _ => Err(D::Error::unknown_variant(
}; &raw,
Ok(result) &["Stdout", "Daily", "Hourly", "Minutely", "Endless"],
)),
}
} }
} }

View file

@ -1,11 +1,14 @@
use crate::{AutoDefault, config}; use crate::AutoDefault;
use serde::de::Error;
use serde::{Deserialize, Deserializer}; use serde::{Deserialize, Deserializer};
/// Opciones para el *banner* ASCII mostrado al arrancar la aplicación. /// 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 /// Se obtiene de [`global::SETTINGS.app.startup_banner`] y controla si se muestra un *banner* en la
/// controla si se muestra un *banner* en la salida estándar al arrancar la aplicación. /// 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)] #[derive(AutoDefault, Clone, Copy, Debug, Eq, PartialEq)]
pub enum StartupBanner { pub enum StartupBanner {
/// No muestra ningún banner de inicio. /// No muestra ningún banner de inicio.
@ -27,14 +30,16 @@ impl<'de> Deserialize<'de> for StartupBanner {
D: Deserializer<'de>, D: Deserializer<'de>,
{ {
let raw = String::deserialize(deserializer)?; let raw = String::deserialize(deserializer)?;
let result = match raw.trim().to_ascii_lowercase().as_str() { match raw.trim().to_ascii_lowercase().as_str() {
"off" => Self::Off, "off" => Ok(Self::Off),
"slant" => Self::Slant, "slant" => Ok(Self::Slant),
"small" => Self::Small, "small" => Ok(Self::Small),
"speed" => Self::Speed, "speed" => Ok(Self::Speed),
"starwars" => Self::Starwars, "starwars" => Ok(Self::Starwars),
_ => config::invalid_setting("[app].startup_banner", &raw, Self::default()), _ => Err(D::Error::unknown_variant(
}; &raw,
Ok(result) &["Off", "Slant", "Small", "Speed", "Starwars"],
)),
}
} }
} }

View file

@ -1,14 +1,16 @@
use crate::{AutoDefault, config}; use crate::AutoDefault;
use serde::de::Error;
use serde::{Deserialize, Deserializer}; use serde::{Deserialize, Deserializer};
/// Criterios para ordenar las regiones de zonas horarias que se ofrecen para elegir. /// 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 /// Se obtiene de [`global::SETTINGS.app.timezone_order`] y determina el orden de los grupos de
/// determina el orden de los grupos de [`Timezone::supported_by_region()`]. Es también el orden /// [`Timezone::supported_by_region()`]. Es también el orden por defecto de
/// por defecto de [`form::SelectTimezone`], que puede cambiarse con `with_order()`. En todos los /// [`form::SelectTimezone`], que puede cambiarse con `with_order()`. En todos los casos el grupo
/// casos el grupo *"Etc"* (`Etc/UTC`) va siempre al final. /// *"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 /// [`Timezone::supported_by_region()`]: crate::datetime::Timezone::supported_by_region
/// [`form::SelectTimezone`]: crate::base::component::form::SelectTimezone /// [`form::SelectTimezone`]: crate::base::component::form::SelectTimezone
#[derive(AutoDefault, Clone, Copy, Debug, Eq, PartialEq)] #[derive(AutoDefault, Clone, Copy, Debug, Eq, PartialEq)]
@ -23,10 +25,11 @@ pub enum TimezoneOrder {
/// ///
/// [`form::SelectTimezone`]: crate::base::component::form::SelectTimezone /// [`form::SelectTimezone`]: crate::base::component::form::SelectTimezone
Alphabetical, Alphabetical,
/// En el orden en que se indican las regiones, en /// En el orden en que se indican las regiones, en [`global::SETTINGS.app.timezone_regions`] o
/// [`global::SETTINGS.app.timezone_regions`](crate::global::App::timezone_regions) o con /// con `SelectTimezone::with_regions()`; si no se indica ninguna región válida, por nombre,
/// `SelectTimezone::with_regions()`; si no se indica ninguna región válida, por nombre, como /// como `TimezoneOrder::Alphabetical`.
/// `TimezoneOrder::Alphabetical`. ///
/// [`global::SETTINGS.app.timezone_regions`]: crate::global::AppSettings::timezone_regions
Listed, Listed,
} }
@ -36,12 +39,14 @@ impl<'de> Deserialize<'de> for TimezoneOrder {
D: Deserializer<'de>, D: Deserializer<'de>,
{ {
let raw = String::deserialize(deserializer)?; let raw = String::deserialize(deserializer)?;
let result = match raw.trim().to_ascii_lowercase().as_str() { match raw.trim().to_ascii_lowercase().as_str() {
"nearest" => Self::Nearest, "nearest" => Ok(Self::Nearest),
"alphabetical" => Self::Alphabetical, "alphabetical" => Ok(Self::Alphabetical),
"listed" => Self::Listed, "listed" => Ok(Self::Listed),
_ => config::invalid_setting("[app].timezone_order", &raw, Self::default()), _ => Err(D::Error::unknown_variant(
}; &raw,
Ok(result) &["Nearest", "Alphabetical", "Listed"],
)),
}
} }
} }

View file

@ -137,7 +137,12 @@ pub const PAGETOP_VERSION: &str = env!("CARGO_PKG_VERSION");
/// [`impl Extension`](crate::core::extension::Extension). /// [`impl Extension`](crate::core::extension::Extension).
pub use async_trait::async_trait; 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}; pub use pagetop_statics::{StaticFile, resource};

View file

@ -4,14 +4,12 @@
pub use crate::PAGETOP_VERSION; 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}; pub use crate::{AutoDefault, CowStr, Getters, StaticResources, UniqueId, Weight};
// MACROS. // MACROS.
// crate::config
pub use crate::include_config;
// crate::locale // crate::locale
pub use crate::include_locales; pub use crate::include_locales;
// crate::web // crate::web
@ -25,6 +23,9 @@ pub use crate::{render_component, setup_component};
pub use crate::util; pub use crate::util;
pub use crate::config;
pub use crate::config::{LazySettings, LoadSettings};
pub use crate::global; pub use crate::global;
pub use crate::trace; pub use crate::trace;

View file

@ -212,8 +212,9 @@ pub fn normalize_ascii(input: &str) -> Option<Cow<'_, str>> {
} }
} }
/// Recorta espacios y pasa a minúsculas el nombre de una propiedad, tratando el resultado vacío /// Recorta espacios y pasa a minúsculas el nombre de una propiedad.
/// como ausencia. ///
/// Si el resultado queda vacío, devuelve `None`.
/// ///
/// # Ejemplo /// # Ejemplo
/// ///

View file

@ -1,40 +1,115 @@
use pagetop::prelude::*; use pagetop::prelude::*;
use serde::Deserialize; use std::sync::atomic::{AtomicBool, Ordering};
include_config!(SETTINGS: Settings => [ // The `testing` *feature* (active with `cargo ts` / `cargo tw`) fixes the "test" run mode at
"test.string_value" => "Test String", // compile time, so that `global::SETTINGS` and any other settings automatically load the "test"
"test.int_value" => -321, // mode configuration from `config/test.toml` (versioned, unlike the `local.*.toml` files).
"test.float_value" => 2.3456,
]);
#[derive(Debug, Deserialize)] #[settings(section = "test")]
pub struct Settings { pub struct TestSettings {
pub test: Test, #[default = "Test String"]
}
#[derive(Debug, Deserialize)]
pub struct Test {
pub string_value: String, pub string_value: String,
#[default(-321)]
pub int_value: i32, pub int_value: i32,
#[default = 2.3456]
pub float_value: f32, pub float_value: f32,
pub nested: NestedSettings,
} }
// The `testing` *feature* (active with `cargo ts` / `cargo tw`) fixes the "test" mode at compile #[settings]
// time inside `config::CONFIG_VALUES`, so that `global::SETTINGS` and any local `include_config!` pub struct NestedSettings {
// automatically load the "test" mode configuration from `config/test.toml` (versioned, unlike the #[default = true]
// `local.*.toml` files). pub enabled: bool,
}
static SETTINGS: LazySettings<TestSettings> = 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] #[pagetop::test]
async fn check_global_config() { async fn check_global_config() {
assert_eq!(global::SETTINGS.app.run_mode, "test"); assert_eq!(global::SETTINGS.app.run_mode, "test");
assert_eq!(global::SETTINGS.app.name, "Testing"); assert_eq!(global::SETTINGS.app.name, "Testing");
assert_eq!(global::SETTINGS.server.bind_port, 9000); 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] #[pagetop::test]
async fn check_local_config() { async fn files_override_defaults_key_by_key() {
assert_eq!(SETTINGS.test.string_value, "Modified value"); assert_eq!(SETTINGS.string_value, "Modified value");
assert_eq!(SETTINGS.test.int_value, -321); assert_eq!(SETTINGS.int_value, -321);
assert_eq!(SETTINGS.test.float_value, 8.7654); assert_eq!(SETTINGS.float_value, 8.7654);
assert!(SETTINGS.nested.enabled);
}
#[pagetop::test]
async fn absent_section_uses_all_defaults() {
static ABSENT: LazySettings<AbsentSettings> = 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::<TestSettings>(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::<TestSettings>(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::<TestSettings>("[test]\nstring_valu = \"typo\"\n")
.expect_err("unknown key accepted")
.to_string();
assert!(error.contains("string_valu"));
} }

View file

@ -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<ClashingSettings> = LazySettings::new();
// `EXTENSIONS` is a global `OnceLock`, so this test needs its own test binary.
struct ClashingExtension;
#[async_trait]
impl Extension for ClashingExtension {
fn settings(&self) -> Option<&'static dyn LoadSettings> {
Some(&SETTINGS)
}
}
#[pagetop::test]
#[should_panic(expected = "Settings section [app] is claimed by more than one extension")]
async fn a_section_claimed_twice_stops_the_startup() {
let _ = Application::prepare(&ClashingExtension).await;
}