pmo

pmoconfig (0.1.1)

Published 2026-11-08 08:47:16 +01:00 by eric

Installation

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

[net]
git-fetch-with-cli = true
cargo add pmoconfig@0.1.1 --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.
  • Surcharges d'environnement : MONAPP_CONFIG__HOST__PORT=9000 surcharge host.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

Keywords

config yaml configuration encryption settings
Details
Cargo
2026-11-08 08:47:16 +01:00
1
CECILL-2.1
191 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