manuelcillero/pagetop
manuelcillero/pagetop
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions

📝 [config] Finalizada documentación básica

Browse source
This commit is contained in:
Manuel Cillero 2022-10-21 20:45:10 +02:00
parent 1ef709ab97
commit 3167c3780d
6 changed files with 200 additions and 274 deletions
Download patch file Download diff file Expand all files Collapse all files

1
pagetop/Cargo.toml
View file

@ -24,7 +24,6 @@ categories = [
[dependencies] [dependencies]
async-trait = "0.1.57" async-trait = "0.1.57"
concat-string = "1.0.1" concat-string = "1.0.1"
doc-comment = "0.3.3"
figlet-rs = "0.1.4" figlet-rs = "0.1.4"
futures = "0.3.24" futures = "0.3.24"
once_cell = "1.15.0" once_cell = "1.15.0"

3
pagetop/src/app/application.rs
View file

@ -38,9 +38,6 @@ impl Application {
// Registra acciones de los módulos. // Registra acciones de los módulos.
module::all::register_actions(); module::all::register_actions();
// Inicializa valores predefinidos de configuración.
// module::all::init_settings();
// Inicializa los módulos. // Inicializa los módulos.
module::all::init_modules(); module::all::init_modules();

454
pagetop/src/config.rs
View file

@ -1,34 +1,36 @@
//! Gestión de la configuración. //! Gestión de la configuración.
//! //!
//! Carga durante el arranque la configuración de la aplicación en forma de pares `clave = valor` //! Carga la configuración de la aplicación en forma de pares `clave = valor` recogidos en archivos
//! recogidos en archivos [TOML](https://toml.io). //! [TOML](https://toml.io).
//! //!
//! La metodología [The Twelve-Factor App](https://12factor.net/es/) define **la configuración de //! La metodología [The Twelve-Factor App](https://12factor.net/es/) define **la configuración de
//! una aplicación como todo lo que puede variar entre despliegues**, diferenciando entre entornos //! una aplicación como todo lo que puede variar entre despliegues**, diferenciando entre entornos
//! de desarrollo, pre-producción, producción, etc. //! de desarrollo, pre-producción, producción, etc.
//! //!
//! A veces las aplicaciones guardan configuraciones como constantes en el código, lo que supone una //! A veces las aplicaciones guardan configuraciones como constantes en el código, lo que implica
//! violación de esta metodología. Debe existir una **estricta separación entre la configuración y //! una violación de esta metodología. PageTop recomienda una **estricta separación entre código y
//! el código**. La configuración variará sustancialmente en cada despliegue, el código no. //! configuración**. La configuración variará en cada tipo de despliegue, y el código no.
//!
//! //!
//! # Cómo usar archivos de configuración //! # Cómo usar archivos de configuración
//! //!
//! Si tu aplicación requiere archivos de configuración debes crear un directorio llamado *config* al //! Si tu aplicación requiere archivos de configuración debes crear un directorio llamado *config*
//! mismo nivel del archivo *Cargo.toml* de tu proyecto (o del ejecutable binario de la aplicación). //! al mismo nivel del archivo *Cargo.toml* de tu proyecto (o del ejecutable binario de la
//! aplicación).
//! //!
//! Guarda la configuración usando archivos TOML asumiendo el siguiente orden de lectura secuencial //! Guarda la configuración usando archivos TOML asumiendo el siguiente orden de lectura secuencial
//! (todos los archivos son opcionales): //! (todos los archivos son opcionales):
//! //!
//! 1. *config/common.toml*, útil para los ajustes comunes para cualquier entorno. Estos valores //! 1. **config/common.toml**, útil para los ajustes comunes para cualquier entorno. Estos valores
//! podrán ser sobrescritos al fusionar los archivos de configuración siguientes. //! podrán ser sobrescritos al fusionar los archivos de configuración siguientes.
//! //!
//! 2. *config/{archivo}.toml*, donde *{archivo}* puede definirse mediante la variable de entorno //! 2. **config/{archivo}.toml**, donde *{archivo}* puede definirse mediante la variable de entorno
//! PAGETOP_RUN_MODE: //! PAGETOP_RUN_MODE:
//! //!
//! * Si no está definida, se asumirá *default* por defecto, y PageTop cargará el archivo de //! * Si no lo está, se asumirá *default* por defecto, y PageTop cargará el archivo de
//! configuración *config/default.toml* si existe. //! configuración *config/default.toml* si existe.
//! //!
//! * De esta manera, se pueden tener diferentes ajustes de configuración para diferentes //! * De esta manera se pueden tener diferentes ajustes de configuración para diferentes
//! entornos de ejecución. Por ejemplo, para *devel.toml*, *staging.toml* o *production.toml*. //! entornos de ejecución. Por ejemplo, para *devel.toml*, *staging.toml* o *production.toml*.
//! O también para *server1.toml* o *server2.toml*. Sólo uno será cargado. //! O también para *server1.toml* o *server2.toml*. Sólo uno será cargado.
//! //!
@ -36,158 +38,90 @@
//! sensible asociada al entorno correspondiente. Estos archivos no deberían ser publicados en //! sensible asociada al entorno correspondiente. Estos archivos no deberían ser publicados en
//! el repositorio Git por razones de seguridad. //! el repositorio Git por razones de seguridad.
//! //!
//! 3. *config/local.toml*, para añadir o sobrescribir ajustes. //! 3. **config/local.toml**, para añadir o sobrescribir ajustes previos.
//! //!
//! # Cómo añadir valores predefinidos de configuración //! Los ajustes de configuración siempre son de sólo lectura.
//!
//! Si nuestra **aplicación** o **módulo** requiere sus propios ajustes de configuración, es
//! recomendable (aunque no imprescindible) inicializarlos antes de su uso.
//!
//! Sólo tienes que añadir el método [`settings()`](crate::core::module::ModuleTrait::settings) al
//! implementar [`ModuleTrait`](crate::core::module::ModuleTrait) para tu módulo, devolviendo los
//! nuevos valores predefinidos con la macro [`predefined_settings!`](crate::predefined_settings).
//!
//! Cuando se carga la configuración de la aplicación, estos valores podrán ser sobrescritos con los
//! ajustes personalizados del entorno. Y sólo será realmente necesario incluir en los archivos de
//! configuración los ajustes que difieran de los predefinidos.
//!
//! ```
//! use pagetop::prelude::*;
//!
//! pub_const_handler!(MY_MODULE_HANDLER);
//!
//! pub struct MyModule;
//!
//! impl ModuleTrait for MyModule {
//! fn handler(&self) -> Handler {
//! MY_MODULE_HANDLER
//! }
//!
//! fn settings(&self) -> PredefinedSettings {
//! predefined_settings![
//! // Valores predefinidos para "my_module".
//! "my_module.name" => "Name",
//! "my_module.desc" => "Description",
//! // Valores predefinidos para "my_module.database".
//! "my_module.database.db_port" => "3306"
//! ]
//! }
//! }
//! ```
//!
//! # Cómo obtener los valores de configuración
//!
//! ```
//! use pagetop::config;
//!
//! // Obtiene el valor (String) de una clave.
//! let name: String = config::get("my_module.name");
//!
//! // Obtiene el valor (del tipo especificado) de una clave.
//! let db_port: u16 = config::get_value::<u16>("my_module.database.db_port");
//! ```
//! //!
//! //!
//! # Cómo añadir ajustes de configuración
//! //!
//! Puedes usar la sintaxis de TOML para crear nuevas secciones en los archivos de configuración,
//! del mismo modo que *\[app\]* o *\[webserver\]* existen en la configuración predeterminada (ver
//! [`SETTINGS`]).
//! //!
//! //! Para cargar y usar esta nueva configuración desde tu **aplicación** o **módulo** tienes que
//! //! incluir [*serde*](https://docs.rs/serde) en las dependencias de tu archivo *Cargo.toml*:
//!
//!
//!
//!
//! # Loading specific type-safe settings
//!
//! You can use the TOML syntax to create new sections in your configuration
//! files, just as *\[app\]*, *\[webserver\]* or *\[database\]* exist in global
//! settings. Or also add new settings in existing sections.
//!
//! Then you just have to load the configuration to use it from your module or
//! application.
//!
//! To do this, add [*serde*](https://docs.rs/serde) in your application's
//! *Cargo.toml*:
//! //!
//! ``` //! ```
//! [dependencies] //! [dependencies]
//! serde = { version = "1.0", features = ["derive"] } //! serde = { version = "1.0", features = ["derive"] }
//! ``` //! ```
//! //!
//! and use the [`config_map!`] macro to create a new static as follows: //! y añadir en tu código una declaración similar a la que utiliza [`SETTINGS`] para instanciar
//! ([`LazyStatic`]) e inicializar ([`init_settings()`]) los nuevos ajustes con tipos seguros y
//! valores predefinidos ([`predefined_settings!`](crate::predefined_settings)):
//! //!
//! ``` //! ```
//! use pagetop::config_map; //! use pagetop::prelude::*;
//! use serde::Deserialize; //! use serde::Deserialize;
//! use std::fmt::Debug;
//! //!
//! #[derive(Debug, Deserialize)] //! #[derive(Debug, Deserialize)]
//! pub struct Section1 { //! pub struct Id {
//! pub var1: String, //! pub name: String,
//! pub var2: u16, //! pub desc: String,
//! } //! }
//! //!
//! #[derive(Debug, Deserialize)] //! #[derive(Debug, Deserialize)]
//! pub struct MySettings { //! pub struct Size {
//! pub section1: Section1, //! pub width: u16,
//! pub height: u16,
//! } //! }
//! //!
//! config_map!("Application settings.", MYSETTINGS, MySettings); //! #[derive(Debug, Deserialize)]
//! pub struct MyApp {
//! pub id: Id,
//! pub size: Size,
//! }
//!
//! pub static MY_APP: LazyStatic<MyApp> = LazyStatic::new(|| {
//! init_settings::<MyApp>(predefined_settings!(
//! // [id]
//! "id.name" => "Value Name",
//! "id.desc" => "Value Description",
//!
//! // [size]
//! "size.width" => "900",
//! "size.height" => "320"
//! ))
//! });
//! ``` //! ```
//! //!
//! Use the first argument of [`config_map!`] for documentation purposes. //! Es importante inicializar todos los ajustes con valores predefinidos (aunque sea con valores
//! vacíos como *""* o *"0"*, por ejemplo) para evitar *panic!*'s no deseados.
//! //!
//! If `MYSETTINGS` contains variables that are not defined in the configuration //!
//! files, the application will *panic!*. To avoid this, you can initialize the //! # Cómo obtener los valores de configuración
//! key=value settings with default values: //!
//! Basta con acceder directamente a la variable estática. Por ejemplo, con [`SETTINGS`]:
//! //!
//! ``` //! ```
//! config_map!(r#" //! use pagetop::prelude::*;
//! My configuration settings for *section1* section. //!
//! "#, //! fn demo() {
//! MYSETTINGS, //! println!("App name: {}", &SETTINGS.app.name);
//! MySettings, //! println!("App description: {}", &SETTINGS.app.description);
//! "section1.var1" => "seven", //! println!("Value of PAGETOP_RUN_MODE: {}", &SETTINGS.app.run_mode);
//! "section1.var2" => 7 //! }
//! );
//! ``` //! ```
//! O a valores específicos de la configuración de tu **aplicación** o **módulo**:
//! //!
//! # How to access configuration //! ```
//! //! fn demo() {
//! * **Using the** [`config_get!`] **macro** //! println!("{}", &MY_APP.id.name);
//! //! println!("{}", &MY_APP.size.width);
//! It will return the value assigned for a given key or an empty String ("") //! }
//! if it doesn't exist: //! ```
//!
//! ```
//! use pagetop::config_get;
//!
//! fn demo() {
//! println!("Address: {}", config_get!("webserver.bind_address"));
//! println!("Port: {}", config_get!("webserver.bind_port"));
//! }
//! ```
//!
//! * Or **using the static** [`SETTINGS`] **to get type-safe global settings**
//!
//! ```
//! use pagetop::config::SETTINGS;
//!
//! fn demo() {
//! println!("App name: {}", &SETTINGS.app.name);
//! println!("App description: {}", &SETTINGS.app.description);
//! println!("Value of PAGETOP_RUN_MODE: {}", &SETTINGS.app.run_mode);
//! }
//! ```
//!
//! * Or **using statics to get specific type-safe settings**
//!
//! Use this for your module or application specific configuration settings.
//!
//! ```
//! fn demo() {
//! println!("{}", &MYSETTINGS.section1.var1);
//! println!("{}", &MYSETTINGS.section1.var2);
//! }
//! ```
mod data; mod data;
mod de; mod de;
@ -197,25 +131,45 @@ mod path;
mod source; mod source;
mod value; mod value;
use crate::{trace, LazyStatic}; use crate::LazyStatic;
use crate::config::data::ConfigData; use crate::config::data::ConfigData;
use crate::config::file::File; use crate::config::file::File;
use serde::Deserialize;
use std::env; use std::env;
use std::fmt::Debug; use std::fmt::Debug;
use std::str::FromStr; use std::collections::HashMap;
use serde::Deserialize;
/// Un *HashMap* con una lista de literales `"clave" => "valor"` para asignar ajustes de
/// configuración predefinidos.
///
/// Ver [`cómo añadir ajustes de configuración`](index.html#cómo-añadir-ajustes-de-configuración).
pub type PredefinedSettings = HashMap<&'static str, &'static str>;
#[macro_export]
/// Macro para crear e inicializar un *HashMap* ([`PredefinedSettings`]) con una lista de literales
/// `"clave" => "valor"` para asignar ajustes de configuración predefinidos.
///
/// Ver [`cómo añadir ajustes de configuración`](config/index.html#cómo-añadir-ajustes-de-configuración).
macro_rules! predefined_settings {
( $($key:literal => $value:literal),* ) => {{
#[allow(unused_mut)]
let mut a = PredefinedSettings::new();
$(
a.insert($key, $value);
)*
a
}};
}
/// Directorio donde se encuentran los archivos de configuración. /// Directorio donde se encuentran los archivos de configuración.
const CONFIG_DIR: &str = "config"; const CONFIG_DIR: &str = "config";
/// Original key=value settings loaded on application startup. /// Todos los valores originales de la configuración en forma de pares `clave = valor` recogidos de
/// Asigna los ajustes específicos de la aplicación, o de un tema, módulo o componente, en una /// los archivos de configuración.
/// estructura similar a [`SETTINGS`] con tipos de variables seguros. Produce un *panic!* en caso de static CONFIG_DATA: LazyStatic<ConfigData> = LazyStatic::new(|| {
/// asignaciones no válidas.
pub static CONFIG: LazyStatic<ConfigData> = LazyStatic::new(|| {
// Modo de ejecución según la variable de entorno PAGETOP_RUN_MODE. Por defecto 'default'. // Modo de ejecución según la variable de entorno PAGETOP_RUN_MODE. Por defecto 'default'.
let run_mode = env::var("PAGETOP_RUN_MODE").unwrap_or_else(|_| "default".into()); let run_mode = env::var("PAGETOP_RUN_MODE").unwrap_or_else(|_| "default".into());
@ -224,7 +178,7 @@ pub static CONFIG: LazyStatic<ConfigData> = LazyStatic::new(|| {
// Combina los archivos de configuración y asigna el modo de ejecución. // Combina los archivos de configuración y asigna el modo de ejecución.
settings settings
// Primero añade configuración común a todos los entornos. Opcional. // Primero añade la configuración común a todos los entornos. Opcional.
.merge(File::with_name(&format!("{}/{}.toml", CONFIG_DIR, "common")).required(false)) .merge(File::with_name(&format!("{}/{}.toml", CONFIG_DIR, "common")).required(false))
.unwrap() .unwrap()
@ -243,147 +197,137 @@ pub static CONFIG: LazyStatic<ConfigData> = LazyStatic::new(|| {
settings settings
}); });
#[macro_export] /// Carga ajustes con tipos seguros y valores predefinidos para tu aplicación o módulo en una
/// Loads specific type-safe settings for your module or application in a structure similar to /// estructura similiar a [`SETTINGS`].
/// [`SETTINGS`].
/// ///
/// See [`How to load specific type-safe settings`](config/index.html#loading-specific-type-safe-settings). /// Ver [`Cómo añadir ajustes de configuración`](index.html#cómo-añadir-ajustes-de-configuración).
macro_rules! pub_config_map { pub fn init_settings<T>(values: PredefinedSettings) -> T
( where T: Deserialize<'static>
$doc:expr, {
$SETTINGS:ident, let mut settings = CONFIG_DATA.clone();
$Type:tt for (key, value) in values.iter() {
$(, $key:expr => $value:expr)* settings.set_default(*key, *value).unwrap();
) => { }
$crate::doc_comment! { match settings.try_into() {
concat!($doc), Ok(c) => c,
Err(e) => panic!("Error parsing settings: {}", e),
pub static $SETTINGS: $crate::LazyStatic<$Type> = $crate::LazyStatic::new(|| {
let mut settings = $crate::config::CONFIG.clone();
$(
settings.set_default($key, $value).unwrap();
)*
match settings.try_into() {
Ok(c) => c,
Err(e) => panic!("Error parsing settings: {}", e),
}
});
}
};
}
/// Devuelve el valor (del tipo especificado) de una clave.
///
/// See [`How to access configuration`](config/index.html#how-to-access-configuration).
pub fn get<T: FromStr + Default>(key: &str) -> T where <T as FromStr>::Err: Debug {
match CONFIG.get_str(key) {
Ok(value) => match value.parse::<T>() {
Ok(value) => value,
_ => {
trace::warn!("Failed to parse value for key \"{}\"! Return default empty value", key);
Default::default()
}
},
_ => {
trace::warn!("Can't get config value for key \"{}\"! Return default empty value", key);
Default::default()
}
} }
} }
#[rustfmt::skip]
#[derive(Debug, Deserialize)] #[derive(Debug, Deserialize)]
/// Sección *\[app\]* de la configuración global.
pub struct App { pub struct App {
pub name : String, /// Valor predefinido: *"PageTop Application"*
pub description : String, pub name: String,
pub theme : String, /// Valor predefinido: *"Developed with the amazing PageTop framework."*
pub language : String, pub description: String,
pub direction : String, /// Valor predefinido: *"Bootsier"*
pub theme: String,
/// Valor predefinido: *"en-US"*
pub language: String,
/// Valor predefinido: *"ltr"*
pub direction: String,
/// Valor predefinido: *"Slant"*
pub startup_banner: String, pub startup_banner: String,
pub run_mode : String, /// Valor predefinido: según variable de entorno PAGETOP_RUN_MODE, o *"default"* si no lo está
pub run_mode: String,
} }
#[rustfmt::skip]
#[derive(Debug, Deserialize)] #[derive(Debug, Deserialize)]
/// Sección *\[log\]* de la configuración global.
pub struct Log { pub struct Log {
pub tracing : String, /// Valor predefinido: *"Info"*
pub rolling : String, pub tracing: String,
pub path : String, /// Valor predefinido: *"Stdout"*
pub prefix : String, pub rolling: String,
pub format : String, /// Valor predefinido: *"log"*
pub path: String,
/// Valor predefinido: *"tracing.log"*
pub prefix: String,
/// Valor predefinido: *"Full"*
pub format: String,
} }
#[rustfmt::skip]
#[derive(Debug, Deserialize)] #[derive(Debug, Deserialize)]
/// Sección *\[database\]* de la configuración global.
pub struct Database { pub struct Database {
pub db_type : String, /// Valor predefinido: *""*
pub db_name : String, pub db_type: String,
pub db_user : String, /// Valor predefinido: *""*
pub db_pass : String, pub db_name: String,
pub db_host : String, /// Valor predefinido: *""*
pub db_port : u16, pub db_user: String,
pub max_pool_size : u32, /// Valor predefinido: *""*
pub db_pass: String,
/// Valor predefinido: *"localhost"*
pub db_host: String,
/// Valor predefinido: *"0"*
pub db_port: u16,
/// Valor predefinido: *"5"*
pub max_pool_size: u32,
} }
#[rustfmt::skip]
#[derive(Debug, Deserialize)] #[derive(Debug, Deserialize)]
/// Sección *\[webserver\]* de la configuración global.
pub struct Webserver { pub struct Webserver {
pub bind_address : String, /// Valor predefinido: *"localhost"*
pub bind_port : u16, pub bind_address: String,
/// Valor predefinido: *"8088"*
pub bind_port: u16,
} }
#[rustfmt::skip]
#[derive(Debug, Deserialize)] #[derive(Debug, Deserialize)]
/// Sección *\[dev\]* de la configuración global.
pub struct Dev { pub struct Dev {
/// Valor predefinido: *""*
pub static_files : String, pub static_files : String,
} }
#[rustfmt::skip]
#[derive(Debug, Deserialize)] #[derive(Debug, Deserialize)]
/// Ajustes globales para las secciones *\[app\]*, *\[log\]*, *\[database\]*, *\[webserver\]* y
/// *\[dev\]* requeridas por PageTop (ver [`SETTINGS`]).
pub struct Settings { pub struct Settings {
pub app : App, pub app: App,
pub log : Log, pub log: Log,
pub database : Database, pub database: Database,
pub webserver : Webserver, pub webserver: Webserver,
pub dev : Dev, pub dev: Dev,
} }
pub_config_map!(r#" /// Instancia los ajustes globales para la estructura [`Settings`].
Ajustes globales con tipos seguros y valores predefinidos para las secciones *\[app\]*, *\[log\]*, ///
*\[database\]*, *\[webserver\]* y *\[dev\]* de PageTop. /// Ver [`Cómo obtener los valores de configuración`](index.html#cómo-obtener-los-valores-de-configuración).
pub static SETTINGS: LazyStatic<Settings> = LazyStatic::new(|| {
init_settings::<Settings>(predefined_settings!(
// [app]
"app.name" => "PageTop Application",
"app.description" => "Developed with the amazing PageTop framework.",
"app.theme" => "Bootsier",
"app.language" => "en-US",
"app.direction" => "ltr",
"app.startup_banner" => "Slant",
See [`How to access configuration`](index.html#how-to-access-configuration). // [log]
"#, "log.tracing" => "Info",
SETTINGS, Settings, "log.rolling" => "Stdout",
"log.path" => "log",
"log.prefix" => "tracing.log",
"log.format" => "Full",
// [app] // [database]
"app.name" => "PageTop Application", "database.db_type" => "",
"app.description" => "Developed with the amazing PageTop framework.", "database.db_name" => "",
"app.theme" => "Bootsier", "database.db_user" => "",
"app.language" => "en-US", "database.db_pass" => "",
"app.direction" => "ltr", "database.db_host" => "localhost",
"app.startup_banner" => "Slant", "database.db_port" => "0",
"database.max_pool_size" => "5",
// [log] // [webserver]
"log.tracing" => "Info", "webserver.bind_address" => "localhost",
"log.rolling" => "Stdout", "webserver.bind_port" => "8088",
"log.path" => "log",
"log.prefix" => "tracing.log",
"log.format" => "Full",
// [database] // [dev]
"database.db_type" => "", "dev.static_files" => ""
"database.db_name" => "", ))
"database.db_user" => "", });
"database.db_pass" => "",
"database.db_host" => "localhost",
"database.db_port" => 0,
"database.max_pool_size" => 5,
// [webserver]
"webserver.bind_address" => "localhost",
"webserver.bind_port" => 8088,
// [dev]
"dev.static_files" => ""
);

9
pagetop/src/core/module/all.rs
View file

@ -85,15 +85,6 @@ pub fn register_actions() {
} }
} }
// INIT SETTINGS ***********************************************************************************
/*
pub fn init_settings() {
trace::info!("initializing custom predefined settings");
for m in ENABLED_MODULES.read().unwrap().iter() {
settings::add_predefined_settings(m.settings());
}
}
*/
// INIT MODULES ************************************************************************************ // INIT MODULES ************************************************************************************
pub fn init_modules() { pub fn init_modules() {

6
pagetop/src/core/module/definition.rs
View file

@ -41,11 +41,7 @@ pub trait ModuleTrait: BaseModule + Send + Sync {
fn actions(&self) -> Vec<HookAction> { fn actions(&self) -> Vec<HookAction> {
vec![] vec![]
} }
/*
fn settings(&self) -> PredefinedSettings {
predefined_settings![]
}
*/
fn init(&self) {} fn init(&self) {}
#[cfg(feature = "database")] #[cfg(feature = "database")]

1
pagetop/src/lib.rs
View file

@ -40,7 +40,6 @@
// GLOBAL. // GLOBAL.
pub use concat_string::concat_string; pub use concat_string::concat_string;
pub use doc_comment::doc_comment;
pub use once_cell::sync::Lazy as LazyStatic; pub use once_cell::sync::Lazy as LazyStatic;
// LOCAL. // LOCAL.