v0.2.1-pre.007

crates/ksp-onchain-transport-lib/USAGE.md

@@ -0,0 +1,164 @@
+<!-- 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.