91 lines
6.1 KiB
Markdown
91 lines
6.1 KiB
Markdown
<!-- file: crates/ksp-config-lib/README.md -->
|
|
<!-- version: 5 -->
|
|
|
|
# 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 HTTP Transport effectif vers `ksp_onchain_transport_lib::HttpTransportSettings`, 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.std.logging -> config/std.logging.json
|
|
cfg.std.transport -> config/std.transport.json
|
|
schema.std.logging -> config/schemas/std.logging.schema.json
|
|
schema.std.transport -> config/schemas/std.transport.schema.json
|
|
schema.composite -> config/schemas/composite.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` démontre le format composite sans créer de composite runtime fictif.
|
|
|
|
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 ou Transport 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.
|
|
|
|
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 endpoint : la valeur réelle est transmise au runtime légitime, tandis que la projection sûre et les `Debug` restent redacted.
|
|
|
|
## Documentation
|
|
|
|
- [`USAGE.md`](USAGE.md) — construction du moteur, résolution runtime et management ;
|
|
- [`TODO.md`](TODO.md) — points explicitement différés après `0.1.3` ;
|
|
- [`../../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 HTTP Transport ;
|
|
- [`../../.env.example`](../../.env.example) — inventaire versionné des variables d'environnement runtime.
|