v0.2.7-pre.003
This commit is contained in:
225
deltas/0.2.7/pre.003.md
Normal file
225
deltas/0.2.7/pre.003.md
Normal file
@@ -0,0 +1,225 @@
|
||||
<!-- file: deltas/0.2.7/pre.003.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Delta `0.2.7-pre.003` — `std.transport` V2 HTTP + WebSocket
|
||||
|
||||
## 1. Base requise
|
||||
|
||||
```text
|
||||
0.2.7-pre.002-fix.001 appliquée
|
||||
workspace.package.version = 0.2.7-pre.2.fix.1
|
||||
```
|
||||
|
||||
Le checkpoint opérateur reçu avant cette tranche est entièrement vert : `cargo fmt`, audit Python, `cargo check --workspace`, `cargo clippy --workspace --all-targets`, tests Transport ciblés et `cargo test --workspace`.
|
||||
|
||||
## 2. Signal technique
|
||||
|
||||
Cette prerelease non-fix modifie configuration exécutable, Rust et tests. Conformément à `VER-ID-009` :
|
||||
|
||||
```text
|
||||
livraison = 0.2.7-pre.003
|
||||
workspace.package.version = 0.2.7-pre.3
|
||||
commit = v0.2.7-pre.003
|
||||
```
|
||||
|
||||
Aucun tag prerelease.
|
||||
|
||||
## 3. `std.transport` V2
|
||||
|
||||
Le document standard livré devient :
|
||||
|
||||
```text
|
||||
format_version = 2
|
||||
retry
|
||||
ws_defaults
|
||||
default_profile
|
||||
profiles[]
|
||||
profile_id
|
||||
endpoints[]
|
||||
ws_endpoints[]
|
||||
kind
|
||||
session?
|
||||
```
|
||||
|
||||
Le HTTP existant reste inchangé dans `endpoints[]`. `ws_defaults` contient les defaults génériques de `WsSessionSettings`; `ws_endpoints[].session` peut surcharger seulement les paramètres génériques nécessaires à un endpoint.
|
||||
|
||||
Le discriminateur est obligatoire :
|
||||
|
||||
```text
|
||||
kind = solana_standard
|
||||
```
|
||||
|
||||
Toute autre famille est rejetée en `0.2.7`. Aucun paramètre Helius, LaserStream ou autre provider-specific n'est pré-implémenté.
|
||||
|
||||
## 4. Backward V1 strict
|
||||
|
||||
Le schema enregistré passe à :
|
||||
|
||||
```text
|
||||
urn:ksp:schema:std.transport:v2
|
||||
```
|
||||
|
||||
Il conserve deux branches strictes discriminées par `format_version` :
|
||||
|
||||
```text
|
||||
V1 -> HTTP-only historique
|
||||
V2 -> HTTP + ws_defaults + ws_endpoints
|
||||
```
|
||||
|
||||
Le V1 n'est pas rendu compatible par un relâchement de `additionalProperties`. Une fixture V1 dédiée prouve le chemin historique.
|
||||
|
||||
Dans l'adapter :
|
||||
|
||||
```text
|
||||
V1 -> HttpTransportSettings + ws_settings = None
|
||||
V2 -> HttpTransportSettings + Some(WsTransportSettings)
|
||||
```
|
||||
|
||||
`WsTransportSettings` conserve donc son invariant `pre.002` : il n'existe jamais comme faux conteneur vide.
|
||||
|
||||
## 5. Adapter Config -> Transport
|
||||
|
||||
`ResolvedTransportConfig` conserve `settings()` pour compatibilité HTTP et ajoute :
|
||||
|
||||
```text
|
||||
http_settings()
|
||||
ws_settings() -> Option<&WsTransportSettings>
|
||||
into_transport_settings() -> (HttpTransportSettings, Option<WsTransportSettings>)
|
||||
```
|
||||
|
||||
Le mapper V2 construit :
|
||||
|
||||
```text
|
||||
WsProviderName
|
||||
WsClusterName
|
||||
WsProtocolKind::SolanaStandard
|
||||
WsEndpointUrl
|
||||
WsReconnectSettings
|
||||
WsResubscribePolicy
|
||||
WsSessionSettings
|
||||
WsEndpointSettings
|
||||
WsTransportSettings
|
||||
```
|
||||
|
||||
La direction reste strictement `Config -> Transport`. Aucun import de Config n'est ajouté à `ksp-onchain-transport-lib`.
|
||||
|
||||
## 6. Overrides session
|
||||
|
||||
Les valeurs de `ws_defaults` correspondent aux defaults KSP matérialisés en `pre.002`. Un endpoint peut surcharger indépendamment :
|
||||
|
||||
```text
|
||||
command_timeout_ms
|
||||
close_timeout_ms
|
||||
reconnect.{max_retries, initial_backoff_ms, max_backoff_ms}
|
||||
resubscribe
|
||||
command_queue_capacity
|
||||
notification_queue_capacity
|
||||
max_active_subscriptions
|
||||
max_pending_requests
|
||||
max_message_size_bytes
|
||||
max_frame_size_bytes
|
||||
max_write_buffer_size_bytes
|
||||
```
|
||||
|
||||
La session résultante est toujours validée par `WsSessionSettings::validate()`.
|
||||
|
||||
## 7. Secrets et logging
|
||||
|
||||
Les URLs HTTP et WebSocket peuvent provenir de `KSP_SECRET_*`; les valeurs réelles restent disponibles au runtime mais la projection Config safe les redacted. Les erreurs d'adaptation ne recopient pas l'URL.
|
||||
|
||||
Le mapping Config utilise exclusivement `ksp-logging-lib` avec le `TRACING_TARGET` existant de `ksp-config-lib` :
|
||||
|
||||
```text
|
||||
trace -> début mapping et chemin backward V1
|
||||
debug -> version, compteurs HTTP/WS après validation
|
||||
```
|
||||
|
||||
Aucun `tracing` direct n'est ajouté.
|
||||
|
||||
## 8. Environment inventory
|
||||
|
||||
Ajouts `.env.example` :
|
||||
|
||||
```text
|
||||
KSP_PUBLIC_SOLANA_DEVNET_WS_URL
|
||||
KSP_PUBLIC_SOLANA_MAINNET_WS_URL
|
||||
# KSP_SECRET_SOLANA_WS_URL
|
||||
```
|
||||
|
||||
Les URLs provider privées restent des valeurs complètes gérées via `KSP_SECRET_*`.
|
||||
|
||||
## 9. Tests ajoutés/étendus
|
||||
|
||||
```text
|
||||
V2 fixture HTTP + WS complète
|
||||
ws_defaults + endpoint overrides
|
||||
V1 strict toujours chargeable
|
||||
V1 n'invente pas de WsTransportSettings vide
|
||||
committed Devnet/Mainnet V2 mappe HTTP + WS
|
||||
provenance ws_defaults globale et ws_endpoints profil
|
||||
secret WebSocket URL disponible au runtime mais redacted en safe/Debug
|
||||
public API canary pour les nouveaux accessors
|
||||
```
|
||||
|
||||
## 10. Fichiers principaux modifiés
|
||||
|
||||
```text
|
||||
Cargo.toml
|
||||
.env.example
|
||||
config/std.transport.json
|
||||
config/examples/std.transport.example.json
|
||||
config/schemas/std.transport.schema.json
|
||||
crates/ksp-config-lib/src/transport.rs
|
||||
crates/ksp-config-lib/src/lib.rs
|
||||
crates/ksp-config-lib/src/registry.rs
|
||||
crates/ksp-config-lib/unit_tests/transport.rs
|
||||
crates/ksp-config-lib/unit_tests/fixtures/std.transport.json
|
||||
crates/ksp-config-lib/tests/public_api.rs
|
||||
crates/ksp-config-lib/README.md
|
||||
crates/ksp-config-lib/USAGE.md
|
||||
docs/plans/014-V0_2_7_ONCHAIN_WEBSOCKET_PLAN.md
|
||||
docs/validation/010-V0_2_7_ONCHAIN_WEBSOCKET.md
|
||||
```
|
||||
|
||||
Nouveau :
|
||||
|
||||
```text
|
||||
crates/ksp-config-lib/unit_tests/fixtures_v1/std.transport.json
|
||||
deltas/0.2.7/pre.003.md
|
||||
```
|
||||
|
||||
Aucune dépendance externe n'est ajoutée.
|
||||
|
||||
## 11. Validation de préparation
|
||||
|
||||
Le sandbox de génération ne fournit pas Cargo. Sont exécutés ici :
|
||||
|
||||
```text
|
||||
python3 scripts/audit_rust_workspace_rules.py
|
||||
validation JSON des documents/schema
|
||||
inspection absence de tracing direct
|
||||
inspection version workspace
|
||||
inspection archive delta
|
||||
```
|
||||
|
||||
Les gates compilés restent opérateur-only.
|
||||
|
||||
## 12. Gates opérateur avant commit
|
||||
|
||||
```bash
|
||||
cargo fmt --all
|
||||
python3 scripts/audit_rust_workspace_rules.py
|
||||
cargo check --workspace
|
||||
cargo clippy --workspace --all-targets
|
||||
cargo test -p ksp-config-lib
|
||||
cargo test -p ksp-onchain-transport-lib
|
||||
cargo test --workspace
|
||||
```
|
||||
|
||||
Si le checkpoint est vert :
|
||||
|
||||
```text
|
||||
commit = v0.2.7-pre.003
|
||||
```
|
||||
|
||||
La tranche suivante est `0.2.7-pre.004` : dépendances WebSocket, actor physique, handshake/read/write, pending JSON-RPC et serveur local déterministe.
|
||||
Reference in New Issue
Block a user