133 lines
6.6 KiB
Markdown
133 lines
6.6 KiB
Markdown
<!-- file: config/README.md -->
|
||
<!-- version: 26 -->
|
||
|
||
# Configuration locale
|
||
|
||
Ce dossier contient les compositions propres aux binaires, les documents de configuration Khadhroony Solana partagés, leurs exemples et les schémas JSON actifs.
|
||
|
||
## Modèle de composition
|
||
|
||
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.
|
||
|
||
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
|
||
```
|
||
|
||
Elle peut être remplacée par `KB_APP_DEMO_DESKTOP_CONFIG_PATH`.
|
||
|
||
`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.
|
||
|
||
## Fichiers actifs
|
||
|
||
```text
|
||
config/
|
||
├── kb-app-demo-desktop.default.config.json
|
||
├── logging.config.json
|
||
├── transport.config.json
|
||
├── listeners.config.json
|
||
├── store.config.json
|
||
├── wallet.config.json
|
||
├── execution.config.json
|
||
├── exemples/
|
||
│ ├── 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
|
||
├── kb-app-demo-desktop.application.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 transitoire `AppConfig/ProfileConfig` reconstruit en mémoire. Aucun binaire ne charge ce schéma comme document source applicatif. La section `application` d'une composition reste opaque pour `ks-config`; `kb-app-demo-desktop` la valide avec `config/schemas/kb-app-demo-desktop.application.config.schema.json`.
|
||
|
||
## 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_*`.
|
||
|
||
|
||
```text
|
||
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
|
||
```
|
||
|
||
`ks-config` valide l'existence des fichiers référencés et des profils sélectionnés avant de construire le contrat runtime.
|
||
|
||
## Valeurs globales hors profils
|
||
|
||
Une valeur qui ne dépend pas du profil reste au niveau racine de son document spécialisé.
|
||
|
||
Actuellement :
|
||
|
||
- `logging.config.json.logs_directory` vaut `${KS_LOGS_DIRECTORY:-logs}` ;
|
||
- `wallet.config.json.wallets_directory` vaut `${KS_WALLETS_DIRECTORY:-wallets}`.
|
||
- un profil wallet peut sélectionner un wallet natif persistant avec `wallet_alias`; le champ est optionnel/non sensible et ne contient jamais de mot de passe ni de matériau privé.
|
||
|
||
Ces valeurs peuvent être remplacées par l'environnement ou `.env` sans dupliquer un chemin dans tous les profils.
|
||
|
||
## Transport WebSocket
|
||
|
||
`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 :
|
||
|
||
```text
|
||
standard_rpc_ws
|
||
high_capacity_rpc_ws
|
||
```
|
||
|
||
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.
|
||
|
||
## Wallet et exécution
|
||
|
||
`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.
|
||
|
||
## Store
|
||
|
||
`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`.
|
||
|
||
## Frontière source/runtime/public/diagnostic
|
||
|
||
Les documents source et le contrat runtime résolu peuvent contenir des valeurs sensibles après résolution des placeholders. Ils restent backend-only et ne sont ni sérialisables ni `Debug` par défaut. Les applications construisent explicitement leurs DTO publics et diagnostics bornés, sans sérialiser puis masquer un `AppConfig/ProfileConfig` complet.
|
||
|
||
Une valeur composée hérite de la sensibilité la plus forte de ses placeholders (`Secret > Internal > Public`). Une URL ou un DSN incorporant un `KS_SECRET_*`/`KB_SECRET_*` est donc secret même si le champ final ne porte pas le mot `SECRET`.
|
||
|
||
## 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. Depuis `0.5.1`, les contrats source/runtime sensibles restent backend-only, tandis que les applications exposent uniquement des DTO publics ou diagnostics explicitement bornés.
|
||
|
||
## Exemples et schémas
|
||
|
||
Les exemples sous `config/exemples/` 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`, `schema.config.json` et `ks-pipeline-demo-scenarios.default.config.json` sont obsolètes dans l'architecture courante.
|