135 lines
4.9 KiB
Markdown
135 lines
4.9 KiB
Markdown
<!-- file: docs/guides/CONFIGURATION.md -->
|
|
<!-- version: 6 -->
|
|
|
|
# Guide de configuration
|
|
|
|
## Objectif
|
|
|
|
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
|
|
|
|
Compositions :
|
|
|
|
- `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.
|
|
|
|
Documents partagés :
|
|
|
|
- `config/logging.config.json` ;
|
|
- `config/transport.config.json` ;
|
|
- `config/listeners.config.json`.
|
|
|
|
Exemples :
|
|
|
|
- `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
|
|
```
|
|
|
|
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.
|
|
|
|
## Desktop
|
|
|
|
Le chemin de composition du desktop peut être remplacé par :
|
|
|
|
```text
|
|
KB_APP_DEMO_DESKTOP_CONFIG_PATH
|
|
```
|
|
|
|
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 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.
|