v0.2.7-pre.009
This commit is contained in:
197
deltas/0.2.7/pre.009.md
Normal file
197
deltas/0.2.7/pre.009.md
Normal file
@@ -0,0 +1,197 @@
|
||||
<!-- file: deltas/0.2.7/pre.009.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Delta `0.2.7-pre.009` — wrappers WebSocket stables lot A
|
||||
|
||||
## Base
|
||||
|
||||
Base requise :
|
||||
|
||||
```text
|
||||
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
|
||||
|
||||
```text
|
||||
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 :
|
||||
|
||||
```text
|
||||
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 :
|
||||
|
||||
```text
|
||||
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 :
|
||||
|
||||
```text
|
||||
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 :
|
||||
|
||||
```text
|
||||
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 :
|
||||
|
||||
```text
|
||||
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 :
|
||||
|
||||
```text
|
||||
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 :
|
||||
|
||||
```text
|
||||
SolanaRpcResponse<SolanaLogsNotification>
|
||||
```
|
||||
|
||||
`SolanaLogsNotification` conserve :
|
||||
|
||||
```text
|
||||
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 :
|
||||
|
||||
```text
|
||||
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 :
|
||||
|
||||
```text
|
||||
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 :
|
||||
|
||||
```text
|
||||
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
|
||||
|
||||
```text
|
||||
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
|
||||
|
||||
```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 --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.
|
||||
Reference in New Issue
Block a user