khadhroony-bot3/docs/guides/CONFIGURATION.md

Guide de configuration

Objectif

Ce guide décrit le chargement et l’utilisation de la configuration bot3. La référence d’API détaillée reste ks-config/USAGE.md.

Fichiers actifs

• config/example.config.json : exemple utilisateur complet ;
• config/schema.config.json : contrat JSON formel ;
• .env, ou le fichier sélectionné par KS_ENV_FILE : valeurs d’environnement non versionnées ;
• .env.example : noms de variables attendues sans secrets.

Le format actif est JSON. Le futur split de configuration prévu en 0.5.x ne modifie pas le contrat actuel.

Séquence de chargement

L’API recommandée est read_config_json_file_with_environment. Elle :

1. charge .env, ou le fichier explicitement sélectionné par KS_ENV_FILE, sans écraser les variables du processus ;
2. lit le JSON ;
3. résout les placeholders namespacés ${KS_*} / ${KB_*} et les fallbacks éventuels ;
4. valide le schéma JSON ;
5. désérialise les types de configuration et applique les invariants métier ;
6. laisse ensuite active_profile sélectionner le profil actif.

Exemple opérateur

let config = match ks_config::read_config_json_file_with_environment(
    std::path::Path::new("config/example.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),
};

println!("active profile={}", profile.name);

Invariants

• aucun secret ne doit être ajouté à l’exemple versionné ;
• les placeholders non résolus doivent provoquer un diagnostic explicite ;
• le schéma embarqué et config/schema.config.json doivent rester identiques ;
• tant que 0.5.1-pre.006 n’a pas introduit les DTO publics sûrs, la configuration runtime résolue reste strictement backend et ne doit pas être exposée telle quelle ;
• les noms de profils et rôles d’endpoints doivent rester cohérents avec leurs consommateurs.

Quotas HTTP cumulés

Les limites HTTP sont déclarées par rôle, mais les quotas d’un endpoint public s’appliquent généralement à l’endpoint ou à l’adresse IP entière. Pour un endpoint unique, il faut donc considérer au minimum :

• la somme des requests_per_second de tous les rôles actifs ;
• la somme des bursts pouvant partir dans la même fenêtre ;
• la limite propre à une méthode RPC répétée ;
• les autres processus utilisant la même IP ou le même fournisseur.

Le profil public Devnet de l’exemple utilise 3 r/s pour http_queries et 1 r/s pour http_transactions. Un profil privé ou payant peut utiliser d’autres valeurs, mais elles doivent suivre le contrat réel du fournisseur.

Diagnostic

Pour isoler une erreur :

1. afficher la liste des fichiers d’environnement chargés ;
2. résoudre le JSON sans l’écrire dans les logs s’il contient des secrets ;
3. valider le schéma ;
4. valider le modèle typé ;
5. vérifier le profil actif ;
6. vérifier les rôles HTTP, WebSocket, stockage et logging.

Références

• ks-config/README.md ;
• ks-config/USAGE.md ;
• ks-config/TODO.md ;
• config/README.md ;
• docs/decisions/WINCODE_COMPATIBILITY_POLICY.md.