Utilisation de ks-config

Chargement recommandé

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

Cette API charge l’environnement du workspace, résout les placeholders puis applique successivement le schéma JSON général, la désérialisation typée et les invariants métier.

Le fichier chargé par défaut par le desktop est config/app.config.json. KS_CONFIG_PATH permet de remplacer explicitement ce chemin.

Chargement de l’environnement

let report = match ks_config::load_workspace_environment(std::path::Path::new(".")) {
    Ok(value) => value,
    Err(error) => return Err(error),
};

if let Some(path) = report.loaded_path {
    println!("environment file: {}", path.display());
}

EnvironmentLoadReport indique le fichier chargé. Par défaut, ks-config sélectionne .env; KS_ENV_FILE permet d’en choisir un autre sans écraser les variables déjà présentes dans le processus.

Les contrats d’environnement utilisent KS_* pour Khadhroony Solana et KB_* pour les besoins réellement propres au Bot.

Résolution explicite des placeholders

let raw = r#"{"databaseUrl":"${KS_SECRET_POSTGRES_DEVNET_URL:-postgres://localhost/ks}"}"#;
let resolved = ks_config::resolve_environment_placeholders(raw);

assert!(resolved.contains("databaseUrl"));

Cette API retourne encore une chaîne ordinaire pouvant contenir des secrets résolus. Elle reste strictement backend jusqu’à l’introduction de la représentation sensible de 0.5.1-pre.006.

Validation et parsing

if let Err(error) = ks_config::validate_config_json_schema(raw_json) {
    return Err(error);
}
let config = match ks_config::parse_config_json(raw_json) {
    Ok(value) => value,
    Err(error) => return Err(error),
};
if let Err(error) = ks_config::validate_config(&config) {
    return Err(error);
}

parse_config_json effectue déjà les deux validations ; les appels séparés servent aux outils de diagnostic.

Schéma embarqué

let schema_text = ks_config::config_json_schema_text();
let schema_value = match ks_config::config_json_schema_value() {
    Ok(value) => value,
    Err(error) => return Err(error),
};

println!("embedded app schema bytes={}", schema_text.len());
assert!(schema_value.is_object());

Le schéma actif est ../config/schemas/app.config.schema.json. Les fichiers ../config/app.config.json et ../config/example.app.config.json doivent tous deux être conformes.

Sélection du profil actif

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

println!("active profile: {}", profile.name);
println!("http endpoints: {}", profile.solana.http_endpoints.len());
println!("websocket endpoints: {}", profile.solana.ws_endpoints.len());

Le profil applicatif ne contient plus de configuration logging. Le document logging et son active_profile sont chargés par ks-logging.

Sérialisation

let pretty = match ks_config::serialize_config_json_pretty(&config) {
    Ok(value) => value,
    Err(error) => return Err(error),
};

let write_result = std::fs::write("config/generated.app.config.json", pretty);
if let Err(error) = write_result {
    return Err(ks_core::Error::new(
        "config_write_failed",
        format!("cannot write generated configuration: {error}"),
    ));
}

La configuration est validée avant sérialisation.

Types publics importants

AppConfig, ProfileConfig, AppSectionConfig ;
DatabaseConfig, PostgresConfig, SqliteConfig, DataConfig ;
SolanaConfig, HttpEndpointConfig, WsEndpointConfig, EndpointRoleConfig ;
ListenerConfig et ses variantes ;
WalletConfig, ExecutionConfig, DemoConfig.

Les types logging ne font plus partie de ks-config.

Erreurs et invariants

Les erreurs utilisent ks_core::Error avec un code stable. Les validations couvrent notamment l’unicité des profils, l’existence du profil actif, les URLs, les rôles d’endpoints, les limites d’exécution et les contraintes wallet.

Tests instructifs

Les tests vérifient séparément app.config.json et example.app.config.json, le roundtrip du document général et les invariants parser_rejects_* / schema_rejects_*.

Limites

format JSON uniquement ;
aucune connexion externe n’est ouverte par la crate ;
la politique de camouflage des valeurs résolues appartient à 0.5.1-pre.006.

4.9 KiB Raw Blame History Unescape Escape