v0.1.3-pre.001-fix.002
This commit is contained in:
@@ -1,11 +1,11 @@
|
||||
<!-- file: docs/plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md -->
|
||||
<!-- version: 2 -->
|
||||
<!-- version: 3 -->
|
||||
|
||||
# Plan `0.1.3` — Configuration foundation
|
||||
|
||||
## 1. Statut et objectif
|
||||
|
||||
Ce plan a été établi par `0.1.3-pre.001`, puis corrigé par `0.1.3-pre.001-fix.001` avant tout développement fonctionnel de Config.
|
||||
Ce plan a été établi par `0.1.3-pre.001`, corrigé par `0.1.3-pre.001-fix.001`, puis complété par `0.1.3-pre.001-fix.002` avant tout développement fonctionnel de Config.
|
||||
|
||||
La base auditée reste la release stable `v0.1.2`.
|
||||
|
||||
@@ -23,6 +23,8 @@ Elles passent par les contrats publics de `ksp-config-lib`.
|
||||
|
||||
`ksp-config-lib` doit fournir le moteur commun nécessaire à :
|
||||
|
||||
- un registre logique interne `file_id -> filename` pour tous les fichiers Config/schemas connus, avec identifiants uniques et mappings par défaut surchargeables au bootstrap ;
|
||||
- deux chemins bootstrap non récursifs (`cfgpath` et `schemapath`) possédés par Config, avec défauts codés en dur et surcharge uniquement par argument/paramètre de démarrage ;
|
||||
- la lecture des documents spécialisés JSON ;
|
||||
- la validation JSON Schema ;
|
||||
- les paramètres globaux hors profils ;
|
||||
@@ -38,7 +40,7 @@ Elles passent par les contrats publics de `ksp-config-lib`.
|
||||
- la création/modification/suppression des entrées du `.env` ;
|
||||
- la construction des contrats runtime nécessaires aux consommateurs, en commençant par `ksp_logging_lib::LoggingSettings`.
|
||||
|
||||
`0.1.3-pre.001-fix.001` reste une tranche documentaire de conception. Il ne crée pas encore `ksp-config-lib`, ne crée aucun fichier runtime Config et n'ajoute aucune dépendance fonctionnelle.
|
||||
`0.1.3-pre.001-fix.002` reste une tranche documentaire de conception. Il ne crée pas encore `ksp-config-lib`, ne crée aucun fichier runtime Config et n'ajoute aucune dépendance fonctionnelle.
|
||||
|
||||
## 2. Audit de la base stable `0.1.2`
|
||||
|
||||
@@ -89,7 +91,29 @@ initialize(...)
|
||||
reinitialize(...)
|
||||
```
|
||||
|
||||
Config ne redéfinit pas ces contrats. Il lit et résout sa configuration Logging, puis construit explicitement un `ksp_logging_lib::LoggingSettings`.
|
||||
L'audit réel du code `v0.1.2` montre cependant que cette surface est **plus étroite** que la configuration Logging historique de bot3 :
|
||||
|
||||
- une seule sortie console optionnelle ;
|
||||
- un seul sink fichier optionnel ;
|
||||
- rotation fichier `never/hourly/daily` ;
|
||||
- filtre par défaut + overrides par préfixe de target ;
|
||||
- formatter actuellement fixé par Logging ;
|
||||
- pas de sélection `console_ansi` publique ;
|
||||
- pas de plusieurs fichiers simultanés ;
|
||||
- pas de format `human/compact/pretty/json` sélectionnable par sink ;
|
||||
- pas de routage d'un sink par combinaison `target/domain/level` ;
|
||||
- `domain` reste aujourd'hui un champ structuré émis par le caller mais n'est pas un sélecteur public de routing.
|
||||
|
||||
La référence bot3 possédait déjà plusieurs sinks console/fichier, des niveaux et targets par sink, des formats, ANSI et rotation. KSP ne doit donc pas figer un `std.logging.json` qui constituerait une régression fonctionnelle par rapport à cette surface utile.
|
||||
|
||||
Décision :
|
||||
|
||||
- Config ne réimplémente jamais le routing Logging ;
|
||||
- `ksp-logging-lib` reste propriétaire de `LoggingSettings`, du subscriber, des layers, des writers et du lifecycle `initialize/reinitialize` ;
|
||||
- avant gel de `std.logging.schema.json`, la surface publique de Logging doit être complétée de manière bornée pour représenter les sinks/routings retenus par ce plan ;
|
||||
- cette complétion ne change ni la direction de dépendance ni la propriété du lifecycle Logging et n'introduit aucune lecture Config dans Logging.
|
||||
|
||||
Config lit/résout le document puis construit uniquement des contrats publics `ksp_logging_lib::*` suffisamment expressifs.
|
||||
|
||||
La direction de dépendance reste :
|
||||
|
||||
@@ -122,9 +146,12 @@ La référence historique bot3 utilisait déjà :
|
||||
- des placeholders comme `${KS_LOGS_DIRECTORY:-logs}` ;
|
||||
- des URLs composées contenant `${KS_SECRET_HELIUS_API_KEY}` ;
|
||||
- des compositions applicatives ;
|
||||
- une classification de sensibilité dérivée des placeholders.
|
||||
- une classification de sensibilité dérivée des placeholders ;
|
||||
- un document Logging avec `logs_directory`, `default_profile` et une liste de profils nommés ;
|
||||
- plusieurs sorties Logging par profil, chacune avec identifiant, activation, sink console/fichier, niveau, chemin, rotation, format, ANSI et liste de targets ;
|
||||
- plusieurs fichiers simultanés permettant notamment de séparer debug/info/error et des targets spécialisées.
|
||||
|
||||
Cette référence reste utile, mais KSP ne copie pas ses structures ni ses APIs aveuglément.
|
||||
Cette référence reste utile, mais KSP ne copie pas ses structures ni ses APIs aveuglément. En particulier, KSP utilise maintenant un target propriétaire égal au nom Cargo de la crate et des champs structurés comme `domain`; le nouveau modèle doit donc permettre un routing plus propre par `target` **et/ou** `domain` sans ressusciter artificiellement les anciens pseudo-targets hiérarchiques.
|
||||
|
||||
### 3.1 Principes conservés et renforcés
|
||||
|
||||
@@ -141,7 +168,8 @@ KSP conserve :
|
||||
- classification nominale des variables ;
|
||||
- propagation de la sensibilité la plus forte dans une valeur composée ;
|
||||
- distinction entre valeur réelle et représentation diagnostic sûre ;
|
||||
- DTO Tauri possédés par l'application et non par `ksp-config-lib`.
|
||||
- DTO Tauri possédés par l'application et non par `ksp-config-lib` ;
|
||||
- richesse de configuration Logging au moins équivalente aux besoins utiles de bot3, sans recopier ses limites de conception.
|
||||
|
||||
### 3.2 Corrections par rapport au plan `pre.001` initial
|
||||
|
||||
@@ -151,7 +179,8 @@ Le plan initial de `pre.001` avait retenu à tort :
|
||||
- une grammaire d'environnement KSP spéciale ;
|
||||
- l'interdiction de l'interpolation `${...}` ;
|
||||
- des bindings d'environnement prédéclarés clé Config -> variable ;
|
||||
- une lecture limitée aux variables enregistrées par ces bindings.
|
||||
- une lecture limitée aux variables enregistrées par ces bindings ;
|
||||
- un exemple `std.logging.json` réduit à une console + un fichier, alors que cette surface ne représente pas les besoins Logging déjà connus.
|
||||
|
||||
Ces décisions sont annulées.
|
||||
|
||||
@@ -161,22 +190,26 @@ La règle corrigée est :
|
||||
|
||||
Config peut également exposer une API explicite de lecture d'une variable par nom avec fallback optionnel pour les rares usages qui ne proviennent pas d'un document JSON, mais les consumers ne lisent jamais directement `std::env`.
|
||||
|
||||
Le nom physique d'un fichier Config ou schema n'est pas non plus son identité logique : toute référence inter-document passe par un `file_id` stable connu du registre Config.
|
||||
|
||||
## 4. Décision de périmètre : `0.1.3` reste une seule release
|
||||
|
||||
Le périmètre reste compatible avec une seule release si la première implémentation concrète reste bornée.
|
||||
Le périmètre reste compatible avec une seule release si l'implémentation reste découpée et si la complétion Logging est strictement bornée à la représentation/routage nécessaire au premier document Config réel.
|
||||
|
||||
La release construit le moteur générique nécessaire à :
|
||||
|
||||
1. documents JSON spécialisés ;
|
||||
2. schémas ;
|
||||
3. paramètres globaux ;
|
||||
4. profils et `default_profile` ;
|
||||
5. compositions ;
|
||||
6. `.env` + environnement du processus ;
|
||||
7. interpolation/fallback ;
|
||||
8. provenance/sensibilité/redaction ;
|
||||
9. mutation/persistence ;
|
||||
10. adaptation Logging.
|
||||
1. bootstrap Config non récursif (`cfgpath`, `schemapath`) ;
|
||||
2. registre logique des fichiers `file_id -> filename` et overrides de mapping au démarrage ;
|
||||
3. documents JSON spécialisés ;
|
||||
4. schémas ;
|
||||
5. paramètres globaux ;
|
||||
6. profils et `default_profile` ;
|
||||
7. compositions ;
|
||||
8. `.env` + environnement du processus ;
|
||||
9. interpolation/fallback ;
|
||||
10. provenance/sensibilité/redaction ;
|
||||
11. mutation/persistence ;
|
||||
12. adaptation Logging sans perte de capacités nécessaires.
|
||||
|
||||
Mais le seul document spécialisé runtime créé et exercé concrètement en `0.1.3` est :
|
||||
|
||||
@@ -189,34 +222,153 @@ Aucun `std.store.json`, `std.wallet.json`, `std.onchain-transport.json` ou autre
|
||||
La séquence reste :
|
||||
|
||||
```text
|
||||
0.1.3 ksp-config-lib
|
||||
0.1.3 ksp-config-lib + complétion bornée du contrat Logging nécessaire
|
||||
0.1.4 ksp-app-config-desk
|
||||
```
|
||||
|
||||
La complétion Logging n'ouvre ni une nouvelle façade ni une dépendance inverse : elle enrichit uniquement les contrats publics déjà possédés par `ksp-logging-lib` afin que Config puisse exprimer sans régression le document Logging.
|
||||
|
||||
## 5. Matrice de responsabilités
|
||||
|
||||
| Responsabilité | Propriétaire | Consommateurs | Interdit |
|
||||
|----------------------------------------------------------|--------------------------------------|------------------------------------|-----------------------------------------------------------|
|
||||
| Lire un document Config JSON | `ksp-config-lib` | crates/apps via API Config | lecture directe par consumer |
|
||||
| Valider JSON Schema | `ksp-config-lib` | orchestration/management | validation divergente dans chaque crate |
|
||||
| Résoudre globals/profils/compositions | `ksp-config-lib` | orchestration | résolution locale dans un binaire |
|
||||
| Lire `KSP_*` / `KSPB_*` du processus | `ksp-config-lib` | crates/apps via API Config | `std::env::var*` applicatif hors Config |
|
||||
| Lire `.env` | `ksp-config-lib` | crates/apps via API Config | loader dotenv direct hors Config |
|
||||
| Résoudre `${...}` et fallback | `ksp-config-lib` | tous les consumers | interpolation locale dans les consumers |
|
||||
| Classer sensibilité et construire une valeur sûre | `ksp-config-lib` | runtime/logging/diagnostics | redaction ad hoc dans chaque crate |
|
||||
| Modifier/sauvegarder JSON Config | `ksp-config-lib` | management explicite | écriture directe par application |
|
||||
| Créer/modifier/supprimer une entrée `.env` | `ksp-config-lib` | management explicite | édition directe par application |
|
||||
| Modifier l'environnement externe du shell/systemd/parent | propriétaire externe de ce processus | Config le lit seulement | prétendre qu'un child process peut administrer son parent |
|
||||
| Posséder `LoggingSettings` | `ksp-logging-lib` | Config le construit | copie du type dans Config |
|
||||
| Posséder `LoggingGuard` | orchestration/application | lifecycle Logging | singleton Config global |
|
||||
| Initialiser/recharger Logging | orchestration | Config fournit settings/changement | Logging lisant Config |
|
||||
| DTO/bindings Tauri | application Tauri | frontend | TS-RS automatique dans Config |
|
||||
| Responsabilité | Propriétaire | Consommateurs | Interdit |
|
||||
|---|---|---|---|
|
||||
| Définir les `file_id` connus et leur mapping par défaut | `ksp-config-lib` | bootstrap Config | noms physiques codés dans les consumers |
|
||||
| Résoudre `file_id -> filename` | `ksp-config-lib` | session Config | référence inter-document par filename |
|
||||
| Interpréter `--cfgpath`, `--schemapath` et overrides de mapping KSP | `ksp-config-lib` | applications qui transmettent argv/options | parser ces options différemment dans chaque binaire |
|
||||
| Lire un document Config JSON | `ksp-config-lib` | crates/apps via API Config | lecture directe par consumer |
|
||||
| Valider JSON Schema | `ksp-config-lib` | orchestration/management | validation divergente dans chaque crate |
|
||||
| Résoudre globals/profils/compositions | `ksp-config-lib` | orchestration | résolution locale dans un binaire |
|
||||
| Lire `KSP_*` / `KSPB_*` du processus | `ksp-config-lib` | crates/apps via API Config | `std::env::var*` applicatif hors Config |
|
||||
| Lire `.env` | `ksp-config-lib` | crates/apps via API Config | loader dotenv direct hors Config |
|
||||
| Résoudre `${...}` et fallback | `ksp-config-lib` | tous les consumers | interpolation locale dans les consumers |
|
||||
| Classer sensibilité et construire une valeur sûre | `ksp-config-lib` | runtime/logging/diagnostics | redaction ad hoc dans chaque crate |
|
||||
| Modifier/sauvegarder JSON Config | `ksp-config-lib` | management explicite | écriture directe par application |
|
||||
| Créer/modifier/supprimer une entrée `.env` | `ksp-config-lib` | management explicite | édition directe par application |
|
||||
| Modifier l'environnement externe du shell/systemd/parent | propriétaire externe de ce processus | Config le lit seulement | prétendre qu'un child process peut administrer son parent |
|
||||
| Posséder les settings/sinks/routing Logging | `ksp-logging-lib` | Config construit les contrats publics | logique de routing dupliquée dans Config |
|
||||
| Posséder `LoggingGuard` | orchestration/application | lifecycle Logging | singleton Config global |
|
||||
| Initialiser/recharger Logging | orchestration | Config fournit settings/changement | Logging lisant Config |
|
||||
| DTO/bindings Tauri | application Tauri | frontend | TS-RS automatique dans Config |
|
||||
|
||||
## 6. Arborescence et nomenclature
|
||||
## 6. Registre de fichiers, bootstrap, arborescence et nomenclature
|
||||
|
||||
### 6.1 Documents runtime
|
||||
### 6.1 Identité logique : `file_id`
|
||||
|
||||
Les vrais documents JSON runtime appartiennent sous :
|
||||
`ksp-config-lib` possède un registre des fichiers qu'il sait interpréter. Un fichier n'est jamais identifié par son nom physique dans les contrats inter-documentaires.
|
||||
|
||||
Chaque entrée possède au minimum :
|
||||
|
||||
```text
|
||||
file_id unique
|
||||
kind = config_document | schema
|
||||
filename par défaut
|
||||
racine = cfgpath | schemapath
|
||||
schema_file_id éventuel pour un document Config
|
||||
```
|
||||
|
||||
Les `file_id` sont uniques dans **un même namespace global Config**, y compris entre documents et schemas. Préfixes retenus :
|
||||
|
||||
```text
|
||||
cfg.std.logging
|
||||
schema.std.logging
|
||||
schema.composite
|
||||
cfg.composite.<consumer>
|
||||
```
|
||||
|
||||
Premier mapping codé dans `ksp-config-lib` :
|
||||
|
||||
```text
|
||||
cfg.std.logging -> std.logging.json
|
||||
schema.std.logging -> std.logging.schema.json
|
||||
schema.composite -> composite.schema.json
|
||||
```
|
||||
|
||||
Le descriptor `cfg.std.logging` référence logiquement `schema.std.logging`; il ne contient pas le nom physique du schema.
|
||||
|
||||
Un futur consumer pourra introduire par le registre KSP :
|
||||
|
||||
```text
|
||||
cfg.composite.ksp-app-wallet-desk -> composite.ksp-app-wallet-desk.json
|
||||
```
|
||||
|
||||
avec validation par `schema.composite` tant qu'un schema plus spécialisé n'est pas nécessaire.
|
||||
|
||||
Un override change uniquement le **filename résolu**, jamais le `file_id`. Ainsi un composite continue de référencer `cfg.std.logging` même si l'utilisateur sélectionne `my-logging.local.json` au démarrage.
|
||||
|
||||
Par défaut, un override CLI d'un `file_id` inconnu est refusé : il ne doit pas permettre de contourner le type/schema que Config sait gérer.
|
||||
|
||||
### 6.2 Bootstrap non récursif : `cfgpath` et `schemapath`
|
||||
|
||||
Deux valeurs seulement doivent exister avant toute lecture de document Config :
|
||||
|
||||
```text
|
||||
DEFAULT_CFG_PATH = "config"
|
||||
DEFAULT_SCHEMA_PATH = "config/schemas"
|
||||
```
|
||||
|
||||
Ces défauts sont codés en dur dans `ksp-config-lib`.
|
||||
|
||||
Ils **ne peuvent pas** être définis ou remplacés par :
|
||||
|
||||
```text
|
||||
std.*.json
|
||||
composite.*.json
|
||||
.env
|
||||
KSP_*
|
||||
KSPB_*
|
||||
```
|
||||
|
||||
sinon Config aurait besoin de charger Config pour savoir où charger Config.
|
||||
|
||||
Ils peuvent changer uniquement au bootstrap par :
|
||||
|
||||
```text
|
||||
--cfgpath=/path/to/configs
|
||||
--schemapath=/path/to/schemas
|
||||
```
|
||||
|
||||
ou par l'équivalent programmatique explicite de `ConfigBootstrapOptions` lorsqu'un caller embarque Config sans CLI.
|
||||
|
||||
`ksp-config-lib` doit posséder l'interprétation de ces options. Un binaire peut lui transmettre les arguments bruts ou construire explicitement le type public prévu, mais ne doit pas réimplémenter leur sémantique.
|
||||
|
||||
Les deux chemins sont indépendants : remplacer `cfgpath` ne remplace pas implicitement `schemapath`.
|
||||
|
||||
### 6.3 Override des mappings physiques au bootstrap
|
||||
|
||||
Le registre utilise ses filenames par défaut sauf surcharge explicite au démarrage.
|
||||
|
||||
Syntaxe CLI retenue pour le plan, répétable :
|
||||
|
||||
```text
|
||||
--filemap=<file_id>=<filename>
|
||||
```
|
||||
|
||||
Exemples :
|
||||
|
||||
```text
|
||||
--filemap=cfg.std.logging=my.logging.json
|
||||
--filemap=schema.std.logging=my.logging.schema.json
|
||||
--filemap=cfg.composite.ksp-app-wallet-desk=wallet-desk.local.json
|
||||
```
|
||||
|
||||
Équivalent conceptuel programmatique :
|
||||
|
||||
```text
|
||||
ConfigBootstrapOptions
|
||||
.with_file_mapping(file_id, filename)
|
||||
```
|
||||
|
||||
Garanties :
|
||||
|
||||
- dernier override explicite d'un même `file_id` gagne ou duplication est refusée selon la règle qui sera figée avec le parser CLI ;
|
||||
- filename absolu interdit dans un mapping : la racine reste possédée par `cfgpath`/`schemapath` ;
|
||||
- traversal hors racine (`..`) refusé ;
|
||||
- le mapping final est consultable via diagnostics/management sans exposer de secret ;
|
||||
- les compositions référencent des `file_id`, jamais les filenames résolus.
|
||||
|
||||
### 6.4 Documents runtime
|
||||
|
||||
Les vrais documents JSON runtime appartiennent par défaut sous :
|
||||
|
||||
```text
|
||||
config/
|
||||
@@ -225,7 +377,7 @@ config/
|
||||
Nomenclature retenue pour les documents spécialisés/unitaires :
|
||||
|
||||
```text
|
||||
config/std.<domain>.json
|
||||
std.<domain>.json
|
||||
```
|
||||
|
||||
Premier fichier concret :
|
||||
@@ -242,9 +394,9 @@ config/std.wallet.json
|
||||
config/std.onchain-transport.json
|
||||
```
|
||||
|
||||
### 6.2 Compositions
|
||||
### 6.5 Compositions
|
||||
|
||||
Les compositions propres à un exécutable/application utilisent :
|
||||
Les compositions propres à un exécutable/application utilisent par défaut :
|
||||
|
||||
```text
|
||||
config/composite.<consumer>.json
|
||||
@@ -256,11 +408,13 @@ Exemple futur :
|
||||
config/composite.ksp-app-wallet-desk.json
|
||||
```
|
||||
|
||||
Leur identité logique reste `cfg.composite.<consumer>`; le filename peut être remplacé par `--filemap` sans modifier leur contenu logique.
|
||||
|
||||
Aucun composite runtime fictif n'est créé avant l'existence d'un consumer concret. Le moteur et le schéma génériques peuvent néanmoins être testés dans `0.1.3` par fixtures/examples.
|
||||
|
||||
### 6.3 Schémas
|
||||
### 6.6 Schémas
|
||||
|
||||
Les schémas appartiennent sous :
|
||||
Les schémas appartiennent par défaut sous :
|
||||
|
||||
```text
|
||||
config/schemas/
|
||||
@@ -273,14 +427,16 @@ config/schemas/std.logging.schema.json
|
||||
config/schemas/composite.schema.json
|
||||
```
|
||||
|
||||
La nomenclature d'un futur document suit la même famille :
|
||||
Chaque schema possède également un `file_id` et son filename peut être surchargé indépendamment :
|
||||
|
||||
```text
|
||||
std.store.json
|
||||
std.store.schema.json
|
||||
schema.std.logging
|
||||
schema.composite
|
||||
```
|
||||
|
||||
### 6.4 Exemples
|
||||
Le choix du schema applicable provient du descriptor Config, pas d'un filename construit par convention à chaque lecture.
|
||||
|
||||
### 6.7 Exemples
|
||||
|
||||
Les exemples appartiennent sous :
|
||||
|
||||
@@ -297,23 +453,21 @@ config/examples/composite.example.json
|
||||
|
||||
Les exemples ne contiennent aucun vrai secret.
|
||||
|
||||
### 6.5 `.env`
|
||||
### 6.8 `.env`
|
||||
|
||||
Le fichier d'environnement local par défaut est le fichier conventionnel :
|
||||
Le fichier d'environnement local par défaut reste le fichier conventionnel :
|
||||
|
||||
```text
|
||||
.env
|
||||
```
|
||||
|
||||
à la racine runtime/workspace fournie à Config.
|
||||
à la racine de lancement du processus (`./.env`) capturée au bootstrap. `0.1.3` n'introduit pas de troisième path configurable pour `.env`; il n'est ni un substitut de `cfgpath` ni de `schemapath`.
|
||||
|
||||
Il reste ignoré par Git. Un éventuel `.env.example` peut être versionné plus tard lorsqu'une première variable concrète doit être documentée.
|
||||
|
||||
La racine runtime et les chemins Config doivent être fournis explicitement à la session/locator Config ; `ksp-config-lib` ne doit pas rendre son comportement dépendant d'un current working directory implicite.
|
||||
|
||||
## 7. Contrat commun des documents JSON
|
||||
|
||||
Chaque document JSON KSP possède une version de format :
|
||||
Chaque document JSON KSP est chargé à partir de son `file_id` résolu par le registre, puis possède une version de format :
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -326,7 +480,7 @@ Politique :
|
||||
- `format_version` obligatoire ;
|
||||
- version inconnue refusée ;
|
||||
- JSON syntaxiquement invalide refusé ;
|
||||
- validation par le schéma correspondant avant utilisation runtime ;
|
||||
- validation par le schema référencé par le descriptor du `file_id` avant utilisation runtime ;
|
||||
- invariants sémantiques supplémentaires après validation schema ;
|
||||
- document source modifiable représenté par un type sérialisable ;
|
||||
- configuration effective contenant potentiellement des secrets non sérialisable aveuglément ;
|
||||
@@ -341,42 +495,110 @@ Le schéma source doit donc autoriser explicitement une valeur littérale ou une
|
||||
|
||||
Logging est le seul composant runtime existant qui justifie aujourd'hui un document Config réel.
|
||||
|
||||
Structure conceptuelle candidate :
|
||||
Le modèle ne doit pas être réduit à la surface actuelle « une console + un fichier » de `LoggingSettings 0.1.2`. Il doit conserver les besoins déjà connus : plusieurs profils, console configurable, plusieurs sorties fichier simultanées et routing par target/domain/niveau.
|
||||
|
||||
Structure conceptuelle candidate révisée :
|
||||
|
||||
```json
|
||||
{
|
||||
"format_version": 1,
|
||||
"logs_directory": "${KSP_LOGS_DIRECTORY:-logs}",
|
||||
"default_profile": "default",
|
||||
"default_profile": "local_dev",
|
||||
"profiles": [
|
||||
{
|
||||
"name": "default",
|
||||
"default_filter": "info",
|
||||
"profile_id": "local_dev",
|
||||
"default_filter": "warn",
|
||||
"span_events": "new_and_close",
|
||||
"console": {
|
||||
"output": "stdout"
|
||||
},
|
||||
"file": {
|
||||
"file_name_prefix": "ksp",
|
||||
"rotation": "daily"
|
||||
"enabled": true,
|
||||
"output": "stderr",
|
||||
"ansi": true,
|
||||
"format": "compact",
|
||||
"filter": {
|
||||
"level": "debug",
|
||||
"targets": ["*"],
|
||||
"domains": ["*"]
|
||||
}
|
||||
},
|
||||
"files": [
|
||||
{
|
||||
"output_id": "file.all.debug",
|
||||
"enabled": true,
|
||||
"path": "debug.log",
|
||||
"rotation": "daily",
|
||||
"format": "human",
|
||||
"ansi": false,
|
||||
"filter": {
|
||||
"level": "debug",
|
||||
"targets": ["*"],
|
||||
"domains": ["*"]
|
||||
}
|
||||
},
|
||||
{
|
||||
"output_id": "file.config.error",
|
||||
"enabled": true,
|
||||
"path": "config/error.jsonl",
|
||||
"rotation": "daily",
|
||||
"format": "json",
|
||||
"ansi": false,
|
||||
"filter": {
|
||||
"level": "error",
|
||||
"targets": ["ksp-config-lib"],
|
||||
"domains": ["config"]
|
||||
}
|
||||
}
|
||||
],
|
||||
"target_filters": []
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Ce JSON reste **conceptuel** jusqu'à validation du contrat public Logging correspondant. Il fixe néanmoins les capacités attendues.
|
||||
|
||||
Décisions :
|
||||
|
||||
- `logs_directory` est global, hors profils ;
|
||||
- son fallback est exprimé dans le document au point d'usage ;
|
||||
- `default_profile` est global et référence un profil existant ;
|
||||
- les noms de profils sont uniques ;
|
||||
- `file` ne duplique pas le répertoire global ;
|
||||
- console/file peuvent être désactivés selon le schéma final ;
|
||||
- `target_filters` conserve l'ordre source ;
|
||||
- Config valide le document puis construit `LoggingSettings` ;
|
||||
- `LoggingSettings::validate()` reste l'ultime validation du contrat Logging.
|
||||
- `default_profile` est global et référence un `profile_id` existant ;
|
||||
- `profile_id` est obligatoire et unique dans le document ;
|
||||
- `default_filter` gouverne le comportement général du profil ;
|
||||
- la console est un sink spécialisé avec `enabled`, `output`, `ansi`, `format` et son filtre ;
|
||||
- `files[]` peut contenir zéro, un ou plusieurs sinks fichier ;
|
||||
- chaque sink fichier possède un `output_id` unique dans le profil ;
|
||||
- le nom `output_id` est volontairement distinct du `file_id` global de Config afin de ne pas confondre identité d'un document Config et identité d'une sortie Logging ;
|
||||
- `path` d'un sink fichier est relatif à `logs_directory` sauf contrat futur explicite ;
|
||||
- chaque sink peut filtrer au minimum par niveau et par target ;
|
||||
- KSP doit également pouvoir sélectionner par `domain` puisque les macros KSP utilisent déjà ce champ structuré ;
|
||||
- wildcard `*` signifie « tous » dans la dimension concernée ;
|
||||
- `rotation` doit au moins conserver `never/hourly/daily`; d'autres politiques ne sont ajoutées qu'après vérification du backend ;
|
||||
- `format` doit au moins couvrir les formats utiles retenus (`human`, `compact`, `pretty`, `json`) si Logging peut les offrir proprement ;
|
||||
- `ansi` doit être configurable pour la console et doit rester `false`/sans séquences persistées pour les fichiers ;
|
||||
- `target_filters` reste disponible pour la politique générale de takeover/overrides et n'est pas remplacé par les filtres de sink ;
|
||||
- Config valide le document puis construit des settings/sinks publics Logging ;
|
||||
- la validation propre à Logging reste l'ultime validation de son contrat runtime.
|
||||
|
||||
### 8.1 Écart `ksp-logging-lib 0.1.2` à fermer
|
||||
|
||||
| Capacité | `0.1.2` | Requise par `std.logging.json` |
|
||||
|---|---:|---:|
|
||||
| filtre global | oui | oui |
|
||||
| overrides par target | oui | oui |
|
||||
| lifecycle spans | oui | oui |
|
||||
| console stdout/stderr | oui | oui |
|
||||
| console enabled | via `Option` | oui explicite |
|
||||
| console ANSI configurable | non | oui |
|
||||
| format console configurable | non | oui |
|
||||
| plusieurs fichiers | non | oui |
|
||||
| rotation par fichier | un seul fichier | oui par sink |
|
||||
| format par fichier | non | oui |
|
||||
| filtre par sink/target | non | oui |
|
||||
| filtre par sink/domain | non | oui |
|
||||
| filtre par sink/niveau | non indépendant | oui |
|
||||
| hot reload transactionnel | oui | à conserver |
|
||||
| non-blocking/guards/drop counters | oui | à conserver et généraliser par sinks |
|
||||
|
||||
Ce tableau est un **gap identifié**, pas une invitation à déplacer Logging dans Config. La tranche qui le ferme modifie `ksp-logging-lib` uniquement dans son domaine propriétaire.
|
||||
|
||||
`std.logging.json` sert de premier test réel du moteur générique, mais son modèle ne doit pas enfermer Config dans Logging.
|
||||
|
||||
@@ -413,7 +635,7 @@ Un `default_profile` absent peut être autorisé uniquement pour un type de docu
|
||||
|
||||
## 10. Contrat de composition générique
|
||||
|
||||
Une composition assemble plusieurs documents spécialisés sans dupliquer leur contenu.
|
||||
Une composition assemble plusieurs documents spécialisés sans dupliquer leur contenu et les référence par **`file_id` logique**, jamais par filename.
|
||||
|
||||
Structure conceptuelle :
|
||||
|
||||
@@ -423,15 +645,15 @@ Structure conceptuelle :
|
||||
"default_profile": "default",
|
||||
"documents": {
|
||||
"logging": {
|
||||
"source": "std.logging.json"
|
||||
"file_id": "cfg.std.logging"
|
||||
}
|
||||
},
|
||||
"profiles": [
|
||||
{
|
||||
"name": "default",
|
||||
"profile_id": "default",
|
||||
"documents": {
|
||||
"logging": {
|
||||
"profile": "default"
|
||||
"profile_id": "local_dev"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -441,17 +663,19 @@ Structure conceptuelle :
|
||||
|
||||
Principes :
|
||||
|
||||
- la composition référence des documents spécialisés ;
|
||||
- la composition référence des documents spécialisés par `file_id` ;
|
||||
- le registre résout ensuite ce `file_id` vers le filename effectif ;
|
||||
- un `--filemap=cfg.std.logging=...` remplace donc le fichier physique sans modifier le composite ;
|
||||
- chaque document conserve ses globals ;
|
||||
- une composition peut choisir le profil d'un document ;
|
||||
- sans choix explicite, le `default_profile` du document est utilisé ;
|
||||
- le composite ne recopie pas les paramètres spécialisés ;
|
||||
- un profil composite assemble donc les **paramètres globaux** du document et le **profil sélectionné** de ce document ;
|
||||
- un document référencé est toujours lu et résolu par Config ;
|
||||
- profil/document inexistant = erreur ;
|
||||
- un document référencé est toujours lu, validé et résolu par Config ;
|
||||
- `file_id`/profil inexistant = erreur ;
|
||||
- aucun JSON patch générique n'est introduit en `0.1.3` sans besoin concret.
|
||||
|
||||
Cette structure répond au besoin « un composite pioche dans les documents et leurs profils/paramètres » sans dupliquer les valeurs.
|
||||
Cette structure répond au besoin « un composite pioche dans les documents et leurs profils/paramètres » tout en rendant les filenames remplaçables au bootstrap.
|
||||
|
||||
Les références cross-document à une propriété individuelle ne sont pas ouvertes tant qu'un cas concret ne les exige pas.
|
||||
|
||||
@@ -907,11 +1131,13 @@ La stratégie exacte d'écriture atomique et la dépendance éventuelle sont aud
|
||||
|
||||
### 19.4 Chemins
|
||||
|
||||
Les documents sous `config/` sont bornés par un `ConfigRoot` explicite.
|
||||
Les documents Config sont bornés par le `cfgpath` effectif et les schemas par le `schemapath` effectif.
|
||||
|
||||
Les compositions ne doivent pas pouvoir sortir de cette frontière par un chemin absolu ou `..` non autorisé.
|
||||
Un mapping `file_id -> filename` ne peut pas transformer un filename en chemin absolu ni sortir de sa racine par `..`.
|
||||
|
||||
Le `.env` est une source distincte, localisée par un chemin de session Config explicite avec défaut workspace/runtime `.env`.
|
||||
Les compositions ne fournissent aucun chemin physique : elles référencent uniquement des `file_id`.
|
||||
|
||||
Le `.env` est une source distincte fixée à `./.env` pour `0.1.3`; il ne sert pas à relocaliser `cfgpath` ou `schemapath`.
|
||||
|
||||
## 20. Surface runtime, diagnostic et management
|
||||
|
||||
@@ -1042,6 +1268,12 @@ config.schema_validation_failed
|
||||
config.invalid_document
|
||||
config.profile_not_found
|
||||
config.invalid_composition
|
||||
config.invalid_bootstrap_option
|
||||
config.invalid_config_path
|
||||
config.invalid_schema_path
|
||||
config.unknown_file_id
|
||||
config.duplicate_file_id
|
||||
config.invalid_file_mapping
|
||||
config.path_outside_root
|
||||
config.invalid_environment_name
|
||||
config.dotenv_read_failed
|
||||
@@ -1061,17 +1293,29 @@ Une erreur liée à `KSP_SECRET_*` peut contenir le **nom** de variable et son o
|
||||
|
||||
## 24. Dépendances externes candidates
|
||||
|
||||
Aucune dépendance n'est ajoutée dans `pre.001-fix.001`.
|
||||
Aucune dépendance n'est ajoutée dans `pre.001-fix.002`.
|
||||
|
||||
Les besoins prévisibles sont :
|
||||
Le choix de base est désormais clair :
|
||||
|
||||
- `serde` : source typed sérialisable/désérialisable ;
|
||||
- `serde_json` : JSON ;
|
||||
- moteur JSON Schema ;
|
||||
- éventuellement une primitive d'écriture atomique ;
|
||||
- `serde` pour les structures source typées et la serialization/deserialization ;
|
||||
- `serde_json` pour le JSON source, les valeurs intermédiaires et la persistence ;
|
||||
- `jsonschema` pour la validation JSON Schema ;
|
||||
- éventuellement une primitive d'écriture atomique lorsque la tranche de persistence l'introduit ;
|
||||
- éventuellement une bibliothèque dotenv **uniquement si** elle permet la lecture sans mutation globale du processus et si sa sémantique est compatible avec le contrat KSP.
|
||||
|
||||
Les versions courantes et les features sont vérifiées uniquement au delta qui introduit réellement la dépendance, puis déclarées sous `[workspace.dependencies]` avec la contrainte de génération retenue par les règles KSP.
|
||||
Vérification effectuée pendant `pre.001-fix.002` le 15 août 2026 :
|
||||
|
||||
```text
|
||||
serde 1.0.229 -> génération candidate ^1.0
|
||||
serde_json 1.0.151 -> génération candidate ^1.0
|
||||
jsonschema 0.49.6 -> génération candidate ^0.49
|
||||
```
|
||||
|
||||
Ces versions ne sont pas ajoutées par ce fix documentaire. Elles doivent être revérifiées au delta qui introduit réellement chaque dépendance, conformément aux règles Cargo KSP.
|
||||
|
||||
`jsonschema` est retenu comme moteur candidat principal plutôt qu'une validation maison. Son API actuelle sait construire des validators réutilisables et gérer les drafts JSON Schema ; `std.logging.schema.json` devra déclarer explicitement le draft KSP retenu.
|
||||
|
||||
Les dépendances externes communes sont déclarées uniquement sous `[workspace.dependencies]`, puis consommées avec `.workspace = true`.
|
||||
|
||||
### 24.1 Parser dotenv
|
||||
|
||||
@@ -1100,6 +1344,8 @@ Structure interne candidate :
|
||||
```text
|
||||
src/lib.rs
|
||||
src/error.rs
|
||||
src/bootstrap.rs
|
||||
src/file_registry.rs
|
||||
src/document.rs
|
||||
src/schema.rs
|
||||
src/profile.rs
|
||||
@@ -1119,7 +1365,14 @@ Les modules restent privés ; l'API utile est réexportée au crate-root.
|
||||
Types conceptuels à faire émerger au besoin :
|
||||
|
||||
```text
|
||||
ConfigRoot
|
||||
ConfigBootstrapOptions
|
||||
ConfigPath
|
||||
SchemaPath
|
||||
ConfigFileId
|
||||
ConfigFileKind
|
||||
ConfigFileDescriptor
|
||||
ConfigFileRegistry
|
||||
ResolvedConfigFile
|
||||
ConfigSession
|
||||
ConfigDocumentKind
|
||||
ConfigSource
|
||||
@@ -1136,9 +1389,21 @@ ConfigChangeReport
|
||||
ConfigManagementAccess
|
||||
LoggingConfigDocument
|
||||
LoggingProfileConfig
|
||||
LoggingOutputConfig
|
||||
LoggingOutputFilterConfig
|
||||
ResolvedLoggingConfig
|
||||
```
|
||||
|
||||
Le registre doit exposer au minimum :
|
||||
|
||||
```text
|
||||
lookup(file_id)
|
||||
resolve_filename(file_id)
|
||||
override_filename(file_id, filename)
|
||||
```
|
||||
|
||||
avec validation du kind/racine et refus d'un `file_id` inconnu.
|
||||
|
||||
Cette liste n'impose pas de tout créer dans `pre.002`.
|
||||
|
||||
## 26. Audits et tests à introduire
|
||||
@@ -1150,16 +1415,28 @@ Empêcher les accès applicatifs directs hors Config :
|
||||
- `std::env::var`, `var_os`, `vars` pour `KSP_*`/`KSPB_*` ;
|
||||
- loaders dotenv directs ;
|
||||
- lecture/écriture directe des documents `config/std.*.json` et `config/composite.*.json` ;
|
||||
- filenames Config/schema codés dans les consumers au lieu d'un `file_id` ;
|
||||
- parsing divergent de `--cfgpath`, `--schemapath` ou `--filemap` hors de la surface Config prévue ;
|
||||
- dépendance directe `tracing*` depuis Config ;
|
||||
- dépendance inverse Logging -> Config ;
|
||||
- Tauri/TS-RS dans Config sans décision explicite.
|
||||
|
||||
L'audit doit être ciblé afin de ne pas interdire des usages système de `std::env` sans rapport avec la configuration applicative.
|
||||
|
||||
### 26.2 Documents/schemas
|
||||
### 26.2 Bootstrap/registre/documents/schemas
|
||||
|
||||
Tester :
|
||||
|
||||
- défauts `config` et `config/schemas` ;
|
||||
- `--cfgpath` seul n'altère pas `schemapath` ;
|
||||
- `--schemapath` seul n'altère pas `cfgpath` ;
|
||||
- aucune variable env/`.env`/JSON ne peut changer ces deux paths ;
|
||||
- lookup d'un `file_id` connu ;
|
||||
- `file_id` inconnu refusé ;
|
||||
- override de filename connu ;
|
||||
- override de schema filename indépendant ;
|
||||
- filename absolu/traversal refusé ;
|
||||
- composite inchangé lorsque le mapping physique est remplacé ;
|
||||
- JSON invalide ;
|
||||
- schema invalide ;
|
||||
- format version absent/inconnu ;
|
||||
@@ -1167,8 +1444,7 @@ Tester :
|
||||
- `default_profile` ;
|
||||
- profils dupliqués ;
|
||||
- profil absent ;
|
||||
- composition valide/invalide ;
|
||||
- chemin hors `ConfigRoot`.
|
||||
- composition valide/invalide.
|
||||
|
||||
### 26.3 Environnement
|
||||
|
||||
@@ -1237,22 +1513,32 @@ Tester :
|
||||
- failure avant commit conserve ancien contenu ;
|
||||
- chemins gérés respectés.
|
||||
|
||||
### 26.6 Logging adapter
|
||||
### 26.6 Logging adapter et non-régression
|
||||
|
||||
Tester :
|
||||
|
||||
- `logs_directory` global avec fallback ;
|
||||
- unicité des `profile_id` ;
|
||||
- sélection de profil ;
|
||||
- conversion de chaque enum ;
|
||||
- console/file ;
|
||||
- target filters ;
|
||||
- `LoggingSettings::validate()` ;
|
||||
- console enabled/output/ANSI/format ;
|
||||
- zéro/un/plusieurs sinks fichier ;
|
||||
- unicité des `output_id` ;
|
||||
- rotation/format de chaque fichier ;
|
||||
- routing par target ;
|
||||
- routing par domain ;
|
||||
- niveau par sink ;
|
||||
- target filters globaux ;
|
||||
- combinaison wildcard/spécialisation ;
|
||||
- hot reload conservé ;
|
||||
- writers/guards/drop counters conservés ou généralisés proprement ;
|
||||
- validation publique Logging ;
|
||||
- changement Config sans reconfiguration implicite ;
|
||||
- `LoggingGuard` reste orchestration-owned.
|
||||
- `LoggingGuard` reste orchestration-owned ;
|
||||
- canary démontrant qu'aucun comportement utile déjà offert par la configuration bot3 n'est perdu silencieusement.
|
||||
|
||||
## 27. Découpage souple des prereleases
|
||||
|
||||
### `0.1.3-pre.001` + `pre.001-fix.001` — audit, brainstorming et plan corrigé
|
||||
### `0.1.3-pre.001` + `pre.001-fix.001/.002` — audit, brainstorming et plan corrigé
|
||||
|
||||
- audit `v0.1.2` ;
|
||||
- audit historique ciblé ;
|
||||
@@ -1260,37 +1546,53 @@ Tester :
|
||||
- correction vers `.env` conventionnel ;
|
||||
- interpolation `${...}` + fallback ;
|
||||
- modèle real/safe/provenance/sensitivity ;
|
||||
- aucune crate/dépendance fonctionnelle Config.
|
||||
- registre `file_id -> filename` + schemas ;
|
||||
- bootstrap `cfgpath`/`schemapath` non récursif ;
|
||||
- audit de non-régression Logging et modèle `std.logging.json` enrichi ;
|
||||
- choix `serde`/`serde_json`/`jsonschema` comme base candidate ;
|
||||
- aucune crate/dépendance fonctionnelle Config ajoutée.
|
||||
|
||||
### `0.1.3-pre.002` — fondation de crate + contrats source
|
||||
### `0.1.3-pre.002` — bootstrap Config + registre de fichiers
|
||||
|
||||
- créer `ksp-config-lib` ;
|
||||
- dépendances minimales réellement utilisées ;
|
||||
- erreurs initiales ;
|
||||
- `ConfigRoot`/session/locator ;
|
||||
- contrat commun document/version ;
|
||||
- premiers types `std.logging` source ;
|
||||
- tests initiaux.
|
||||
- `ConfigBootstrapOptions` ;
|
||||
- défauts hardcodés `config` / `config/schemas` ;
|
||||
- parsing/contrat `--cfgpath`, `--schemapath`, `--filemap` ;
|
||||
- `ConfigFileId`/descriptors/registre/mappings ;
|
||||
- tests bootstrap sans ouvrir encore le moteur complet.
|
||||
|
||||
### `0.1.3-pre.003` — JSON Schema + `std.logging.json`
|
||||
### `0.1.3-pre.003` — complétion bornée du contrat Logging
|
||||
|
||||
- étendre les settings publics Logging uniquement où l'audit `0.1.2` montre un gap ;
|
||||
- plusieurs sinks fichier ;
|
||||
- console ANSI/format selon faisabilité du backend ;
|
||||
- filters de sink par niveau/target/domain ;
|
||||
- préserver subscriber unique, takeover, hot reload transactionnel, non-blocking, guards et compteurs ;
|
||||
- aucun accès Config depuis Logging.
|
||||
|
||||
### `0.1.3-pre.004` — JSON/JSON Schema + `std.logging.json`
|
||||
|
||||
- `serde`/`serde_json`/`jsonschema` au workspace avec versions revérifiées ;
|
||||
- `config/`, `config/schemas/`, `config/examples/` ;
|
||||
- `std.logging.schema.json` ;
|
||||
- runtime `config/std.logging.json` ;
|
||||
- exemple Logging ;
|
||||
- pipeline parse/schema/semantic ;
|
||||
- `default_profile` et globals.
|
||||
- `default_profile`, `profile_id`, globals et outputs Logging.
|
||||
|
||||
### `0.1.3-pre.004` — profils + composition
|
||||
### `0.1.3-pre.005` — profils + composition
|
||||
|
||||
- résolution de profils spécialisés ;
|
||||
- contrat composite générique ;
|
||||
- schema/example composite ;
|
||||
- références de documents par `file_id` ;
|
||||
- sélection de profils documentaires ;
|
||||
- provenance document/global/profile ;
|
||||
- aucun composite runtime fictif obligatoire.
|
||||
|
||||
### `0.1.3-pre.005` — `.env` + resolver `${...}`
|
||||
### `0.1.3-pre.006` — `.env` + resolver `${...}`
|
||||
|
||||
- lecture process env ;
|
||||
- lecture `.env` sans écrasement process ;
|
||||
@@ -1300,17 +1602,17 @@ Tester :
|
||||
- namespaces KSP/KSPB ;
|
||||
- tests d'isolation process env.
|
||||
|
||||
### `0.1.3-pre.006` — sensibilité + valeurs real/safe + Logging adapter
|
||||
### `0.1.3-pre.007` — sensibilité + valeurs real/safe + Logging adapter
|
||||
|
||||
- `Public/Internal/Secret` ;
|
||||
- propagation par chaîne composée ;
|
||||
- redaction par segment ;
|
||||
- contrat `ResolvedValue` ou équivalent ;
|
||||
- adaptation `ResolvedLoggingConfig -> LoggingSettings` ;
|
||||
- adaptation `ResolvedLoggingConfig ->` contrats publics Logging ;
|
||||
- tests canary de non-divulgation ;
|
||||
- démonstration `initialize/reinitialize` avec guard orchestration-owned.
|
||||
|
||||
### `0.1.3-pre.007` — management + persistence JSON/.env
|
||||
### `0.1.3-pre.008` — management + persistence JSON/.env
|
||||
|
||||
- lecture management ;
|
||||
- reveal secret explicite ;
|
||||
@@ -1319,15 +1621,15 @@ Tester :
|
||||
- persistence atomique ;
|
||||
- desired/effective/shadow report.
|
||||
|
||||
### `0.1.3-pre.008` — ownership audits + robustesse
|
||||
### `0.1.3-pre.009` — ownership audits + robustesse
|
||||
|
||||
- audits interdisant les accès Config/env directs ailleurs ;
|
||||
- invalid documents/env/placeholders ;
|
||||
- invalid documents/env/placeholders/file mappings ;
|
||||
- graphe dépendances/features ;
|
||||
- corrections de surface publique ;
|
||||
- robustesse des diagnostics sans fuite.
|
||||
|
||||
### `0.1.3-pre.009` — clôture
|
||||
### `0.1.3-pre.010` — clôture
|
||||
|
||||
- validations finales ;
|
||||
- documentation durable ;
|
||||
@@ -1377,17 +1679,27 @@ Une commande non exécutée n'est jamais déclarée réussie.
|
||||
|
||||
## 30. Critères de validation du plan avant `pre.002`
|
||||
|
||||
Le `pre.001-fix.001` est validable lorsque les décisions suivantes sont acceptées :
|
||||
Le `pre.001-fix.002` est validable lorsque les décisions suivantes sont acceptées :
|
||||
|
||||
- `ksp-config-lib` est l'unique manager KSP des documents Config et variables applicatives ;
|
||||
- premier document réel : `config/std.logging.json` ;
|
||||
- Config possède un registre logique de fichiers avec `file_id` globalement unique ;
|
||||
- les documents et schemas connus disposent d'un mapping par défaut `file_id -> filename` ;
|
||||
- les composites référencent les documents par `file_id`, jamais par filename ;
|
||||
- les mappings physiques peuvent être remplacés au bootstrap, y compris pour les schemas ;
|
||||
- `cfgpath` et `schemapath` ont les défauts hardcodés `config` et `config/schemas` ;
|
||||
- ces deux paths ne peuvent être remplacés ni par JSON, ni `.env`, ni `KSP_*`/`KSPB_*` ;
|
||||
- ils ne changent qu'au bootstrap via `--cfgpath`/`--schemapath` ou options programmatiques explicites ;
|
||||
- `--filemap=<file_id>=<filename>` est le mécanisme de sélection d'un filename alternatif ;
|
||||
- premier document réel : `config/std.logging.json` identifié par `cfg.std.logging` ;
|
||||
- futurs documents : `config/std.<domain>.json` ;
|
||||
- futurs composites : `config/composite.<consumer>.json` ;
|
||||
- JSON validé par schema avant usage ;
|
||||
- JSON validé par `jsonschema` contre le schema associé au descriptor du `file_id` ;
|
||||
- `serde` + `serde_json` constituent la base de parsing/manipulation/persistence ;
|
||||
- globals hors profils ;
|
||||
- `default_profile` autonome ;
|
||||
- profils identifiés par `profile_id` unique ;
|
||||
- composite assemble documents + globals + profils sans recopier les valeurs ;
|
||||
- `.env` conventionnel à la racine runtime/workspace ;
|
||||
- `.env` conventionnel `./.env` à la racine de lancement, sans troisième path Config dans `0.1.3` ;
|
||||
- environnement du processus > `.env` > fallback ;
|
||||
- fallback déclaré par `${KSP_VAR:-fallback}` ;
|
||||
- fallback utilisé seulement lorsque la variable est absente ; une chaîne vide compte comme définie ;
|
||||
@@ -1400,7 +1712,10 @@ Le `pre.001-fix.001` est validable lorsque les décisions suivantes sont accept
|
||||
- une chaîne composée conserve valeur réelle + valeur sûre + provenance + sensibilité ;
|
||||
- `ksp-app-config-desk` pourra révéler/modifier les secrets via une surface management privilégiée ;
|
||||
- même cette application ne logge jamais les secrets ;
|
||||
- Config construit `LoggingSettings` et l'orchestration possède `LoggingGuard` ;
|
||||
- `std.logging.json` supporte conceptuellement une console configurable et plusieurs sinks fichier avec identifiants uniques, niveaux, targets, domains, rotation, format et ANSI selon la nature du sink ;
|
||||
- l'écart de capacités de `ksp-logging-lib 0.1.2` est reconnu et sera fermé dans Logging, pas contourné par Config ;
|
||||
- le lifecycle/ownership Logging `initialize/reinitialize/LoggingGuard` reste inchangé ;
|
||||
- persistence JSON et `.env` atomique ;
|
||||
- `0.1.3` reste une release unique bornée ;
|
||||
- `0.1.3` reste une release unique bornée avec clôture prévisionnelle en `pre.010` ;
|
||||
- aucune implémentation `pre.002` ne commence avant validation utilisateur de ce plan corrigé.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user