pmo

pmoconfig (0.3.2)

Published 2026-11-12 01:42:46 +01:00 by eric

Installation

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

[net]
git-fetch-with-cli = true
cargo add pmoconfig@0.3.2 --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é aléatoire propre à l'installation (secret.key).
  • 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.

Organisation des modules

  • spec.rs : AppSpec, l'identité d'une application (préfixe vérifié dès new) et les noms qui en découlent (dossier, variables d'environnement, sels).
  • config.rs : Config : chargement, sauvegarde atomique, get_value / set_value, dossiers gérés.
  • tree.rs : opérations pures sur l'arbre YAML (chemins, fusion, clés en minuscules, surcharges d'environnement). typed.rs : lecteurs typés.
  • global.rs : la configuration du processus (init, init_in, get_config, try_get_config).
  • encryption.rs : mots de passe (encrypted:BASE64). La clé secret.key est tirée au premier chiffrement, jamais au déchiffrement.
  • key.rs : les clés déclarées (Key, Kind, DefaultValue) : chemin, type, bornes, options, unité et défaut écrits une seule fois par la crate qui possède la clé. declared.rs : leurs lecteurs (read_text, read_integer, read_bool, read_value) : la valeur écrite si elle est valide, le défaut déclaré si rien n'est écrit, une erreur sinon. Retirer la clé (set_value(chemin, Null)) ramène au défaut.
  • registry.rs : ConfigKeys, les clés déclarées d'un binaire ; validate rapporte toutes les erreurs d'un coup.
  • introspect.rs : d'où vient une valeur (source_of, Source), écriture en lot (set_values).
  • page/ : descripteurs des pages de configuration (Setting, ConfigPage, ConfigPages) et leur vue avec les valeurs, sans serveur web. webui/ (feature webui) : routeur et rendu HTML.
  • error.rs : PmoConfigError (#[non_exhaustive]). Une erreur d'entrée/sortie dit l'opération et le chemin : PmoConfigError::io(contexte, erreur), jamais un ? nu.

Développement

make help   # commandes (kit crate-kit)
make ci     # deps-check + fmt-check + clippy + tests + doc
make test   # lance --all-features : les tests des pages web en font partie

tests/global.rs teste la configuration du processus (état global : un seul scénario par binaire). Les tests qui lisent des variables d'environnement utilisent un préfixe d'application propre au test (ils s'exécutent en parallèle dans le même processus). Direction et règle d'écriture d'une clé : Blackboard/evolution_pmoconfig.md.

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

Keywords

config yaml configuration encryption settings
Details
Cargo
2026-11-12 01:42:46 +01:00
0
CECILL-2.1
826 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