0.5.1-pre.007
This commit is contained in:
@@ -1,50 +1,45 @@
|
||||
<!-- file: docs/guides/CONFIGURATION.md -->
|
||||
<!-- version: 6 -->
|
||||
<!-- version: 7 -->
|
||||
|
||||
# Guide de configuration
|
||||
|
||||
## Objectif
|
||||
|
||||
La configuration est organisée autour de compositions propres aux binaires et de documents spécialisés réutilisables. Un binaire choisit les fichiers partagés et les profils dont il a besoin au lieu de recopier une configuration monolithique.
|
||||
La configuration sépare les responsabilités Solana partagées des choix propres aux binaires. Les documents spécialisés sont autonomes grâce à leurs valeurs globales et à leur `default_profile`; une composition de binaire ne fournit que les overrides nécessaires.
|
||||
|
||||
## Fichiers actifs
|
||||
## Documents actifs
|
||||
|
||||
Compositions :
|
||||
Composition actuelle :
|
||||
|
||||
- `config/kb-app-demo-desktop.default.config.json` : composition par défaut du desktop ;
|
||||
- `config/ks-pipeline-demo-scenarios.default.config.json` : composition par défaut du CLI/scénarios.
|
||||
- `config/kb-app-demo-desktop.default.config.json` : composition par défaut du desktop.
|
||||
|
||||
Documents partagés :
|
||||
|
||||
- `config/logging.config.json` ;
|
||||
- `config/transport.config.json` ;
|
||||
- `config/listeners.config.json`.
|
||||
- `config/listeners.config.json` ;
|
||||
- `config/store.config.json` ;
|
||||
- `config/wallet.config.json` ;
|
||||
- `config/execution.config.json`.
|
||||
|
||||
Exemples :
|
||||
|
||||
- `config/example.kb-app-demo-desktop.default.config.json` ;
|
||||
- `config/example.logging.config.json` ;
|
||||
- `config/example.transport.config.json` ;
|
||||
- `config/example.listeners.config.json`.
|
||||
|
||||
Schémas :
|
||||
|
||||
- `config/schemas/composition.config.schema.json` ;
|
||||
- `config/schemas/logging.config.schema.json` ;
|
||||
- `config/schemas/transport.config.schema.json` ;
|
||||
- `config/schemas/listeners.config.schema.json` ;
|
||||
- `config/schemas/resolved.app.config.schema.json` pour le contrat runtime reconstruit.
|
||||
Chaque document possède un exemple `example.*.config.json`. Les schémas correspondants résident sous `config/schemas/`.
|
||||
|
||||
`.env`, ou le fichier sélectionné par `KS_ENV_FILE`, fournit les valeurs non versionnées.
|
||||
|
||||
## Defaults partagés
|
||||
|
||||
Chaque document spécialisé définit un `default_profile`. Lorsqu'aucune composition n'est fournie, `ks-config` combine les defaults propres à transport, listeners, store, wallet et execution ; les noms de ces profils n'ont pas besoin d'être identiques. Une composition sélectionne des sources et profils, mais ne duplique pas des paramètres arbitraires : les overrides fins restent dans le schéma propriétaire et les globals explicitement configurables passent par leur variable d'environnement dédiée.
|
||||
|
||||
Cette règle permet à une bibliothèque, un scénario ou un futur worker d'utiliser une configuration cohérente sans créer un fichier de composition uniquement pour répéter les choix par défaut.
|
||||
|
||||
## Composition d'un binaire
|
||||
|
||||
Une composition définit :
|
||||
|
||||
1. son `active_profile` ;
|
||||
1. son `active_profile` applicatif ;
|
||||
2. les chemins des documents partagés ;
|
||||
3. pour chaque profil, le `logging_profile`, `transport_profile` et `listeners_profile` à sélectionner ;
|
||||
4. temporairement, les sections qui n'ont pas encore leur document spécialisé.
|
||||
3. les éventuels overrides de profils spécialisés ;
|
||||
4. les paramètres propres au binaire qui ne relèvent pas d'un document partagé.
|
||||
|
||||
Exemple conceptuel :
|
||||
|
||||
@@ -53,14 +48,23 @@ kb-app-demo-desktop.default.config.json
|
||||
sources.logging -> config/logging.config.json
|
||||
sources.transport -> config/transport.config.json
|
||||
sources.listeners -> config/listeners.config.json
|
||||
sources.store -> config/store.config.json
|
||||
sources.wallet -> config/wallet.config.json
|
||||
sources.execution -> config/execution.config.json
|
||||
|
||||
profile local_devnet
|
||||
aucun override -> defaults des documents partagés
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
Les `active_profile` propres aux documents partagés restent utiles lorsqu'ils sont chargés seuls. Dans une composition, la référence explicite du binaire prime.
|
||||
`ks-config` charge les fichiers référencés, valide leurs schémas/types et refuse une composition qui référence un profil inexistant.
|
||||
|
||||
## Desktop
|
||||
|
||||
@@ -70,65 +74,100 @@ Le chemin de composition du desktop peut être remplacé par :
|
||||
KB_APP_DEMO_DESKTOP_CONFIG_PATH
|
||||
```
|
||||
|
||||
Le logging conserve l'override opérationnel :
|
||||
Le logging conserve aussi l'override opérationnel :
|
||||
|
||||
```text
|
||||
KS_LOGGING_CONFIG_PATH
|
||||
```
|
||||
|
||||
Sans cet override, le desktop utilise le chemin logging déclaré par sa composition.
|
||||
|
||||
## Scénarios Devnet
|
||||
|
||||
Les scénarios opt-in utilisent :
|
||||
Par défaut, `ks-pipeline-demo-scenarios` utilise directement les defaults des documents partagés. Il n'existe plus de `config/ks-pipeline-demo-scenarios.default.config.json` obligatoire.
|
||||
|
||||
Les overrides opérateur restent :
|
||||
|
||||
```text
|
||||
KS_DEVNET_CONFIG_PATH
|
||||
KS_DEVNET_PROFILE
|
||||
KS_DEVNET_CONFIG_PATH # composition explicite facultative
|
||||
KS_DEVNET_PROFILE # sélection d'un profil runtime compatible Devnet
|
||||
```
|
||||
|
||||
`KS_DEVNET_CONFIG_PATH` désigne désormais un fichier de composition. Sans override, les scénarios utilisent `config/ks-pipeline-demo-scenarios.default.config.json`.
|
||||
## Valeurs hors profils
|
||||
|
||||
## Transport
|
||||
Les paramètres globaux ne doivent pas être dupliqués dans chaque profil.
|
||||
|
||||
`transport.config.json` possède les endpoints HTTP et WebSocket ainsi que leurs rôles et limites. Le profil transport peut être consommé directement par `ks-onchain-transport` sans dépendre d'un profil applicatif complet.
|
||||
### Logging
|
||||
|
||||
Cela prépare les futurs workers : un worker de capture pourra sélectionner un profil transport différent du desktop tout en partageant le même document.
|
||||
```text
|
||||
logs_directory = ${KS_LOGS_DIRECTORY:-logs}
|
||||
```
|
||||
|
||||
## Listeners
|
||||
Les chemins de fichiers des targets sont relatifs à cette racine lorsqu'ils ne sont pas absolus.
|
||||
|
||||
`listeners.config.json` contient les déclarations de subscriptions par logs, programme et compte. Un profil listeners peut être associé à n'importe quel profil transport compatible par le fichier de composition du consommateur.
|
||||
### Wallet
|
||||
|
||||
La séparation évite de recopier les listes de `program_id` et les filtres lorsque plusieurs binaires observent la même surface Solana.
|
||||
```text
|
||||
wallets_directory = ${KS_WALLETS_DIRECTORY:-wallets}
|
||||
```
|
||||
|
||||
## Logging
|
||||
Chaque profil wallet ne contient plus qu'un chemin relatif et ses paramètres d'identité/persistance.
|
||||
|
||||
`logging.config.json` appartient à `ks-logging`. Une composition référence son fichier et son profil, mais les types et validations logging ne reviennent pas dans `ks-config`.
|
||||
## Transport WebSocket
|
||||
|
||||
## Contrat runtime résolu
|
||||
Les paramètres communs d'un type d'endpoint WebSocket sont définis dans `ws_endpoint_defaults`. Chaque endpoint choisit une classe de defaults et peut écraser individuellement :
|
||||
|
||||
Pendant la migration `0.5.1`, `ks-config` reconstruit encore un `AppConfig/ProfileConfig` contenant les sections nécessaires aux consommateurs existants. Ce contrat est une projection runtime, pas une configuration source.
|
||||
- `connect_timeout_ms` ;
|
||||
- `request_timeout_ms` ;
|
||||
- `unsubscribe_timeout_ms` ;
|
||||
- `write_channel_capacity` ;
|
||||
- `event_channel_capacity` ;
|
||||
- `auto_reconnect`.
|
||||
|
||||
Les tests de compatibilité utilisent les fixtures sous `test-fixtures/config/`. Aucun binaire ne doit charger ces fixtures en production.
|
||||
Les classes actuelles couvrent le RPC WS standard et le RPC WS à capacité plus élevée. Une future surface Helius avancée devra avoir son propre contrat/default lorsqu'elle sera réellement implémentée.
|
||||
|
||||
## Étapes suivantes
|
||||
## Store
|
||||
|
||||
Le prochain split doit extraire :
|
||||
`store.config.json` porte les paramètres PostgreSQL/SQLite. Ce déplacement ne change aucune table ni migration SQL ; la normalisation SQL reste réservée à `0.5.3`.
|
||||
|
||||
- database vers le document store ;
|
||||
- `logs_directory` vers logging ;
|
||||
- `wallets_directory`, le stockage wallet et les paramètres de wallet vers un document wallet ;
|
||||
- les permissions `*_send_enabled` du wallet vers la politique execution ;
|
||||
- execution ;
|
||||
- configuration spécifique au desktop.
|
||||
## Wallet et politique d'exécution
|
||||
|
||||
Après cette étape seulement, les DTO publics, diagnostics et règles de camouflage seront construits sur les nouvelles frontières.
|
||||
Les propriétés de stockage/identité du wallet appartiennent à `wallet.config.json`.
|
||||
|
||||
Les autorisations :
|
||||
|
||||
```text
|
||||
localnet_send_enabled
|
||||
devnet_send_enabled
|
||||
testnet_send_enabled
|
||||
mainnet_send_enabled
|
||||
```
|
||||
|
||||
appartiennent à `execution.config.json`, avec les limites de dépense, frais, simulation et confirmation. Un wallet sait signer ; la politique d'exécution décide si une soumission est autorisée.
|
||||
|
||||
## Contrat runtime transitoire
|
||||
|
||||
Pendant `0.5.1`, `ks-config` reconstruit encore `AppConfig/ProfileConfig` afin de préserver les consommateurs existants. Il s'agit d'une projection runtime, pas d'un document source.
|
||||
|
||||
Les fixtures de compatibilité sont sous `test-fixtures/config/`. Elles ne doivent pas être chargées en production.
|
||||
|
||||
## Frontière TS-RS
|
||||
|
||||
L'audit `pre.007` confirme que le frontend du desktop n'importe directement aucun binding généré depuis `ks-config` ou `ks-lib`. Les dérivations TS-RS des crates généralistes seront donc réévaluées dans la prerelease suivante : les DTO réellement destinés à Tauri doivent être définis/wrappés dans l'application, sauf contrat TypeScript générique explicitement justifié.
|
||||
|
||||
## Étape suivante
|
||||
|
||||
La prochaine prerelease traite ensemble :
|
||||
|
||||
- représentation source / runtime / publique / diagnostic ;
|
||||
- propagation `SECRET` / `PUBLIC` / interne ;
|
||||
- suppression de l'exposition Tauri de la configuration runtime complète ;
|
||||
- réduction des bindings TS-RS dans les crates généralistes et wrappers applicatifs nécessaires.
|
||||
|
||||
## Invariants
|
||||
|
||||
- aucun secret réel dans les fichiers versionnés ;
|
||||
- tous les schémas actifs sous `config/schemas/` ;
|
||||
- aucun retour au fichier monolithique `app.config.json` ;
|
||||
- un fichier de composition appartient à son binaire ;
|
||||
- les valeurs globales restent hors profils ;
|
||||
- une composition appartient à son binaire ;
|
||||
- un document spécialisé reste indépendant des binaires qui le consomment ;
|
||||
- `ks-config` fournit les mécanismes partagés sans enregistrer une liste fermée de workers/applications.
|
||||
- `ks-config` valide les références mais ne maintient pas une liste fermée de futurs workers/applications.
|
||||
|
||||
@@ -1,88 +1,49 @@
|
||||
<!-- file: docs/guides/LOGGING.md -->
|
||||
<!-- version: 6 -->
|
||||
<!-- version: 7 -->
|
||||
|
||||
# Guide de logging et tracing
|
||||
|
||||
## Objectif
|
||||
|
||||
`ks-logging` possède désormais le contrat logging, son document de profils, son schéma JSON et l’initialisation runtime `tracing`.
|
||||
`ks-logging` possède le contrat logging, son document de profils, son schéma JSON et l'initialisation runtime `tracing`.
|
||||
|
||||
## Flux de démarrage
|
||||
## Valeur globale
|
||||
|
||||
1. charger `config/logging.config.json` avec `ks_logging::read_logging_json_file_with_environment` ;
|
||||
2. sélectionner le profil avec `ks_logging::active_logging_profile` ;
|
||||
3. appeler `ks_logging::init_logging` une seule fois ;
|
||||
4. conserver `LoggingGuard` jusqu’à la fermeture du processus ;
|
||||
5. émettre les événements avec des targets canoniques.
|
||||
|
||||
```rust
|
||||
let document = match ks_logging::read_logging_json_file_with_environment(
|
||||
std::path::Path::new("config/logging.config.json"),
|
||||
std::path::Path::new("."),
|
||||
) {
|
||||
std::result::Result::Ok(value) => value,
|
||||
std::result::Result::Err(error) => return std::result::Result::Err(error),
|
||||
};
|
||||
let config = match ks_logging::active_logging_profile(&document) {
|
||||
std::result::Result::Ok(value) => value,
|
||||
std::result::Result::Err(error) => return std::result::Result::Err(error),
|
||||
};
|
||||
let guard = match ks_logging::init_logging(config) {
|
||||
std::result::Result::Ok(value) => value,
|
||||
std::result::Result::Err(error) => return std::result::Result::Err(error),
|
||||
};
|
||||
```
|
||||
|
||||
Le document logging reste indépendant de la composition binaire. Une composition `<binary>.default.config.json` sélectionne explicitement le profil logging qu’elle veut utiliser ; le `active_profile` propre à `logging.config.json` reste disponible pour les consommateurs autonomes.
|
||||
|
||||
## Contrat JSON
|
||||
|
||||
Le schéma est `config/schemas/logging.config.schema.json`. Les exemples sont `config/logging.config.json` pour la configuration runtime de référence et `config/example.logging.config.json` pour un exemple minimal.
|
||||
|
||||
Une route définit notamment :
|
||||
|
||||
- sink console ou fichier ;
|
||||
- niveau minimal ;
|
||||
- format humain, compact, pretty ou JSON ;
|
||||
- rotation ;
|
||||
- targets exactes ou préfixes ;
|
||||
- activation ANSI.
|
||||
|
||||
Les routes fichier ne doivent jamais écrire de secrets ou de keypairs.
|
||||
|
||||
## Nomenclature des targets
|
||||
|
||||
Les targets suivent les conventions du workspace, par exemple :
|
||||
La racine des logs n'est pas un profil :
|
||||
|
||||
```text
|
||||
ks-pipeline.backfill
|
||||
ks-pipeline.decode-replay
|
||||
ks-onchain-transport.http
|
||||
ks-lib-executor.spl.token-2022
|
||||
ks-lib-materializer.compliance.audit
|
||||
ks-lib-materializer.token.accounts
|
||||
logging.config.json.logs_directory = ${KS_LOGS_DIRECTORY:-logs}
|
||||
```
|
||||
|
||||
Pour un matérialisateur, la target de tracing reste distincte du `processorName` persisté.
|
||||
Les targets fichier utilisent des chemins relatifs, par exemple `devnet/ks-pipeline/debug.log`. `ks-logging` les résout sous `logs_directory` au chargement. Une valeur absolue explicite reste absolue.
|
||||
|
||||
## Frontend desktop
|
||||
Cette séparation évite de recopier `logs/` dans chaque profil et permet à l'opérateur de déplacer tous les logs par variable d'environnement ou `.env`.
|
||||
|
||||
Le desktop charge les documents app et logging séparément. Il ne convertit plus un type `ks_config::LoggingConfig` vers `ks_logging::LoggingConfig` : le type runtime est possédé directement par `ks-logging`.
|
||||
## Sélection du profil
|
||||
|
||||
La surface publique de diagnostic/configuration reste volontairement inchangée jusqu’à `0.5.1-pre.006`, qui supprimera l’exposition des configurations résolues complètes.
|
||||
`logging.config.json` définit `default_profile`. Un consommateur autonome l'utilise avec `default_logging_profile`.
|
||||
|
||||
## Diagnostic
|
||||
Un binaire possédant une composition peut sélectionner un autre profil avec `logging_profile`; cette sélection ne modifie pas le document partagé.
|
||||
|
||||
- vérifier `KS_LOGGING_CONFIG_PATH` si le fichier par défaut n’est pas utilisé ;
|
||||
- vérifier le profil logging actif indépendamment du profil app ;
|
||||
- valider le document contre son schéma ;
|
||||
- confirmer le niveau global et les filtres spécifiques ;
|
||||
- vérifier les chemins et permissions des routes fichier ;
|
||||
- ne pas réinitialiser le subscriber global pendant l’exécution.
|
||||
## Flux de démarrage desktop
|
||||
|
||||
## Références
|
||||
1. charger la composition `config/kb-app-demo-desktop.default.config.json` ;
|
||||
2. résoudre le chemin `logging` référencé ;
|
||||
3. charger `logging.config.json` ;
|
||||
4. choisir l'override du profil ou son `default_profile` ;
|
||||
5. résoudre les paths sous `logs_directory` ;
|
||||
6. appeler `ks_logging::init_logging` ;
|
||||
7. poursuivre l'initialisation du runtime.
|
||||
|
||||
- `ks-logging/README.md` ;
|
||||
- `ks-logging/USAGE.md` ;
|
||||
- `config/README.md` ;
|
||||
- `docs/OPERATION_NAMING_CONVENTION.md`.
|
||||
`KS_LOGGING_CONFIG_PATH` remplace le chemin du document et `KS_LOGS_DIRECTORY` remplace uniquement sa racine de sortie.
|
||||
|
||||
## Sécurité
|
||||
|
||||
Les logs ne doivent jamais exposer :
|
||||
|
||||
- une valeur `KS_SECRET_*` ou `KB_SECRET_*` ;
|
||||
- un DSN avec credentials ;
|
||||
- une clé privée/keypair ;
|
||||
- une configuration runtime complète résolue.
|
||||
|
||||
Le masquage structurel et les DTO diagnostics sûrs sont finalisés dans la prochaine prerelease de `0.5.1`.
|
||||
|
||||
Reference in New Issue
Block a user