ksp-onchain-transport-lib
ksp-onchain-transport-lib est la bibliothèque KSP propriétaire du transport on-chain Solana. Sa première surface est le transport HTTP JSON-RPC ; les extensions WebSocket et gRPC sont introduites séparément lorsque leur release les cible.
Responsabilités
La crate possède :
- les settings runtime HTTP publics ;
- les endpoints nommés et leurs metadata provider/cluster ;
- les rôles, capabilities/request kinds et priorités ;
- la sélection/fairness/fallback du pool ;
- les limites RPS/burst/concurrence et le cooldown ;
- les deadlines et timeouts ;
- le retry/backoff borné et la règle no-resend après dispatch ambigu ;
- les enveloppes JSON-RPC 2.0 et leur validation ;
- le registre audité des méthodes Solana HTTP ;
- l'exécution générique des méthodes standard supportées ;
- les wrappers typés explicitement livrés par KSP ;
- les snapshots runtime sûrs ;
- l'observabilité Transport via
ksp-logging-lib.
La crate ne possède ni documents Config, ni persistence Store, ni modèles Program/métier.
Frontières de dépendances
La direction autorisée est :
ksp-config-lib
-> ksp-onchain-transport-lib
-> ksp-core-lib
-> ksp-logging-lib
-> reqwest / tokio / serde
La direction inverse est interdite :
ksp-onchain-transport-lib -X-> ksp-config-lib
ksp-onchain-transport-lib -X-> Store
ksp-onchain-transport-lib -X-> Program
ksp-onchain-transport-lib -X-> tracing direct
ksp-config-lib peut donc charger std.transport.json et construire HttpTransportSettings, tandis que Transport reste directement utilisable par un consumer qui fournit lui-même ses settings.
Surface HTTP standard
Le registre KSP conserve deux inventaires distincts :
52 méthodes HTTP courantes
14 méthodes historiques Deprecated / runtime Removed
Le registre porte notamment :
- catégorie ;
- request kind ;
- statut documentaire ;
- statut runtime ;
- forme de requête stable/legacy ;
- type d'opération ;
- classe de retry ;
- remplacement historique éventuel ;
- release de couverture typée KSP.
Les quatre wrappers typés de la foundation sont :
getBalance
getGenesisHash
getHealth
getVersion
Les autres méthodes courantes peuvent déjà passer par l'exécuteur JSON-RPC standard générique lorsqu'un consumer fournit explicitement descriptor et paramètres JSON. Cette surface raw/générique ne vaut pas couverture typée : les wrappers et DTOs typés restants sont introduits selon la matrice HTTP KSP.
Les 14 méthodes historiques restent découvrables pour la compliance mais sont Removed et ne sont pas simulées comme appelables.
Résilience
L'admission est calculée par couple endpoint/rôle. Le pool applique :
- rôle et capability ;
- priorité croissante ;
- round-robin dans le meilleur tier ;
- RPS/burst ;
- concurrence ;
- cooldown rate-limit ;
- fallback vers les pairs puis les tiers inférieurs ;
- deadline commune à l'opération et ses retries.
Les retries ne sont autorisés que lorsque la metadata de méthode et l'état de dispatch les rendent sûrs. WriteSubmission / NeverAfterDispatch interdit tout resend automatique après un dispatch ambigu.
Les erreurs JSON-RPC applicatives ne sont pas transformées en retries transport génériques.
Sécurité et diagnostics
Les URLs d'endpoint peuvent contenir des credentials. Elles ne sont donc pas exposées par les Debug, snapshots ou logs ordinaires.
Les reqwest::Error attachées comme source sont neutralisées avec without_url() avant exposition dans le contrat d'erreur KSP.
Le target de tracing est possédé explicitement par :
src/constants.rs
TRACING_TARGET = "ksp-onchain-transport-lib"
La configuration Logging de référence conserve un fichier dédié Transport à niveau info. Un niveau debug/trace ciblé peut être réactivé temporairement via Config lors d'un développement ou diagnostic explicite.
Tests
Les tests par défaut sont déterministes et n'exigent pas Internet : fixtures JSON et serveur HTTP local couvrent requêtes, réponses, retry, 429, timeout, redaction et routing.
Un smoke Devnet live existe côté ksp-config-lib afin de tester la chaîne réelle :
Config -> std.transport/devnet_public -> HttpTransportPool
-> getHealth/getGenesisHash/getVersion/getBalance
Il est ignored par défaut et doit être exécuté explicitement.
Documentation
USAGE.md— consommation directe, Config -> Transport, API typed/raw et inspection runtime ;../../docs/plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md— plan et matrice HTTP ;../../docs/validation/003-V0_2_1_ONCHAIN_HTTP.md— matrice de clôture ;../../config/std.transport.json— configuration standard HTTP.