96 lines
3.9 KiB
Markdown
96 lines
3.9 KiB
Markdown
<!-- file: docs/guides/CONFIGURATION.md -->
|
||
<!-- version: 5 -->
|
||
|
||
# Guide de configuration
|
||
|
||
## Objectif
|
||
|
||
Ce guide décrit le chargement des documents de configuration après leur séparation. La référence d’API générale reste `ks-config/USAGE.md` et la configuration logging appartient à `ks-logging`.
|
||
|
||
## Fichiers actifs
|
||
|
||
- `config/app.config.json` : configuration générale chargée par défaut ;
|
||
- `config/logging.config.json` : configuration logging chargée par défaut ;
|
||
- `config/example.app.config.json` et `config/example.logging.config.json` : exemples minimaux conformes ;
|
||
- `config/schemas/app.config.schema.json` : schéma général ;
|
||
- `config/schemas/logging.config.schema.json` : schéma logging ;
|
||
- `.env`, ou le fichier sélectionné par `KS_ENV_FILE` : valeurs d’environnement non versionnées ;
|
||
- `.env.example` : noms de variables attendues sans secrets réels.
|
||
|
||
`KS_CONFIG_PATH` et `KS_LOGGING_CONFIG_PATH` permettent de remplacer indépendamment les deux chemins par défaut.
|
||
|
||
## Configuration générale
|
||
|
||
L’API recommandée reste `ks_config::read_config_json_file_with_environment`. Elle :
|
||
|
||
1. charge `.env`, ou le fichier sélectionné par `KS_ENV_FILE`, sans écraser les variables du processus ;
|
||
2. lit le JSON général ;
|
||
3. résout les placeholders `${KS_*}` / `${KB_*}` ;
|
||
4. valide `config/schemas/app.config.schema.json` ;
|
||
5. désérialise `AppConfig` et applique les invariants métier ;
|
||
6. laisse `active_profile` sélectionner le profil applicatif actif.
|
||
|
||
```rust
|
||
let config = match ks_config::read_config_json_file_with_environment(
|
||
std::path::Path::new("config/app.config.json"),
|
||
std::path::Path::new("."),
|
||
) {
|
||
std::result::Result::Ok(value) => value,
|
||
std::result::Result::Err(error) => return std::result::Result::Err(error),
|
||
};
|
||
let profile = match ks_config::active_profile(&config) {
|
||
std::result::Result::Ok(value) => value,
|
||
std::result::Result::Err(error) => return std::result::Result::Err(error),
|
||
};
|
||
```
|
||
|
||
Le profil général ne contient plus de bloc `logging`.
|
||
|
||
## Configuration logging
|
||
|
||
`ks_logging::read_logging_json_file_with_environment` charge séparément le document logging et `ks_logging::active_logging_profile` sélectionne son profil actif.
|
||
|
||
```rust
|
||
let logging = match ks_logging::read_logging_json_file_with_environment(
|
||
std::path::Path::new("config/logging.config.json"),
|
||
std::path::Path::new("."),
|
||
) {
|
||
std::result::Result::Ok(value) => value,
|
||
std::result::Result::Err(error) => return std::result::Result::Err(error),
|
||
};
|
||
let logging_profile = match ks_logging::active_logging_profile(&logging) {
|
||
std::result::Result::Ok(value) => value,
|
||
std::result::Result::Err(error) => return std::result::Result::Err(error),
|
||
};
|
||
```
|
||
|
||
Les deux `active_profile` sont indépendants. Il n’existe aucun fallback implicite du profil logging vers le nom du profil applicatif.
|
||
|
||
## Invariants
|
||
|
||
- aucun secret réel ne doit être ajouté aux fichiers versionnés ;
|
||
- les placeholders non résolus doivent rester détectables ;
|
||
- chaque schéma embarqué doit rester identique au fichier sous `config/schemas/` ;
|
||
- les profils applicatifs et logging sont validés indépendamment ;
|
||
- `ks-config` ne possède plus de types logging ;
|
||
- tant que `0.5.1-pre.006` n’a pas introduit les DTO sûrs, la configuration runtime résolue reste strictement backend et ne doit pas être exposée telle quelle.
|
||
|
||
## Diagnostic
|
||
|
||
Pour isoler une erreur :
|
||
|
||
1. vérifier le fichier d’environnement chargé ;
|
||
2. vérifier séparément les chemins app et logging ;
|
||
3. valider chaque document contre son schéma ;
|
||
4. vérifier son `active_profile` ;
|
||
5. vérifier ensuite les rôles HTTP/WebSocket, stockage ou routes logging concernés.
|
||
|
||
Ne jamais écrire dans les logs le JSON résolu complet s’il contient une valeur issue de `KS_SECRET_*` ou `KB_SECRET_*`.
|
||
|
||
## Références
|
||
|
||
- `ks-config/README.md` et `ks-config/USAGE.md` ;
|
||
- `ks-logging/README.md` et `ks-logging/USAGE.md` ;
|
||
- `config/README.md` ;
|
||
- `docs/decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md`.
|