Sasedev/khadhroony-bot3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

0.5.1-pre.007

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-10 09:28:57 +02:00
parent 34a670eaec
commit a2820062eb
81 changed files with 3357 additions and 2381 deletions
Download Patch File Download Diff File Expand all files Collapse all files

105
ks-config/USAGE.md
View File

@@ -1,15 +1,28 @@
<!-- file: ks-config/USAGE.md -->
<!-- version: 8 -->
<!-- version: 9 -->
# Utilisation de ks-config
## Rôle de la crate
`ks-config` fournit les types, validations et chargeurs des configurations Khadhroony Solana partagées. Un binaire choisit son propre fichier de composition et combine les profils spécialisés dont il a besoin.
`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 doit pas connaître la liste des futurs workers ou applications.
`ks-config` ne connaît pas la liste des futurs workers ou applications.
## Chargement d'une composition
## 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(
@@ -20,25 +33,22 @@ let composed = match ks_config::read_composed_app_config_with_environment(
Err(error) => return Err(error),
};
let config = composed.app_config;
let profile = match ks_config::active_profile(&config) {
Ok(value) => value,
Err(error) => return Err(error),
};
```
Le chargeur :
1. charge l'environnement du workspace ;
2. valide la composition ;
3. résout les chemins `transport` et `listeners` déclarés par la composition ;
4. charge et valide les deux documents spécialisés ;
5. sélectionne les profils référencés ;
6. reconstruit le contrat runtime `AppConfig/ProfileConfig` ;
7. applique les invariants métier existants.
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 logging reste chargé par `ks-logging`, car son type runtime appartient à cette crate. La composition fournit néanmoins le chemin et le nom de profil à sélectionner.
Le document logging est ensuite chargé par `ks-logging`, qui possède son type runtime.
## Configuration transport indépendante
## Transport et defaults WebSocket
```rust
let transport = match ks_config::read_transport_json_file_with_environment(
@@ -48,31 +58,31 @@ let transport = match ks_config::read_transport_json_file_with_environment(
Ok(value) => value,
Err(error) => return Err(error),
};
let profile = match ks_config::transport_profile(&transport, "mainnet_research") {
let profile = match ks_config::default_transport_profile(&transport) {
Ok(value) => value,
Err(error) => return Err(error),
};
```
Le document expose `TransportConfigDocument` et `TransportProfileConfig` avec les endpoints HTTP/WebSocket et leurs rôles.
Les endpoints WebSocket source sélectionnent une classe `ws_endpoint_defaults`; les `overrides` propres à l'endpoint sont appliqués avant de produire `TransportProfileConfig`.
## Configuration listeners indépendante
## Listeners
```rust
let listeners = match ks_config::read_listeners_json_file_with_environment(
std::path::Path::new("config/listeners.config.json"),
std::path::Path::new("."),
) {
Ok(value) => value,
Err(error) => return Err(error),
};
let profile = match ks_config::listeners_profile(&listeners, "mainnet_research") {
Ok(value) => value,
Err(error) => return Err(error),
};
```
`default_listeners_profile` ou `listeners_profile` sélectionnent un ensemble de subscriptions. `resolved_listener_config` le convertit vers le contrat runtime transitoire `ListenerConfig`.
`resolved_listener_config` convertit ce profil spécialisé vers le contrat runtime `ListenerConfig` utilisé pendant la phase de transition.
## Store
`store.config.json` possède les paramètres de backend et les profils PostgreSQL/SQLite. Les helpers principaux sont `read_store_json_file_with_environment`, `default_store_profile` et `store_profile`.
## Wallet
`wallet.config.json` porte `wallets_directory` hors profils. Chaque profil définit un chemin relatif, le cluster, l'alias et la politique temporaire/persistante. `resolved_wallet_profile` construit le chemin runtime final.
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
@@ -85,34 +95,19 @@ let report = match ks_config::load_workspace_environment(std::path::Path::new(".
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.
## Résolution des placeholders
Les valeurs globales peuvent être remplacées, notamment :
```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"));
```text
KS_LOGS_DIRECTORY
KS_WALLETS_DIRECTORY
```
La chaîne résolue peut encore contenir des secrets. Elle reste strictement backend jusqu'à l'introduction de la représentation sensible dédiée.
## 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 `config/app.config.json` chargé directement.
`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 résolu est `config/schemas/resolved.app.config.schema.json`. Les fixtures correspondantes sont sous `test-fixtures/config/` et ne sont pas des configurations runtime.
Le schéma de ce contrat est `config/schemas/resolved.app.config.schema.json`. Les fixtures correspondantes sont sous `test-fixtures/config/`.
## Types publics importants
## Frontière TypeScript
- `CompositionConfigDocument`, `CompositionProfileConfig`, `CompositionConfigSources` ;
- `TransportConfigDocument`, `TransportProfileConfig` ;
- `ListenersConfigDocument`, `ListenersProfileConfig` ;
- `AppConfig`, `ProfileConfig` comme contrat runtime de transition ;
- `HttpEndpointConfig`, `WsEndpointConfig`, `EndpointRoleConfig` ;
- `ListenerConfig` et ses variantes ;
- `DatabaseConfig`, `WalletConfig`, `ExecutionConfig` jusqu'à leur split dédié.
Les types logging appartiennent à `ks-logging`.
## Prochaine frontière
Les sections store/data, wallet, execution et desktop seront sorties de la composition dans la prerelease suivante. Une fois cette décomposition terminée, les surfaces source/runtime/public/diagnostic et le camouflage des secrets pourront être définis sur des responsabilités stables.
Les bindings TS-RS générés depuis `ks-config` ne sont pas importés directement par le frontend desktop actuel. Ils sont donc considérés comme transitoires jusqu'à la prochaine prerelease, qui introduira les DTO publics/diagnostiques et supprimera les exports TypeScript non justifiés des crates généralistes.