# Delta `0.2.7-pre.002` — WebSocket settings + lifecycle contracts ## 1. Objet Cette tranche matérialise la première surface Rust WebSocket de `ksp-onchain-transport-lib` sans ouvrir encore de socket physique et sans ajouter de dépendance WebSocket externe. Version workspace : ```text 0.2.7-pre.2 ``` Livraison : ```text 0.2.7-pre.002 ``` Commit attendu : ```text v0.2.7-pre.002 ``` Aucun tag prerelease. ## 2. Surface Transport ajoutée Settings publics : ```text WsEndpointUrl WsProviderName WsClusterName WsProtocolKind WsReconnectSettings WsResubscribePolicy WsSessionSettings WsEndpointSettings WsTransportSettings ``` Lifecycle public : ```text WsSessionId WsSubscriptionId WsSessionState WsSubscriptionState WsSubscriptionKind WsSessionSnapshot WsSubscriptionSnapshot ``` `WsProtocolKind` est `#[non_exhaustive]` et ne fournit pour `0.2.7` que `SolanaStandard`. Cette forme prépare l'ajout futur d'une famille provider-specific telle que Helius Enhanced WebSocket sans ajouter de paramètres Helius dans les settings Solana standard. Les IDs locaux reposent sur `NonZeroU64`. Aucun ID serveur WebSocket n'entre dans le contrat public de contrôle. ## 3. URL et secrets `WsEndpointUrl` : - accepte uniquement `ws://` et `wss://` ; - exige un host ; - conserve la valeur sensible uniquement pour le futur code de connexion ; - rend `WsEndpointUrl()` en `Debug` ; - ne copie pas la valeur URL dans les erreurs de validation. `WsEndpointSettings` et `WsTransportSettings` peuvent conserver `Debug` dérivé car le sous-type URL est lui-même redacted. Les snapshots ne contiennent jamais : ```text URL complète credential/query token request body raw notification remote subscription id ``` ## 4. Settings session bornés Defaults initiaux Transport, explicitement policies KSP locales : ```text command timeout 10 s close timeout 5 s reconnect retries 5 reconnect initial backoff 250 ms reconnect maximum backoff 5 s command queue 128 notification queue per sub 256 active subscriptions 1024 pending JSON-RPC requests 128 maximum message 64 MiB maximum frame 16 MiB maximum write buffer 1 MiB resubscribe default ActiveSubscriptions ``` Ces valeurs ne sont pas présentées comme des limites Solana. `pre.004`/`pre.005` devront les appliquer réellement à l'actor/socket et pourront les recalibrer si les fixtures adversariales le justifient. Validation structurelle : - timeouts non nuls ; - reconnect backoff non nul et ordonné ; - capacités/limites strictement positives ; - au moins un endpoint WS configuré et enabled ; - noms endpoint uniques ; - name/provider/cluster non vides et sans whitespace de bord. ## 5. Lifecycle et snapshots États session matérialisés : ```text Disconnected Connecting Active Reconnecting { attempt } Closing Closed Failed ``` États subscription matérialisés : ```text Requested Active Resubscribing Cancelling Closed Failed ``` `WsSubscriptionKind` couvre les neuf familles standard auditées : account, block, logs, program, root, signature, slot, slotsUpdates et vote. `WsSessionSnapshot` expose uniquement des metadata sûres : local session ID, endpoint logical name, provider, cluster, protocol, state, pending request count, continuity gap count, overflow count et projections de subscriptions. `WsSubscriptionSnapshot` expose local subscription ID, kind, state et `remote_bound`; l'ID distant reste interne et remappable. Les constructeurs de snapshots sont crate-internal : les consumers ne peuvent pas fabriquer de faux états runtime. ## 6. Logging et tracing La constante existante reste l'autorité crate-wide : ```rust TRACING_TARGET = "ksp-onchain-transport-lib" ``` Elle est définie dans `crates/ksp-onchain-transport-lib/src/constants.rs`. Toute nouvelle émission passe par `ksp-logging-lib` : - `trace` pour entrée/succès de validations et metadata endpoint sûres ; - `debug` pour settings validés, compteurs et bornes ; - `warn` pour rejets de settings/URL ; - aucun `error` artificiel pour une erreur de validation caller. Aucun appel direct à `tracing` n'est ajouté. Les logs n'incluent jamais la valeur de `WsEndpointUrl`. ## 7. Tests ajoutés Tests unitaires settings : ```text ws/wss acceptés HTTP rejeté Debug URL redacted erreur de scheme sans secret protocol kind standard settings defaults bornés zero bound rejeté reconnect backoff inversé rejeté transport endpoints valides endpoint names dupliqués rejetés au moins un endpoint enabled Debug transport sans URL/credential ``` Tests unitaires lifecycle : ```text IDs locaux non-zéro et ordonnables états reconnect/resubscribe/cancelling distincts 9 familles standard couvertes snapshot sans URL ni remote subscription id ``` Un canari `tests/public_api.rs` vérifie l'accès crate-root aux nouveaux contrats. ## 8. Fichiers principaux Nouveaux : ```text crates/ksp-onchain-transport-lib/src/ws_settings.rs crates/ksp-onchain-transport-lib/src/ws_lifecycle.rs crates/ksp-onchain-transport-lib/unit_tests/ws_settings.rs crates/ksp-onchain-transport-lib/unit_tests/ws_lifecycle.rs deltas/0.2.7/pre.002.md ``` Modifiés : ```text Cargo.toml crates/ksp-onchain-transport-lib/src/constants.rs crates/ksp-onchain-transport-lib/src/lib.rs crates/ksp-onchain-transport-lib/tests/public_api.rs docs/plans/014-V0_2_7_ONCHAIN_WEBSOCKET_PLAN.md docs/validation/010-V0_2_7_ONCHAIN_WEBSOCKET.md ``` Aucune dependency externe n'est ajoutée dans cette tranche. ## 9. Validation disponible dans le sandbox Exécuté après modifications : ```text python3 scripts/audit_rust_workspace_rules.py General Rust rule audit: clean Rust export completeness audit: 0 candidate(s) KSP workspace Rust rule audit: clean ``` Le sandbox ne fournit toujours pas `cargo`; les gates Rust compilés ne sont donc pas déclarés réussis ici. Baseline opérateur reçue avant `pre.002` : `cargo fmt`, audit Python, `cargo check` et `cargo clippy` verts sur `0.2.7-pre.1`. `cargo test --workspace` n'échoue que sur le canari Config Desk qui compare encore la ressource packagée `0.2.6` à la version workspace `0.2.7-pre.1`; aucune régression WebSocket n'y est impliquée. ## 10. Gates opérateur avant commit Après application du delta : ```bash cargo fmt --all python3 scripts/audit_rust_workspace_rules.py cargo check --workspace cargo clippy --workspace --all-targets cargo test -p ksp-onchain-transport-lib ``` Le test workspace complet peut encore reproduire le canari de version packagée Config Desk tant que cette ressource n'est volontairement resynchronisée. ## 11. Suite `0.2.7-pre.003` doit matérialiser : ```text std.transport V2 HTTP + WS backward read V1 HTTP-only schema/fixtures V2 Config -> WsTransportSettings ws_endpoints[].kind = solana_standard ``` La direction reste strictement `Config -> Transport`; aucun reverse dependency n'est autorisé.