v0.2.9-pre.003
This commit is contained in:
@@ -1,9 +1,9 @@
|
||||
<!-- file: docs/plans/016-V0_2_9_YELLOWSTONE_GRPC_PLAN.md -->
|
||||
<!-- version: 7 -->
|
||||
<!-- version: 8 -->
|
||||
|
||||
# Plan `0.2.9` — moteur Yellowstone gRPC + standard Solana + PublicNode
|
||||
|
||||
> **Statut : `0.2.9-pre.002-fix.002` — second correctif du gate opérateur : `fix.001` est confirmé vert sur fmt/audit/check/Clippy et les 346 unit tests ; seul le canari d’intégration `public_api` appelait encore le channel lazy depuis un test synchrone. `fix.002` place ce canari sous runtime Tokio sans modifier N1 en production. Les tests Transport/workspace doivent être réexécutés avant commit. `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.003` — `pre.002-fix.002` est fermée sur gate opérateur intégralement vert (fmt/audit/check/Clippy, Transport 346 unit + 42 public API + 35 completeness + 4 doctests, dependency canary et workspace complet). `pre.003` ajoute uniquement TLS client, metadata générique redacted, connexion HTTP/2 réelle, fixture Geyser locale et les sept unary standard ; `Subscribe`, 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.**
|
||||
|
||||
## 1. Objet, base et état d'ouverture
|
||||
|
||||
@@ -298,19 +298,22 @@ https://docs.rs/crate/yellowstone-grpc-proto/latest
|
||||
|
||||
KSP suit la **Rust stable courante de l'opérateur** et ne documente pas de numéro Rust upstream comme objectif de projet. Le seul gate utile est opérationnel : les dépendances finalement retenues doivent compiler avec la stable courante utilisée par le workspace.
|
||||
|
||||
Résultat de matérialisation `pre.002` :
|
||||
Résultat après matérialisation `pre.003` :
|
||||
|
||||
```text
|
||||
yellowstone-grpc-proto ^12.6 workspace dependency, default-features = false, aucune feature KSP activée
|
||||
tonic ^0.14 workspace dependency, default-features = false ; Transport active seulement `channel`
|
||||
yellowstone-grpc-proto ^12.6 runtime : default-features = false, aucune feature `tonic`
|
||||
dev/test : feature `tonic` uniquement pour GeyserServer de fixture
|
||||
tonic ^0.14 runtime : channel + tls-aws-lc + tls-webpki-roots
|
||||
dev/test : codegen + server ajoutés explicitement
|
||||
http ^1.5 direct KSP pour PathAndQuery unary sans constructeur panic
|
||||
tonic-prost ^0.14 direct KSP pour ProstCodec ; sa dépendance Tonic désactive les defaults
|
||||
yellowstone-grpc-client absent
|
||||
prost/prost-types aucune dépendance KSP directe
|
||||
tonic-prost aucune dépendance KSP directe à ce stade
|
||||
proto crate publiée/générée ; aucun .proto copié dans KSP
|
||||
protoc aucun outil système KSP ajouté ; la crate proto publiée utilise son build vendored
|
||||
```
|
||||
|
||||
Le feature `tonic` optionnel de `yellowstone-grpc-proto` n'est **pas** activé en `pre.002`. KSP n'a besoin à ce stade que des messages Protobuf générés bruts ; le channel physique est construit directement avec Tonic. Cette décision évite de tirer prématurément la surface client/serveur Tonic générée et laisse `pre.003` choisir explicitement les features supplémentaires réellement nécessaires aux unary/TLS/metadata.
|
||||
La séparation reste intentionnelle : les messages Protobuf officiels sont consommés sans activer le client généré Yellowstone dans le runtime. La feature `tonic` du proto est réservée au graphe dev/test pour matérialiser le serveur Geyser de fixture. KSP utilise le dispatcher `tonic::client::Grpc` + `tonic-prost::ProstCodec` derrière sa façade N2 et conserve ainsi ses propres timeouts, redactions et erreurs.
|
||||
|
||||
Un minimum Rust déclaré par une dépendance n'est enregistré que s'il devient un **blocage réel** lors de la compilation ; il n'est pas suivi comme métrique de release.
|
||||
|
||||
@@ -535,19 +538,21 @@ Avantages :
|
||||
|
||||
**Décision : stratégie cible retenue.**
|
||||
|
||||
Matérialisation réalisée en `pre.002` :
|
||||
Matérialisation après `pre.003` :
|
||||
|
||||
```text
|
||||
yellowstone-grpc-proto ^12.6 root : default-features = false ; Transport : .workspace = true sans feature
|
||||
tonic ^0.14 root : default-features = false ; Transport : features = ["channel"]
|
||||
yellowstone-grpc-proto ^12.6 runtime sans feature ; dev/test feature `tonic` pour le serveur de fixture uniquement
|
||||
tonic ^0.14 runtime features = ["channel", "tls-aws-lc", "tls-webpki-roots"]
|
||||
dev/test ajoute ["codegen", "server"]
|
||||
tonic-prost ^0.14 runtime, ProstCodec bas niveau
|
||||
http ^1.5 runtime, PathAndQuery borné/interne
|
||||
yellowstone-grpc-client absent
|
||||
prost/prost-types pas de dépendance KSP directe
|
||||
tonic-prost pas de dépendance KSP directe en pre.002
|
||||
tokio-stream pas ajouté
|
||||
futures-util dépendance existante inchangée
|
||||
tokio-stream pas ajouté directement
|
||||
futures-util dépendance existante réutilisée par la fixture Stream
|
||||
```
|
||||
|
||||
Le choix est volontairement plus étroit que le forecast initial : `pre.002` matérialise les messages wire publiés et le channel HTTP/2 lazy, mais **pas encore le client RPC généré, TLS, metadata ou compression**. Les éventuelles features/dependencies supplémentaires doivent être justifiées par `pre.003` et vérifiées par `cargo tree`; elles ne sont pas activées par anticipation.
|
||||
`pre.003` n'active toujours ni client Yellowstone upstream ni compression. Les sept unary passent par une façade KSP au-dessus du channel N1 ; la surface `GeyserServer` générée n'existe que dans les tests pour prouver le wire exact localement. Le graphe Cargo doit être réinspecté après application parce que les features TLS et les deux dépendances directes `http`/`tonic-prost` changent le graphe runtime.
|
||||
|
||||
Le premier gate opérateur de `pre.002` confirme l'alignement de versions utile : Tonic 0.14.6 réutilise `http` 1.5, `hyper` 1.11, `hyper-util` 0.1, `tower` 0.5 et `bytes` 1.12 déjà présents ; `yellowstone-grpc-proto` unifie `solana-pubkey` en 4.3.0. Les occurrences Prost 0.14.4 visibles dans `cargo tree --duplicates` correspondent aux contextes runtime/build de la même version, notamment `prost-build`/`tonic-prost-build`, et ne constituent pas une seconde génération de version à corriger.
|
||||
|
||||
@@ -897,11 +902,11 @@ Prévision courante :
|
||||
pre.001 DONE — audit upstream/service/proto + providers gratuits + licences/deps + architecture + threat model + sizing
|
||||
budget : 15–20 min nominal ; preuve : plan + matrice + stratégie B + forecast recalibré
|
||||
|
||||
pre.002 FIX.002 CANDIDATE — moteur Yellowstone : proto/dependencies + settings/errors + channel minimal
|
||||
budget : 15–20 min ; second gate : fmt/audit/check/Clippy + 346 unit PASS ; public_api sync corrigé sous Tokio ; cargo tree inspecté
|
||||
pre.002 DONE — moteur Yellowstone : proto/dependencies + settings/errors + channel minimal
|
||||
budget : 15–20 min ; gate final fix.002 : fmt/audit/check/Clippy + Transport 346/42/35/4 + dependency canary + workspace PASS
|
||||
|
||||
pre.003 moteur Yellowstone : TLS/metadata générique + fixture locale + 7 unary RPCs
|
||||
budget : 15–20 min ; preuve : connect/TLS/timeouts/Status safe + wire unary exact
|
||||
pre.003 CANDIDATE — moteur TLS/metadata + façade N2 unary + fixture locale + 7 unary RPCs
|
||||
budget : 15–20 min ; preuve cible : connect/TLS/timeouts/Status safe + metadata redacted + wire unary exact + cargo tree
|
||||
|
||||
pre.004 standard Solana : Subscribe foundation + maps/commitment/ping/from_slot/data slices/bounds
|
||||
budget : 15–20 min ; preuve : omitted/empty/oneof exact + rejets avant I/O
|
||||
@@ -962,12 +967,17 @@ crates/ksp-onchain-transport-lib/src/grpc_channel.rs
|
||||
crates/ksp-onchain-transport-lib/unit_tests/grpc_settings.rs
|
||||
crates/ksp-onchain-transport-lib/unit_tests/grpc_channel.rs
|
||||
|
||||
# pre.003+
|
||||
# pre.003
|
||||
crates/ksp-onchain-transport-lib/src/grpc_unary.rs
|
||||
crates/ksp-onchain-transport-lib/unit_tests/grpc_unary.rs
|
||||
crates/ksp-onchain-transport-lib/src/grpc_channel.rs
|
||||
crates/ksp-onchain-transport-lib/src/grpc_settings.rs
|
||||
|
||||
# pre.004+
|
||||
crates/ksp-onchain-transport-lib/src/grpc_session.rs
|
||||
crates/ksp-onchain-transport-lib/src/grpc_protocol.rs
|
||||
crates/ksp-onchain-transport-lib/src/grpc_subscribe.rs
|
||||
crates/ksp-onchain-transport-lib/src/grpc_updates.rs
|
||||
crates/ksp-onchain-transport-lib/src/grpc_unary.rs
|
||||
unit_tests/ correspondants
|
||||
tests/public_api.rs
|
||||
tests/release_completeness.rs
|
||||
@@ -1008,6 +1018,7 @@ Après ajout/modification de la stack gRPC :
|
||||
|
||||
```bash
|
||||
cargo tree -p ksp-onchain-transport-lib
|
||||
cargo tree -p ksp-onchain-transport-lib -e features
|
||||
cargo tree -p ksp-onchain-transport-lib --duplicates
|
||||
cargo tree --duplicates
|
||||
```
|
||||
@@ -1021,9 +1032,43 @@ prost / prost-types
|
||||
bytes / http / hyper / hyper-util
|
||||
tower
|
||||
rustls / tokio-rustls
|
||||
features Tonic : channel/TLS runtime ; codegen/server dev ; pas de router/gzip/zstd KSP
|
||||
solana-* transitifs
|
||||
```
|
||||
|
||||
|
||||
## 19.1 Gate opérateur final `pre.002-fix.002`
|
||||
|
||||
Preuve opérateur du `2026-08-24` :
|
||||
|
||||
```text
|
||||
cargo fmt --all PASS
|
||||
python3 scripts/audit_rust_workspace_rules.py PASS / clean
|
||||
cargo check --workspace PASS
|
||||
cargo clippy --workspace --all-targets PASS
|
||||
Transport unit PASS 346/346
|
||||
Transport public_api PASS 42/42
|
||||
Transport release_completeness PASS 35/35
|
||||
Transport doctests PASS 4/4
|
||||
Core workspace_dependencies PASS 3/3
|
||||
cargo test --workspace PASS ; seuls smokes/bench diagnostics explicitement ignored
|
||||
```
|
||||
|
||||
`pre.002` est donc **fermée**. Les graphes Cargo fournis au premier gate restent valides pour son dependency set ; `pre.003` doit les relancer parce qu'elle active TLS et ajoute `http`/`tonic-prost`.
|
||||
|
||||
## 19.2 Gate source `pre.003`
|
||||
|
||||
La candidate matérialise :
|
||||
|
||||
```text
|
||||
N1 : connect() réel + TLS WebPKI/rustls + metadata ASCII publique/secrète redacted
|
||||
N2 : exactement 7 unary Yellowstone standard via dispatcher Tonic privé
|
||||
fixture : GeyserServer local dev-only, metadata + commitment + timeout + Status hostile
|
||||
OUT : Subscribe, SubscribeDeshred, PublicNode, Config V3, reconnect/stream lifecycle
|
||||
```
|
||||
|
||||
Le runtime n'active pas la feature `tonic` de `yellowstone-grpc-proto`; cette feature et `tonic codegen/server` sont réservées au graphe dev/test de la fixture. Le gate Cargo opérateur reste requis avant commit.
|
||||
|
||||
## 20. Conditions de clôture
|
||||
|
||||
`0.2.9` ne devient stable que si :
|
||||
|
||||
Reference in New Issue
Block a user