pmo

pmoconfig (0.2.0)

Published 2026-11-08 12:20:22 +01:00 by eric

Installation

[registries.forgejo]
index = "sparse+" # Sparse index
# index = "" # Git

[net]
git-fetch-with-cli = true
cargo add pmoconfig@0.2.0 --registry forgejo

About this package

Configuration YAML d'une application : arbre lu et écrit par chemin, valeurs par défaut, surcharges d'environnement, chiffrement des mots de passe

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.yaml dans 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=9000 surcharge host.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_bool et leurs variantes …_or_set) : une clé absente ou null vaut « 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

Keywords

config yaml configuration encryption settings
Details
Cargo
2026-11-08 12:20:22 +01:00
0
CECILL-2.1
274 KiB
Assets (1)
Versions (7) View all
0.3.5 2026-11-16
0.3.3 2026-11-12
0.3.2 2026-11-12
0.3.1 2026-11-11
0.3.0 2026-11-11