175 lines
7.6 KiB
Markdown
175 lines
7.6 KiB
Markdown
<!-- file: crates/ksp-onchain-transport-lib/USAGE.md -->
|
|
<!-- version: 5 -->
|
|
|
|
# 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 quatre canaris `0.2.1` restent disponibles. `0.2.2` ajoute les wrappers typés Accounts, Tokens et Cluster. Exemples représentatifs :
|
|
|
|
```rust
|
|
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 :
|
|
|
|
```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. Smokes Devnet opt-in
|
|
|
|
Le smoke **Transport pur** construit ses settings programmatiquement et exerce un sous-ensemble représentatif de `0.2.2` :
|
|
|
|
```bash
|
|
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 :
|
|
|
|
```bash
|
|
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.
|