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

v0.1.0-pre.069

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-07-31 13:25:26 +02:00
parent f23ecd6675
commit 46071b7fed
21 changed files with 799 additions and 410 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
kb-config/CHANGELOG.md Normal file
View File

@@ -0,0 +1,42 @@
<!-- file: kb-config/CHANGELOG.md -->
<!-- version: 2 -->
# CHANGELOG — kb-config
## 0.1.0-pre.069-fix-001
### Corrigé
- suppression de la section `Non publié`, incompatible avec le rôle chronologique du changelog ;
- retrait des limitations et travaux futurs, désormais maintenus dans `TODO.md` ou `USAGE.md` selon leur nature ;
- clarification de la séparation entre historique de prerelease et objectifs futurs.
### Documentation
- réécriture de `TODO.md` sous forme de tâches uniquement ;
- correction des exemples de `USAGE.md` afin de ne pas utiliser l’opérateur `?`.
## 0.1.0-pre.069
### Documentation
- création de `TODO.md`, `USAGE.md` et du changelog détaillé ;
- réécriture du README selon l’architecture bot3.
## 0.1.0
### Migré
- migration et consolidation de la configuration typée bot2 dans `kb-config` ;
- conservation du schéma JSON, des profils, endpoints, listeners, paramètres de stockage, logging, wallet et exécution.
### Modifié
- adoption des règles Rust 2024 et Khadhroony ;
- export TypeScript contrôlé des types destinés au frontend ;
- validation structurée par `kb_core::Error`.
### Validation
- validation de l’exemple contre le schéma ;
- tests de round-trip, profils actifs, placeholders, URLs, rôles et invariants opérationnels.

99
kb-config/README.md
View File

@@ -1,90 +1,41 @@
<!-- file: kb-config/README.md -->
<!-- version: 7 -->
<!-- version: 4 -->
# kb-config
Ce crate définit le contrat de configuration commun du workspace.
`kb-config` définit le contrat de configuration typé du workspace, son schéma JSON embarqué et les fonctions de chargement, résolution d’environnement, validation et sérialisation.
## Rôle dans l'écosystème
## Responsabilités
`kb-config` charge, valide et sérialise un fichier JSON contenant plusieurs profils. Un seul profil est actif à l'exécution grâce au champ `active_profile`.
- exposer `AppConfig` et les sections de configuration publiques ;
- valider le JSON contre le schéma embarqué ;
- appliquer les invariants métier après désérialisation ;
- charger `.env` et `.env.local` depuis la racine du workspace ;
- résoudre les placeholders `${NAME}` et `${NAME:-fallback}` ;
- sélectionner le profil actif ;
- exporter les types nécessaires au frontend avec `ts-rs`.
Le crate fournit les structures typées runtime pour :
## Hors périmètre
- l'application et l'environnement ;
- les sorties de logs console, fichier humain, fichier JSON et fichier erreurs ;
- les filtres de targets `tracing` ;
- les stores PostgreSQL et SQLite ;
- les endpoints HTTP JSON-RPC et WebSocket Solana ;
- les rôles et limites par endpoint ;
- les listeners Solana standards ;
- le wallet temporaire géré par profil ;
- les permissions d'envoi localnet/devnet/testnet/mainnet ;
- les plafonds de dépense, frais, priorité et fraîcheur du blockhash ;
- les pages de démonstration Tauri.
La crate n’initialise ni le logging, ni PostgreSQL, ni les transports et ne manipule aucun secret de wallet. Elle fournit uniquement la configuration validée à ces consommateurs.
## Wallet temporaire
## Surface publique
Le profil `local_devnet` active un wallet persistant de laboratoire sous :
Les principales fonctions sont `read_config_json_file_with_environment`, `parse_config_json`, `validate_config`, `validate_config_json_schema`, `active_profile` et les sérialiseurs JSON. Les types publics couvrent les profils, endpoints, listeners, logging, base de données, wallet, exécution et démonstration.
```text
wallets/temporary/local_devnet/local-devnet-operator.json
```
## Relations
Les profils mainnet conservent `temporary_wallet_enabled = false`. La validation typée refuse un wallet temporaire actif sur `mainnet-beta`, une persistance sans activation et les alias pouvant produire un chemin arbitraire.
- dépend de `kb-core` pour les erreurs structurées ;
- alimente `kb-logging`, `kb-store`, `kb-onchain-transport`, `kb-pipeline`, `kb-wallet` et les applications ;
- utilise [`../config/example.config.json`](../config/example.config.json) et [`../config/schema.config.json`](../config/schema.config.json) comme exemple utilisateur et contrat de schéma actifs.
## Exécution
## Statut
La configuration sépare :
La configuration actuelle est fonctionnelle et validée. Un futur découpage de la configuration générale et du logging est prévu en `0.5.x` afin de réduire les duplications entre profils.
- le dry-run par défaut ;
- l'obligation de simulation ;
- la confirmation opérateur ;
- les plafonds de dépense localnet, devnet, testnet et mainnet ;
- le plafond de frais ;
- le plafond de prix par compute unit ;
- l'âge maximal du recent blockhash.
## Documents
Un cluster dont l'envoi est activé doit disposer d'un plafond de dépense positif. Toute dépense configurée exige la simulation et toute dépense mainnet exige la confirmation opérateur. Les paramètres de confirmation sont bornés et le plafond d’airdrop Devnet est interdit dans les profils d’un autre cluster.
## Validation
La validation se fait en deux étapes :
1. validation JSON brute via `config/schema.config.json` et `jsonschema` ;
2. validation typée après désérialisation Rust.
## Secrets et placeholders
Le fichier versionné doit rester sans secret. Les placeholders restent directement dans les URLs. Les keypairs générés par `kb-wallet` vivent hors du fichier de configuration et sous un répertoire ignoré par Git.
## Exports TS-rs
Les structures exposées à Tauri utilisent `TS` avec un chemin `export_to` explicite. Les fichiers générés servent uniquement au partage des types Rust/TypeScript et ne remplacent pas le schéma JSON runtime.
```bash
cargo test export_bindings -p kb-config
cargo test -p kb-config settings::tests::
```
## Résolution de l'environnement
`kb-config` est l'unique propriétaire du chargement des fichiers `.env` utilisés par la configuration. La priorité est déterministe :
1. variables déjà présentes dans l'environnement du processus ;
2. fichier indiqué par `KB_ENV_FILE`, sinon `.env` à la racine du workspace ;
3. fallback `${NOM:-valeur}` déclaré dans le JSON ;
4. conservation de `${NOM}` lorsqu'une valeur requise reste absente, afin que les consommateurs optionnels puissent échouer seulement à l'utilisation.
Les crates métier ne chargent pas elles-mêmes de fichier `.env`.
Le modèle racine utilise :
```text
HELIUS_API_KEY
KB_POSTGRES_MAINNET_URL
KB_POSTGRES_DEVNET_URL
KB_POSTGRES_TEST_URL
```
Les deux URLs runtime alimentent les profils correspondants. `KB_POSTGRES_TEST_URL` reste réservé aux tests d’intégration de `kb-store`.
- [Utilisation](USAGE.md)
- [Travaux restants](TODO.md)
- [Historique](CHANGELOG.md)
- [Architecture](../docs/architecture/ARCHITECTURE.md)

15
kb-config/TODO.md Normal file
View File

@@ -0,0 +1,15 @@
<!-- file: kb-config/TODO.md -->
<!-- version: 2 -->
# TODO — kb-config
## Série 0.5.x — scission de la configuration
- [ ] définir si la configuration doit être scindée en deux ou trois fichiers ;
- [ ] extraire les blocs de logging dupliqués entre profils vers une configuration dédiée ;
- [ ] alléger la configuration générale sans casser les invariants existants ;
- [ ] définir une stratégie de migration explicite pour les fichiers de configuration actuels ;
- [ ] maintenir l’identité entre le schéma embarqué et `config/schema.config.json` ;
- [ ] ajouter les tests de migration et de compatibilité du futur format multi-fichiers ;
- [ ] mettre à jour la documentation et les exemples après implémentation ;
- [ ] coordonner la migration avec `kb-logging` et toutes les crates consommatrices.

100
kb-config/USAGE.md Normal file
View File

@@ -0,0 +1,100 @@
<!-- file: kb-config/USAGE.md -->
<!-- version: 2 -->
# Utilisation de kb-config
## Chargement recommandé
```rust
let config_result = kb_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 kb_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
```rust
let report = match kb_config::load_workspace_environment(std::path::Path::new(".")) {
Ok(value) => value,
Err(error) => return Err(error),
};
```
`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.
## Validation et parsing
```rust
if let Err(error) = kb_config::validate_config_json_schema(raw_json) {
return Err(error);
}
let config = match kb_config::parse_config_json(raw_json) {
Ok(value) => value,
Err(error) => return Err(error),
};
if let Err(error) = kb_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
```rust
let compact = match kb_config::serialize_config_json(&config) {
Ok(value) => value,
Err(error) => return Err(error),
};
let pretty = match kb_config::serialize_config_json_pretty(&config) {
Ok(value) => value,
Err(error) => return Err(error),
};
```
La configuration est validée avant sérialisation.
## Schéma embarqué
```rust
let schema_text = kb_config::config_json_schema_text();
let schema_value = match kb_config::config_json_schema_value() {
Ok(value) => value,
Err(error) => return Err(error),
};
```
Le schéma actif est aussi disponible sous [`../config/schema.config.json`](../config/schema.config.json). Le fichier [`../config/example.config.json`](../config/example.config.json) fournit un exemple utilisateur complet.
## 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 `kb_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.