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 kb-config/USAGE.md.

Fichiers actifs

• config/example.config.json : exemple utilisateur complet ;
• config/schema.config.json : contrat JSON formel ;
• .env et variantes locales : 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

1. charger les fichiers d’environnement autorisés avec load_workspace_environment ;
2. lire le fichier JSON ;
3. résoudre les placeholders ${NAME} ou ${NAME:-fallback} ;
4. parser avec load_config_from_str ou load_config_from_path ;
5. valider le schéma et les invariants typés ;
6. sélectionner le profil actif avec active_profile.

Exemple opérateur

let environment = match kb_config::load_workspace_environment(
    std::path::Path::new("."),
) {
    std::result::Result::Ok(value) => value,
    std::result::Result::Err(error) => return std::result::Result::Err(error),
};

let config = match kb_config::load_config_from_path(
    std::path::Path::new("config/example.config.json"),
) {
    std::result::Result::Ok(value) => value,
    std::result::Result::Err(error) => return std::result::Result::Err(error),
};

let profile = match kb_config::active_profile(&config) {
    std::result::Result::Ok(value) => value,
    std::result::Result::Err(error) => return std::result::Result::Err(error),
};

println!("loaded environment files={}", environment.loaded_files.len());
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 ;
• une sérialisation publique doit être précédée d’une validation ;
• 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

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