v0.2.7-pre.004

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

@@ -1,5 +1,5 @@
 <!-- file: crates/ksp-onchain-transport-lib/USAGE.md -->
-<!-- version: 9 -->
+<!-- version: 10 -->
 
 # Utilisation de `ksp-onchain-transport-lib`
 
@@ -65,7 +65,38 @@ let pool = match ksp_onchain_transport_lib::HttpTransportPool::new(resolved.into
 
 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
+## 3. Session physique WebSocket
+
+À partir de `0.2.7-pre.004`, un consumer peut créer explicitement une session physique :
+
+```rust
+let ws_url = match ksp_onchain_transport_lib::WsEndpointUrl::parse("wss://api.devnet.solana.com") {
+    Ok(value) => value,
+    Err(error) => return Err(error),
+};
+let endpoint = ksp_onchain_transport_lib::WsEndpointSettings::new(
+    "devnet_public",
+    true,
+    ksp_onchain_transport_lib::WsProviderName::new("solana-public"),
+    ksp_onchain_transport_lib::WsClusterName::new("devnet"),
+    ksp_onchain_transport_lib::WsProtocolKind::SolanaStandard,
+    ws_url,
+    ksp_onchain_transport_lib::WsSessionSettings::default(),
+);
+let session = match ksp_onchain_transport_lib::WsSession::connect(endpoint).await {
+    Ok(value) => value,
+    Err(error) => return Err(error),
+};
+let snapshot = session.snapshot();
+```
+
+Deux appels `WsSession::connect` avec le même endpoint créent volontairement deux connexions physiques distinctes. Il n'existe encore aucun pool de sessions automatique.
+
+Le socket brut et la primitive JSON-RPC générique ne sont pas publics. Les wrappers `*Subscribe` typed et leurs handles seront ajoutés au-dessus de l'actor ; `pre.004` ne doit donc pas être utilisé comme escape hatch provider-specific.
+
+Le snapshot expose seulement l'identité locale, les metadata logiques de l'endpoint, l'état et les compteurs sûrs. L'URL n'est jamais projetée. Le shutdown async explicite arrive en `pre.005`; la disparition de tous les handles déclenche seulement le cleanup actor best-effort de cette foundation.
+
+## 4. Appels typés
 
 Les wrappers typés se trouvent directement sur `HttpTransportPool`.
 
@@ -125,7 +156,7 @@ let stake_minimum = pool.get_stake_minimum_delegation(&role, Some(&context)).awa
 
 `getBlock` possède également une forme bare-encoding legacy séparée et deprecated. Les valeurs Economics restent celles du runtime : le consumer ne doit pas supposer localement un taux d'inflation ou un minimum de délégation constant.
 
-## 4. Exécution JSON-RPC standard générique
+## 5. Exécution JSON-RPC standard générique
 
 Une méthode courante auditée peut être appelée via son descriptor :
 
@@ -139,7 +170,7 @@ Cette API retourne un `serde_json::Value`. Elle reste utile pour les extensions
 
 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
+## 6. Sélection et admission sans exécuter la requête
 
 Pour inspecter le routing :
 
@@ -154,13 +185,13 @@ Dans le même bloc, `acquire_for_method()` réserve réellement la capacité RPS
 
 `HttpRequestPermit` détient la capacité de concurrence jusqu'à sa destruction. Aucun verrou synchrone n'est conservé pendant l'attente réseau.
 
-## 6. Snapshots runtime
+## 7. 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
+## 8. Retry et write submissions
 
 La policy de retry est portée par la metadata des méthodes et `evaluate_transport_retry()`.
 
@@ -168,7 +199,7 @@ Les reads/simulations classés `RetrySafe` peuvent être réessayés dans le bud
 
 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
+## 9. Logging
 
 Les événements Transport utilisent le target :
 
@@ -180,7 +211,7 @@ Ne jamais journaliser l'URL complète, un token provider, un body massif, une tr
 
 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
+## 10. Smokes Devnet opt-in
 
 Le smoke **Transport pur** construit ses settings programmatiquement et exerce un sous-ensemble représentatif d'Accounts/Tokens/Cluster, trois reads Transactions, puis des reads Blocks/Economics de la release stable `0.2.4` :