87 lines
4.1 KiB
Markdown
87 lines
4.1 KiB
Markdown
<!-- file: config/README.md -->
|
||
<!-- version: 20 -->
|
||
|
||
# Configuration locale
|
||
|
||
Ce dossier contient les deux documents de configuration runtime, leurs exemples et leurs schémas JSON indépendants.
|
||
|
||
## Fichiers chargés par défaut
|
||
|
||
- `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.
|
||
|
||
Les chemins par défaut peuvent être remplacés indépendamment par :
|
||
|
||
```text
|
||
KS_CONFIG_PATH
|
||
KS_LOGGING_CONFIG_PATH
|
||
```
|
||
|
||
## 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` :
|
||
|
||
```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
|
||
KS_SECRET_POSTGRES_MAINNET_URL
|
||
KS_SECRET_POSTGRES_DEVNET_URL
|
||
```
|
||
|
||
`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é.
|
||
|
||
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é.
|
||
|
||
## Schémas
|
||
|
||
Les schémas runtime sont localisés exclusivement sous `config/schemas/`.
|
||
|
||
`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.
|
||
|
||
## Migration depuis le format combiné
|
||
|
||
L’ancien `example.config.json` combinait configuration générale et logging dans chaque profil. La migration consiste à :
|
||
|
||
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
|
||
|
||
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.
|
||
|
||
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.
|