khadhroony-solana-project/crates/ksp-config-lib/README.md

ksp-config-lib

ksp-config-lib est le propriétaire unique de la configuration applicative KSP.

La crate centralise les documents JSON, leurs schemas, les profils et compositions, les variables d'environnement KSP_* / KSPB_*, le fichier .env, la résolution effective et les mutations persistantes explicitement autorisées.

Responsabilités

ksp-config-lib possède :

• le bootstrap non récursif config/ / config/schemas/ et les overrides --cfgpath / --schemapath ;
• le registre logique file_id -> filename, son inventaire public read-only ordonné par file_id et les overrides --filemap=<file_id>=<filename> ;
• la lecture JSON et la validation JSON Schema Draft 2020-12 ;
• les invariants sémantiques KSP des documents connus ;
• les globals, default_profile, profils nommés et leur provenance ;
• les compositions génériques par file_id, sans dépendance à un filename physique ;
• le snapshot des variables process KSP/KSPB et la lecture de ./.env ;
• la priorité process > .env > fallback > missing ;
• les placeholders ${NAME} et ${NAME:-fallback} ;
• la classification Public, Internal, Secret ;
• les représentations réelle et sûre/redacted ainsi que la provenance des valeurs résolues ;
• l'adapter du document Logging effectif vers ksp_logging_lib::LoggingSettings ;
• l'adapter du document Transport V1/V2/V3 vers HttpTransportSettings, WsTransportSettings et, en V3, YellowstoneGrpcTransportSettings, y compris redaction/provenance des URLs KSP_SECRET_* ;
• l'adapter de cfg.std.offchain_transport vers ksp_offchain_transport_lib::MarketPriceService, avec contrôle de provenance des credentials/public fields et sans rendre les limites provider configurables ;
• l'adapter de cfg.std.store vers ksp_store_lib::StoreSettings, avec sélection d'un target nommé, réseau explicite et URI PostgreSQL à provenance Secret ;
• la surface de management pour inspecter et réparer les sources Config enregistrées, modifier std.logging.json, consulter les rapports d'environnement, révéler explicitement une valeur réelle et modifier .env ;
• les écritures atomiques JSON/.env et la protection des permissions .env ;
• les audits workspace empêchant les bypass d'ownership Config et les oublis dans .env.example.

Ressources gérées

Le registre par défaut connaît :

cfg.composite.ksp-app-backfill-desk  -> config/composite.ksp-app-backfill-desk.json
cfg.composite.ksp-app-solprices-desk -> config/composite.ksp-app-solprices-desk.json
cfg.composite.ksp-app-store-desk     -> config/composite.ksp-app-store-desk.json
cfg.composite.ksp-app-wallet-desk    -> config/composite.ksp-app-wallet-desk.json
cfg.std.logging                    -> config/std.logging.json
cfg.std.offchain_transport         -> config/std.offchain_transport.json
cfg.std.store                      -> config/std.store.json
cfg.std.transport                  -> config/std.transport.json
cfg.std.wallet                     -> config/std.wallet.json
schema.composite                   -> config/schemas/composite.schema.json
schema.std.logging                 -> config/schemas/std.logging.schema.json
schema.std.offchain_transport      -> config/schemas/std.offchain_transport.schema.json
schema.std.store                   -> config/schemas/std.store.schema.json
schema.std.transport               -> config/schemas/std.transport.schema.json
schema.std.wallet                  -> config/schemas/std.wallet.schema.json

ConfigFileRegistry::descriptors() expose ces descripteurs en lecture seule et dans un ordre déterministe par file_id. Une application de management peut ainsi découvrir les fichiers connus sans maintenir une liste parallèle ni dépendre de leurs filenames physiques.

ConfigManagement::read_source() permet d'inspecter le texte brut d'un document Config enregistré même lorsque ce document est invalide. save_source_candidate() complète cette frontière : le candidat brut est parsé, validé contre son schema et les invariants sémantiques KSP, puis persisté atomiquement uniquement après validation complète. Le file_id doit appartenir au registre et désigner un document Config ; aucun path arbitraire n'est accepté.

config/examples/composite.example.json conserve l’exemple générique. Les composites runtime committed restent possédés par Config : Backfill Desk compose Logging + Transport + Store, SOL Prices Desk compose Logging + Off-chain Transport, Store Desk compose Logging + Store, et Wallet Desk compose Logging + Off-chain Transport + On-chain Transport + Wallet. Tous référencent leurs documents par file_id, sans dépendre de filenames physiques.

Le fichier local d'environnement est :

./.env

Il n'est ni versionné ni livré. Le dépôt maintient /.env.example comme inventaire versionné des variables runtime utilisées. Toute nouvelle variable KSP/KSPB concrète doit y être ajoutée avec un commentaire d'usage dans le même delta que sa première utilisation.

Frontières

Les autres crates et applications KSP ne doivent pas :

• lire directement les variables applicatives KSP_* / KSPB_* ;
• parser ou écrire directement .env ;
• ouvrir directement les documents Config connus par leur filename physique ;
• réimplémenter la sélection de profils, les compositions ou les placeholders ;
• reconstruire elles-mêmes la configuration Logging, On-chain Transport, Off-chain Transport, Store ou Wallet depuis le JSON.

ksp-config-lib dépend de ksp-core-lib pour Error/Result, de ksp-logging-lib pour les événements Config utiles et le contrat LoggingSettings, de ksp-onchain-transport-lib pour construire le contrat runtime On-chain Transport et de ksp-offchain-transport-lib pour construire le service market-price dans la direction Config -> Transport et de ksp-store-lib avec default-features = false pour construire les settings Store dans la direction Config -> Store sans forcer un backend physique. Le document Wallet reste un contrat de chemins/profils Config et n’introduit aucune dépendance Config -> ksp-wallet-lib.

La dépendance inverse est interdite : ksp-core-lib, ksp-logging-lib, ksp-onchain-transport-lib, ksp-offchain-transport-lib et les crates Store ne dépendent pas de Config.

Config ne possède pas le LoggingGuard. L'application ou le service qui orchestre le runtime construit la configuration effective puis possède le lifecycle ksp_logging_lib::initialize/reinitialize.

Tauri et les DTO TS-RS restent hors de cette crate. ksp-app-config-desk reste une frontière applicative mince au-dessus des APIs Config et découvre les documents standards via le registre Config sans déplacer leur logique métier dans l'application.

Secrets

Un secret reste accessible au runtime ou au management lorsqu'un consumer autorisé en a réellement besoin, mais les vues ordinaires utilisent la représentation sûre.

Les méthodes reveal_* constituent un opt-in explicite au réel. L'authentification/autorisation de l'utilisateur humain appartient à l'application appelante et les valeurs retournées par ces méthodes ne doivent jamais être journalisées.

Le document Logging refuse les valeurs de sensibilité Secret dans sa configuration effective. Le document Transport accepte les valeurs secrètes pour les URLs HTTP/WebSocket et, en V3, pour grpc_endpoints[].secret_metadata[] : la valeur réelle est transmise au runtime légitime, tandis que la projection sûre et les Debug restent redacted. Les metadata gRPC publiques et secrètes sont séparées et leur provenance Config est contrôlée avant mapping. std.offchain_transport exige une provenance Secret pour les API keys effectives et une provenance Public pour la paire DexScreener lorsqu'elle vient de l'environnement ; il ne permet ni URL provider arbitraire ni override de rate limit. std.store exige une provenance Secret pour chaque URI PostgreSQL effective et conserve des targets réseau-spécifiques indépendants (devnet, mainnet, testnet) sans exposer l'URI dans les projections sûres. std.wallet refuse également toute sensibilité Secret pour wallets_directory/wallets_subdirectory; les passwords Wallet restent un autre flux Config et ne sont jamais stockés dans ce JSON.

Documentation

• USAGE.md — construction du moteur, résolution runtime et management ;
• TODO.md — points explicitement différés ;
• ../../docs/plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md — plan historique détaillé de la fondation Config ;
• ../../config/std.logging.json — document standard Logging ;
• ../../config/std.transport.json — document standard Transport V3 HTTP + WebSocket + Yellowstone gRPC, avec lecture backward des V1/V2 ;
• ../../config/std.offchain_transport.json — document standard Off-chain Transport V1, actuellement limité au domaine market_price SOL/USD ;
• ../../config/std.store.json — targets Store PostgreSQL Devnet/Mainnet/Testnet et settings runtime bornés ;
• ../../config/std.wallet.json — racine Wallet globale et sous-répertoire optionnel par profil ;
• ../../config/composite.ksp-app-backfill-desk.json — composition Logging/Transport/Store de Backfill Desk ;
• ../../config/composite.ksp-app-solprices-desk.json — composition Logging/Off-chain Transport de SOL Prices Desk ;
• ../../config/composite.ksp-app-store-desk.json — composition Logging/Store de Store Desk ;
• ../../config/composite.ksp-app-wallet-desk.json — composition Logging/Off-chain Transport/On-chain Transport/Wallet de Wallet Desk ;
• ../../.env.example — inventaire versionné des variables d'environnement runtime.