0.5.1-pre.007
This commit is contained in:
103
config/README.md
103
config/README.md
@@ -1,110 +1,123 @@
|
||||
<!-- file: config/README.md -->
|
||||
<!-- version: 21 -->
|
||||
<!-- version: 22 -->
|
||||
|
||||
# Configuration locale
|
||||
|
||||
Ce dossier contient les compositions propres aux binaires, les documents de configuration partagés, leurs exemples et les schémas JSON actifs.
|
||||
Ce dossier contient les compositions propres aux binaires, les documents de configuration Khadhroony Solana partagés, leurs exemples et les schémas JSON actifs.
|
||||
|
||||
## Principe de composition
|
||||
## Modèle de composition
|
||||
|
||||
Un binaire ne possède pas une copie complète de toutes les configurations partagées. Il charge un fichier de composition `<binary>.default.config.json` qui référence les documents spécialisés et sélectionne explicitement un profil dans chacun.
|
||||
Les documents spécialisés possèdent leur propre configuration globale et un `default_profile`. Ils peuvent donc être consommés directement sans fichier de composition.
|
||||
|
||||
Le desktop utilise par défaut :
|
||||
Un fichier `<binary>.default.config.json` n'est nécessaire que lorsqu'un binaire veut :
|
||||
|
||||
- choisir des fichiers spécialisés différents des fichiers canoniques ;
|
||||
- sélectionner un profil différent du `default_profile` d'un document ;
|
||||
- ajouter des paramètres propres au binaire.
|
||||
|
||||
La composition du desktop est :
|
||||
|
||||
```text
|
||||
config/kb-app-demo-desktop.default.config.json
|
||||
```
|
||||
|
||||
Le CLI des scénarios possède également une composition explicite :
|
||||
Elle peut être remplacée par `KB_APP_DEMO_DESKTOP_CONFIG_PATH`.
|
||||
|
||||
```text
|
||||
config/ks-pipeline-demo-scenarios.default.config.json
|
||||
```
|
||||
`ks-pipeline-demo-scenarios` n'a plus de composition dédiée par défaut : il consomme directement les defaults des documents partagés. `KS_DEVNET_CONFIG_PATH` reste disponible pour fournir explicitement une composition alternative lorsque cela est nécessaire.
|
||||
|
||||
La composition desktop peut être remplacée par `KB_APP_DEMO_DESKTOP_CONFIG_PATH`. Les tests/scénarios Devnet opt-in peuvent remplacer leur composition avec `KS_DEVNET_CONFIG_PATH`.
|
||||
|
||||
## Documents partagés actuels
|
||||
## Fichiers actifs
|
||||
|
||||
```text
|
||||
config/
|
||||
├── kb-app-demo-desktop.default.config.json
|
||||
├── ks-pipeline-demo-scenarios.default.config.json
|
||||
├── logging.config.json
|
||||
├── transport.config.json
|
||||
├── listeners.config.json
|
||||
├── store.config.json
|
||||
├── wallet.config.json
|
||||
├── execution.config.json
|
||||
├── example.kb-app-demo-desktop.default.config.json
|
||||
├── example.logging.config.json
|
||||
├── example.transport.config.json
|
||||
├── example.listeners.config.json
|
||||
├── example.store.config.json
|
||||
├── example.wallet.config.json
|
||||
├── example.execution.config.json
|
||||
└── schemas/
|
||||
├── composition.config.schema.json
|
||||
├── logging.config.schema.json
|
||||
├── transport.config.schema.json
|
||||
├── listeners.config.schema.json
|
||||
├── store.config.schema.json
|
||||
├── wallet.config.schema.json
|
||||
├── execution.config.schema.json
|
||||
└── resolved.app.config.schema.json
|
||||
```
|
||||
|
||||
`resolved.app.config.schema.json` décrit uniquement le contrat runtime `AppConfig/ProfileConfig` reconstruit par `ks-config`. Il ne correspond pas à un fichier runtime chargé directement.
|
||||
`resolved.app.config.schema.json` décrit uniquement le contrat transitoire `AppConfig/ProfileConfig` reconstruit en mémoire. Aucun binaire ne charge ce schéma comme document source applicatif.
|
||||
|
||||
## Sélection des profils
|
||||
## Defaults et overrides
|
||||
|
||||
Chaque document partagé définit un `default_profile`. Une composition peut remplacer uniquement les sélections nécessaires. Elle ne devient pas une seconde copie des paramètres spécialisés : un override de champ reste dans le document propriétaire, tandis qu’une valeur globale déclarée comme configurable par environnement utilise son contrat `KS_*`/`KB_*`.
|
||||
|
||||
Les documents partagés conservent un `active_profile` pour les consommateurs autonomes. Une composition binaire peut cependant sélectionner un autre profil explicitement :
|
||||
|
||||
```text
|
||||
composition profile mainnet_research
|
||||
transport.default_profile = local_devnet
|
||||
listeners.default_profile = local_devnet
|
||||
store.default_profile = local_devnet
|
||||
wallet.default_profile = local_devnet
|
||||
execution.default_profile = local_devnet
|
||||
logging.default_profile = local_devnet
|
||||
|
||||
kb-app-demo-desktop 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
|
||||
```
|
||||
|
||||
Lorsqu'une composition est utilisée, sa sélection explicite prime pour le binaire. Le même `transport.config.json` ou `listeners.config.json` peut donc être réutilisé par plusieurs binaires avec des combinaisons différentes.
|
||||
`ks-config` valide l'existence des fichiers référencés et des profils sélectionnés avant de construire le contrat runtime.
|
||||
|
||||
## Transport
|
||||
## Valeurs globales hors profils
|
||||
|
||||
`transport.config.json` possède les endpoints HTTP et WebSocket, leurs providers, clusters, timeouts, capacités, rôles, limites et politique de reconnexion propre aux endpoints.
|
||||
Une valeur qui ne dépend pas du profil reste au niveau racine de son document spécialisé.
|
||||
|
||||
`ks-onchain-transport` peut consommer directement un `TransportProfileConfig`. Un futur worker n'a donc pas besoin de dépendre d'un `ProfileConfig` applicatif complet pour construire ses pools réseau.
|
||||
Actuellement :
|
||||
|
||||
## Listeners
|
||||
- `logging.config.json.logs_directory` vaut `${KS_LOGS_DIRECTORY:-logs}` ;
|
||||
- `wallet.config.json.wallets_directory` vaut `${KS_WALLETS_DIRECTORY:-wallets}`.
|
||||
|
||||
`listeners.config.json` possède les ensembles de listeners Solana :
|
||||
Ces valeurs peuvent être remplacées par l'environnement ou `.env` sans dupliquer un chemin dans tous les profils.
|
||||
|
||||
- `logsSubscribe` par mention de programme ;
|
||||
- `programSubscribe` ;
|
||||
- `accountSubscribe` ;
|
||||
- commitment et rôles d'endpoint associés.
|
||||
## Transport WebSocket
|
||||
|
||||
La séparation prépare les futurs workers de capture, qui pourront associer un profil transport et un profil listeners sans recopier les définitions dans leur propre configuration.
|
||||
`transport.config.json` possède des classes de defaults WebSocket nommées. Un endpoint référence une classe puis peut fournir des `overrides` propres :
|
||||
|
||||
## Logging
|
||||
```text
|
||||
standard_rpc_ws
|
||||
high_capacity_rpc_ws
|
||||
```
|
||||
|
||||
`logging.config.json` reste possédé par `ks-logging`. Une composition sélectionne le profil logging souhaité. `KS_LOGGING_CONFIG_PATH` reste un override direct du chemin logging pour l'exploitation ; sans override, le chemin déclaré par la composition est utilisé.
|
||||
Les defaults portent les timeouts, capacités de channels et `auto_reconnect`. Une future surface WebSocket avancée peut ajouter une classe dédiée sans modifier les endpoints RPC standard existants.
|
||||
|
||||
## Configuration encore transitoire dans la composition
|
||||
## Wallet et exécution
|
||||
|
||||
Après `pre.006`, les sections suivantes restent temporairement dans les profils de composition :
|
||||
`wallet.config.json` possède la racine de stockage et les paramètres d'identité/persistance des wallets. Les autorisations `*_send_enabled` appartiennent désormais à `execution.config.json`, avec les plafonds de dépense, frais et confirmation.
|
||||
|
||||
- `database` et `data` ;
|
||||
- `wallet` ;
|
||||
- `execution` ;
|
||||
- `demo`.
|
||||
## Store
|
||||
|
||||
Elles seront séparées dans la prerelease suivante. En particulier, `demo` est propre au desktop et ne doit pas rester durablement dans un contrat généraliste `ks-config`.
|
||||
`store.config.json` possède la sélection et les paramètres PostgreSQL/SQLite. Le split reste structurel : aucune migration SQL n'est introduite par `0.5.1`.
|
||||
|
||||
## Variables d'environnement
|
||||
|
||||
Les composants `ks-*` utilisent `KS_SECRET_*`, `KS_PUBLIC_*` ou `KS_*`. Les besoins réellement spécifiques à une application `kb-*` utilisent `KB_SECRET_*`, `KB_PUBLIC_*` ou `KB_*`.
|
||||
|
||||
Les secrets ne sont jamais écrits en clair dans le dépôt. La propagation de sensibilité et les DTO publics sûrs sont traités après la fin du découpage des fichiers de configuration.
|
||||
Les secrets ne sont jamais écrits en clair dans le dépôt. La séparation source/runtime/public/diagnostic et le camouflage systématique sont traités après ce split.
|
||||
|
||||
## Exemples et schémas
|
||||
|
||||
Les exemples sous `config/` sont des références conformes et ne sont pas chargés automatiquement. Tous les schémas actifs résident exclusivement sous `config/schemas/`.
|
||||
|
||||
Les fichiers historiques `app.config.json`, `example.app.config.json`, `schemas/app.config.schema.json`, `example.config.json` et `schema.config.json` sont obsolètes et ne doivent pas coexister avec cette architecture.
|
||||
|
||||
## Logging de développement
|
||||
|
||||
Le fichier `logging.config.json` conserve les routes globales ainsi que trois fichiers dédiés par crate opérationnelle utilisant `tracing` : `debug.log`, `info.log` et `error.jsonl`.
|
||||
|
||||
Les logs ne doivent contenir ni secret, ni DSN non masqué, ni keypair, ni payload de configuration résolue complet.
|
||||
Les fichiers historiques `app.config.json`, `example.app.config.json`, `schemas/app.config.schema.json`, `example.config.json`, `schema.config.json` et `ks-pipeline-demo-scenarios.default.config.json` sont obsolètes dans l'architecture courante.
|
||||
|
||||
Reference in New Issue
Block a user