138 lines
6.4 KiB
Markdown
138 lines
6.4 KiB
Markdown
<!-- file: ks-config/USAGE.md -->
|
|
<!-- version: 13 -->
|
|
|
|
# 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`.
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```rust
|
|
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
|
|
|
|
```rust
|
|
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 :
|
|
|
|
1. charge l'environnement du workspace ;
|
|
2. valide la composition ;
|
|
3. résout les six chemins spécialisés ;
|
|
4. charge et valide transport, listeners, store, wallet et execution ;
|
|
5. vérifie l'existence du profil logging référencé sans créer de dépendance `ks-config -> ks-logging` ;
|
|
6. applique les overrides ou les `default_profile` ;
|
|
7. reconstruit le contrat runtime `AppConfig/ProfileConfig` ;
|
|
8. 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
|
|
|
|
```rust
|
|
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
|
|
|
|
```rust
|
|
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 :
|
|
|
|
```text
|
|
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`.
|