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

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