0.5.1-pre.005
This commit is contained in:
121
config/README.md
121
config/README.md
@@ -1,29 +1,50 @@
|
||||
<!-- file: config/README.md -->
|
||||
<!-- version: 19 -->
|
||||
<!-- version: 20 -->
|
||||
|
||||
# Configuration locale
|
||||
|
||||
Ce dossier contient les exemples et le schéma de configuration JSON.
|
||||
Ce dossier contient les deux documents de configuration runtime, leurs exemples et leurs schémas JSON indépendants.
|
||||
|
||||
## Règles
|
||||
## Fichiers chargés par défaut
|
||||
|
||||
- Le fichier versionné doit rester sans secret.
|
||||
- Les placeholders de clés restent directement dans les URLs.
|
||||
- Le champ `active_profile` sélectionne un seul profil actif.
|
||||
- Un profil actif doit être présent et unique.
|
||||
- Les profils non actifs peuvent rester dans le fichier pour les tests devnet, mainnet lecture seule, backfill ou future production.
|
||||
- Le contrat courant couvre HTTP JSON-RPC Solana et WebSocket JSON-RPC générique.
|
||||
- Helius `transactionSubscribe` et Yellowstone gRPC seront ajoutés plus tard dans `ks_onchain_transport`, avec évolution explicite du schéma quand les transports seront réellement utilisés.
|
||||
- Les IDLs restent des artefacts de développement et ne font pas partie de la configuration runtime.
|
||||
- `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.
|
||||
|
||||
## Fichiers
|
||||
Les chemins par défaut peuvent être remplacés indépendamment par :
|
||||
|
||||
- `example.config.json` : exemple complet avec profils `local_devnet`, `mainnet_research` et `mainnet`.
|
||||
- `schema.config.json` : JSON Schema de validation du fichier de configuration.
|
||||
```text
|
||||
KS_CONFIG_PATH
|
||||
KS_LOGGING_CONFIG_PATH
|
||||
```
|
||||
|
||||
## Variables d’environnement de l’exemple
|
||||
## Exemples conformes
|
||||
|
||||
`example.config.json` conserve la topologie des profils et référence les valeurs locales avec des placeholders :
|
||||
- `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` :
|
||||
|
||||
```text
|
||||
app.config.json
|
||||
active_profile = mainnet_research
|
||||
|
||||
logging.config.json
|
||||
active_profile = mainnet_research
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
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 :
|
||||
|
||||
```text
|
||||
KS_SECRET_HELIUS_API_KEY
|
||||
@@ -31,73 +52,35 @@ KS_SECRET_POSTGRES_MAINNET_URL
|
||||
KS_SECRET_POSTGRES_DEVNET_URL
|
||||
```
|
||||
|
||||
`KS_SECRET_POSTGRES_TEST_URL` n’est pas utilisé par un profil runtime : il reste réservé aux tests d’intégration PostgreSQL. Le profil `local_devnet` utilise `KS_SECRET_POSTGRES_DEVNET_URL`; les profils `mainnet_research` et `mainnet` utilisent `KS_SECRET_POSTGRES_MAINNET_URL`. Les trois bases doivent être distinctes.
|
||||
`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é.
|
||||
|
||||
Le fichier réel `.env` reste local et ignoré par Git. `.env.example` est le seul modèle dotenv versionné.
|
||||
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é.
|
||||
|
||||
## Phase `0.3.x`
|
||||
## Schémas
|
||||
|
||||
`0.3.x` utilise les endpoints HTTP des profils de recherche existants pour :
|
||||
Les schémas runtime sont localisés exclusivement sous `config/schemas/`.
|
||||
|
||||
```text
|
||||
getSignaturesForAddress
|
||||
getTransaction
|
||||
getSignatureStatuses
|
||||
```
|
||||
`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.
|
||||
|
||||
Aucun profil Helius payant ou Yellowstone n’est activé à ce stade.
|
||||
## Migration depuis le format combiné
|
||||
|
||||
Les sources futures devront déclarer séparément :
|
||||
L’ancien `example.config.json` combinait configuration générale et logging dans chaque profil. La migration consiste à :
|
||||
|
||||
- provider ;
|
||||
- protocole ;
|
||||
- rôle ;
|
||||
- limites de streams et filtres ;
|
||||
- authentification ;
|
||||
- région éventuelle.
|
||||
|
||||
## Évolution du schéma
|
||||
|
||||
`schema.config.json` est le contrat de validation runtime. Il évolue seulement lorsqu’un champ est réellement utilisé par l’exécution.
|
||||
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.
|
||||
|
||||
## Logging de développement
|
||||
|
||||
L’exemple configure, pour chacun des trois profils, quatre fichiers globaux puis trois fichiers dédiés par crate opérationnelle utilisant `tracing` : `debug.log`, `info.log` et `error.jsonl`.
|
||||
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 natifs consolidés rejoignent la console et disposent de leurs routes propres sous :
|
||||
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.
|
||||
|
||||
```text
|
||||
logs/<profil>/ks-lib/materializer/admin/
|
||||
logs/<profil>/ks-lib/materializer/compliance/audit/
|
||||
logs/<profil>/ks-lib/materializer/lifecycle/
|
||||
logs/<profil>/ks-lib/materializer/risk/
|
||||
logs/<profil>/ks-lib/materializer/staking/
|
||||
logs/<profil>/ks-lib/materializer/token/accounts/
|
||||
logs/<profil>/ks-lib/materializer/transaction/annotations/
|
||||
```
|
||||
|
||||
Le test de configuration découvre dynamiquement toutes les crates déclarant `tracing.workspace = true` et vérifie leurs trois routes dans chaque profil. Les logs ne doivent contenir ni secret, ni DSN non masqué, ni payload Config ou bytecode complet.
|
||||
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.
|
||||
|
||||
L’exemple `local_devnet` utilise donc volontairement des valeurs conservatrices :
|
||||
|
||||
```text
|
||||
http_queries:
|
||||
requests_per_second: 3
|
||||
burst_capacity: 3
|
||||
max_concurrent_requests: 2
|
||||
pause_after_rate_limit_ms: 10000
|
||||
|
||||
http_transactions:
|
||||
requests_per_second: 1
|
||||
burst_capacity: 1
|
||||
max_concurrent_requests: 1
|
||||
pause_after_rate_limit_ms: 10000
|
||||
```
|
||||
|
||||
Un fichier de configuration local déjà créé n’est pas modifié automatiquement lorsque `example.config.json` évolue. L’opérateur doit reporter explicitement ces valeurs dans son profil `local_devnet`.
|
||||
|
||||
Un warning `retry_http_json_rpc_after_rate_limit` reste possible sur un service public partagé. Il indique que le cooldown et le retry borné ont été activés ; il ne constitue un échec que si les tentatives finissent par être épuisées.
|
||||
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