174 lines
6.5 KiB
Markdown
174 lines
6.5 KiB
Markdown
<!-- file: docs/guides/CONFIGURATION.md -->
|
|
<!-- version: 7 -->
|
|
|
|
# Guide de configuration
|
|
|
|
## Objectif
|
|
|
|
La configuration sépare les responsabilités Solana partagées des choix propres aux binaires. Les documents spécialisés sont autonomes grâce à leurs valeurs globales et à leur `default_profile`; une composition de binaire ne fournit que les overrides nécessaires.
|
|
|
|
## Documents actifs
|
|
|
|
Composition actuelle :
|
|
|
|
- `config/kb-app-demo-desktop.default.config.json` : composition par défaut du desktop.
|
|
|
|
Documents partagés :
|
|
|
|
- `config/logging.config.json` ;
|
|
- `config/transport.config.json` ;
|
|
- `config/listeners.config.json` ;
|
|
- `config/store.config.json` ;
|
|
- `config/wallet.config.json` ;
|
|
- `config/execution.config.json`.
|
|
|
|
Chaque document possède un exemple `example.*.config.json`. Les schémas correspondants résident sous `config/schemas/`.
|
|
|
|
`.env`, ou le fichier sélectionné par `KS_ENV_FILE`, fournit les valeurs non versionnées.
|
|
|
|
## Defaults partagés
|
|
|
|
Chaque document spécialisé définit un `default_profile`. Lorsqu'aucune composition n'est fournie, `ks-config` combine les defaults propres à transport, listeners, store, wallet et execution ; les noms de ces profils n'ont pas besoin d'être identiques. Une composition sélectionne des sources et profils, mais ne duplique pas des paramètres arbitraires : les overrides fins restent dans le schéma propriétaire et les globals explicitement configurables passent par leur variable d'environnement dédiée.
|
|
|
|
Cette règle permet à une bibliothèque, un scénario ou un futur worker d'utiliser une configuration cohérente sans créer un fichier de composition uniquement pour répéter les choix par défaut.
|
|
|
|
## Composition d'un binaire
|
|
|
|
Une composition définit :
|
|
|
|
1. son `active_profile` applicatif ;
|
|
2. les chemins des documents partagés ;
|
|
3. les éventuels overrides de profils spécialisés ;
|
|
4. les paramètres propres au binaire qui ne relèvent pas d'un document partagé.
|
|
|
|
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
|
|
sources.store -> config/store.config.json
|
|
sources.wallet -> config/wallet.config.json
|
|
sources.execution -> config/execution.config.json
|
|
|
|
profile local_devnet
|
|
aucun override -> defaults des documents partagés
|
|
|
|
profile mainnet_research
|
|
logging_profile -> mainnet_research
|
|
transport_profile -> mainnet_research
|
|
listeners_profile -> mainnet_research
|
|
store_profile -> mainnet_research
|
|
wallet_profile -> mainnet_research
|
|
execution_profile -> mainnet_research
|
|
```
|
|
|
|
`ks-config` charge les fichiers référencés, valide leurs schémas/types et refuse une composition qui référence un profil inexistant.
|
|
|
|
## Desktop
|
|
|
|
Le chemin de composition du desktop peut être remplacé par :
|
|
|
|
```text
|
|
KB_APP_DEMO_DESKTOP_CONFIG_PATH
|
|
```
|
|
|
|
Le logging conserve aussi l'override opérationnel :
|
|
|
|
```text
|
|
KS_LOGGING_CONFIG_PATH
|
|
```
|
|
|
|
## Scénarios Devnet
|
|
|
|
Par défaut, `ks-pipeline-demo-scenarios` utilise directement les defaults des documents partagés. Il n'existe plus de `config/ks-pipeline-demo-scenarios.default.config.json` obligatoire.
|
|
|
|
Les overrides opérateur restent :
|
|
|
|
```text
|
|
KS_DEVNET_CONFIG_PATH # composition explicite facultative
|
|
KS_DEVNET_PROFILE # sélection d'un profil runtime compatible Devnet
|
|
```
|
|
|
|
## Valeurs hors profils
|
|
|
|
Les paramètres globaux ne doivent pas être dupliqués dans chaque profil.
|
|
|
|
### Logging
|
|
|
|
```text
|
|
logs_directory = ${KS_LOGS_DIRECTORY:-logs}
|
|
```
|
|
|
|
Les chemins de fichiers des targets sont relatifs à cette racine lorsqu'ils ne sont pas absolus.
|
|
|
|
### Wallet
|
|
|
|
```text
|
|
wallets_directory = ${KS_WALLETS_DIRECTORY:-wallets}
|
|
```
|
|
|
|
Chaque profil wallet ne contient plus qu'un chemin relatif et ses paramètres d'identité/persistance.
|
|
|
|
## Transport WebSocket
|
|
|
|
Les paramètres communs d'un type d'endpoint WebSocket sont définis dans `ws_endpoint_defaults`. Chaque endpoint choisit une classe de defaults et peut écraser individuellement :
|
|
|
|
- `connect_timeout_ms` ;
|
|
- `request_timeout_ms` ;
|
|
- `unsubscribe_timeout_ms` ;
|
|
- `write_channel_capacity` ;
|
|
- `event_channel_capacity` ;
|
|
- `auto_reconnect`.
|
|
|
|
Les classes actuelles couvrent le RPC WS standard et le RPC WS à capacité plus élevée. Une future surface Helius avancée devra avoir son propre contrat/default lorsqu'elle sera réellement implémentée.
|
|
|
|
## Store
|
|
|
|
`store.config.json` porte les paramètres PostgreSQL/SQLite. Ce déplacement ne change aucune table ni migration SQL ; la normalisation SQL reste réservée à `0.5.3`.
|
|
|
|
## Wallet et politique d'exécution
|
|
|
|
Les propriétés de stockage/identité du wallet appartiennent à `wallet.config.json`.
|
|
|
|
Les autorisations :
|
|
|
|
```text
|
|
localnet_send_enabled
|
|
devnet_send_enabled
|
|
testnet_send_enabled
|
|
mainnet_send_enabled
|
|
```
|
|
|
|
appartiennent à `execution.config.json`, avec les limites de dépense, frais, simulation et confirmation. Un wallet sait signer ; la politique d'exécution décide si une soumission est autorisée.
|
|
|
|
## Contrat runtime transitoire
|
|
|
|
Pendant `0.5.1`, `ks-config` reconstruit encore `AppConfig/ProfileConfig` afin de préserver les consommateurs existants. Il s'agit d'une projection runtime, pas d'un document source.
|
|
|
|
Les fixtures de compatibilité sont sous `test-fixtures/config/`. Elles ne doivent pas être chargées en production.
|
|
|
|
## Frontière TS-RS
|
|
|
|
L'audit `pre.007` confirme que le frontend du desktop n'importe directement aucun binding généré depuis `ks-config` ou `ks-lib`. Les dérivations TS-RS des crates généralistes seront donc réévaluées dans la prerelease suivante : les DTO réellement destinés à Tauri doivent être définis/wrappés dans l'application, sauf contrat TypeScript générique explicitement justifié.
|
|
|
|
## Étape suivante
|
|
|
|
La prochaine prerelease traite ensemble :
|
|
|
|
- représentation source / runtime / publique / diagnostic ;
|
|
- propagation `SECRET` / `PUBLIC` / interne ;
|
|
- suppression de l'exposition Tauri de la configuration runtime complète ;
|
|
- réduction des bindings TS-RS dans les crates généralistes et wrappers applicatifs nécessaires.
|
|
|
|
## 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` ;
|
|
- les valeurs globales restent hors profils ;
|
|
- une composition appartient à son binaire ;
|
|
- un document spécialisé reste indépendant des binaires qui le consomment ;
|
|
- `ks-config` valide les références mais ne maintient pas une liste fermée de futurs workers/applications.
|