Utilisation de ks-config

Chargement recommandé

let config_result = ks_config::read_config_json_file_with_environment(
    std::path::Path::new("config/example.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 fonction charge l’environnement du workspace, résout les placeholders puis applique successivement le schéma JSON, la désérialisation typée et les invariants métier.

Chargement de l’environnement

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

for path in report.loaded_files {
    println!("environment file: {}", path.display());
}

EnvironmentLoadReport indique les fichiers chargés. Les placeholders non résolus sans fallback restent visibles afin que la validation ou le consommateur puisse les signaler explicitement. Le format 0.4.8 accepte encore les anciens noms d’environnement ; la migration 0.5.1 imposera le namespace KS_*.

Résolution explicite des placeholders

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

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

Cette API retourne actuellement une chaîne résolue ordinaire et peut donc contenir des secrets issus de l’environnement. Elle doit rester strictement backend et ne doit pas être utilisée pour afficher, logger ou transmettre le JSON résolu. 0.5.1 remplacera cette frontière par une résolution conservant la classification de sensibilité.

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.

Sérialisation

let compact = match ks_config::serialize_config_json(&config) {
    Ok(value) => value,
    Err(error) => return Err(error),
};
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.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.

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),
};

let property_count = schema_value
    .get("properties")
    .and_then(serde_json::Value::as_object)
    .map_or(0, serde_json::Map::len);

println!("embedded schema bytes={}, properties={property_count}", schema_text.len());

Le schéma actif est aussi disponible sous ../config/schema.config.json. Le fichier ../config/example.config.json fournit un exemple utilisateur complet.

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());

Types publics importants

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

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, les routes de logging et les contraintes wallet.

Tests instructifs

Les tests example_config_validates_against_schema, example_config_parses_and_resolves_active_profile et example_config_routes_global_and_operational_crate_files démontrent le contrat complet de l’exemple actif. Les tests parser_rejects_* et schema_rejects_* documentent les invariants refusés.

Limites

format JSON uniquement ;
la crate valide les références et paramètres, mais n’ouvre aucune connexion externe.

5.0 KiB Raw Blame History Unescape Escape