106 lines
9.6 KiB
Markdown
106 lines
9.6 KiB
Markdown
<!-- file: crates/ksp-config-lib/README.md -->
|
||
<!-- version: 11 -->
|
||
|
||
# ksp-config-lib
|
||
|
||
`ksp-config-lib` est le propriétaire unique de la configuration applicative KSP.
|
||
|
||
La crate centralise les documents JSON, leurs schemas, les profils et compositions, les variables d'environnement `KSP_*` / `KSPB_*`, le fichier `.env`, la résolution effective et les mutations persistantes explicitement autorisées.
|
||
|
||
## Responsabilités
|
||
|
||
`ksp-config-lib` possède :
|
||
|
||
- le bootstrap non récursif `config/` / `config/schemas/` et les overrides `--cfgpath` / `--schemapath` ;
|
||
- le registre logique `file_id -> filename`, son inventaire public read-only ordonné par `file_id` et les overrides `--filemap=<file_id>=<filename>` ;
|
||
- la lecture JSON et la validation JSON Schema Draft 2020-12 ;
|
||
- les invariants sémantiques KSP des documents connus ;
|
||
- les globals, `default_profile`, profils nommés et leur provenance ;
|
||
- les compositions génériques par `file_id`, sans dépendance à un filename physique ;
|
||
- le snapshot des variables process KSP/KSPB et la lecture de `./.env` ;
|
||
- la priorité `process > .env > fallback > missing` ;
|
||
- les placeholders `${NAME}` et `${NAME:-fallback}` ;
|
||
- la classification `Public`, `Internal`, `Secret` ;
|
||
- les représentations réelle et sûre/redacted ainsi que la provenance des valeurs résolues ;
|
||
- l'adapter du document Logging effectif vers `ksp_logging_lib::LoggingSettings` ;
|
||
- l'adapter du document Transport V1/V2/V3 vers `HttpTransportSettings`, `WsTransportSettings` et, en V3, `YellowstoneGrpcTransportSettings`, y compris redaction/provenance des URLs `KSP_SECRET_*` ;
|
||
- l'adapter de `cfg.std.offchain_transport` vers `ksp_offchain_transport_lib::MarketPriceService`, avec contrôle de provenance des credentials/public fields et sans rendre les limites provider configurables ;
|
||
- l'adapter de `cfg.std.store` vers `ksp_store_lib::StoreSettings`, avec sélection d'un target nommé, réseau explicite et URI PostgreSQL à provenance `Secret` ;
|
||
- la surface de management pour inspecter et réparer les sources Config enregistrées, modifier `std.logging.json`, consulter les rapports d'environnement, révéler explicitement une valeur réelle et modifier `.env` ;
|
||
- les écritures atomiques JSON/`.env` et la protection des permissions `.env` ;
|
||
- les audits workspace empêchant les bypass d'ownership Config et les oublis dans `.env.example`.
|
||
|
||
## Ressources gérées
|
||
|
||
Le registre par défaut connaît :
|
||
|
||
```text
|
||
cfg.composite.ksp-app-solprices-desk -> config/composite.ksp-app-solprices-desk.json
|
||
cfg.composite.ksp-app-wallet-desk -> config/composite.ksp-app-wallet-desk.json
|
||
cfg.std.logging -> config/std.logging.json
|
||
cfg.std.offchain_transport -> config/std.offchain_transport.json
|
||
cfg.std.store -> config/std.store.json
|
||
cfg.std.transport -> config/std.transport.json
|
||
cfg.std.wallet -> config/std.wallet.json
|
||
schema.composite -> config/schemas/composite.schema.json
|
||
schema.std.logging -> config/schemas/std.logging.schema.json
|
||
schema.std.offchain_transport -> config/schemas/std.offchain_transport.schema.json
|
||
schema.std.store -> config/schemas/std.store.schema.json
|
||
schema.std.transport -> config/schemas/std.transport.schema.json
|
||
schema.std.wallet -> config/schemas/std.wallet.schema.json
|
||
```
|
||
|
||
`ConfigFileRegistry::descriptors()` expose ces descripteurs en lecture seule et dans un ordre déterministe par `file_id`. Une application de management peut ainsi découvrir les fichiers connus sans maintenir une liste parallèle ni dépendre de leurs filenames physiques.
|
||
|
||
`ConfigManagement::read_source()` permet d'inspecter le texte brut d'un document Config enregistré même lorsque ce document est invalide. `save_source_candidate()` complète cette frontière : le candidat brut est parsé, validé contre son schema et les invariants sémantiques KSP, puis persisté atomiquement uniquement après validation complète. Le `file_id` doit appartenir au registre et désigner un document Config ; aucun path arbitraire n'est accepté.
|
||
|
||
`config/examples/composite.example.json` conserve l’exemple générique. Les composites runtime committed restent possédés par Config : `config/composite.ksp-app-solprices-desk.json` sélectionne Logging + Off-chain Transport, tandis que `config/composite.ksp-app-wallet-desk.json` sélectionne Logging + Off-chain Transport + On-chain Transport + Wallet. Tous référencent leurs documents par `file_id`, sans dépendre de filenames physiques.
|
||
|
||
Le fichier local d'environnement est :
|
||
|
||
```text
|
||
./.env
|
||
```
|
||
|
||
Il n'est ni versionné ni livré. Le dépôt maintient `/.env.example` comme inventaire versionné des variables runtime utilisées. Toute nouvelle variable KSP/KSPB concrète doit y être ajoutée avec un commentaire d'usage dans le même delta que sa première utilisation.
|
||
|
||
## Frontières
|
||
|
||
Les autres crates et applications KSP ne doivent pas :
|
||
|
||
- lire directement les variables applicatives `KSP_*` / `KSPB_*` ;
|
||
- parser ou écrire directement `.env` ;
|
||
- ouvrir directement les documents Config connus par leur filename physique ;
|
||
- réimplémenter la sélection de profils, les compositions ou les placeholders ;
|
||
- reconstruire elles-mêmes la configuration Logging, On-chain Transport, Off-chain Transport, Store ou Wallet depuis le JSON.
|
||
|
||
`ksp-config-lib` dépend de `ksp-core-lib` pour `Error`/`Result`, de `ksp-logging-lib` pour les événements Config utiles et le contrat `LoggingSettings`, de `ksp-onchain-transport-lib` pour construire le contrat runtime On-chain Transport et de `ksp-offchain-transport-lib` pour construire le service market-price dans la direction Config -> Transport et de `ksp-store-lib` avec `default-features = false` pour construire les settings Store dans la direction Config -> Store sans forcer un backend physique. Le document Wallet reste un contrat de chemins/profils Config et n’introduit aucune dépendance Config -> `ksp-wallet-lib`.
|
||
|
||
La dépendance inverse est interdite : `ksp-core-lib`, `ksp-logging-lib`, `ksp-onchain-transport-lib`, `ksp-offchain-transport-lib` et les crates Store ne dépendent pas de Config.
|
||
|
||
Config ne possède pas le `LoggingGuard`. L'application ou le service qui orchestre le runtime construit la configuration effective puis possède le lifecycle `ksp_logging_lib::initialize/reinitialize`.
|
||
|
||
Tauri et les DTO TS-RS restent hors de cette crate. `ksp-app-config-desk` reste une frontière applicative mince au-dessus des APIs Config et découvre les documents standards via le registre Config sans déplacer leur logique métier dans l'application.
|
||
|
||
## Secrets
|
||
|
||
Un secret reste accessible au runtime ou au management lorsqu'un consumer autorisé en a réellement besoin, mais les vues ordinaires utilisent la représentation sûre.
|
||
|
||
Les méthodes `reveal_*` constituent un opt-in explicite au réel. L'authentification/autorisation de l'utilisateur humain appartient à l'application appelante et les valeurs retournées par ces méthodes ne doivent jamais être journalisées.
|
||
|
||
Le document Logging refuse les valeurs de sensibilité `Secret` dans sa configuration effective. Le document Transport accepte les valeurs secrètes pour les URLs HTTP/WebSocket et, en V3, pour `grpc_endpoints[].secret_metadata[]` : la valeur réelle est transmise au runtime légitime, tandis que la projection sûre et les `Debug` restent redacted. Les metadata gRPC publiques et secrètes sont séparées et leur provenance Config est contrôlée avant mapping. `std.offchain_transport` exige une provenance `Secret` pour les API keys effectives et une provenance `Public` pour la paire DexScreener lorsqu'elle vient de l'environnement ; il ne permet ni URL provider arbitraire ni override de rate limit. `std.store` exige une provenance `Secret` pour chaque URI PostgreSQL effective et conserve des targets réseau-spécifiques indépendants (`devnet`, `mainnet`, `testnet`) sans exposer l'URI dans les projections sûres. `std.wallet` refuse également toute sensibilité `Secret` pour `wallets_directory`/`wallets_subdirectory`; les passwords Wallet restent un autre flux Config et ne sont jamais stockés dans ce JSON.
|
||
|
||
## Documentation
|
||
|
||
- [`USAGE.md`](USAGE.md) — construction du moteur, résolution runtime et management ;
|
||
- [`TODO.md`](TODO.md) — points explicitement différés ;
|
||
- [`../../docs/plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md`](../../docs/plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md) — plan historique détaillé de la fondation Config ;
|
||
- [`../../config/std.logging.json`](../../config/std.logging.json) — document standard Logging ;
|
||
- [`../../config/std.transport.json`](../../config/std.transport.json) — document standard Transport V3 HTTP + WebSocket + Yellowstone gRPC, avec lecture backward des V1/V2 ;
|
||
- [`../../config/std.offchain_transport.json`](../../config/std.offchain_transport.json) — document standard Off-chain Transport V1, actuellement limité au domaine `market_price` SOL/USD ;
|
||
- [`../../config/std.store.json`](../../config/std.store.json) — targets Store PostgreSQL Devnet/Mainnet/Testnet et settings runtime bornés ;
|
||
- [`../../config/std.wallet.json`](../../config/std.wallet.json) — racine Wallet globale et sous-répertoire optionnel par profil ;
|
||
- [`../../config/composite.ksp-app-solprices-desk.json`](../../config/composite.ksp-app-solprices-desk.json) — composition Logging/Off-chain Transport de SOL Prices Desk ;
|
||
- [`../../config/composite.ksp-app-wallet-desk.json`](../../config/composite.ksp-app-wallet-desk.json) — composition Logging/Off-chain Transport/On-chain Transport/Wallet de Wallet Desk ;
|
||
- [`../../.env.example`](../../.env.example) — inventaire versionné des variables d'environnement runtime.
|