0.5.1-pre.006
This commit is contained in:
@@ -1,95 +1,134 @@
|
||||
<!-- file: docs/guides/CONFIGURATION.md -->
|
||||
<!-- version: 5 -->
|
||||
<!-- version: 6 -->
|
||||
|
||||
# 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`.
|
||||
La configuration est organisée autour de compositions propres aux binaires et de documents spécialisés réutilisables. Un binaire choisit les fichiers partagés et les profils dont il a besoin au lieu de recopier une configuration monolithique.
|
||||
|
||||
## 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.
|
||||
Compositions :
|
||||
|
||||
`KS_CONFIG_PATH` et `KS_LOGGING_CONFIG_PATH` permettent de remplacer indépendamment les deux chemins par défaut.
|
||||
- `config/kb-app-demo-desktop.default.config.json` : composition par défaut du desktop ;
|
||||
- `config/ks-pipeline-demo-scenarios.default.config.json` : composition par défaut du CLI/scénarios.
|
||||
|
||||
## Configuration générale
|
||||
Documents partagés :
|
||||
|
||||
L’API recommandée reste `ks_config::read_config_json_file_with_environment`. Elle :
|
||||
- `config/logging.config.json` ;
|
||||
- `config/transport.config.json` ;
|
||||
- `config/listeners.config.json`.
|
||||
|
||||
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.
|
||||
Exemples :
|
||||
|
||||
```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),
|
||||
};
|
||||
- `config/example.kb-app-demo-desktop.default.config.json` ;
|
||||
- `config/example.logging.config.json` ;
|
||||
- `config/example.transport.config.json` ;
|
||||
- `config/example.listeners.config.json`.
|
||||
|
||||
Schémas :
|
||||
|
||||
- `config/schemas/composition.config.schema.json` ;
|
||||
- `config/schemas/logging.config.schema.json` ;
|
||||
- `config/schemas/transport.config.schema.json` ;
|
||||
- `config/schemas/listeners.config.schema.json` ;
|
||||
- `config/schemas/resolved.app.config.schema.json` pour le contrat runtime reconstruit.
|
||||
|
||||
`.env`, ou le fichier sélectionné par `KS_ENV_FILE`, fournit les valeurs non versionnées.
|
||||
|
||||
## Composition d'un binaire
|
||||
|
||||
Une composition définit :
|
||||
|
||||
1. son `active_profile` ;
|
||||
2. les chemins des documents partagés ;
|
||||
3. pour chaque profil, le `logging_profile`, `transport_profile` et `listeners_profile` à sélectionner ;
|
||||
4. temporairement, les sections qui n'ont pas encore leur document spécialisé.
|
||||
|
||||
Exemple conceptuel :
|
||||
|
||||
```text
|
||||
kb-app-demo-desktop.default.config.json
|
||||
sources.logging -> config/logging.config.json
|
||||
sources.transport -> config/transport.config.json
|
||||
sources.listeners -> config/listeners.config.json
|
||||
|
||||
profile mainnet_research
|
||||
logging_profile -> mainnet_research
|
||||
transport_profile -> mainnet_research
|
||||
listeners_profile -> mainnet_research
|
||||
```
|
||||
|
||||
Le profil général ne contient plus de bloc `logging`.
|
||||
Les `active_profile` propres aux documents partagés restent utiles lorsqu'ils sont chargés seuls. Dans une composition, la référence explicite du binaire prime.
|
||||
|
||||
## Configuration logging
|
||||
## Desktop
|
||||
|
||||
`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.
|
||||
Le chemin de composition du desktop peut être remplacé par :
|
||||
|
||||
```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),
|
||||
};
|
||||
```text
|
||||
KB_APP_DEMO_DESKTOP_CONFIG_PATH
|
||||
```
|
||||
|
||||
Les deux `active_profile` sont indépendants. Il n’existe aucun fallback implicite du profil logging vers le nom du profil applicatif.
|
||||
Le logging conserve l'override opérationnel :
|
||||
|
||||
```text
|
||||
KS_LOGGING_CONFIG_PATH
|
||||
```
|
||||
|
||||
Sans cet override, le desktop utilise le chemin logging déclaré par sa composition.
|
||||
|
||||
## Scénarios Devnet
|
||||
|
||||
Les scénarios opt-in utilisent :
|
||||
|
||||
```text
|
||||
KS_DEVNET_CONFIG_PATH
|
||||
KS_DEVNET_PROFILE
|
||||
```
|
||||
|
||||
`KS_DEVNET_CONFIG_PATH` désigne désormais un fichier de composition. Sans override, les scénarios utilisent `config/ks-pipeline-demo-scenarios.default.config.json`.
|
||||
|
||||
## Transport
|
||||
|
||||
`transport.config.json` possède les endpoints HTTP et WebSocket ainsi que leurs rôles et limites. Le profil transport peut être consommé directement par `ks-onchain-transport` sans dépendre d'un profil applicatif complet.
|
||||
|
||||
Cela prépare les futurs workers : un worker de capture pourra sélectionner un profil transport différent du desktop tout en partageant le même document.
|
||||
|
||||
## Listeners
|
||||
|
||||
`listeners.config.json` contient les déclarations de subscriptions par logs, programme et compte. Un profil listeners peut être associé à n'importe quel profil transport compatible par le fichier de composition du consommateur.
|
||||
|
||||
La séparation évite de recopier les listes de `program_id` et les filtres lorsque plusieurs binaires observent la même surface Solana.
|
||||
|
||||
## Logging
|
||||
|
||||
`logging.config.json` appartient à `ks-logging`. Une composition référence son fichier et son profil, mais les types et validations logging ne reviennent pas dans `ks-config`.
|
||||
|
||||
## Contrat runtime résolu
|
||||
|
||||
Pendant la migration `0.5.1`, `ks-config` reconstruit encore un `AppConfig/ProfileConfig` contenant les sections nécessaires aux consommateurs existants. Ce contrat est une projection runtime, pas une configuration source.
|
||||
|
||||
Les tests de compatibilité utilisent les fixtures sous `test-fixtures/config/`. Aucun binaire ne doit charger ces fixtures en production.
|
||||
|
||||
## Étapes suivantes
|
||||
|
||||
Le prochain split doit extraire :
|
||||
|
||||
- database vers le document store ;
|
||||
- `logs_directory` vers logging ;
|
||||
- `wallets_directory`, le stockage wallet et les paramètres de wallet vers un document wallet ;
|
||||
- les permissions `*_send_enabled` du wallet vers la politique execution ;
|
||||
- execution ;
|
||||
- configuration spécifique au desktop.
|
||||
|
||||
Après cette étape seulement, les DTO publics, diagnostics et règles de camouflage seront construits sur les nouvelles frontières.
|
||||
|
||||
## 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`.
|
||||
- aucun secret réel dans les fichiers versionnés ;
|
||||
- tous les schémas actifs sous `config/schemas/` ;
|
||||
- aucun retour au fichier monolithique `app.config.json` ;
|
||||
- un fichier de composition appartient à son binaire ;
|
||||
- un document spécialisé reste indépendant des binaires qui le consomment ;
|
||||
- `ks-config` fournit les mécanismes partagés sans enregistrer une liste fermée de workers/applications.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/guides/LOGGING.md -->
|
||||
<!-- version: 5 -->
|
||||
<!-- version: 6 -->
|
||||
|
||||
# Guide de logging et tracing
|
||||
|
||||
@@ -33,7 +33,7 @@ let guard = match ks_logging::init_logging(config) {
|
||||
};
|
||||
```
|
||||
|
||||
Le profil logging est sélectionné indépendamment du profil général de `app.config.json`.
|
||||
Le document logging reste indépendant de la composition binaire. Une composition `<binary>.default.config.json` sélectionne explicitement le profil logging qu’elle veut utiliser ; le `active_profile` propre à `logging.config.json` reste disponible pour les consommateurs autonomes.
|
||||
|
||||
## Contrat JSON
|
||||
|
||||
|
||||
Reference in New Issue
Block a user