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

v0.2.9-pre.006

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-24 13:17:24 +02:00
parent 15e3402e1c
commit b32de48c0b
16 changed files with 1299 additions and 115 deletions
Download Patch File Download Diff File Expand all files Collapse all files

74
docs/plans/016-V0_2_9_YELLOWSTONE_GRPC_PLAN.md
View File

@@ -1,9 +1,9 @@
<!-- file: docs/plans/016-V0_2_9_YELLOWSTONE_GRPC_PLAN.md -->
<!-- version: 13 -->
<!-- version: 15 -->
# Plan `0.2.9` — moteur Yellowstone gRPC + standard Solana + PublicNode
> **Statut : `0.2.9-pre.004-fix.001` est fermée sur gate opérateur sans warning : fmt/audit/check/Clippy/workspace PASS, Transport 359 unit + 44 public API + 37 completeness + 4 doctests. `0.2.9-pre.005` est fonctionnellement verte sur le gate opérateur (364 unit + 45 public API + 38 completeness + workspace PASS) mais nécessite `pre.005-fix.001` pour supprimer quatre warnings `dead_code` test-only et deux diagnostics Clippy de forme dans `grpc_subscribe.rs`. Le fix ne change ni le contrat Accounts/Slots ni le wire. Transactions/Blocks, PublicNode et Config V3 restent hors tranche. `0.2.9` reste bornée à un moteur client Yellowstone partagé, une façade Solana Yellowstone standard et une première intégration concrète PublicNode. Seuls OrbitFlare puis Helius LaserStream gRPC sont actuellement planifiés comme releases provider suivantes ; les autres providers restent en TODO/IDEAS sans numéro réservé. Chaque prerelease vise 15–20 minutes de travail effectif et la release complète doit rester clôturable dans une seule session de chat.**
> **Statut : `0.2.9-pre.005-fix.001` est fermée sur gate opérateur intégralement vert et sans warning : fmt/audit/check/Clippy/workspace PASS, Transport 364 unit + 45 public API + 38 completeness + 4 doctests. `0.2.9-pre.006` est une tranche structurelle dédiée au nommage des modules privés : les cinq modules sans ambiguïté HTTP (`client`, `executor`, `pool`, `resilience`, `settings`) deviennent `http_*`, avec leurs unit tests miroirs. Les modules `rpc_*`, `json_rpc`, `constants` et `error` ne sont pas préfixés artificiellement car ils décrivent une couche/protocole partagé ou portent déjà des DTOs utilisés par WS/gRPC. Cette insertion décale l’ancien forecast fonctionnel `pre.006–011` vers `pre.007–012` sans changer son contenu. Aucun contrat public ni comportement runtime ne change.**
## 1. Objet, base et état d'ouverture
@@ -442,7 +442,7 @@ accounts_data_slice length <= 64 MiB
offset + length aucun overflow u64
```
Les bornes account/owner/include/exclude/required, memcmp et Cuckoo restent volontairement dans les tranches de famille `pre.005–007`.
Les bornes Accounts sont matérialisées en `pre.005`; les bornes include/exclude/required et Cuckoo propres aux Transactions/Blocks restent dans `pre.007–008`.
## 8. Matrice `SubscribeUpdate`
@@ -709,7 +709,7 @@ max logical filter groups/names
reconnect attempts/backoff
```
La forme JSON exacte et les bornes sont matérialisées en `pre.010`, mais **la décision V3 + `grpc_endpoints` séparés + metadata publique/secrète séparée est fermée par `pre.001`**.
La forme JSON exacte et les bornes sont matérialisées en `pre.011`, mais **la décision V3 + `grpc_endpoints` séparés + metadata publique/secrète séparée est fermée par `pre.001`**.
## 14. Audit fournisseurs gRPC gratuits et durables
@@ -822,7 +822,7 @@ OrbitFlare et Helius sont validés dans leurs releases dédiées. Les autres pro
Le smoke 1/2 peut vivre dans `ksp-onchain-transport-lib/tests` car il construit ses settings programmatiquement et ne teste que Transport.
Le smoke 3 ne doit pas être ajouté à `ksp-config-lib` par facilité. Si aucune surface d'intégration dédiée n'existe encore, il peut rester une procédure opérateur/documentée ou être placé sur une surface de composition déjà légitime ; le plan doit revalider l'owner au moment de `pre.010/pre.011`.
Le smoke 3 ne doit pas être ajouté à `ksp-config-lib` par facilité. Si aucune surface d'intégration dédiée n'existe encore, il peut rester une procédure opérateur/documentée ou être placé sur une surface de composition déjà légitime ; le plan doit revalider l'owner au moment de `pre.011/pre.012`.
Aucun secret provider n'est versionné.
@@ -922,31 +922,34 @@ pre.003 DONE — moteur TLS/metadata + façade N2 unary + fixture locale + 7 un
pre.004 DONE — standard Solana : Subscribe foundation + maps/commitment/ping/from_slot/data slices/bounds
budget : 15–20 min ; gate final fix.001 : fmt/audit/check/Clippy/workspace PASS sans warning + Transport 359/44/37/4
pre.005 CANDIDATE — standard Solana : Accounts + Slots filters/updates
budget : 15–20 min ; preuve : request wire complet + Cuckoo/memcmp/predicates + Account/Slot updates exacts/malformed/adversarial
pre.005 DONE — standard Solana : Accounts + Slots filters/updates
budget : 15–20 min ; gate final fix.001 : fmt/audit/check/Clippy/workspace PASS sans warning + Transport 364/45/38/4
pre.006 standard Solana : Transactions + transaction_status
pre.006 CANDIDATE — structure Transport : namespace privé HTTP explicite
budget : 15–20 min ; preuve : 5 modules + 5 unit tests renommés `http_*`, API publique inchangée, canari d'absence des anciens modules
pre.007 standard Solana : Transactions + transaction_status
budget : 15–20 min ; preuve : include/exclude/required/Cuckoo/token expansion + tx/meta
pre.007 standard Solana : Blocks + block_meta + entry
pre.008 standard Solana : Blocks + block_meta + entry
budget : 15–20 min ; preuve : counts/arrays/optional/oneof/payload bounds
pre.008 moteur partagé : bidi mutation + Ping/Pong + half-close + backpressure + shutdown
pre.009 moteur partagé : bidi mutation + Ping/Pong + half-close + backpressure + shutdown
budget : 15–20 min ; preuve : actor/session local + bounded queues + cleanup déterministe
pre.009 moteur partagé : reconnect/resubscribe + from_slot/ReplayInfo + gaps/duplicates
pre.010 moteur partagé : reconnect/resubscribe + from_slot/ReplayInfo + gaps/duplicates
budget : 15–20 min ; preuve : reconnect local déterministe + aucune promesse lossless
pre.010 Config V3 + séparation protocol/provider + profils PublicNode Mainnet/Testnet
pre.011 Config V3 + séparation protocol/provider + profils PublicNode Mainnet/Testnet
budget : 15–20 min ; preuve : V1/V2 backward + schema/mapping/redaction + Config -> Transport
pre.011 intégration PublicNode + smokes live + compliance + docs finales + prompt 0.2.10 OrbitFlare
pre.012 intégration PublicNode + smokes live + compliance + docs finales + prompt 0.2.10 OrbitFlare
budget : 15–20 min ; preuve : Mainnet/Testnet opt-in + HTTP 52/14 + WS 18/18 + Helius + cargo graphs + workspace final
rel.001 publication stable stricte
```
Prévision : **11 prereleases**, soit environ **165–220 minutes de travail effectif nominal hors temps d'attente des commandes**, compatible avec une session complète. Si une tranche réelle excède son budget ou si `pre.011` ne peut pas raisonnablement fermer la release dans la session, on scinde avant de poursuivre au lieu de prolonger artificiellement `0.2.9`.
Prévision : **12 prereleases**, soit environ **180–240 minutes de travail effectif nominal hors temps d'attente des commandes**, compatible avec une session complète. Si une tranche réelle excède son budget ou si `pre.012` ne peut pas raisonnablement fermer la release dans la session, on scinde avant de poursuivre au lieu de prolonger artificiellement `0.2.9`.
### Critères de split
@@ -1118,7 +1121,7 @@ Slot update : filters/created_at + slot + parent? + 7 SlotStatus + dead_error?
Les bornes provider-neutral KSP de cette tranche couvrent notamment les sélecteurs Accounts, predicates, memcmp, Cuckoo, taille account-data, noms de filtres d'update, timestamp nanos, signature fixe 64 octets et `dead_error`. Les Debug KSP n'exposent ni pubkeys sélectionnées, ni payload memcmp/Cuckoo/account-data, ni texte `dead_error`.
Les conversions protobuf et décodeurs update restent sous `#[cfg(test)]` jusqu'à `pre.008`, car aucun stream runtime ne les consomme encore. Cette décision évite du faux `dead_code` sans créer une seconde implémentation : les mêmes helpers seront remis en runtime au moment de l'ouverture bidi.
Les conversions protobuf et décodeurs update restent sous `#[cfg(test)]` jusqu'à `pre.009`, car aucun stream runtime ne les consomme encore. Cette décision évite du faux `dead_code` sans créer une seconde implémentation : les mêmes helpers seront remis en runtime au moment de l'ouverture bidi.
OUT de `pre.005` : Transactions/transaction_status, Blocks/block_meta/entry, stream bidi, provider PublicNode, Config V3 et `SubscribeDeshred`.
@@ -1176,13 +1179,40 @@ Pour toute intégration provider future, la règle reste : N1 n'est jamais dupli
Le premier gate opérateur de `pre.005` confirme la surface fonctionnelle : 364/364 unit, 45/45 public API, 38/38 release-completeness et workspace complet PASS. Les seuls écarts sont quatre constantes utilisées uniquement par les décodeurs `#[cfg(test)]`, une convention `to_wire(&self)` sur un type `Copy`, et une closure `is_some_and` soumise à `-D clippy::implicit-return`.
| Correction | Traitement | Impact runtime |
|-------------------------------------------|-------------------------------------------------|-------------------------|
| quatre constantes de bounds update | `#[cfg(test)]` | aucun avant `pre.008` |
| `YellowstoneSubscribeSlotFilter::to_wire` | receiver `self` | aucun, helper test-only |
| closure `dead_error.is_some_and` | `return` explicite | aucun |
| tableaux `016` et `012` | réalignement systématique des colonnes Markdown | documentaire uniquement |
| Correction | Traitement | Impact runtime |
|-------------------------------------------|----------------------------------------------------------------------|-------------------------|
| quatre constantes de bounds update | `#[cfg(test)]` | aucun avant `pre.009` |
| `YellowstoneSubscribeSlotFilter::to_wire` | receiver `self` | aucun, helper test-only |
| closure `dead_error.is_some_and` | `return` explicite | aucun |
| tableaux `016` et `012` | reformatage JetBrains RustRover (largeur max + un espace de padding) | documentaire uniquement |
Le réalignement documentaire conserve le contenu des cellules et ne modifie que les espaces de padding et les séparateurs de tableaux.
Le reformatage documentaire reproduit le comportement RustRover : largeur calculée sur le contenu le plus large de chaque colonne et exactement un espace de padding de chaque côté du contenu avant les pipes.
**Verdict `pre.005-fix.001` : correctif minimal prêt ; `pre.005` reste ouverte jusqu'à réexécution sans warning de check/Clippy/workspace.**
### 19.6 Gate final `pre.005-fix.001`
Le second gate opérateur confirme la fermeture complète de `pre.005` : fmt, audit Rust, check et Clippy passent sans warning ; Transport passe 364 unit + 45 public API + 38 release-completeness + 4 doctests ; le dependency canary Core passe 3/3 et `cargo test --workspace` est vert.
**Verdict : `pre.005` fermée.**
## 20. `pre.006` — namespace privé HTTP explicite
Le développement simultané de HTTP, WebSocket et Yellowstone gRPC rend les anciens noms privés `client`, `executor`, `pool`, `resilience` et `settings` trop ambigus. Ces cinq modules sont exclusivement propriétaires de la pile HTTP et deviennent donc :
```text
client.rs -> http_client.rs
executor.rs -> http_executor.rs
pool.rs -> http_pool.rs
resilience.rs -> http_resilience.rs
settings.rs -> http_settings.rs
```
Les unit tests miroirs reçoivent les mêmes noms. Le changement reste privé à la crate : les types publics sont déjà explicitement nommés `Http*` et leurs chemins au crate root ne changent pas.
Le mini-audit interdit un renommage aveugle des autres modules : `rpc_accounts`, `rpc_blocks`, `rpc_transactions` et `rpc_common` portent des DTOs/types déjà réutilisés par WebSocket et/ou gRPC ; `json_rpc` décrit le protocole d'enveloppe ; `constants` et `error` sont transverses. Ils conservent donc leur nom actuel.
Cette tranche est volontairement séparée de Transactions afin de respecter le budget 15–20 minutes et d'éviter de combiner un refactor de fichiers avec une nouvelle surface protobuf. L'ancien forecast fonctionnel `pre.006–011` est décalé vers `pre.007–012` sans changement de contenu.
**Gate candidat :** audit Rust clean, public API inchangée, cinq anciens modules absents après suppression opérateur, cinq nouveaux modules `http_*` compilés, release-completeness canary dédié, workspace complet vert.