pmoconfig (0.2.0)
Installation
[registries.forgejo]
index = "sparse+ " # Sparse index
# index = " " # Git
[net]
git-fetch-with-cli = truecargo add pmoconfig@0.2.0 --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. - API REST de lecture et d'écriture, en option (feature
api).
Installation
[dependencies]
pmoconfig = { version = "0.2", registry = "pmo" }
La feature api ajoute les routes REST : pmoconfig = { version = "0.2", registry = "pmo", features = ["api"] }.
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", "host:\n port: 8080\n");
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.
AppSpec::with_default_yaml donne une variante avec un autre YAML par défaut (un binaire qui n'a
besoin que d'une partie des réglages, un test).
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", "host:\n port: 8080\n"), directory)?;
assert_eq!(config.get_integer(&["host", "port"])?, Some(8080));
config.set_value(&["host", "name"], Value::String("salon".into()))?; // sauvegardé aussitôt
assert_eq!(config.get_string_or_set(&["host", "label"], "maison")?, "maison"); // défaut écrit
# 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", "host:\n port: 8080\n"), 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
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. Le chiffrement est déterministe (même mot de
passe, même texte chiffré).
Sous Linux, l'UUID est /etc/machine-id : dans un conteneur, monter celui de l'hôte, sans quoi le
chiffrement échoue (il n'y a pas de repli) et un identifiant qui change rend les mots de passe déjà
chiffrés indéchiffrables.
API REST (feature api)
api::create_router(config) expose :
| Route | Rôle |
|---|---|
GET /api/config |
toute la configuration, en JSON |
GET /api/config/{path} |
la valeur à path, niveaux séparés par des points (host.port) |
POST /api/config |
écrit {"path": "host.port", "value": 9000} ; répond 204 |
ApiDoc en décrit l'OpenAPI. Le router n'authentifie personne : il sert les valeurs telles
quelles, mots de passe chiffrés compris, et permet d'écrire n'importe quelle clé. L'application qui le
monte doit en restreindre l'accès.
ApiDoc implémente le trait utoipa::OpenApi de la version majeure d'utoipa de la crate (6) : une
application qui l'imbrique doit utiliser la même version majeure.
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, API REST |
dirs |
dossier personnel |
thiserror, tracing |
erreurs, journal |
aes-gcm, sha2, base64 |
chiffrement des mots de passe |
axum, utoipa (feature api) |
routes REST |
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 |
| serde | ^1.0 |
| serde_json | ^1.0 |
| serde_yaml_ng | ^0.10 |
| sha2 | ^0.11 |
| thiserror | ^2.0 |
| tracing | ^0.1 |
| utoipa | ^6.0 |
| tempfile | ^3 |
| tokio | ^1.54 |
| tower | ^0.5 |