♻️ (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.
#
# 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.
@ -164,3 +166,5 @@ list_page_size = 20 # Filas por página en los listados de admin
[bootsier]
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:
//!
@ -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<BootsierSettings> = 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::<BootsierSettings>(REFERENCE).unwrap();
}
}

View file

@ -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()

View file

@ -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())

View file

@ -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<DatabaseSettings> = 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<u16>,
/// 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::<DatabaseSettings>(REFERENCE).unwrap();
}
}

View file

@ -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::<ConnectOptions>({
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

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
//! [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<UserSettings> = 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<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.
/// 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<String>,
}
/// 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::<UserSettings>(REFERENCE).unwrap();
}
}

View file

@ -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<ExtensionRef> {
vec![
&pagetop_admin::Admin,

View file

@ -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<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_`.
///
/// 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
// 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`],
/// `Cow<str>`...) 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<str>`...) 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

View file

@ -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();

View file

@ -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 {

View file

@ -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.

View file

@ -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<TzRegion>,
/// 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,
}

View file

@ -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<BlogSettings> = 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<String>,
//! /// Comentarios, en la subsección `[blog.comments]`.
//! pub comments: CommentsSettings,
//! }
//!
//! #[derive(Debug, Deserialize)]
//! pub struct MyApp {
//! pub name: String,
//! pub description: Option<String>,
//! 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<T>` 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);
//! impl Extension for Blog {
//! fn settings(&self) -> Option<&'static dyn LoadSettings> {
//! 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 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<ConfigBuilder<DefaultState>> = 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<Config> = 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<ConfigBuilder<DefaultState>> = 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<T: fmt::Debug>(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<String> {
CONFIG_VALUES
.clone()
.try_deserialize::<HashMap<String, IgnoredAny>>()
.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: 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
/// include_config!(SETTINGS_NAME: SettingsType => [
/// "ruta.clave" => valor,
/// // ...
/// ]);
/// pub static SETTINGS: LazySettings<BlogSettings> = 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<String>,
/// 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<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.
/// # 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<T: SettingsSection>(LazyLock<T>);
impl<T: SettingsSection> LazySettings<T> {
/// Crea la variable de ajustes de la sección [`SettingsSection::SECTION`] de `T`.
pub const fn new() -> Self {
Self(LazyLock::new(load::<T>))
}
}
// A mano y no derivado: el `Default` de `LazyLock` usaría `T::default()` en lugar de cargar los
// ajustes de la configuración.
impl<T: SettingsSection> Default for LazySettings<T> {
fn default() -> Self {
Self::new()
}
}
impl<T: SettingsSection> Deref for LazySettings<T> {
type Target = T;
fn deref(&self) -> &T {
&self.0
}
}
// **< LoadSettings >*******************************************************************************
/// Ajustes que PageTop carga durante el arranque.
///
/// Lo implementa [`LazySettings<T>`] 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<T: SettingsSection> LoadSettings for LazySettings<T> {
fn load(&self) {
LazyLock::force(&self.0);
}
fn section(&self) -> &'static str {
T::SECTION
}
}

View file

@ -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 {

View file

@ -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(&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 >*****************************************************************
pub async fn initialize_extensions() {

View file

@ -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

View file

@ -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

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()`],
/// [`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

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;
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<Settings> = 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] = [
<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`].
#[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::<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};
/// 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"],
)),
}
}
}

View file

@ -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"],
)),
}
}
}

View file

@ -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"],
)),
}
}
}

View file

@ -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"],
)),
}
}
}

View file

@ -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"],
)),
}
}
}

View file

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

View file

@ -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;

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
/// como ausencia.
/// Recorta espacios y pasa a minúsculas el nombre de una propiedad.
///
/// Si el resultado queda vacío, devuelve `None`.
///
/// # Ejemplo
///

View file

@ -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<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]
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<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;
}