v0.2.9-pre.002
This commit is contained in:
259
deltas/0.2.9/pre.002.md
Normal file
259
deltas/0.2.9/pre.002.md
Normal file
@@ -0,0 +1,259 @@
|
||||
<!-- 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
|
||||
```
|
||||
Reference in New Issue
Block a user