7.6 KiB
Utilisation de ksp-onchain-transport-lib
Ce guide présente les surfaces publiques destinées aux consumers. Les notes de release restent dans CHANGELOG.md et les deltas.
1. Construction directe du runtime
Transport peut être utilisé sans Config. Le consumer construit les settings publics puis le pool :
let url = match ksp_onchain_transport_lib::HttpEndpointUrl::parse("https://api.devnet.solana.com") {
Ok(value) => value,
Err(error) => return Err(error),
};
let role = ksp_onchain_transport_lib::HttpEndpointRoleSettings::new(
ksp_onchain_transport_lib::HttpRoleName::new("default"),
true,
vec![ksp_onchain_transport_lib::HttpRequestKind::wildcard()],
100,
ksp_onchain_transport_lib::HttpRoleLimits::new(None, None, None, None),
);
let endpoint = ksp_onchain_transport_lib::HttpEndpointSettings::new(
"solana_devnet_public",
true,
ksp_onchain_transport_lib::HttpProviderName::new("solana-public"),
ksp_onchain_transport_lib::HttpClusterName::new("devnet"),
url,
std::time::Duration::from_secs(5),
std::time::Duration::from_secs(15),
Some(8),
vec![role],
);
let settings = ksp_onchain_transport_lib::HttpTransportSettings::new(
vec![endpoint],
ksp_onchain_transport_lib::HttpRetrySettings::new(
2,
std::time::Duration::from_millis(100),
std::time::Duration::from_secs(2),
),
);
let pool = match ksp_onchain_transport_lib::HttpTransportPool::new(settings) {
Ok(value) => value,
Err(error) => return Err(error),
};
HttpTransportSettings::validate() peut être appelé explicitement avant la construction du pool lorsque le consumer veut séparer validation et initialisation.
2. Construction via ksp-config-lib
Lorsque le consumer utilise Config, la direction reste Config -> Transport :
let resolved = match engine.load_resolved_transport_config(Some("devnet_public"), &environment) {
Ok(value) => value,
Err(error) => return Err(error),
};
let pool = match ksp_onchain_transport_lib::HttpTransportPool::new(resolved.into_settings()) {
Ok(value) => value,
Err(error) => return Err(error),
};
Le document standard peut contenir une URL provenant d'un KSP_SECRET_*. La valeur réelle est transmise au runtime, mais les projections sûres et Debug restent redacted.
3. Appels typés
Les wrappers typés se trouvent directement sur HttpTransportPool.
let role = ksp_onchain_transport_lib::HttpRoleName::new("default");
let health = pool.get_health(&role).await;
let genesis_hash = pool.get_genesis_hash(&role).await;
let version = pool.get_version(&role).await;
let balance = pool
.get_balance(
&role,
&ksp_core_lib::PRGIDPK_SOLANA_SYSTEM,
Some(&ksp_onchain_transport_lib::GetBalanceConfig::new(
Some(ksp_onchain_transport_lib::SolanaCommitment::Confirmed),
None,
)),
)
.await;
Les quatre canaris 0.2.1 restent disponibles. 0.2.2 ajoute les wrappers typés Accounts, Tokens et Cluster. Exemples représentatifs :
let account = pool
.get_account_info(&role, &ksp_core_lib::PRGIDPK_SOLANA_SYSTEM, None)
.await;
let epoch = pool.get_epoch_info(&role, None).await;
let vote_accounts = pool.get_vote_accounts(&role, None).await;
La surface stable 0.2.2 contient 26 wrappers typés au total : 4 foundation + 5 Accounts + 5 Tokens + 12 Cluster. Les DTOs Transport conservent les null, options et formes wire : données Account encodées/jsonParsed, TokenAmount.uiAmount, contexte RPC, nodes, epoch, leader schedule et vote accounts. Aucun décodage Program/SPL métier n'est effectué ici.
4. Exécution JSON-RPC standard générique
Une méthode courante auditée peut être appelée via son descriptor :
if let Some(descriptor) = ksp_onchain_transport_lib::find_http_rpc_method("getSlot") {
let _result = pool.execute_standard_rpc(&role, descriptor, vec![]).await;
}
Cette API retourne un serde_json::Value. Elle est utile pour les consumers techniques et pour préparer les futures surfaces typées, mais elle ne remplace pas le wrapper typé d'une méthode dans la matrice de couverture KSP.
Avant exécution, ensure_runtime_supported() est appliqué. Une méthode historique Removed retourne ERROR_CODE_METHOD_REMOVED au lieu d'émettre un appel réseau fictif.
5. Sélection et admission sans exécuter la requête
Pour inspecter le routing :
if let Some(descriptor) = ksp_onchain_transport_lib::find_http_rpc_method("getBalance") {
let _selection = pool.select_for_method(&role, descriptor);
let _permit = pool.acquire_for_method(&role, descriptor).await;
}
Dans le même bloc, acquire_for_method() réserve réellement la capacité RPS/concurrence sous deadline.
HttpRequestPermit détient la capacité de concurrence jusqu'à sa destruction. Aucun verrou synchrone n'est conservé pendant l'attente réseau.
6. Snapshots runtime
HttpTransportPool::snapshot() fournit une vue sûre des endpoints/rôles : disponibilité, limites, requêtes en vol, cooldown restant et compteurs runtime.
Les URLs d'endpoint n'y apparaissent jamais.
7. Retry et write submissions
La policy de retry est portée par la metadata des méthodes et evaluate_transport_retry().
Les reads/simulations classés RetrySafe peuvent être réessayés dans le budget configuré lorsqu'une cause transport est explicitement retryable.
Pour une opération WriteSubmission / NeverAfterDispatch, un timeout ou autre résultat ambigu après dispatch arrête la resoumission automatique. Le consumer métier ne doit pas contourner cette protection avec une boucle de retry externe aveugle.
8. Logging
Les événements Transport utilisent le target :
ksp-onchain-transport-lib
Ne jamais journaliser l'URL complète, un token provider, un body massif, une transaction complète ou une réponse complète.
La configuration standard route les événements info de Transport vers un fichier dédié. Pour une investigation temporaire, élever uniquement ce target/sink à debug ou trace, puis revenir à info avant clôture du développement.
9. Smokes Devnet opt-in
Le smoke Transport pur construit ses settings programmatiquement et exerce un sous-ensemble représentatif de 0.2.2 :
cargo test -p ksp-onchain-transport-lib --test transport_devnet_smoke -- --ignored --nocapture
Il appelle getAccountInfo, getTokenAccountsByOwner, getEpochInfo et getVoteAccounts. La branche Token suit la forme Devnet documentée : owner Pubkey ordinaire de l'exemple officiel, selector programId avec l'ID canonique du programme SPL Token, puis config explicite commitment: finalized + encoding: jsonParsed. Une réponse vide reste acceptable : le smoke valide ainsi la route Token sans dépendre de la persistance d'un mint ou d'un token account Devnet particulier.
Le smoke historique de composition Config -> Transport reste également disponible :
cargo test -p ksp-config-lib --test transport_devnet_smoke -- --ignored --nocapture
Il valide le profil committé devnet_public et les quatre canaris foundation. Il reste transitoirement hébergé dans Config : les futurs smokes cross-crates ne doivent pas faire de Config leur destination générale et devront migrer vers une surface d'intégration/orchestration dédiée lorsqu'elle existera.
Les endpoints publics Solana sont rate-limités et non destinés à la production. Un échec réseau externe n'est pas assimilé automatiquement à une régression locale ; les fixtures HTTP locales restent les gates reproductibles.