pmoconfig (0.3.1)
Installation
[registries.forgejo]
index = "sparse+ " # Sparse index
# index = " " # Git
[net]
git-fetch-with-cli = truecargo add pmoconfig@0.3.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, et une section vide du fichier (
host:) garde le défaut. Les listes du fichier remplacent celles du défaut, elles ne sont pas fusionnées. - Surcharges d'environnement :
MONAPP_CONFIG__HOST__PORT=9000surchargehost.port. La surcharge l'emporte à la lecture mais n'est jamais écrite dans le fichier. - Clés insensibles à la casse, accès par chemin (
&["host", "port"]), écriture sauvegardée aussitôt et de façon atomique (fichier temporaire puis renommage). - Lecteurs typés (
get_string,get_number,get_integer,get_boolet leurs variantes…_or_set) : une clé absente ounullvaut « rien », 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. - Pages web d'édition (feature
webui) : un formulaire par page, tout le lot vérifié avant d'écrire.
Installation
[dependencies]
pmoconfig = { version = "0.2", registry = "pmo" }
La feature webui ajoute les pages web : pmoconfig = { version = "0.2", registry = "pmo", features = ["webui"] }.
Les valeurs de l'arbre sont des serde_yaml_ng::Value : une application qui les manipule dépend de
serde_yaml_ng, dans la même version que pmoconfig.
Une application = un AppSpec
use pmoconfig::{AppSpec, Config};
# let dir = tempfile::tempdir()?;
# let directory = dir.path().to_str().unwrap();
let spec = AppSpec::new("MONAPP");
let config = Config::load(&spec, directory)?; // avec "" : le dossier est cherché, voir ci-dessous
# Ok::<(), Box<dyn std::error::Error>>(())
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 préfixe est vérifié à la création : lettres majuscules, chiffres et _, en commençant par une
lettre. AppSpec::new étant const, un const SPEC au préfixe invalide ne compile pas.
Il n'y a pas de YAML par défaut : le défaut d'une clé est celui de sa déclaration (Key), écrit une fois par la
crate qui la possède. Une application dont le défaut d'une clé partagée n'est pas celui de la crate le dit
dans son AppSpec : AppSpec::with_defaults(&[(chemin, DefaultValue::…)]) (const, rien n'est écrit dans
le fichier).
Le dossier est cherché dans cet ordre : argument de Config::load, variable d'environnement,
dossier courant, dossier personnel. config.config_dir() rend celui d'une instance.
Lire et écrire
use pmoconfig::{AppSpec, Config};
use serde_yaml_ng::Value;
# let dir = tempfile::tempdir()?;
# let directory = dir.path().to_str().unwrap();
let config = Config::load(&AppSpec::new("MONAPP"), directory)?;
config.set_value(&["host", "name"], Value::String("salon".into()))?; // sauvegardé aussitôt
assert_eq!(config.get_string(&["host", "name"])?.as_deref(), Some("salon"));
assert_eq!(config.get_integer(&["host", "port"])?, None); // absent : rien n'est inventé
# Ok::<(), Box<dyn std::error::Error>>(())
Config::save réécrit le fichier sans attendre une écriture ; Value::Null retire une clé au lieu
de l'écrire.
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. try_get_config rend None à la place. Un second init avec une
autre application, ou un autre dossier, est une erreur.
use pmoconfig::{AppSpec, get_config, init_in};
# let dir = tempfile::tempdir()?;
# let directory = dir.path().to_str().unwrap();
init_in(AppSpec::new("MONAPP"), directory)?; // en vrai : `init(spec)`
let config = get_config();
# Ok::<(), Box<dyn std::error::Error>>(())
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> {
let port = self.get_integer_or_set(&["host", "http_port"], 8080)?;
u16::try_from(port).map_err(|_| pmoconfig::error::PmoConfigError::InvalidValue {
path: "host.http_port".to_string(),
reason: format!("{port} n'est pas un port"),
})
}
}
Chiffrement des mots de passe
config.encrypt_password("secret") rend encrypted:BASE64… ; config.get_password(valeur) déchiffre une
valeur chiffrée et rend telle quelle une valeur en clair. La clé est propre à l'installation : 32
octets aléatoires tirés au premier chiffrement et rangés dans secret.key, à côté de config.yaml
(droits 0600), puis combinés avec le sel de l'application (deux applications n'ont pas la même clé).
Elle suit le dossier de configuration (donc le volume d'un conteneur), sans dépendre de la machine.
C'est une protection contre la lecture du seul config.yaml (copié, synchronisé, collé), pas contre
un utilisateur qui a accès au dossier entier. Le chiffrement est déterministe (même mot de passe,
même texte chiffré). Une clé perdue ou remplacée rend les mots de passe illisibles : les ressaisir.
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_ng, serde_json |
arbre YAML, vues JSON des pages |
dirs |
dossier personnel |
thiserror, tracing |
erreurs, journal |
aes-gcm, sha2, base64 |
chiffrement des mots de passe |
axum (feature webui) |
pages web |
Licence
CeCILL v2.1 (voir LICENSE, traduction anglaise : LICENSE.en).
Dependencies
| ID | Version |
|---|---|
| aes-gcm | ^0.11 |
| axum | ^0.8 |
| base64 | ^0.23 |
| dirs | ^7.0 |
| getrandom | ^0.4 |
| serde | ^1.0 |
| serde_json | ^1.0 |
| serde_yaml_ng | ^0.10 |
| sha2 | ^0.11 |
| thiserror | ^2.0 |
| tracing | ^0.1 |
| tempfile | ^3 |
| tokio | ^1.54 |
| tower | ^0.5 |