v0.2.8-pre.007
This commit is contained in:
211
deltas/0.2.8/pre.007.md
Normal file
211
deltas/0.2.8/pre.007.md
Normal file
@@ -0,0 +1,211 @@
|
||||
<!-- file: deltas/0.2.8/pre.007.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Delta `0.2.8-pre.007` — heartbeat Helius WebSocket + idle lifecycle
|
||||
|
||||
## 1. Base et objet
|
||||
|
||||
Base appliquée :
|
||||
|
||||
```text
|
||||
0.2.8-pre.6
|
||||
```
|
||||
|
||||
Le checkpoint opérateur de `pre.006` est intégralement vert et sans warning :
|
||||
|
||||
```text
|
||||
cargo fmt --all OK
|
||||
python3 scripts/audit_rust_workspace_rules.py clean
|
||||
cargo check --workspace OK
|
||||
cargo clippy --workspace --all-targets OK
|
||||
Transport unit 325/325
|
||||
Transport public API 40/40
|
||||
Transport release completeness 28/28
|
||||
Transport doctests compile-fail 4/4
|
||||
cargo test --workspace OK
|
||||
```
|
||||
|
||||
Cette tranche ajoute uniquement la policy de heartbeat Helius LaserStream WebSocket dans l'actor physique commun. Elle ne rouvre pas le lifecycle transaction validé par `pre.006`.
|
||||
|
||||
## 2. Version technique
|
||||
|
||||
```text
|
||||
workspace.package.version = 0.2.8-pre.7
|
||||
commit attendu = v0.2.8-pre.007
|
||||
Git tag = aucun tag prerelease
|
||||
```
|
||||
|
||||
Le header root `Cargo.toml` passe en version `227`.
|
||||
|
||||
## 3. Policy heartbeat provider-owned
|
||||
|
||||
La décision d'architecture de `pre.001` est matérialisée sans nouveau réglage public :
|
||||
|
||||
```text
|
||||
protocol WsProtocolKind::HeliusLaserStream uniquement
|
||||
intervalle nominal 60 s
|
||||
frame WebSocket Ping control frame vide
|
||||
état actor Active uniquement
|
||||
succès réarmement à now + 60 s
|
||||
reconnect réussi réarmement depuis la connexion de remplacement
|
||||
write timeout/failure WsActorIoOutcome::Failed
|
||||
close/shutdown timer abandonné ; shutdown prioritaire
|
||||
SolanaStandard aucun heartbeat provider
|
||||
```
|
||||
|
||||
Le heartbeat n'est pas un appel JSON-RPC `ping`. KSP utilise la frame de contrôle WebSocket `Ping`, déjà compatible avec le traitement `Pong` de l'actor.
|
||||
|
||||
Aucun champ `heartbeat_*` n'est ajouté à :
|
||||
|
||||
```text
|
||||
WsSessionSettings
|
||||
WsEndpointSettings
|
||||
Config
|
||||
.env.example
|
||||
schema Transport
|
||||
```
|
||||
|
||||
La cadence est donc une policy Helius WebSocket interne, pas une option de configuration générique.
|
||||
|
||||
## 4. Intégration dans l'actor unique
|
||||
|
||||
`run_ws_session_actor` possède le deadline heartbeat avec les mêmes priorités de shutdown que le reste du moteur :
|
||||
|
||||
```text
|
||||
shutdown
|
||||
command
|
||||
socket input
|
||||
Helius heartbeat deadline
|
||||
pending JSON-RPC timeout
|
||||
```
|
||||
|
||||
Le branch heartbeat est désactivé pour `SolanaStandard`.
|
||||
|
||||
Sur succès du Ping, le prochain deadline est recalculé à partir de `Instant::now()`. Pendant reconnect, aucun heartbeat n'est émis ; lorsque `recover_websocket_session` rend une connexion de remplacement active, le deadline est réarmé à 60 s.
|
||||
|
||||
Le helper d'écriture sélectionne de façon bornée entre :
|
||||
|
||||
```text
|
||||
shutdown signal
|
||||
websocket.send(Ping)
|
||||
command_timeout
|
||||
```
|
||||
|
||||
Une erreur d'écriture ou un timeout retourne le même `WsActorIoOutcome::Failed` que les autres erreurs de connexion. Le chemin de reconnect, son budget, son backoff, les remaps et le shutdown restent donc uniques.
|
||||
|
||||
## 5. Timers déterministes de test
|
||||
|
||||
La cadence runtime ne doit pas être raccourcie pour rendre les tests rapides. La crate active donc uniquement côté dev/test la feature Tokio :
|
||||
|
||||
```text
|
||||
test-util
|
||||
```
|
||||
|
||||
avec `io-util` nécessaire au canari de socket cassé en mémoire.
|
||||
|
||||
Il ne s'agit pas d'une nouvelle dépendance ; aucune feature runtime de production n'est ajoutée au contrat KSP.
|
||||
|
||||
Les tests utilisent `tokio::time::pause()` / `advance()` pour vérifier la vraie constante de 60 s.
|
||||
|
||||
## 6. Canaris ajoutés
|
||||
|
||||
Six tests unitaires Transport sont ajoutés :
|
||||
|
||||
```text
|
||||
Helius-only + constante 60 s
|
||||
premier Ping à 60 s + second Ping après réarmement
|
||||
absence totale de heartbeat provider sur SolanaStandard
|
||||
close à 30 s sans Ping
|
||||
échec d'écriture Ping -> WsActorIoOutcome::Failed / ERROR_CODE_WS_CONNECTION_FAILED
|
||||
reconnect avant heartbeat -> nouveau deadline 60 s depuis la connexion de remplacement
|
||||
```
|
||||
|
||||
Le test hérité `websocket_shutdown_interrupts_reconnect_backoff_without_new_connection` continue de couvrir l'interruption du backoff par shutdown, tandis que le nouveau branch heartbeat place également le signal shutdown en première priorité.
|
||||
|
||||
Le canari release-completeness vérifie que :
|
||||
|
||||
- la policy reste dans `ws_session.rs` ;
|
||||
- le Ping est une frame WebSocket ;
|
||||
- `WsSessionSettings` ne gagne aucun champ de heartbeat ;
|
||||
- la façade Helius ne possède aucun timer séparé.
|
||||
|
||||
Comptages attendus :
|
||||
|
||||
```text
|
||||
Transport unit 331
|
||||
Transport public API 40
|
||||
release completeness 29
|
||||
doctests compile-fail 4
|
||||
```
|
||||
|
||||
## 7. Non-régressions
|
||||
|
||||
Cette tranche ne modifie pas :
|
||||
|
||||
```text
|
||||
surface Helius standard 6 familles
|
||||
transactionSubscribe request/filter/options
|
||||
transactionNotification Full/Signature/Unknown
|
||||
WsSubscriptionKind::HeliusTransaction
|
||||
remote/local ID remapping
|
||||
late notification handling
|
||||
backpressure logical subscription
|
||||
standard Solana WebSocket 18/18
|
||||
HTTP 52 current / 14 historical
|
||||
Config Helius mainnet/devnet
|
||||
dependency firewall
|
||||
```
|
||||
|
||||
Aucune promesse de replay WebSocket ou de livraison lossless n'est introduite.
|
||||
|
||||
## 8. Documentation
|
||||
|
||||
Le plan `015` :
|
||||
|
||||
- ferme `pre.006` sur preuve opérateur ;
|
||||
- marque `pre.007` PREPARED ;
|
||||
- matérialise la policy Helius-only 60 s et ses canaris.
|
||||
|
||||
La validation `011` :
|
||||
|
||||
- transforme les critères lifecycle `pre.006` en preuves acquises ;
|
||||
- ouvre la gate `pre.007` ;
|
||||
- conserve les tests adversariaux élargis pour `pre.008`.
|
||||
|
||||
## 9. Hors scope
|
||||
|
||||
Restent hors de `pre.007` :
|
||||
|
||||
```text
|
||||
provider adversarial lifecycle élargi pre.008
|
||||
payload/security/redaction adversarial pre.008
|
||||
compliance Helius + standard + HTTP pre.009
|
||||
smoke Helius WebSocket live opt-in pre.010
|
||||
LaserStream gRPC future backend distinct
|
||||
```
|
||||
|
||||
## 10. Fichiers modifiés
|
||||
|
||||
```text
|
||||
Cargo.toml
|
||||
crates/ksp-onchain-transport-lib/Cargo.toml
|
||||
crates/ksp-onchain-transport-lib/src/ws_session.rs
|
||||
crates/ksp-onchain-transport-lib/unit_tests/ws_session.rs
|
||||
crates/ksp-onchain-transport-lib/tests/release_completeness.rs
|
||||
docs/plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md
|
||||
docs/validation/011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md
|
||||
deltas/0.2.8/pre.007.md
|
||||
```
|
||||
|
||||
## 11. Gate opérateur
|
||||
|
||||
```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
|
||||
cargo test --workspace
|
||||
```
|
||||
|
||||
Critère de fermeture : zéro warning nouveau, audit Rust clean, **331 unit / 40 public API / 29 completeness / 4 doctests** et workspace vert.
|
||||
Reference in New Issue
Block a user