6.4 KiB
Utilisation de ks-config
Rôle de la crate
ks-config fournit les types, validations et chargeurs des configurations Khadhroony Solana partagées. Un consommateur peut utiliser les defaults des documents spécialisés ou fournir une composition qui remplace seulement les sélections nécessaires.
ks-config ne connaît pas la liste des futurs workers ou applications.
Sélectionner un wallet persistant par alias
Le document wallet.config.json accepte un champ optionnel wallet_alias par profil. Son omission ou null signifie qu'aucun wallet natif persistant n'est sélectionné ; une chaîne valide sélectionne uniquement l'identité logique. Le mot de passe reste fourni au runtime directement à ks-wallet et n'appartient jamais à ks-config.
{
"name": "worker_devnet",
"directory": "workers/devnet",
"cluster": "devnet",
"wallet_alias": "worker-operator",
"temporary_wallet_enabled": false,
"temporary_wallet_alias": "worker-temporary-disabled",
"temporary_wallet_persist": false
}
Charger les defaults partagés
let config = match ks_config::read_default_shared_app_config_with_environment(
std::path::Path::new("."),
) {
Ok(value) => value,
Err(error) => return Err(error),
};
Le chargeur combine les default_profile indépendants de transport, listeners, store, wallet et execution. Il ne suppose pas que ces profils portent tous le même nom.
Charger une composition de binaire
let composed = match ks_config::read_composed_app_config_with_environment(
std::path::Path::new("config/kb-app-demo-desktop.default.config.json"),
std::path::Path::new("."),
) {
Ok(value) => value,
Err(error) => return Err(error),
};
let config = composed.app_config;
Le chargeur :
- charge l'environnement du workspace ;
- valide la composition ;
- résout les six chemins spécialisés ;
- charge et valide transport, listeners, store, wallet et execution ;
- vérifie l'existence du profil logging référencé sans créer de dépendance
ks-config -> ks-logging; - applique les overrides ou les
default_profile; - reconstruit le contrat runtime
AppConfig/ProfileConfig; - applique les invariants croisés existants.
Le document logging est ensuite chargé par ks-logging, qui possède son type runtime.
Transport et defaults WebSocket
let transport = match ks_config::read_transport_json_file_with_environment(
std::path::Path::new("config/transport.config.json"),
std::path::Path::new("."),
) {
Ok(value) => value,
Err(error) => return Err(error),
};
let profile = match ks_config::default_transport_profile(&transport) {
Ok(value) => value,
Err(error) => return Err(error),
};
Les endpoints WebSocket source sélectionnent une classe ws_endpoint_defaults; les overrides propres à l'endpoint sont appliqués avant de produire TransportProfileConfig.
Listeners
default_listeners_profile ou listeners_profile sélectionnent un ensemble de subscriptions. resolved_listener_config le convertit vers le contrat runtime transitoire ListenerConfig.
Store
store.config.json sélectionne un backend par profil et transporte ses paramètres sous backend_options. Ce bloc reste opaque pour ks-config : seuls le code backend non vide et la forme objet sont validés ici. Les helpers principaux sont read_store_json_file_with_environment, default_store_profile et store_profile; ks-store interprète ensuite les options du backend sélectionné et crée la connexion.
Wallet
wallet.config.json porte wallets_directory hors profils. Cette valeur résout directement wallet.wallet_dir, racine commune des .kswallet persistants. Chaque profil conserve directory uniquement pour ses wallets/keypairs temporaires ; resolved_wallet_profile le résout séparément dans wallet.temporary_wallet_dir (par défaut wallets/temporary/<profil>).
Un changement de profil ne déplace donc pas les .kswallet persistants. Les fixtures temporaires restent isolées par profil et les autorisations de soumission ne font plus partie du wallet.
Exécution
execution.config.json possède simulation, confirmation, limites et *_send_enabled. Les helpers sont read_execution_json_file_with_environment, default_execution_profile et execution_profile.
Chargement de l'environnement
let report = match ks_config::load_workspace_environment(std::path::Path::new(".")) {
Ok(value) => value,
Err(error) => return Err(error),
};
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 valeurs globales peuvent être remplacées, notamment :
KS_LOGS_DIRECTORY
KS_WALLETS_DIRECTORY
Contrat runtime résolu
AppConfig et ProfileConfig restent provisoirement le contrat runtime commun afin de ne pas casser tous les consommateurs pendant les splits successifs. Ils ne correspondent plus à un fichier source app.config.json.
Le schéma de ce contrat est config/schemas/resolved.app.config.schema.json. Les fixtures correspondantes sont sous test-fixtures/config/.
Frontière source/runtime/public/diagnostic
AppConfig, ProfileConfig et les documents spécialisés chargés avec résolution d'environnement sont des contrats backend-only. Ils peuvent contenir des URLs, DSN, chemins ou autres valeurs sensibles et ne dérivent ni serde::Serialize ni Debug. ks-config n'offre plus de sérialiseur du runtime résolu.
La sensibilité des variables suit Secret > Internal > Public. classify_environment_template applique cette règle aux chaînes composées : une URL contenant ${KS_SECRET_HELIUS_API_KEY} est secrète même si le champ s'appelle simplement url. diagnostic_environment_value ne retourne jamais une valeur secrète ou interne en clair.
Les fragments propres à un binaire restent opaques dans CompositionProfileConfig.application. Le propriétaire les valide avec validate_json_value_against_schema et son schéma dédié.
Frontière TypeScript
ks-config ne dépend plus de TS-RS et ne génère aucun binding TypeScript. Les types traversant Tauri sont définis comme DTO/wrappers dans l'application propriétaire ; kb-app-demo-desktop construit notamment ses projections de configuration publique et diagnostic sans sérialiser AppConfig/ProfileConfig.