Version: v0.9.0

Configuration

All settings parameters reside in .yaml configuration files, and these values can be retreived anywhere in our application by calling kalgan::settings built-in functions, which in turn rely on crate kalgan_config to parse and access all the data defined in these files.

Settings Management

As we have already said, all settings parameters are defined in .yaml files(s). How to organize these parameters is up to us. We can set all of them in a single file (best way for small applications) or split them in multiple files or even folders.

The only important thing is to tell Kalgan the path of the file or folder where our settings parameters are. We have to do this in the main.rs of our application and pass this path as the first parameter in function kalgan::run. By convention it's recommended to locate our settings parameters in the folder config/app/:

...
fn main() {
    kalgan::run("config/app", controller::resolver, None);
}

However this is just a convention, fell free to locate your settings up to your needs.

Application Static Data

Keep in mind that we can use this path to locate any other static data that should not be in a database but in the application file system. Again, by convention we recomended to keep this data away from the settings paratemers, for example in a different file:

project/
    ...
    config/
        app/
            settings.yaml
            data.yaml
...

The discussion whether a data set should be in a database or in the file system is out of the sope of these docs.

Settings Access

The first action Kalgan executes, even before the startup of the server, is to parse all the configuration files and create a std::collections::HashMap with all these parameters. Thanks to crate lazy_static this Hashmap can be access from any place in our application.

We have a few built-in functions in kalgan/src/settings.rs to retrieve the values of this collection, which basically are a wrapper for serde_yaml::Value functions:

get Returns Result<serde_yaml::Value, String>.
get_string Returns Result<String, String>.
get_bool Returns Result<bool, String>.
get_number Returns Result<i64, String>.
get_float Returns Result<f64, String>.
get_vec Returns Result<Vec<serde_yaml::Value>, String>.
exists Returns true if the given key exists or false if not.

Regarding the syntax, these parameters must fulfil YAML rules and one more thing: the use of dots in the key name is forbidden. As a workaround we can use hyphen instead or a colon followed by a line break and indent.

Notice that access is based on dot notation. For example:

familiy:
    father:
        name: "Foo Bar"

Which can be retrieved as follows:

...
let father_name: String = kalgan::settings::get_string("family.father.name").unwrap(); // "Foo Bar"
...

Settings Reload

While developing it's annoying to stop and rebuild the app to test every little change we make. Sometimes there's no other way, for example, when we change our controllers, middlewares, services... that is to say, Rust code.

But we can prevent this situation when working with non-rust code: templates, statics and .yaml files. This means that every time we refresh the browser we can see the changes we make in these files on the fly. This feature is extremely powerful but it has a couple of caveats:

  • Performance: reloading all these files in every request impacts on the response time of our app. Keep in mind that the browser usually sends not only one but multiple requests on the background (as minimum, one for each static file).
  • Console output: while this feature is extremely useful to test our changes, having all these processes being trigger in every request the console output gets pretty overloaded.

To coupe with these downsides we can count with 2 settings parameters:

environment.is_prod When it's set to true dinamic files stop being reloaded. By default this parameter is set to false. See Production in the docs.
environment.refresh_config_timeout Idle time in seconds until the dynamic files are reloaded. By default this parameter is set to 3 seconds. Basically this parameter prevents the reloading when browser requests the static files or while while we're actively browsing.

Notice that refresh_config_timeout only works when is_prod is false and as soon as the latter is set to true we'll have to restart our app to reverse this settings.

Settings Table

Find below the table with all the settings parameters available:

Parameter Type Description Default Feature
server
Parameter: server.address Type: string Description: IP or Domain server address. Default: Feature:
Parameter: server.port Type: u64 Description: Por number of the server. Default: Feature:
Parameter: server.number_of_workers Type: u64 Description: Number of concurrent connections. Default: 10 Feature:
environment
Parameter: environment.is_prod Type: bool Description: Is it a production environment? Default: false Feature:
Parameter: environment.refresh_config_timeout Type: u64 Description: Seconds passed to refresh configuration. Default: 3 Feature:
router
Parameter: router.path Type: string Description: Path to routes folder/file. Default: Feature:
error
Parameter: error.{error_code} Type: string Description: Path to error controller. Default: Feature:
static
Parameter: static.folders Type: string Description: Folders containing static files. Default: Feature:
Parameter: static.path Type: string Description: Path to static files. Default: Feature:
Parameter: static.version Type: string Description: Version of static files in PROD. Default: Feature:
cookie
Parameter: cookie.renew Type: string Description: Name of the cookies to be refreshed on each request. Default: Feature:
Parameter: cookie.{cookie_name}.name Type: string Description: Name of the cookie. Default: Kalgan Feature:
Parameter: cookie.{cookie_name}.max_age Type: usize Description: Time in milliseconds for expiration date. Default: 86400000 Feature:
Parameter: cookie.{cookie_name}.http_only Type: bool Description: Prevent client-side scripts from accessing cookie? Default: true Feature:
Parameter: cookie.{cookie_name}.secure Type: bool Description: Only sent cookie over the HTTPS? Default: true Feature:
Parameter: cookie.{cookie_name}.value Type: string Description: Value of the cookie. Default: Kalgan Feature:
Parameter: cookie.{cookie_name}.expires Type: string Description: Specific expiration date. Default: Feature:
Parameter: cookie.{cookie_name}.domain Type: string Description: Domain which can receive the cookie. Default: Feature:
Parameter: cookie.{cookie_name}.path Type: string Description: URL scope of the cookie. Default: / Feature:
tera
Parameter: tera.path Type: string Description: Path to templates folder. Default: Feature: tera
i18n
Parameter: i18n.path Type: string Description: Path to translation folder/file. Default: Feature: kalgan_i18n
db
Parameter: db.path Type: string Description: The file path of the database. Only for SQLite. Default: Feature: sqlx
Parameter: db.server Type: string Description: The file path of the database. Only for SQLite. Default: Feature: sqlx
Parameter: db.name Type: string Description: Database name in server. Only for MySQL/Pg. Default: Feature: sqlx
Parameter: db.user Type: string Description: User name in database server. Only for MySQL/Pg. Default: Feature: sqlx
Parameter: db.password Type: string Description: User password in database server. Only for MySQL/Pg. Default: Feature: sqlx
Parameter: db.max_connections Type: string Description: User password in database server. Only for MySQL/Pg. Default: ¿? Feature: sqlx
mailer
Parameter: mailer.sender Type: string Description: Sender email address. Default: Feature: mailer
Parameter: mailer.server Type: string Description: IP or Domain smtp server address. Default: Feature: mailer
Parameter: mailer.user Type: string Description: User name in smtp server. Default: Feature: mailer
Parameter: mailer.password Type: string Description: User password in smtpserver. Default: Feature: mailer
cache
Parameter: cache.server Type: string Description: IP or Domain redis server address. Default: Feature: kalgan_cache
session
Parameter: session.{session_name}.cookie Type: string Description: Config name of the cookie used for the session. Default: Feature: session