khadhroony-bot3/docs/guides/CONFIGURATION.md

Guide de configuration

Objectif

Ce guide décrit le chargement des documents de configuration après leur séparation. La référence d’API générale reste ks-config/USAGE.md et la configuration logging appartient à ks-logging.

Fichiers actifs

• config/app.config.json : configuration générale chargée par défaut ;
• config/logging.config.json : configuration logging chargée par défaut ;
• config/example.app.config.json et config/example.logging.config.json : exemples minimaux conformes ;
• config/schemas/app.config.schema.json : schéma général ;
• config/schemas/logging.config.schema.json : schéma logging ;
• .env, ou le fichier sélectionné par KS_ENV_FILE : valeurs d’environnement non versionnées ;
• .env.example : noms de variables attendues sans secrets réels.

KS_CONFIG_PATH et KS_LOGGING_CONFIG_PATH permettent de remplacer indépendamment les deux chemins par défaut.

Configuration générale

L’API recommandée reste ks_config::read_config_json_file_with_environment. Elle :

1. charge .env, ou le fichier sélectionné par KS_ENV_FILE, sans écraser les variables du processus ;
2. lit le JSON général ;
3. résout les placeholders ${KS_*} / ${KB_*} ;
4. valide config/schemas/app.config.schema.json ;
5. désérialise AppConfig et applique les invariants métier ;
6. laisse active_profile sélectionner le profil applicatif actif.

let config = match ks_config::read_config_json_file_with_environment(
    std::path::Path::new("config/app.config.json"),
    std::path::Path::new("."),
) {
    std::result::Result::Ok(value) => value,
    std::result::Result::Err(error) => return std::result::Result::Err(error),
};
let profile = match ks_config::active_profile(&config) {
    std::result::Result::Ok(value) => value,
    std::result::Result::Err(error) => return std::result::Result::Err(error),
};

Le profil général ne contient plus de bloc logging.

Configuration logging

ks_logging::read_logging_json_file_with_environment charge séparément le document logging et ks_logging::active_logging_profile sélectionne son profil actif.

let logging = match ks_logging::read_logging_json_file_with_environment(
    std::path::Path::new("config/logging.config.json"),
    std::path::Path::new("."),
) {
    std::result::Result::Ok(value) => value,
    std::result::Result::Err(error) => return std::result::Result::Err(error),
};
let logging_profile = match ks_logging::active_logging_profile(&logging) {
    std::result::Result::Ok(value) => value,
    std::result::Result::Err(error) => return std::result::Result::Err(error),
};

Les deux active_profile sont indépendants. Il n’existe aucun fallback implicite du profil logging vers le nom du profil applicatif.

Invariants

• aucun secret réel ne doit être ajouté aux fichiers versionnés ;
• les placeholders non résolus doivent rester détectables ;
• chaque schéma embarqué doit rester identique au fichier sous config/schemas/ ;
• les profils applicatifs et logging sont validés indépendamment ;
• ks-config ne possède plus de types logging ;
• tant que 0.5.1-pre.006 n’a pas introduit les DTO sûrs, la configuration runtime résolue reste strictement backend et ne doit pas être exposée telle quelle.

Diagnostic

Pour isoler une erreur :

1. vérifier le fichier d’environnement chargé ;
2. vérifier séparément les chemins app et logging ;
3. valider chaque document contre son schéma ;
4. vérifier son active_profile ;
5. vérifier ensuite les rôles HTTP/WebSocket, stockage ou routes logging concernés.

Ne jamais écrire dans les logs le JSON résolu complet s’il contient une valeur issue de KS_SECRET_* ou KB_SECRET_*.

Références

• ks-config/README.md et ks-config/USAGE.md ;
• ks-logging/README.md et ks-logging/USAGE.md ;
• config/README.md ;
• docs/decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md.