96 lines
7.1 KiB
Markdown
96 lines
7.1 KiB
Markdown
<!-- file: crates/ksp-config-lib/README.md -->
|
||
<!-- version: 8 -->
|
||
|
||
# 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 vers `HttpTransportSettings` et, en V2, `WsTransportSettings`, y compris redaction/provenance des URLs `KSP_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-wallet-desk -> config/composite.ksp-app-wallet-desk.json
|
||
cfg.std.logging -> config/std.logging.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.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. `config/composite.ksp-app-wallet-desk.json` est le premier composite runtime concret : il sélectionne Logging, Transport et Wallet par `file_id`, sans dépendre de leurs 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, Transport 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`, et de `ksp-onchain-transport-lib` pour construire le contrat runtime Transport dans la direction Config -> Transport. 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` et `ksp-onchain-transport-lib` 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 les accepte pour les URLs HTTP et WebSocket : la valeur réelle est transmise au runtime légitime, tandis que la projection sûre et les `Debug` restent redacted. `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 V2 HTTP + WebSocket, avec lecture backward du V1 HTTP-only ;
|
||
- [`../../config/std.wallet.json`](../../config/std.wallet.json) — racine Wallet globale et sous-répertoire optionnel par profil ;
|
||
- [`../../config/composite.ksp-app-wallet-desk.json`](../../config/composite.ksp-app-wallet-desk.json) — composition Logging/Transport/Wallet de Wallet Desk ;
|
||
- [`../../.env.example`](../../.env.example) — inventaire versionné des variables d'environnement runtime.
|