0.5.1-pre.006
This commit is contained in:
132
config/README.md
132
config/README.md
@@ -1,86 +1,110 @@
|
||||
<!-- file: config/README.md -->
|
||||
<!-- version: 20 -->
|
||||
<!-- version: 21 -->
|
||||
|
||||
# Configuration locale
|
||||
|
||||
Ce dossier contient les deux documents de configuration runtime, leurs exemples et leurs schémas JSON indépendants.
|
||||
Ce dossier contient les compositions propres aux binaires, les documents de configuration partagés, leurs exemples et les schémas JSON actifs.
|
||||
|
||||
## Fichiers chargés par défaut
|
||||
## Principe de composition
|
||||
|
||||
- `app.config.json` : configuration générale Khadhroony Solana ;
|
||||
- `logging.config.json` : configuration logging/tracing ;
|
||||
- `schemas/app.config.schema.json` : schéma du document général ;
|
||||
- `schemas/logging.config.schema.json` : schéma du document logging.
|
||||
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 chemins par défaut peuvent être remplacés indépendamment par :
|
||||
Le desktop utilise par défaut :
|
||||
|
||||
```text
|
||||
KS_CONFIG_PATH
|
||||
KS_LOGGING_CONFIG_PATH
|
||||
config/kb-app-demo-desktop.default.config.json
|
||||
```
|
||||
|
||||
## Exemples conformes
|
||||
|
||||
- `example.app.config.json` : exemple général minimal conforme ;
|
||||
- `example.logging.config.json` : exemple logging minimal conforme.
|
||||
|
||||
Les exemples servent de référence de structure. Ils ne sont pas sélectionnés automatiquement au démarrage.
|
||||
|
||||
## Sélection indépendante des profils
|
||||
|
||||
Chaque document possède son propre `active_profile` :
|
||||
Le CLI des scénarios possède également une composition explicite :
|
||||
|
||||
```text
|
||||
app.config.json
|
||||
active_profile = mainnet_research
|
||||
|
||||
logging.config.json
|
||||
active_profile = mainnet_research
|
||||
config/ks-pipeline-demo-scenarios.default.config.json
|
||||
```
|
||||
|
||||
Ces valeurs sont indépendantes. Changer le profil applicatif ne change pas implicitement le profil logging, et inversement. Les noms peuvent être identiques pour faciliter l’exploitation sans créer de couplage contractuel.
|
||||
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`.
|
||||
|
||||
Le document général ne contient plus de propriété `logging`. Les routes, niveaux, formats et filtres sont exclusivement possédés par `logging.config.json` et `ks-logging`.
|
||||
|
||||
## Variables d’environnement
|
||||
|
||||
`app.config.json` référence notamment :
|
||||
## Documents partagés actuels
|
||||
|
||||
```text
|
||||
KS_SECRET_HELIUS_API_KEY
|
||||
KS_SECRET_POSTGRES_MAINNET_URL
|
||||
KS_SECRET_POSTGRES_DEVNET_URL
|
||||
config/
|
||||
├── kb-app-demo-desktop.default.config.json
|
||||
├── ks-pipeline-demo-scenarios.default.config.json
|
||||
├── logging.config.json
|
||||
├── transport.config.json
|
||||
├── listeners.config.json
|
||||
├── example.kb-app-demo-desktop.default.config.json
|
||||
├── example.logging.config.json
|
||||
├── example.transport.config.json
|
||||
├── example.listeners.config.json
|
||||
└── schemas/
|
||||
├── composition.config.schema.json
|
||||
├── logging.config.schema.json
|
||||
├── transport.config.schema.json
|
||||
├── listeners.config.schema.json
|
||||
└── resolved.app.config.schema.json
|
||||
```
|
||||
|
||||
`KS_SECRET_POSTGRES_TEST_URL` reste réservé aux tests d’intégration PostgreSQL. Le fichier réel `.env` reste local et ignoré par Git ; `.env.example` est le modèle versionné.
|
||||
`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.
|
||||
|
||||
La classification `KS_SECRET_*` / `KS_PUBLIC_*` / `KS_*` et `KB_SECRET_*` / `KB_PUBLIC_*` / `KB_*` est normative. Le camouflage et la propagation de sensibilité dans les valeurs composées sont traités dans la prerelease suivante ; aucun secret ne doit être écrit en clair dans un fichier versionné.
|
||||
## Sélection des profils
|
||||
|
||||
## Schémas
|
||||
Les documents partagés conservent un `active_profile` pour les consommateurs autonomes. Une composition binaire peut cependant sélectionner un autre profil explicitement :
|
||||
|
||||
Les schémas runtime sont localisés exclusivement sous `config/schemas/`.
|
||||
```text
|
||||
composition profile mainnet_research
|
||||
logging_profile = mainnet_research
|
||||
transport_profile = mainnet_research
|
||||
listeners_profile = mainnet_research
|
||||
```
|
||||
|
||||
`ks-config` embarque `schemas/app.config.schema.json`. `ks-logging` embarque `schemas/logging.config.schema.json`. Les fichiers embarqués et leurs versions sur disque doivent rester identiques.
|
||||
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.
|
||||
|
||||
## Migration depuis le format combiné
|
||||
## Transport
|
||||
|
||||
L’ancien `example.config.json` combinait configuration générale et logging dans chaque profil. La migration consiste à :
|
||||
`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.
|
||||
|
||||
1. conserver dans `app.config.json` les sections `app`, `database`, `data`, `solana`, `wallet`, `execution` et `demo` ;
|
||||
2. extraire chaque ancien bloc `logging` vers le profil homonyme de `logging.config.json` ;
|
||||
3. sélectionner explicitement un `active_profile` dans chacun des deux documents ;
|
||||
4. supprimer l’ancien fichier combiné une fois la migration validée.
|
||||
`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.
|
||||
|
||||
## Listeners
|
||||
|
||||
`listeners.config.json` possède les ensembles de listeners Solana :
|
||||
|
||||
- `logsSubscribe` par mention de programme ;
|
||||
- `programSubscribe` ;
|
||||
- `accountSubscribe` ;
|
||||
- commitment et rôles d'endpoint associés.
|
||||
|
||||
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.
|
||||
|
||||
## Logging
|
||||
|
||||
`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é.
|
||||
|
||||
## Configuration encore transitoire dans la composition
|
||||
|
||||
Après `pre.006`, les sections suivantes restent temporairement dans les profils de composition :
|
||||
|
||||
- `database` et `data` ;
|
||||
- `wallet` ;
|
||||
- `execution` ;
|
||||
- `demo`.
|
||||
|
||||
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`.
|
||||
|
||||
## 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.
|
||||
|
||||
## 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 actuellement les routes globales ainsi que trois fichiers dédiés par crate opérationnelle utilisant `tracing` : `debug.log`, `info.log` et `error.jsonl`.
|
||||
|
||||
Les matérialisateurs consolidés disposent de leurs routes sous les targets `ks-lib-materializer.*`. Les tests de `ks-logging` découvrent dynamiquement les crates déclarant `tracing.workspace = true` et vérifient les routes canoniques du document logging par défaut.
|
||||
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.
|
||||
|
||||
## Limites du profil public Devnet
|
||||
|
||||
`api.devnet.solana.com` est un endpoint public partagé. Les limites configurées par rôle ne sont pas des quotas indépendants fournis par le serveur : leur débit cumulé doit rester sous la limite globale de l’endpoint, et chaque méthode RPC doit également rester sous sa propre limite.
|
||||
|
||||
Le profil `local_devnet` de `app.config.json` utilise donc volontairement des valeurs conservatrices pour les rôles HTTP. Un warning `retry_http_json_rpc_after_rate_limit` reste possible sur un service partagé ; il indique que le cooldown et le retry borné ont été activés.
|
||||
|
||||
Reference in New Issue
Block a user