260 lines
7.5 KiB
Markdown
260 lines
7.5 KiB
Markdown
<!-- file: deltas/0.2.9/pre.002.md -->
|
||
<!-- version: 1 -->
|
||
|
||
# Delta `0.2.9-pre.002` — moteur Yellowstone : dépendances + settings/errors + channel minimal
|
||
|
||
## 1. Objet
|
||
|
||
Cette tranche matérialise uniquement la première fondation **N1 moteur Yellowstone gRPC** validée par `pre.001` :
|
||
|
||
```text
|
||
proto Yellowstone publié
|
||
+ dépendances Tonic minimales
|
||
+ settings runtime bornés/redacted
|
||
+ error code initial gRPC
|
||
+ channel Tonic lazy privé
|
||
```
|
||
|
||
Elle ne commence pas encore N2 fonctionnel : aucun unary Yellowstone, aucune metadata/auth, aucune fixture serveur gRPC, aucun `Subscribe`, aucun lifecycle bidi et aucune intégration PublicNode ne sont introduits ici.
|
||
|
||
Version workspace :
|
||
|
||
```text
|
||
0.2.9-pre.2
|
||
```
|
||
|
||
Commit attendu après validation opérateur :
|
||
|
||
```text
|
||
v0.2.9-pre.002
|
||
```
|
||
|
||
## 2. Dépendances matérialisées
|
||
|
||
Stratégie B conservée, mais avec le feature set le plus étroit utile à cette tranche :
|
||
|
||
```text
|
||
workspace root:
|
||
tonic = ^0.14, default-features = false
|
||
yellowstone-grpc-proto = ^12.6, default-features = false
|
||
|
||
ksp-onchain-transport-lib:
|
||
tonic workspace = true, features = ["channel"]
|
||
yellowstone-grpc-proto workspace = true, aucune feature locale
|
||
```
|
||
|
||
Explicitement absents :
|
||
|
||
```text
|
||
yellowstone-grpc-client
|
||
tonic-prost direct KSP
|
||
prost direct KSP
|
||
prost-types direct KSP
|
||
tokio-stream nouveau
|
||
feature tonic du proto
|
||
feature tonic-compression du proto
|
||
TLS Tonic
|
||
```
|
||
|
||
La crate publiée `yellowstone-grpc-proto` fournit les messages Protobuf générés utiles sans que KSP copie les `.proto`. Son build utilise son outillage `protoc` vendored ; aucun `protoc` système ni `build.rs` KSP n'est ajouté.
|
||
|
||
Le feature optionnel `tonic` de la crate proto n'est pas activé en `pre.002` : le moteur ne consomme encore aucun client RPC généré. `pre.003` devra justifier explicitement toute feature/dependency supplémentaire nécessaire aux unary, TLS et metadata.
|
||
|
||
## 3. Settings Yellowstone N1
|
||
|
||
Ajout de `grpc_settings.rs` avec les contrats publics crate-root :
|
||
|
||
```text
|
||
YellowstoneGrpcEndpointUrl
|
||
YellowstoneGrpcProviderName
|
||
YellowstoneGrpcClusterName
|
||
YellowstoneGrpcReconnectSettings
|
||
YellowstoneGrpcSessionSettings
|
||
YellowstoneGrpcEndpointSettings
|
||
YellowstoneGrpcTransportSettings
|
||
```
|
||
|
||
Principes :
|
||
|
||
```text
|
||
Transport-owned
|
||
aucun Config/env
|
||
aucun WsProtocolKind/WsEndpointSettings
|
||
URL http/https distincte de HTTP/WS et Debug redacted
|
||
provider/cluster = descripteurs ouverts, pas des enums commerciaux fermés
|
||
URL/descripteurs/nombre d’endpoints bornés
|
||
connect/unary/close timeouts bornés
|
||
reconnect attempts/backoff bornés
|
||
request/update channel capacities bornées
|
||
max inbound/outbound message sizes bornées
|
||
au moins un endpoint configuré et enabled
|
||
endpoint names uniques
|
||
```
|
||
|
||
Les defaults servent uniquement de runtime defaults N1 ; ils ne deviennent pas des quotas provider.
|
||
|
||
## 4. Channel minimal
|
||
|
||
Ajout de `YellowstoneGrpcChannel` dans `grpc_channel.rs`.
|
||
|
||
`prepare()` :
|
||
|
||
```text
|
||
valide les settings avant I/O
|
||
refuse un endpoint disabled
|
||
construit tonic::transport::Endpoint depuis l'URL sensible
|
||
applique connect timeout / unary timeout / request buffer
|
||
utilise connect_lazy()
|
||
ne réalise aucune connexion réseau
|
||
ne configure encore ni TLS ni metadata
|
||
ne recopie pas les erreurs URI Tonic arbitraires dans KspError
|
||
```
|
||
|
||
Le `tonic::transport::Channel` réel est un champ privé et n'a aucun getter public. `Debug` n'expose ni URL, ni channel brut, ni credential potentiel.
|
||
|
||
Cette surface ne constitue pas encore `YellowstoneGrpcSession` : elle prépare seulement la ressource physique minimale qui sera utilisée par `pre.003+`.
|
||
|
||
## 5. Erreurs et observabilité
|
||
|
||
Nouveau code :
|
||
|
||
```text
|
||
onchain_transport/grpc_channel_failed
|
||
```
|
||
|
||
Les erreurs de préparation conservent uniquement des contexts allowlistés sûrs (`endpoint_name`) et n'injectent pas le message d'erreur Tonic/URI dans le contrat KSP.
|
||
|
||
Les logs passent exclusivement par `ksp-logging-lib` et n'émettent que :
|
||
|
||
```text
|
||
endpoint_name
|
||
provider
|
||
cluster
|
||
bornes numériques non sensibles
|
||
```
|
||
|
||
Aucune URL n'est loggée.
|
||
|
||
## 6. Canaries ajoutés
|
||
|
||
Unit tests Transport :
|
||
|
||
```text
|
||
gRPC URL http/https + Debug redacted
|
||
gRPC URL non-http ou surdimensionnée rejetée sans secret echo
|
||
descripteurs et endpoint inventory plafonnés
|
||
defaults session bornés
|
||
zero/excessive/reversed runtime settings rejetés
|
||
endpoint inventory unique/enabled
|
||
channel lazy préparé sans réseau
|
||
channel Debug sans URL/secret
|
||
endpoint disabled rejeté avant I/O
|
||
raw proto disponible uniquement côté interne/test
|
||
```
|
||
|
||
Public API :
|
||
|
||
```text
|
||
settings N1 constructibles depuis crate root
|
||
YellowstoneGrpcChannel constructible sans Config
|
||
nouvel error code public KSP
|
||
aucun raw client Tonic requis par le consumer
|
||
```
|
||
|
||
Release completeness / workspace dependency canaries :
|
||
|
||
```text
|
||
dépendances root/member exactes
|
||
yellowstone-grpc-client absent
|
||
Transport -X-> Config
|
||
aucun couplage Ws*
|
||
aucun pub use tonic/yellowstone_grpc_proto
|
||
channel = from_shared + connect_lazy
|
||
TLS/metadata explicitement absents de pre.002
|
||
```
|
||
|
||
## 7. Documentation
|
||
|
||
Les versions opérateur alignées de :
|
||
|
||
```text
|
||
docs/plans/016-V0_2_9_YELLOWSTONE_GRPC_PLAN.md
|
||
docs/validation/012-V0_2_9_YELLOWSTONE_GRPC.md
|
||
```
|
||
|
||
sont conservées comme base de mise en forme et avancées pour enregistrer :
|
||
|
||
```text
|
||
feature set réellement matérialisé
|
||
séparation stricte pre.002 / pre.003
|
||
surface N1 réellement ouverte
|
||
état des canaries
|
||
Cargo gates encore opérateur
|
||
```
|
||
|
||
Le forecast reste inchangé en nombre de tranches : `pre.003` porte toujours TLS/metadata + fixture locale + 7 unary.
|
||
|
||
## 8. Validation exécutée dans l'environnement de préparation
|
||
|
||
Exécuté réellement :
|
||
|
||
```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
|
||
```
|
||
|
||
L'environnement de préparation ne possède pas Cargo/Rust. Les commandes Cargo ci-dessous ne sont donc **pas déclarées réussies**.
|
||
|
||
## 9. Gate opérateur requis 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
|
||
cargo test -p ksp-core-lib --test workspace_dependencies
|
||
cargo test --workspace
|
||
cargo tree -p ksp-onchain-transport-lib
|
||
cargo tree -p ksp-onchain-transport-lib --duplicates
|
||
cargo tree --duplicates
|
||
```
|
||
|
||
Inspecter particulièrement :
|
||
|
||
```text
|
||
yellowstone-grpc-proto 12.6.x réellement résolu
|
||
tonic 0.14.x réellement résolu
|
||
prost / prost-types / tonic-prost transitifs
|
||
bytes / http / hyper / hyper-util / tower
|
||
rustls / tokio-rustls
|
||
solana-pubkey unifié ou doublons justifiés
|
||
aucune arrivée de yellowstone-grpc-client
|
||
features Tonic réellement activées
|
||
```
|
||
|
||
Si la compilation démontre que `yellowstone-grpc-proto` sans feature `tonic` ou Tonic `channel` ne suffit pas à la tranche actuelle, ne pas élargir silencieusement : produire un `pre.002-fix.001` avec la dépendance minimale démontrée.
|
||
|
||
## 10. Fichiers ajoutés/modifiés
|
||
|
||
```text
|
||
Cargo.toml
|
||
crates/ksp-core-lib/tests/workspace_dependencies.rs
|
||
crates/ksp-onchain-transport-lib/Cargo.toml
|
||
crates/ksp-onchain-transport-lib/src/error.rs
|
||
crates/ksp-onchain-transport-lib/src/grpc_channel.rs
|
||
crates/ksp-onchain-transport-lib/src/grpc_settings.rs
|
||
crates/ksp-onchain-transport-lib/src/lib.rs
|
||
crates/ksp-onchain-transport-lib/tests/public_api.rs
|
||
crates/ksp-onchain-transport-lib/tests/release_completeness.rs
|
||
crates/ksp-onchain-transport-lib/unit_tests/grpc_channel.rs
|
||
crates/ksp-onchain-transport-lib/unit_tests/grpc_settings.rs
|
||
docs/plans/016-V0_2_9_YELLOWSTONE_GRPC_PLAN.md
|
||
docs/validation/012-V0_2_9_YELLOWSTONE_GRPC.md
|
||
deltas/0.2.9/pre.002.md
|
||
```
|