6.2 KiB
Delta 0.2.7-pre.009 — wrappers WebSocket stables lot A
Base
Base requise :
0.2.7-pre.008-fix.001
workspace.package.version = 0.2.7-pre.8.fix.1
Le checkpoint opérateur de cette base est vert : cargo fmt --all, audit Python, cargo check --workspace, cargo clippy --workspace --all-targets, tests Transport et cargo test --workspace.
Signal de version
livraison = 0.2.7-pre.009
workspace.package.version = 0.2.7-pre.9
commit = v0.2.7-pre.009
tag = aucun
Objectif
Ouvrir les trois premiers wrappers WebSocket Solana standard publics sans exposer le moteur générique provider-extension :
accountSubscribe / accountUnsubscribe
programSubscribe / programUnsubscribe
logsSubscribe / logsUnsubscribe
L'unsubscribe reste porté par WsSubscription<T>::unsubscribe() et traduit l'identité locale stable vers l'ID serveur courant détenu par l'actor.
accountSubscribe
Nouvelle configuration dédiée :
SolanaAccountSubscribeConfig
encoding
data_slice
commitment
Les cinq encodings déjà acquis par Transport sont conservés : binary, base58, base64, jsonParsed, base64+zstd.
minContextSlot n'est pas exposé sur ce config WebSocket. Le type partagé upstream le possède, mais le handler PubSub Agave v4.2.1 l'ignore explicitement ; KSP ne transforme donc pas ce champ en promesse effective.
Retour typed :
WsSubscription<SolanaRpcResponse<SolanaAccount>>
Le DTO account et le contexte RPC sont réutilisés sans couche de décodage Program/SPL supplémentaire.
programSubscribe
Nouvelle configuration dédiée :
SolanaProgramSubscribeConfig
account: SolanaAccountSubscribeConfig
filters
with_context
Les filtres dataSize, memcmp et tokenAccountState sont conservés. Les bornes déterministes retenues par l'audit HTTP sont également appliquées à la surface WS : maximum quatre filtres et maximum 128 octets pour SolanaMemcmpBytes::Bytes.
withContext conserve les états omitted/false/true et son défaut upstream false. sortResults n'est pas exposé : cette option appartient à la surface HTTP getProgramAccounts et n'est pas consommée par le handler PubSub audité.
Le résultat est volontairement une union :
SolanaProgramNotification::Account(SolanaKeyedAccount)
SolanaProgramNotification::Context(SolanaRpcResponse<SolanaKeyedAccount>)
Le décodeur accepte donc la forme non contextée documentée et la forme contextée observée sans figer une hypothèse plus stricte que l'upstream.
logsSubscribe
Nouveau filtre public :
SolanaLogsSubscribeFilter::All
SolanaLogsSubscribeFilter::AllWithVotes
SolanaLogsSubscribeFilter::Mentions(Pubkey)
La forme Mentions(Pubkey) encode par construction exactement une adresse, conformément à la contrainte upstream actuelle.
Le commitment réutilise SolanaCommitmentConfig. La notification typed est :
SolanaRpcResponse<SolanaLogsNotification>
SolanaLogsNotification conserve :
signature : String opaque
err : null ou valeur JSON TransactionError
logs : Vec<String> ordonné
Aucune interprétation locale des erreurs transactionnelles ou des messages de log n'est ajoutée à Transport.
Moteur et lifecycle
Les trois wrappers utilisent exclusivement WsSession::subscribe_typed, qui reste pub(crate). Les acquisitions précédentes restent communes :
IDs locaux stables
remote IDs internes
ACK/register atomique
reconnect fini
resubscribe déterministe
continuity_gap_count
backpressure par subscription
overflow_count
terminal_error_code
cleanup distant best-effort
Les paramètres typed sérialisés sont conservés par l'actor et rejoués à l'identique après reconnect avec ActiveSubscriptions.
Tests déterministes ajoutés
Sept tests unitaires supplémentaires couvrent :
account config exact + absence minContextSlot
program config filters/withContext + bornes déterministes
program notification contextée et non contextée
account + program end-to-end sur serveur WS local + unsubscribe exact
logs filters all/allWithVotes/mentions
logs notification context/signature/err/logs + err requis
logs end-to-end sur serveur WS local + unsubscribe exact
Un canari d'API publique supplémentaire vérifie l'adresse des trois méthodes et des nouveaux DTOs depuis la racine de crate.
Comptages attendus après compilation :
Transport unit tests = 294
Transport public API tests = 33
release completeness = 22
Sécurité / observabilité
Aucun wrapper ne journalise les paramètres, pubkeys, logs de transaction ou payloads de notification. Les URL et remote subscription IDs restent absents des DTOs et snapshots publics.
SolanaLogsNotification rend le payload disponible au consumer par API typed, mais il n'est jamais utilisé comme metadata de tracing interne.
Fichiers ajoutés ou modifiés
Cargo.toml
crates/ksp-onchain-transport-lib/README.md
crates/ksp-onchain-transport-lib/USAGE.md
crates/ksp-onchain-transport-lib/src/lib.rs
crates/ksp-onchain-transport-lib/src/rpc_accounts.rs
crates/ksp-onchain-transport-lib/src/rpc_common.rs
crates/ksp-onchain-transport-lib/src/ws_accounts.rs
crates/ksp-onchain-transport-lib/src/ws_session.rs
crates/ksp-onchain-transport-lib/src/ws_transactions.rs
crates/ksp-onchain-transport-lib/tests/public_api.rs
crates/ksp-onchain-transport-lib/unit_tests/ws_accounts.rs
crates/ksp-onchain-transport-lib/unit_tests/ws_transactions.rs
docs/plans/014-V0_2_7_ONCHAIN_WEBSOCKET_PLAN.md
docs/validation/010-V0_2_7_ONCHAIN_WEBSOCKET.md
deltas/0.2.7/pre.009.md
ROADMAP.md et CHANGELOG.md restent inchangés pendant cette tranche.
Validation opérateur requise
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 --workspace
Tranche suivante
Si ce checkpoint est vert, 0.2.7-pre.010 ouvre le lot stable B : signatureSubscribe, slotSubscribe et rootSubscribe, avec terminaison one-shot de signature et compliance KSP-TRANSPORT-007 associée.