299 lines
8.4 KiB
Markdown
299 lines
8.4 KiB
Markdown
<!-- file: deltas/0.1.3/pre.010.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# Delta 0.1.3-pre.010
|
|
|
|
## Base requise
|
|
|
|
Livraison précédente validée :
|
|
|
|
```text
|
|
0.1.3-pre.009-fix.001
|
|
```
|
|
|
|
Version technique de cette base :
|
|
|
|
```text
|
|
workspace.package.version = "0.1.3-pre.9.fix.1"
|
|
Cargo.toml header version = 51
|
|
```
|
|
|
|
Validations utilisateur exécutées le 2026-08-15 :
|
|
|
|
```text
|
|
cargo fmt --all OK
|
|
cargo check --workspace OK
|
|
cargo clippy --workspace --all-targets OK
|
|
cargo test --workspace OK
|
|
cargo tree -p ksp-config-lib OK
|
|
cargo tree -p ksp-config-lib -d OK, doublon transitif syn 2/3 déjà connu
|
|
cargo tree -p ksp-config-lib -e features OK
|
|
```
|
|
|
|
`cargo test --workspace` confirme notamment 39 tests unitaires + 7 tests publics pour `ksp-config-lib`.
|
|
|
|
## Objet de pre.010
|
|
|
|
Introduire la première résolution environnementale Config réellement consommable :
|
|
|
|
```text
|
|
process environment
|
|
>
|
|
./.env
|
|
>
|
|
placeholder/API fallback
|
|
->
|
|
ConfigEnvironmentValue
|
|
->
|
|
${NAME} / ${NAME:-fallback}
|
|
->
|
|
JSON effective values
|
|
```
|
|
|
|
La sensibilité et les représentations sûres restent volontairement réservées à `pre.011`.
|
|
|
|
## Propriété et sources
|
|
|
|
`ConfigEnvironment` est le snapshot possédé par `ksp-config-lib`.
|
|
|
|
`ConfigEnvironment::load()` :
|
|
|
|
1. capture les variables supportées héritées par le processus ;
|
|
2. lit `./.env` s'il existe ;
|
|
3. ne modifie jamais l'environnement du processus, du shell, de systemd ou du parent ;
|
|
4. considère l'absence de `.env` comme une source locale vide.
|
|
|
|
Une erreur de lecture réelle de `.env` reste distincte de son absence.
|
|
|
|
Les seuls namespaces applicatifs acceptés sont :
|
|
|
|
```text
|
|
KSP_*
|
|
KSPB_*
|
|
```
|
|
|
|
ce qui couvre naturellement :
|
|
|
|
```text
|
|
KSP_PUBLIC_*
|
|
KSP_SECRET_*
|
|
KSPB_PUBLIC_*
|
|
KSPB_SECRET_*
|
|
```
|
|
|
|
## Priorité et chaîne vide
|
|
|
|
`ConfigEnvironment::resolve_variable(name, fallback)` applique :
|
|
|
|
```text
|
|
process > .env > fallback > missing
|
|
```
|
|
|
|
Une chaîne vide explicitement présente dans le processus ou `.env` reste une valeur définie. Elle ne déclenche pas le fallback.
|
|
|
|
`ConfigEnvironmentValue` expose :
|
|
|
|
```text
|
|
variable_name
|
|
value réelle
|
|
source = Process | DotEnv | Fallback
|
|
```
|
|
|
|
Le type n'implémente volontairement pas `Debug` afin de ne pas créer une voie de fuite accidentelle avant l'introduction de la sensibilité/redaction en `pre.011`.
|
|
|
|
## Resolver `${...}`
|
|
|
|
Config supporte :
|
|
|
|
```text
|
|
${KSP_VAR}
|
|
${KSP_VAR:-fallback}
|
|
```
|
|
|
|
Règles :
|
|
|
|
- plusieurs placeholders peuvent apparaître dans une même string ;
|
|
- le fallback n'est utilisé que si la variable est absente ;
|
|
- le fallback est littéral dans cette tranche et n'est pas récursivement interprété ;
|
|
- les placeholders imbriqués/malformés sont refusés ;
|
|
- les clés JSON ne sont pas interpolées ; seules les valeurs string le sont ;
|
|
- objets et tableaux JSON sont parcourus récursivement.
|
|
|
|
APIs principales :
|
|
|
|
```text
|
|
ConfigEnvironment::resolve_variable(...)
|
|
ConfigEnvironment::resolve_text(...)
|
|
ConfigEnvironment::resolve_json(...)
|
|
ConfigEnvironment::resolve_map(...)
|
|
ResolvedConfigProfile::resolve_effective_environment(...)
|
|
```
|
|
|
|
La résolution d'environnement d'un profil produit une nouvelle map effective et ne modifie pas la source, le `profile_id`, la provenance `Global/Profile` ni la sélection du profil déjà résolu.
|
|
|
|
## Variable manquante
|
|
|
|
Une référence sans valeur process, sans valeur `.env` et sans fallback retourne :
|
|
|
|
```text
|
|
config.environment_variable_missing
|
|
```
|
|
|
|
Config émet également un warning via la façade KSP :
|
|
|
|
```text
|
|
target = ksp-config-lib
|
|
domain = config.environment
|
|
```
|
|
|
|
Le warning et l'erreur contiennent le nom de la variable mais jamais sa valeur.
|
|
|
|
`ksp-config-lib` dépend donc maintenant réellement de `ksp-logging-lib`. La dépendance inverse Logging -> Config reste interdite.
|
|
|
|
## `.env`
|
|
|
|
Le parser Config de cette tranche accepte un sous-ensemble déterministe adapté au fichier KSP géré :
|
|
|
|
- lignes vides et commentaires `#` ;
|
|
- préfixe optionnel `export ` ;
|
|
- `NAME=value` ;
|
|
- valeur non quotée ;
|
|
- valeur entre quotes simples ;
|
|
- valeur entre quotes doubles avec escapes bornés `\\`, `\"`, `\n`, `\r`, `\t` ;
|
|
- commentaire inline d'une valeur non quotée lorsqu'il commence par ` #` ;
|
|
- chaîne vide ;
|
|
- clés étrangères valides ignorées par Config ;
|
|
- doublon d'une clé KSP/KSPB refusé pour éviter une résolution locale ambiguë.
|
|
|
|
Aucune interpolation interne du fichier `.env` n'est ajoutée dans cette tranche.
|
|
|
|
## `.env.example` — nouvelle règle durable
|
|
|
|
Le dépôt possède désormais à la racine :
|
|
|
|
```text
|
|
.env.example
|
|
```
|
|
|
|
Ce fichier est versionné et sert d'inventaire canonique des variables runtime KSP/KSPB utilisées par les fichiers Config ou le code opérationnel.
|
|
|
|
Règles enregistrées :
|
|
|
|
- toute nouvelle variable runtime KSP/KSPB est ajoutée à `.env.example` dans le même delta que sa première utilisation ;
|
|
- chaque variable est précédée d'un commentaire expliquant son usage/utilité ;
|
|
- une entrée peut être active avec une valeur par défaut sûre, porter une valeur générique non secrète ou être commentée ;
|
|
- aucun vrai secret n'y est stocké ;
|
|
- le fichier local `.env` reste non versionné et non échangé ;
|
|
- l'objectif est de pouvoir créer `.env` depuis `.env.example` et repérer localement les nouvelles clés par diff.
|
|
|
|
La première entrée est :
|
|
|
|
```text
|
|
KSP_LOGS_DIRECTORY=logs
|
|
```
|
|
|
|
car `config/std.logging.json` est actuellement le seul fichier runtime utilisant une variable d'environnement.
|
|
|
|
`.gitignore` possédait déjà :
|
|
|
|
```text
|
|
.env
|
|
.env.*
|
|
!.env.example
|
|
```
|
|
|
|
et n'a donc pas besoin d'être modifié.
|
|
|
|
## Tests
|
|
|
|
Les nouveaux tests couvrent notamment :
|
|
|
|
- priorité process > `.env` > fallback ;
|
|
- chaîne vide process et `.env` considérée comme définie ;
|
|
- variable manquante sans fallback ;
|
|
- namespaces KSP/KSPB ;
|
|
- résolution de plusieurs placeholders ;
|
|
- placeholder malformé/imbriqué ;
|
|
- résolution récursive object/array JSON ;
|
|
- parsing `.env` avec commentaires, `export` et quotes ;
|
|
- refus des doublons KSP dans `.env` ;
|
|
- collecte process synthétique sans mutation du vrai environnement ;
|
|
- résolution du fallback `${KSP_LOGS_DIRECTORY:-logs}` du document Logging commité ;
|
|
- présence commentée de `KSP_LOGS_DIRECTORY` dans `.env.example` ;
|
|
- disponibilité de la surface environment depuis le crate-root.
|
|
|
|
Les tests n'appellent pas `std::env::set_var` / `remove_var`; aucune mutation unsafe de l'environnement n'est nécessaire en Rust 2024.
|
|
|
|
## Dépendances
|
|
|
|
Aucune nouvelle dépendance externe n'est ajoutée.
|
|
|
|
Dépendance KSP désormais utilisée :
|
|
|
|
```text
|
|
ksp-config-lib -> ksp-logging-lib
|
|
```
|
|
|
|
pour les warnings/diagnostics runtime Config.
|
|
|
|
Les dépendances externes `serde`, `serde_json` et `jsonschema` restent inchangées.
|
|
|
|
## Version technique
|
|
|
|
La prerelease devient :
|
|
|
|
```text
|
|
workspace.package.version = "0.1.3-pre.10"
|
|
Cargo.toml header version = 52
|
|
```
|
|
|
|
## Fichiers ajoutés
|
|
|
|
```text
|
|
.env.example
|
|
crates/ksp-config-lib/src/environment.rs
|
|
crates/ksp-config-lib/unit_tests/environment.rs
|
|
deltas/0.1.3/pre.010.md
|
|
```
|
|
|
|
## Fichiers modifiés
|
|
|
|
```text
|
|
Cargo.toml
|
|
crates/ksp-config-lib/Cargo.toml
|
|
crates/ksp-config-lib/src/error.rs
|
|
crates/ksp-config-lib/src/lib.rs
|
|
crates/ksp-config-lib/src/profile.rs
|
|
crates/ksp-config-lib/tests/public_api.rs
|
|
docs/architecture/005-DEPENDENCY_GRAPH.md
|
|
docs/plans/000-README.md
|
|
docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md
|
|
docs/plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md
|
|
docs/rules/FILE_CONTRACTS.md
|
|
docs/rules/RULES_KSP.md
|
|
```
|
|
|
|
## Fichiers supprimés
|
|
|
|
Aucun.
|
|
|
|
## Contrôles exécutés dans l'environnement de génération
|
|
|
|
- parsing TOML du manifest racine et de `ksp-config-lib` ;
|
|
- audit statique des accès `std::env::*` : seul `crates/ksp-config-lib/src/environment.rs` lit l'environnement applicatif ;
|
|
- audit statique des variables runtime exactes dans `crates/*/src` + `config/` : `KSP_LOGS_DIRECTORY` est la seule clé actuelle et elle est présente dans `.env.example` ;
|
|
- absence de `unsafe`, `unwrap`, `expect`, `panic!` et `?` dans le nouveau code de production Config ;
|
|
- contrôle des headers/version et des lignes Rust ajoutées/modifiées ;
|
|
- comparaison du delta avec la base `pre.009-fix.001` ;
|
|
- aucun `Cargo.lock` ajouté.
|
|
|
|
Le toolchain Rust n'est pas disponible dans l'environnement de génération. `cargo fmt/check/clippy/test` doivent donc être exécutés par l'utilisateur.
|
|
|
|
## Étape suivante
|
|
|
|
Après validation utilisateur :
|
|
|
|
```text
|
|
0.1.3-pre.011 — sensibilité Public/Internal/Secret + real/safe/provenance + redaction par segment
|
|
```
|