165 lines
6.1 KiB
Markdown
165 lines
6.1 KiB
Markdown
<!-- file: crates/ksp-onchain-transport-lib/USAGE.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# 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 :
|
|
|
|
```rust
|
|
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 :
|
|
|
|
```rust
|
|
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`.
|
|
|
|
```rust
|
|
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 types de retour associés sont :
|
|
|
|
```text
|
|
SolanaNodeHealth
|
|
SolanaGenesisHash
|
|
SolanaNodeVersion
|
|
GetBalanceResult
|
|
SolanaRpcContext
|
|
```
|
|
|
|
`GetBalanceResult::value()` renvoie les lamports et `context()` fournit le slot/API version retournés par Solana.
|
|
|
|
## 4. Exécution JSON-RPC standard générique
|
|
|
|
Une méthode courante auditée peut être appelée via son descriptor :
|
|
|
|
```rust
|
|
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 :
|
|
|
|
```rust
|
|
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 :
|
|
|
|
```text
|
|
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. Smoke Devnet opt-in
|
|
|
|
Le smoke live est volontairement hors des tests par défaut :
|
|
|
|
```bash
|
|
cargo test -p ksp-config-lib --test transport_devnet_smoke -- --ignored --nocapture
|
|
```
|
|
|
|
Il charge le profil Config `devnet_public`, construit le pool puis appelle les quatre wrappers typés. Les endpoints publics Solana étant rate-limités et non destinés à la production, un échec réseau externe n'est pas interprété comme un échec déterministe de la suite locale.
|