From 58c48aad164cc86cab6972e0b7b2976bfda75ff4 Mon Sep 17 00:00:00 2001 From: Manuel Cillero Date: Mon, 12 Oct 2026 07:57:39 +0200 Subject: [PATCH] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20(config):=20Revisa=20aviso?= =?UTF-8?q?s=20diferidos=20y=20documentaci=C3=B3n?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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()`. --- config/reference.toml | 32 +++++---- src/config.rs | 122 +++++++++++++++++++++++++-------- src/global.rs | 2 +- src/global/lang_negotiation.rs | 4 +- src/global/log_format.rs | 4 +- src/global/log_rolling.rs | 4 +- src/global/startup_banner.rs | 4 +- src/global/timezone_order.rs | 4 +- src/trace.rs | 36 +++++----- 9 files changed, 143 insertions(+), 69 deletions(-) diff --git a/config/reference.toml b/config/reference.toml index a99ad6d7..86f5d693 100644 --- a/config/reference.toml +++ b/config/reference.toml @@ -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. diff --git a/src/config.rs b/src/config.rs index 7c7580cb..b3c66350 100644 --- a/src/config.rs +++ b/src/config.rs @@ -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` 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> = 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> = 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(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> = 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 /// @@ -200,7 +257,7 @@ pub static CONFIG_VALUES: LazyLock> = LazyLock::new( /// pub struct Blog { /// pub title: String, /// pub description: Option, -/// pub port: u16, +/// pub port: u16, /// } /// /// fn print_title() { @@ -212,21 +269,26 @@ pub static CONFIG_VALUES: LazyLock> = LazyLock::new( /// # Buenas prácticas /// /// * **Valores por defecto**. Declara un valor por defecto para cada clave obligatoria. Las claves -/// opcionales pueden ser `Option`. +/// opcionales pueden ser `Option`. Los valores de esta lista se aplican con `set_default()` +/// antes de deserializar, y sólo en las claves que no defina ningún TOML, así que las estructuras +/// de ajustes no necesitan implementar `Default` ni derivar `AutoDefault`. Si falta una clave +/// obligatoria en los TOML y en la lista, la deserialización falla. /// /// * **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 diff --git a/src/global.rs b/src/global.rs index bfd51643..ff64a7b3 100644 --- a/src/global.rs +++ b/src/global.rs @@ -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, } diff --git a/src/global/lang_negotiation.rs b/src/global/lang_negotiation.rs index 53f65cd4..ed30344f 100644 --- a/src/global/lang_negotiation.rs +++ b/src/global/lang_negotiation.rs @@ -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) } diff --git a/src/global/log_format.rs b/src/global/log_format.rs index d72b9810..75cb3362 100644 --- a/src/global/log_format.rs +++ b/src/global/log_format.rs @@ -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) } diff --git a/src/global/log_rolling.rs b/src/global/log_rolling.rs index ee3829d4..a641d088 100644 --- a/src/global/log_rolling.rs +++ b/src/global/log_rolling.rs @@ -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) } diff --git a/src/global/startup_banner.rs b/src/global/startup_banner.rs index cdc447fb..3b3f61f9 100644 --- a/src/global/startup_banner.rs +++ b/src/global/startup_banner.rs @@ -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) } diff --git a/src/global/timezone_order.rs b/src/global/timezone_order.rs index b265e02f..2b5e6b6c 100644 --- a/src/global/timezone_order.rs +++ b/src/global/timezone_order.rs @@ -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) } diff --git a/src/trace.rs b/src/trace.rs index 3d8d32b9..9b69e176 100644 --- a/src/trace.rs +++ b/src/trace.rs @@ -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> = Mutex::new(Vec::new()); +// Vale `None` cuando `init()` ya los ha procesado. +static DEFERRED_WARNINGS: Mutex>> = 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(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 { 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 - .lock() - .unwrap_or_else(PoisonError::into_inner), - ); + let mut warnings = DEFERRED_WARNINGS + .lock() + .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())