144 lines
4.9 KiB
Markdown
144 lines
4.9 KiB
Markdown
<!-- file: ks-config/USAGE.md -->
|
||
<!-- version: 7 -->
|
||
|
||
# Utilisation de ks-config
|
||
|
||
## Chargement recommandé
|
||
|
||
```rust
|
||
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
|
||
|
||
```rust
|
||
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
|
||
|
||
```rust
|
||
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
|
||
|
||
```rust
|
||
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é
|
||
|
||
```rust
|
||
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`](../config/schemas/app.config.schema.json). Les fichiers [`../config/app.config.json`](../config/app.config.json) et [`../config/example.app.config.json`](../config/example.app.config.json) doivent tous deux être conformes.
|
||
|
||
## Sélection du profil actif
|
||
|
||
```rust
|
||
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
|
||
|
||
```rust
|
||
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`.
|