Sasedev/khadhroony-solana-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.2.8-pre.003

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-23 13:52:57 +02:00
parent c94a54f3e3
commit b3363073c4
13 changed files with 715 additions and 151 deletions
Download Patch File Download Diff File Expand all files Collapse all files

106
docs/plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md
View File

@@ -1,9 +1,9 @@
<!-- file: docs/plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md -->
<!-- version: 7 -->
<!-- version: 8 -->
# Plan `0.2.8` — Helius LaserStream WebSocket
> **Statut : `0.2.8-pre.002` est appliqué et testé, mais son gate Clippy requiert `pre.002-fix.001`.** Les tests Transport et workspace sont verts ; le fix corrige cinq `clippy::implicit_return` dans la nouvelle fixture protocolaire, passe Cargo à `0.2.8-pre.2.fix.1` et réorganise les documents actifs pour garder une séparation nette entre plan, validation et delta. Le moteur physique `WsSession` reste unique et partagé.
> **Statut : `0.2.8-pre.002` + `pre.002-fix.001` sont validés ; `0.2.8-pre.003` est préparé.** La façade `HeliusLaserStreamWsSession` expose désormais uniquement les six familles standard documentées comme supportées par Helius (`account`, `logs`, `program`, `root`, `signature`, `slot`) en réutilisant le wire standard existant. `block`, `slotsUpdates` et `vote` restent absents de la façade Helius. Le checkpoint Cargo opérateur de `pre.003` reste à exécuter.
## 1. Objet, base et état courant
@@ -24,15 +24,16 @@ prompts/013-V0_2_8_START_PROMPT.md présent
pre.001 gate audit/sizing Helius
pre.001-fix.001 séparation des façades + fermeture gate Cargo
pre.001-fix.002 forecast compact + namespace LaserStream WS/gRPC
pre.002 socle protocolaire appliqué ; tests verts, Clippy en échec ciblé
pre.002-fix.001 correction Clippy + audit/normalisation structure documentaire
pre.002 socle protocolaire validé
pre.002-fix.001 correction Clippy + normalisation structure documentaire validées
pre.003 six familles standard Helius préparées ; checkpoint opérateur pending
workspace.package.version courant = 0.2.8-pre.2.fix.1
commit attendu = v0.2.8-pre.002-fix.001
workspace.package.version courant = 0.2.8-pre.3
commit attendu = v0.2.8-pre.003
aucun tag prerelease
```
Le log opérateur de `pre.002` confirme : `cargo fmt`, audit Rust et `cargo check --workspace` verts ; `cargo test -p ksp-onchain-transport-lib` et `cargo test --workspace` verts ; `cargo clippy --workspace --all-targets` bloque uniquement sur cinq `clippy::implicit_return` dans `unit_tests/ws_protocol_session.rs`. Les résultats détaillés restent dans la matrice de validation et le delta du fix, pas dans le plan.
Le checkpoint opérateur de `pre.002-fix.001` est intégralement vert : `cargo fmt`, audit Rust, `cargo check --workspace`, `cargo clippy --workspace --all-targets`, tests Transport et `cargo test --workspace`. `pre.003` peut donc ouvrir la surface standard Helius sans reporter de dette de gate.
## 2. Forecast souple courant
@@ -43,10 +44,10 @@ pre.001 DONE — audit Helius actuel + matrice + architecture + threat model +
fix.001 DONE — séparation des façades standard/Helius + moteur unique + gate Cargo fermé
fix.002 DONE — forecast normalisé + namespace LaserStream WebSocket/gRPC clarifié
pre.002 FIX REQUIRED — socle protocolaire : WsProtocolKind::HeliusLaserStream + façades standard/Helius
pre.002 DONE — socle protocolaire : WsProtocolKind::HeliusLaserStream + façades standard/Helius
+ connexion physique partagée + guards, sans duplication de l'actor
fix.001 PREPARED — correction Clippy `implicit_return` + audit/normalisation structure docs
pre.003 surface Helius standard supportée : account/logs/program/root/signature/slot
fix.001 DONE — correction Clippy `implicit_return` + audit/normalisation structure docs
pre.003 PREPARED — surface Helius standard supportée : account/logs/program/root/signature/slot
+ absence typée de block/slotsUpdates/vote sur Helius + non-régression standard 9/9
pre.004 Config V2 helius_laserstream + schema/fixtures + mapping Config -> Transport
+ stratégie de secret Helius et redaction URL
@@ -454,7 +455,7 @@ Les 18 opérations standard restent donc présentes et testées : 9 subscribe +
### 7.2 Surface cible `HeliusLaserStreamWsSession`
À partir de `pre.003`, la façade Helius doit exposer uniquement les familles de subscription suivantes :
À terme dans `0.2.8`, la façade Helius doit exposer uniquement les familles de subscription suivantes :
```text
account
@@ -466,7 +467,9 @@ slot
transaction
```
Même après `pre.003`, elle **n'expose pas** :
`pre.003` matérialise exactement les six familles standard ; `transaction` reste réservé aux tranches provider-specific ultérieures du forecast.
La façade Helius **n'expose jamais dans le scope courant** :
```text
block
@@ -591,7 +594,34 @@ account block logs program root signature slot slotsUpdates vote
La façade Helius ne recevra les six délégations communes qu'en `pre.003`, afin de garder la tranche actuelle limitée au socle protocolaire et aux guards.
### 7.7 Protocol kind et namespace LaserStream
### 7.7 Réalisation de `pre.003`
`pre.003` ajoute uniquement les six wrappers standard que la matrice Helius autorise :
```text
accountSubscribe / accountUnsubscribe
programSubscribe / programUnsubscribe
logsSubscribe / logsUnsubscribe
signatureSubscribe / signatureUnsubscribe
slotSubscribe / slotUnsubscribe
rootSubscribe / rootUnsubscribe
```
Aucun encoder, decoder ou DTO Helius parallèle n'est créé : chaque méthode de `HeliusLaserStreamWsSession` délègue au même wrapper `WsSession` standard déjà validé en `0.2.7`. Pour éviter que le module de façade devienne un fichier fourre-tout, les implémentations sont rangées auprès de leur propriétaire wire :
```text
ws_accounts.rs -> account / program, façades standard + Helius
ws_transactions.rs -> logs / signature, façades standard + Helius
ws_cluster.rs -> root / slot, plus unstable standard uniquement
ws_blocks.rs -> block, façade standard uniquement
ws_protocol_session.rs -> lifecycle des façades + accès crate-private au moteur partagé
```
`block_subscribe`, `slots_updates_subscribe` et `vote_subscribe` restent absents du type Helius et sont verrouillés par doctests `compile_fail`. L'accès interne au `WsSession` physique est `pub(crate)` seulement ; aucun `inner()`/`into_inner()` public n'est introduit. Une fixture locale Helius dédiée vérifie les six méthodes subscribe/unsubscribe et leurs paramètres exacts ; les tests standard existants restent propriétaires du décodage des notifications.
`transactionSubscribe`, Config Helius et heartbeat restent hors scope de `pre.003`.
### 7.8 Protocol kind et namespace LaserStream
Retenir pour **WebSocket uniquement** :
@@ -609,7 +639,7 @@ Le futur **Helius LaserStream gRPC** reste un backend/provider distinct, hors `0
Cette règle permet de conserver le code court `helius_laserstream` dans son conteneur WS sans créer d'ambiguïté future entre les deux produits portant le nom LaserStream.
### 7.8 Connexion et propriété du moteur
### 7.9 Connexion et propriété du moteur
Cible de `pre.002` :
@@ -629,7 +659,7 @@ pas de second snapshot model
pas de public escape hatch Helius -> raw standard WsSession
```
### 7.9 Capability validation defense-in-depth
### 7.10 Capability validation defense-in-depth
La séparation de façade est la première barrière. Une matrice interne reste utile :
@@ -645,7 +675,7 @@ HeliusLaserStream:
Cette matrice sert aux guards de constructor/descriptor, aux canaries et à la protection interne ; elle ne remplace plus la séparation de l'API publique.
### 7.10 Heartbeat/idle ownership
### 7.11 Heartbeat/idle ownership
Helius annonce un timeout d'inactivité de 10 minutes et recommande des pings périodiques.
@@ -663,7 +693,7 @@ write failure = chemin disconnect/reconnect existant
budget reconnect = fini, inchangé
```
### 7.11 Config V2
### 7.12 Config V2
Évolution :
@@ -675,7 +705,7 @@ profiles[].ws_endpoints[].kind:
Les paramètres de `transactionSubscribe` restent runtime et n'appartiennent pas au profil endpoint Config.
### 7.12 Credentials
### 7.13 Credentials
L'api-key reste uniquement dans l'URL résolue :
@@ -854,35 +884,37 @@ validation finale fermée
prompt 0.2.9 prêt
```
## 13. Checkpoint `pre.002` / `pre.002-fix.001`
## 13. Checkpoint `pre.003`
Le socle `pre.002` est matériellement en place :
```text
WsProtocolKind::HeliusLaserStream -> helius_laserstream
SolanaStandardWsSession
HeliusLaserStreamWsSession
WsSession::connect historique standard-only
connect_for_protocol / connect_physical partagés
aucun second actor/socket/registry
aucun Config Helius / transactionSubscribe / heartbeat anticipé
```
Preuves opérateur déjà reçues pour `pre.002` :
Le checkpoint précédent est fermé par preuve opérateur :
```text
pre.002 + pre.002-fix.001
cargo fmt --all OK
python3 scripts/audit_rust_workspace_rules.py clean
cargo check --workspace OK
cargo clippy --workspace --all-targets FAIL ciblé : 5 implicit_return dans ws_protocol_session.rs
cargo clippy --workspace --all-targets OK
cargo test -p ksp-onchain-transport-lib OK
313 unit tests + 37 public API + 25 release completeness + 2 doctests compile_fail
cargo test --workspace OK
```
`pre.002-fix.001` corrige uniquement ce défaut Clippy dans la fixture, sans modifier le runtime protocolaire. Le fix réorganise aussi les deux documents actifs : le **plan** conserve décisions, audit, forecast et stratégie ; la **validation** conserve matrices, critères et preuves exécutées ; les détails de livraison restent dans les **deltas**.
`pre.003` prépare maintenant :
Après application du fix, le gate opérateur à rejouer est :
```text
HeliusLaserStreamWsSession::account_subscribe
HeliusLaserStreamWsSession::program_subscribe
HeliusLaserStreamWsSession::logs_subscribe
HeliusLaserStreamWsSession::signature_subscribe
HeliusLaserStreamWsSession::slot_subscribe
HeliusLaserStreamWsSession::root_subscribe
block / slotsUpdates / vote -> toujours absents de la façade Helius
transactionSubscribe -> toujours absent
moteur/actor -> inchangé et partagé
new dependency -> aucune
```
La validation locale disponible au moment de préparer l'overlay est l'audit Rust workspace, qui reste `clean`. Le checkpoint opérateur requis avant de déclarer `pre.003` `DONE` est :
```bash
cargo fmt --all
@@ -893,4 +925,4 @@ cargo test -p ksp-onchain-transport-lib
cargo test --workspace
```
Si ce checkpoint est vert, `pre.002` + `fix.001` peuvent être considérés `DONE` et `pre.003` ouvre les six familles standard supportées sur `HeliusLaserStreamWsSession`.
Si ce checkpoint est vert, `pre.004` ouvre uniquement Config V2 `helius_laserstream`, schema/fixtures, mapping Config -> Transport et stratégie de secret/redaction.