♻️ (config): Revisa avisos diferidos y documentación

- Avisa al arrancar si CONFIG_DIR no se puede resolver.
- CONFIG_DIR y PAGETOP_RUN_MODE vacías equivalen a no definirlas.
- `trace::defer_warning()` genérica; detecta su uso tras iniciar trazas.
- `config::invalid_setting()` sustituye `trace::warn_invalid_setting()`.
This commit is contained in:
Manuel Cillero 2026-10-12 07:57:39 +02:00
parent d52cbdef3f
commit 58c48aad16
9 changed files with 143 additions and 69 deletions

View file

@ -10,9 +10,10 @@
# 3. config/local.{rm}.toml -> ajustes locales del modo de ejecución (no se versiona).
# 4. config/local.toml -> ajustes locales para cualquier entorno (no se versiona).
#
# Donde {rm} es el valor de la variable de entorno PAGETOP_RUN_MODE ("default" si no se define).
# El directorio config/ puede cambiarse con la variable de entorno CONFIG_DIR. No hay más
# variables de entorno: el resto de opciones sólo se leen de estos ficheros.
# Donde {rm} es el valor de la variable de entorno PAGETOP_RUN_MODE ("default" si no se define o
# está vacía). El directorio config/ puede cambiarse con la variable de entorno CONFIG_DIR (vacía
# equivale a no definirla). No hay más variables de entorno: el resto de opciones sólo se leen de
# estos ficheros.
#
# Las opciones comentadas no tienen valor por defecto; se muestran con un valor de ejemplo.
#
@ -117,15 +118,6 @@ allow_registration = true # Permite que los visitantes creen su propia
require_email_verification = false # Las cuentas nuevas quedan pendientes ("Pending") en lugar
# de activas hasta verificar el correo.
session_cookie_name = "pgt_session" # Nombre de la cookie de sesión.
session_ttl_secs = 1209600 # Duración de la sesión en segundos si se marca "recordarme"
# al acceder (14 días).
session_idle_ttl_secs = 7200 # Duración de la sesión en segundos sin "recordarme" (2
# horas). Se cuenta desde el acceso, no desde la última
# actividad.
secure_cookie = false # Marca la cookie como Secure (sólo HTTPS). Activar en
# producción.
max_failed_logins = 5 # Intentos fallidos de acceso antes de bloquear la cuenta.
failed_login_window_secs = 900 # Ventana de recuento de intentos fallidos (15 minutos).
# Reservada: todavía no tiene efecto.
@ -134,6 +126,22 @@ locked_for_secs = 600 # Duración del bloqueo de la cuenta en segu
login_strict = false # Dificulta que el navegador recuerde o autorrellene las
# credenciales en el formulario de acceso.
[user.session] # Sesiones de usuario.
cookie_name = "pagetop" # Nombre de la cookie de sesión.
secure_cookie = false # Marca la cookie como Secure (sólo HTTPS). Activar en
# producción.
idle_secs = 7200 # Segundos sin uso tras los que caduca la sesión si no se marca
# "recordarme" al acceder (2 horas). Se cuentan desde la última
# petición.
remember_idle_secs = 1209600 # Segundos sin uso tras los que caduca la sesión si se marca
# "recordarme" al acceder (14 días). Se cuentan igual.
write_interval_secs = 60 # Segundos mínimos entre dos escrituras de la misma sesión en la
# base de datos para prorrogarla. La sesión puede caducar hasta
# este tiempo antes de lo configurado. Subirlo (p. ej. 180)
# reduce escrituras con mucho tráfico o una base de datos lenta;
# bajarlo (o 0, escribir siempre) da más precisión si las
# sesiones caducan tras pocos minutos sin uso.
[user.password] # Contraseñas, cifradas con Argon2id.
argon2_m_cost = 19456 # Coste de memoria en KiB. Si cambia, las contraseñas se
# vuelven a cifrar en el siguiente acceso de cada usuario.

View file

@ -1,17 +1,26 @@
//! Carga las opciones de configuración de la aplicación.
//!
//! Estos ajustes se obtienen de archivos [TOML](https://toml.io) como pares `clave = valor` que se
//! mapean a estructuras **fuertemente tipadas** y valores predefinidos.
//! deserializan en estructuras **fuertemente tipadas**, con valores por defecto para las claves que
//! no se definan.
//!
//! Siguiendo la metodología [Twelve-Factor App](https://12factor.net/config), PageTop separa el
//! **código** de la **configuración**, lo que permite tener configuraciones diferentes para cada
//! despliegue, como *dev*, *staging* o *production*, sin modificar el código fuente.
//! Separar la configuración del código permite que cada despliegue (*dev*, *staging*, *production*,
//! etc.) tenga su propia configuración sin recompilar. Los ajustes sólo se leen de archivos; las
//! variables de entorno no los sobrescriben, únicamente eligen qué archivos cargar (`CONFIG_DIR` y
//! `PAGETOP_RUN_MODE`, cuyo valor queda además en `app.run_mode`).
//!
//! # Orden de carga
//!
//! Si tu aplicación necesita archivos de configuración, crea un directorio `config` en la raíz del
//! proyecto, al mismo nivel que el archivo *Cargo.toml* o que el binario de la aplicación. Puedes
//! cambiar esta ubicación mediante la variable de entorno `CONFIG_DIR`.
//! proyecto, al mismo nivel que el archivo *Cargo.toml*. Puedes cambiar esta ubicación mediante la
//! variable de entorno `CONFIG_DIR` (vacía equivale a no definirla); si no apunta a un directorio
//! existente, se avisa al arrancar.
//!
//! Una ruta relativa, como la predeterminada, se resuelve respecto al directorio del proyecto si
//! está definida la variable de entorno `CARGO_MANIFEST_DIR` (*cargo* la define al ejecutar con
//! `cargo run` o `cargo test`) o, en su defecto, respecto al directorio de trabajo actual. Al
//! ejecutar el binario, lánzalo desde el directorio que contiene `config` o define `CONFIG_DIR` con
//! una ruta absoluta.
//!
//! PageTop carga en este orden, y siempre de forma opcional, los siguientes archivos TOML:
//!
@ -20,8 +29,11 @@
//!
//! 2. **config/{rm}.toml**, donde `{rm}` es el valor de la variable de entorno `PAGETOP_RUN_MODE`:
//!
//! * Si `PAGETOP_RUN_MODE` no está definida, se asume el valor `default`, y PageTop intentará
//! cargar *config/default.toml* si el archivo existe.
//! * Si `PAGETOP_RUN_MODE` no está definida, o está vacía, se asume el valor `default`, y
//! PageTop intentará cargar *config/default.toml* si el archivo existe.
//!
//! * Si se activa la *feature* `testing`, el modo de ejecución es siempre `test` y se ignora
//! `PAGETOP_RUN_MODE`.
//!
//! * Permite definir configuraciones específicas por entorno, garantizando que cada uno (p. ej.,
//! *dev*, *staging* o *production*) disponga de sus propias opciones, como claves de API, URLs
@ -39,8 +51,8 @@
//! 4. **config/local.toml**, para ajustes locales válidos en cualquier entorno, ideal para cambios
//! rápidos o valores temporales que no dependan de un entorno concreto.
//!
//! Los archivos se combinan en el orden anterior, cada archivo sobrescribe a los anteriores en caso
//! de conflicto.
//! 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
//!
@ -85,8 +97,16 @@
//! Se recomienda proporcionar siempre valores por defecto o usar `Option<T>` para los ajustes
//! opcionales.
//!
//! Si la configuración no se inicializa correctamente, la aplicación lanzará *panic* y detendrá la
//! ejecución.
//! 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.
//!
@ -111,12 +131,13 @@
//! }
//! ```
use crate::util;
use crate::{trace, util};
use config::builder::DefaultState;
use config::{Config, ConfigBuilder, File};
use std::env;
use std::fmt;
use std::path::PathBuf;
use std::sync::LazyLock;
@ -126,19 +147,41 @@ const DEFAULT_CONFIG_DIR: &str = "config";
// Modo de ejecución por defecto.
const DEFAULT_RUN_MODE: &str = "default";
/// Valores originales de los archivos de configuración como pares `clave = valor`.
/// 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(|| {
// CONFIG_DIR (si existe) o DEFAULT_CONFIG_DIR. Si no se puede resolver, se usa tal cual.
let dir = env::var_os("CONFIG_DIR").unwrap_or_else(|| DEFAULT_CONFIG_DIR.into());
let config_dir = util::resolve_absolute_dir(&dir).unwrap_or_else(|_| PathBuf::from(&dir));
// 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
// sólo con los valores por defecto sin que nada lo indicara.
let custom_dir = env::var_os("CONFIG_DIR").filter(|dir| !dir.is_empty());
let warn_if_unresolved = custom_dir.is_some();
let dir = custom_dir.unwrap_or_else(|| DEFAULT_CONFIG_DIR.into());
let config_dir = util::resolve_absolute_dir(&dir).unwrap_or_else(|err| {
let dir = PathBuf::from(&dir);
if warn_if_unresolved {
trace::defer_warning(format!(
"CONFIG_DIR \"{}\" cannot be resolved ({err}), using it as given. Check settings",
dir.display()
));
}
dir
});
// Modo de ejecución. Con la *feature* `testing` activa (usada por `cargo ts` y `cargo tw`), se
// fija en "test" en tiempo de compilación, sin manipular el entorno. En caso contrario se lee
// de PAGETOP_RUN_MODE, o se usa DEFAULT_RUN_MODE si la variable no está definida.
// de PAGETOP_RUN_MODE, o se usa DEFAULT_RUN_MODE si la variable no está definida o está vacía.
let rm = if cfg!(feature = "testing") {
"test".to_string()
} else {
env::var("PAGETOP_RUN_MODE").unwrap_or_else(|_| DEFAULT_RUN_MODE.into())
env::var("PAGETOP_RUN_MODE")
.ok()
.filter(|rm| !rm.is_empty())
.unwrap_or_else(|| DEFAULT_RUN_MODE.into())
};
Config::builder()
@ -155,13 +198,25 @@ pub static CONFIG_VALUES: LazyLock<ConfigBuilder<DefaultState>> = LazyLock::new(
.expect("Failed to set application run mode")
});
// 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
}
// **< include_config! >****************************************************************************
/// Incluye los ajustes necesarios de la configuración anticipando valores por defecto.
/// Declara una variable global con los ajustes de configuración.
///
/// Incluye los ajustes necesarios de la configuración, aplicando valores por defecto a las claves
/// que no definan los archivos TOML.
///
/// # Sintaxis
///
/// Hay que añadir en nuestra librería el siguiente código:
/// Se declara en el código de la extensión o de la aplicación así:
///
/// ```rust,ignore
/// include_config!(SETTINGS_NAME: SettingsType => [
@ -177,7 +232,9 @@ pub static CONFIG_VALUES: LazyLock<ConfigBuilder<DefaultState>> = LazyLock::new(
/// * **`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
/// `"seccion.subclave"` para coincidir con el árbol TOML.
/// 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
///
@ -212,21 +269,26 @@ pub static CONFIG_VALUES: LazyLock<ConfigBuilder<DefaultState>> = LazyLock::new(
/// # Buenas prácticas
///
/// * **Valores por defecto**. Declara un valor por defecto para cada clave obligatoria. Las claves
/// opcionales pueden ser `Option<T>`.
/// opcionales pueden ser `Option<T>`. Los valores de esta lista se aplican con `set_default()`
/// antes de deserializar, y sólo en las claves que no defina ningún TOML, así que las estructuras
/// de ajustes no necesitan implementar `Default` ni derivar `AutoDefault`. Si falta una clave
/// obligatoria en los TOML y en la lista, la deserialización falla.
///
/// * **Secciones únicas**. Agrupa tus claves dentro de una sección exclusiva (p. ej. `[blog]`) para
/// evitar colisiones con otras librerías.
/// 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*, *prod*) usa los archivos TOML descritos en la
/// documentación de [`config`](crate::config).
/// configurar distintos entornos (*dev*, *staging*, *production*) usa los archivos TOML descritos
/// en la documentación de [`config`](crate::config).
///
/// * **Errores explícitos**. Si la deserialización falla, la macro lanzará un `panic!` con un
/// mensaje que indica la estructura problemática, facilitando la depuración.
/// * **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
///
/// * Las claves deben coincidir con los campos (*snake case*) de la estructura de ajustes.
/// * 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

View file

@ -148,7 +148,7 @@ pub struct App {
/// *"Starwars"*.
pub startup_banner: StartupBanner,
/// Modo de ejecución, dado por la variable de entorno `PAGETOP_RUN_MODE`, o *"default"* si no
/// está definido.
/// está definida o está vacía. Con la *feature* `testing` activa es siempre *"test"*.
pub run_mode: String,
}

View file

@ -1,4 +1,4 @@
use crate::{AutoDefault, trace};
use crate::{AutoDefault, config};
use serde::{Deserialize, Deserializer};
@ -46,7 +46,7 @@ impl<'de> Deserialize<'de> for LangNegotiation {
"full" => Self::Full,
"noquery" => Self::NoQuery,
"configonly" => Self::ConfigOnly,
_ => trace::warn_invalid_setting("[app].lang_negotiation", &raw, Self::default()),
_ => config::invalid_setting("[app].lang_negotiation", &raw, Self::default()),
};
Ok(result)
}

View file

@ -1,4 +1,4 @@
use crate::{AutoDefault, trace};
use crate::{AutoDefault, config};
use serde::{Deserialize, Deserializer};
@ -34,7 +34,7 @@ impl<'de> Deserialize<'de> for LogFormat {
"full" => Self::Full,
"compact" => Self::Compact,
"pretty" => Self::Pretty,
_ => trace::warn_invalid_setting("[log].format", &raw, Self::default()),
_ => config::invalid_setting("[log].format", &raw, Self::default()),
};
Ok(result)
}

View file

@ -1,4 +1,4 @@
use crate::{AutoDefault, trace};
use crate::{AutoDefault, config};
use serde::{Deserialize, Deserializer};
@ -35,7 +35,7 @@ impl<'de> Deserialize<'de> for LogRolling {
"hourly" => Self::Hourly,
"minutely" => Self::Minutely,
"endless" => Self::Endless,
_ => trace::warn_invalid_setting("[log].rolling", &raw, Self::default()),
_ => config::invalid_setting("[log].rolling", &raw, Self::default()),
};
Ok(result)
}

View file

@ -1,4 +1,4 @@
use crate::{AutoDefault, trace};
use crate::{AutoDefault, config};
use serde::{Deserialize, Deserializer};
@ -33,7 +33,7 @@ impl<'de> Deserialize<'de> for StartupBanner {
"small" => Self::Small,
"speed" => Self::Speed,
"starwars" => Self::Starwars,
_ => trace::warn_invalid_setting("[app].startup_banner", &raw, Self::default()),
_ => config::invalid_setting("[app].startup_banner", &raw, Self::default()),
};
Ok(result)
}

View file

@ -1,4 +1,4 @@
use crate::{AutoDefault, trace};
use crate::{AutoDefault, config};
use serde::{Deserialize, Deserializer};
@ -40,7 +40,7 @@ impl<'de> Deserialize<'de> for TimezoneOrder {
"nearest" => Self::Nearest,
"alphabetical" => Self::Alphabetical,
"listed" => Self::Listed,
_ => trace::warn_invalid_setting("[app].timezone_order", &raw, Self::default()),
_ => config::invalid_setting("[app].timezone_order", &raw, Self::default()),
};
Ok(result)
}

View file

@ -22,24 +22,28 @@ pub use tracing::{debug_span, error_span, info_span, trace_span, warn_span};
use tracing_appender::non_blocking::WorkerGuard;
use tracing_subscriber::EnvFilter;
use std::fmt;
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::{Mutex, PoisonError};
// Avisos generados antes de iniciar las trazas. La configuración se lee antes, porque las trazas
// dependen de la sección `[log]`, así que sus avisos se guardan aquí y se emiten al iniciarlas.
static DEFERRED_WARNINGS: Mutex<Vec<String>> = Mutex::new(Vec::new());
// Vale `None` cuando `init()` ya los ha procesado.
static DEFERRED_WARNINGS: Mutex<Option<Vec<String>>> = Mutex::new(Some(Vec::new()));
// 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 warn_invalid_setting<T: fmt::Debug>(key: &str, raw: &str, default: T) -> T {
DEFERRED_WARNINGS
// Guarda un aviso para emitirlo al iniciar las trazas. Sólo debe usarse antes de iniciarlas, lo que
// basta para la configuración global, que `init()` lee antes de recoger los avisos. Usarla después
// es un error de programación: se emite como `error!` con el aviso incluido, para que no se pierda.
pub(crate) fn defer_warning(message: String) {
let mut deferred = DEFERRED_WARNINGS
.lock()
.unwrap_or_else(PoisonError::into_inner)
.push(format!(
"Invalid value \"{raw}\" for {key}, using \"{default:?}\". Check settings"
));
default
.unwrap_or_else(PoisonError::into_inner);
match deferred.as_mut() {
Some(warnings) => warnings.push(message),
None => {
drop(deferred);
error!("defer_warning() called after tracing started: {message}");
}
}
}
// Inicia las trazas y el registro de eventos de la aplicación, sólo la primera vez que se llama.
@ -64,11 +68,11 @@ pub(crate) fn init() -> Option<WorkerGuard> {
let enabled = global::SETTINGS.log.enabled && !cfg!(test) && !cfg!(feature = "testing");
// Al leer `SETTINGS` en la línea anterior ya se han guardado los avisos de la configuración.
let mut warnings = std::mem::take(
&mut *DEFERRED_WARNINGS
let mut warnings = DEFERRED_WARNINGS
.lock()
.unwrap_or_else(PoisonError::into_inner),
);
.unwrap_or_else(PoisonError::into_inner)
.take() // Deja `None`, desde ahora, `defer_warning()` trata cualquier aviso como mal uso.
.unwrap_or_default();
if !enabled {
// Tracing desactivado, se instala un subscriber nulo.
tracing::subscriber::set_global_default(tracing::subscriber::NoSubscriber::default())