pmoconfig (0.1.1)
Installation
[registries.forgejo]
index = "sparse+ " # Sparse index
# index = " " # Git
[net]
git-fetch-with-cli = truecargo add pmoconfig@0.1.1 --registry forgejoAbout this package
pmoconfig
Configuration YAML d'une application : un arbre lu et écrit par chemin, avec valeurs par défaut, surcharges d'environnement et chiffrement des mots de passe. La crate ne connaît aucune application.
Fonctionnalités
- Fichier
config.yamldans un dossier de configuration, créé au premier lancement. - Défauts fusionnés : le YAML par défaut de l'application est fusionné avec le fichier ; une clé ajoutée au défaut apparaît dans un fichier plus ancien.
- Surcharges d'environnement :
MONAPP_CONFIG__HOST__PORT=9000surchargehost.port. - Clés insensibles à la casse, accès par chemin (
&["host", "port"]), écriture sauvegardée aussitôt. - Lecteurs typés (
get_number,get_string,get_bool_or_set…) : une valeur d'un autre type est une erreur, jamais un repli silencieux sur le défaut. - Dossiers gérés (
get_managed_dir) : absolus ou relatifs au dossier de configuration, créés au besoin. - Chiffrement des mots de passe (
encryption), clé dérivée de l'UUID de la machine. - API REST de lecture et d'écriture, en option (feature
api).
Installation
[dependencies]
pmoconfig = { version = "0.1", registry = "pmo" }
La feature api ajoute les routes REST : pmoconfig = { version = "0.1", registry = "pmo", features = ["api"] }.
Une application = un AppSpec
use pmoconfig::{AppSpec, Config};
let spec = AppSpec::new("MONAPP", "host:\n port: 8080\n");
let config = Config::load(&spec, "")?; // le dossier est cherché, voir ci-dessous
# Ok::<(), pmoconfig::error::PmoConfigError>(())
Le préfixe (MONAPP) donne tout le reste :
| Valeur | Résultat |
|---|---|
| dossier de configuration | .monapp (dossier courant, puis dossier personnel) |
| variable du dossier | MONAPP_CONFIG |
| surcharges d'environnement | MONAPP_CONFIG__… |
| sels de chiffrement | monapp-config-encryption-v1, monapp-nonce-v1 (figés : les changer rend les mots de passe déjà chiffrés indéchiffrables) |
Le dossier est cherché dans cet ordre : argument de Config::load, variable d'environnement,
dossier courant, dossier personnel.
Configuration du processus
Un binaire qui veut une configuration globale appelle init au début de main, puis get_config
partout ailleurs. get_config sans init panique avec un message qui le dit : la crate ne sait pas
quelle application elle sert.
use pmoconfig::{AppSpec, get_config, init};
init(AppSpec::new("MONAPP", "host:\n port: 8080\n"))?;
let config = get_config();
# Ok::<(), pmoconfig::error::PmoConfigError>(())
Ajouter des réglages à Config
Les réglages d'un domaine (un port, un cache…) n'ont pas leur place ici : chaque crate les ajoute à
Config avec un trait d'extension, au-dessus de get_value, des lecteurs typés et de
get_managed_dir.
use pmoconfig::{Config, Result};
pub trait HostConfigExt {
fn get_http_port(&self) -> Result<u16>;
}
impl HostConfigExt for Config {
fn get_http_port(&self) -> Result<u16> {
Ok(self.get_number_or_set(&["host", "http_port"], 8080.0)? as u16)
}
}
Chiffrement des mots de passe
encryption::encrypt_password(&spec, "secret") rend encrypted:BASE64… ; get_password(&spec, valeur)
déchiffre une valeur chiffrée et rend telle quelle une valeur en clair. La clé dérive de l'UUID de la
machine et des sels de l'application : le fichier n'est pas portable d'une machine à l'autre, et deux
applications n'ont pas la même clé. C'est une protection de base contre la lecture directe du fichier,
pas contre un utilisateur qui a accès à la machine.
API REST (feature api)
api::create_router(config) expose GET /api/config, GET /api/config/{path} et POST /api/config,
et ApiDoc en décrit l'OpenAPI.
Développement
make help # commandes (kit crate-kit)
make ci # deps-check + fmt-check + clippy + tests + doc
Dépendances
| Crate | Rôle |
|---|---|
serde, serde_yaml, serde_json |
arbre YAML, API REST |
dirs |
dossier personnel |
thiserror, tracing |
erreurs, journal |
aes-gcm, sha2, base64 |
chiffrement des mots de passe |
axum, tokio, utoipa (feature api) |
routes REST |
Licence
CeCILL v2.1 (voir LICENSE, traduction anglaise : LICENSE.en).
Dependencies
| ID | Version |
|---|---|
| aes-gcm | ^0.10 |
| axum | ^0.8 |
| base64 | ^0.22 |
| dirs | ^6.0 |
| serde | ^1.0 |
| serde_json | ^1.0 |
| serde_yaml | ^0.9 |
| sha2 | ^0.10 |
| thiserror | ^2.0 |
| tokio | ^1.35 |
| tracing | ^0.1 |
| utoipa | ^5.3 |
| tempfile | ^3 |