5.8 KiB
Delta 0.2.7-pre.003 — std.transport V2 HTTP + WebSocket
1. Base requise
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 :
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 :
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 :
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 à :
urn:ksp:schema:std.transport:v2
Il conserve deux branches strictes discriminées par format_version :
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 :
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 :
http_settings()
ws_settings() -> Option<&WsTransportSettings>
into_transport_settings() -> (HttpTransportSettings, Option<WsTransportSettings>)
Le mapper V2 construit :
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 :
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 :
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 :
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
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
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 :
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 :
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
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 :
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.