7.5 KiB
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 :
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 :
0.2.9-pre.2
Commit attendu après validation opérateur :
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 :
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 :
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 :
YellowstoneGrpcEndpointUrl
YellowstoneGrpcProviderName
YellowstoneGrpcClusterName
YellowstoneGrpcReconnectSettings
YellowstoneGrpcSessionSettings
YellowstoneGrpcEndpointSettings
YellowstoneGrpcTransportSettings
Principes :
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() :
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 :
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 :
endpoint_name
provider
cluster
bornes numériques non sensibles
Aucune URL n'est loggée.
6. Canaries ajoutés
Unit tests Transport :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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
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