♻️ (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

@ -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);
//! }
//!
//! fn extension_settings() {
//! println!("{}", &config::SETTINGS.myapp.name);
//! println!("{}", &config::SETTINGS.myapp.width);
//! impl Extension for Blog {
//! fn settings(&self) -> Option<&'static dyn LoadSettings> {
//! Some(&config::SETTINGS)
//! }
//! }
//! ```
//!
//! Desde cualquier parte del código se leen como `config::SETTINGS.title` o
//! `config::SETTINGS.comments.enabled`. Son de **sólo lectura** durante la ejecución.
//!
//! # Carga y errores
//!
//! PageTop carga los ajustes de todas las extensiones durante el arranque, en el orden en que se
//! registran y antes de inicializarlas. Si unos ajustes no pueden cargarse, la aplicación se
//! detiene con un mensaje que indica el problema: el archivo y la línea si un TOML está mal
//! formado, o la sección y el valor no válido o la **clave desconocida** (típicamente una errata).
//! También avisa al arrancar de las secciones de los archivos que no corresponden a PageTop ni a
//! ninguna extensión.
//!
//! Fuera de una aplicación en marcha (p. ej. en pruebas unitarias) los ajustes se cargan en el
//! primer acceso a la variable, con las mismas reglas.
//!
//! Los ajustes globales de PageTop están en [`global::SETTINGS`](crate::global::SETTINGS).
use crate::{trace, util};
use config::builder::DefaultState;
use config::{Config, ConfigBuilder, File};
use config::{Config, ConfigError, File, FileFormat};
use serde::de::{DeserializeOwned, IgnoredAny};
use std::collections::HashMap;
use std::env;
use std::fmt;
use std::ops::Deref;
use std::path::PathBuf;
use std::sync::LazyLock;
@ -147,13 +143,10 @@ const DEFAULT_CONFIG_DIR: &str = "config";
// Modo de ejecución por defecto.
const DEFAULT_RUN_MODE: &str = "default";
/// Fuentes comunes de la configuración.
///
/// Se obtienen de los archivos TOML en el orden de carga y el modo de ejecución (`app.run_mode`).
///
/// Es la base sobre la que [`include_config!`](crate::include_config) aplica sus valores por
/// defecto antes de deserializar. Los archivos se leen cada vez que se construye la configuración.
pub static CONFIG_VALUES: LazyLock<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
///