264 lines
6.9 KiB
Markdown
264 lines
6.9 KiB
Markdown
<!-- file: deltas/0.2.7/pre.002.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# Delta `0.2.7-pre.002` — WebSocket settings + lifecycle contracts
|
|
|
|
## 1. Objet
|
|
|
|
Cette tranche matérialise la première surface Rust WebSocket de `ksp-onchain-transport-lib` sans ouvrir encore de socket physique et sans ajouter de dépendance WebSocket externe.
|
|
|
|
Version workspace :
|
|
|
|
```text
|
|
0.2.7-pre.2
|
|
```
|
|
|
|
Livraison :
|
|
|
|
```text
|
|
0.2.7-pre.002
|
|
```
|
|
|
|
Commit attendu :
|
|
|
|
```text
|
|
v0.2.7-pre.002
|
|
```
|
|
|
|
Aucun tag prerelease.
|
|
|
|
## 2. Surface Transport ajoutée
|
|
|
|
Settings publics :
|
|
|
|
```text
|
|
WsEndpointUrl
|
|
WsProviderName
|
|
WsClusterName
|
|
WsProtocolKind
|
|
WsReconnectSettings
|
|
WsResubscribePolicy
|
|
WsSessionSettings
|
|
WsEndpointSettings
|
|
WsTransportSettings
|
|
```
|
|
|
|
Lifecycle public :
|
|
|
|
```text
|
|
WsSessionId
|
|
WsSubscriptionId
|
|
WsSessionState
|
|
WsSubscriptionState
|
|
WsSubscriptionKind
|
|
WsSessionSnapshot
|
|
WsSubscriptionSnapshot
|
|
```
|
|
|
|
`WsProtocolKind` est `#[non_exhaustive]` et ne fournit pour `0.2.7` que `SolanaStandard`. Cette forme prépare l'ajout futur d'une famille provider-specific telle que Helius Enhanced WebSocket sans ajouter de paramètres Helius dans les settings Solana standard.
|
|
|
|
Les IDs locaux reposent sur `NonZeroU64`. Aucun ID serveur WebSocket n'entre dans le contrat public de contrôle.
|
|
|
|
## 3. URL et secrets
|
|
|
|
`WsEndpointUrl` :
|
|
|
|
- accepte uniquement `ws://` et `wss://` ;
|
|
- exige un host ;
|
|
- conserve la valeur sensible uniquement pour le futur code de connexion ;
|
|
- rend `WsEndpointUrl(<redacted>)` en `Debug` ;
|
|
- ne copie pas la valeur URL dans les erreurs de validation.
|
|
|
|
`WsEndpointSettings` et `WsTransportSettings` peuvent conserver `Debug` dérivé car le sous-type URL est lui-même redacted.
|
|
|
|
Les snapshots ne contiennent jamais :
|
|
|
|
```text
|
|
URL complète
|
|
credential/query token
|
|
request body
|
|
raw notification
|
|
remote subscription id
|
|
```
|
|
|
|
## 4. Settings session bornés
|
|
|
|
Defaults initiaux Transport, explicitement policies KSP locales :
|
|
|
|
```text
|
|
command timeout 10 s
|
|
close timeout 5 s
|
|
reconnect retries 5
|
|
reconnect initial backoff 250 ms
|
|
reconnect maximum backoff 5 s
|
|
command queue 128
|
|
notification queue per sub 256
|
|
active subscriptions 1024
|
|
pending JSON-RPC requests 128
|
|
maximum message 64 MiB
|
|
maximum frame 16 MiB
|
|
maximum write buffer 1 MiB
|
|
resubscribe default ActiveSubscriptions
|
|
```
|
|
|
|
Ces valeurs ne sont pas présentées comme des limites Solana. `pre.004`/`pre.005` devront les appliquer réellement à l'actor/socket et pourront les recalibrer si les fixtures adversariales le justifient.
|
|
|
|
Validation structurelle :
|
|
|
|
- timeouts non nuls ;
|
|
- reconnect backoff non nul et ordonné ;
|
|
- capacités/limites strictement positives ;
|
|
- au moins un endpoint WS configuré et enabled ;
|
|
- noms endpoint uniques ;
|
|
- name/provider/cluster non vides et sans whitespace de bord.
|
|
|
|
## 5. Lifecycle et snapshots
|
|
|
|
États session matérialisés :
|
|
|
|
```text
|
|
Disconnected
|
|
Connecting
|
|
Active
|
|
Reconnecting { attempt }
|
|
Closing
|
|
Closed
|
|
Failed
|
|
```
|
|
|
|
États subscription matérialisés :
|
|
|
|
```text
|
|
Requested
|
|
Active
|
|
Resubscribing
|
|
Cancelling
|
|
Closed
|
|
Failed
|
|
```
|
|
|
|
`WsSubscriptionKind` couvre les neuf familles standard auditées : account, block, logs, program, root, signature, slot, slotsUpdates et vote.
|
|
|
|
`WsSessionSnapshot` expose uniquement des metadata sûres : local session ID, endpoint logical name, provider, cluster, protocol, state, pending request count, continuity gap count, overflow count et projections de subscriptions.
|
|
|
|
`WsSubscriptionSnapshot` expose local subscription ID, kind, state et `remote_bound`; l'ID distant reste interne et remappable.
|
|
|
|
Les constructeurs de snapshots sont crate-internal : les consumers ne peuvent pas fabriquer de faux états runtime.
|
|
|
|
## 6. Logging et tracing
|
|
|
|
La constante existante reste l'autorité crate-wide :
|
|
|
|
```rust
|
|
TRACING_TARGET = "ksp-onchain-transport-lib"
|
|
```
|
|
|
|
Elle est définie dans `crates/ksp-onchain-transport-lib/src/constants.rs`.
|
|
|
|
Toute nouvelle émission passe par `ksp-logging-lib` :
|
|
|
|
- `trace` pour entrée/succès de validations et metadata endpoint sûres ;
|
|
- `debug` pour settings validés, compteurs et bornes ;
|
|
- `warn` pour rejets de settings/URL ;
|
|
- aucun `error` artificiel pour une erreur de validation caller.
|
|
|
|
Aucun appel direct à `tracing` n'est ajouté. Les logs n'incluent jamais la valeur de `WsEndpointUrl`.
|
|
|
|
## 7. Tests ajoutés
|
|
|
|
Tests unitaires settings :
|
|
|
|
```text
|
|
ws/wss acceptés
|
|
HTTP rejeté
|
|
Debug URL redacted
|
|
erreur de scheme sans secret
|
|
protocol kind standard
|
|
settings defaults bornés
|
|
zero bound rejeté
|
|
reconnect backoff inversé rejeté
|
|
transport endpoints valides
|
|
endpoint names dupliqués rejetés
|
|
au moins un endpoint enabled
|
|
Debug transport sans URL/credential
|
|
```
|
|
|
|
Tests unitaires lifecycle :
|
|
|
|
```text
|
|
IDs locaux non-zéro et ordonnables
|
|
états reconnect/resubscribe/cancelling distincts
|
|
9 familles standard couvertes
|
|
snapshot sans URL ni remote subscription id
|
|
```
|
|
|
|
Un canari `tests/public_api.rs` vérifie l'accès crate-root aux nouveaux contrats.
|
|
|
|
## 8. Fichiers principaux
|
|
|
|
Nouveaux :
|
|
|
|
```text
|
|
crates/ksp-onchain-transport-lib/src/ws_settings.rs
|
|
crates/ksp-onchain-transport-lib/src/ws_lifecycle.rs
|
|
crates/ksp-onchain-transport-lib/unit_tests/ws_settings.rs
|
|
crates/ksp-onchain-transport-lib/unit_tests/ws_lifecycle.rs
|
|
deltas/0.2.7/pre.002.md
|
|
```
|
|
|
|
Modifiés :
|
|
|
|
```text
|
|
Cargo.toml
|
|
crates/ksp-onchain-transport-lib/src/constants.rs
|
|
crates/ksp-onchain-transport-lib/src/lib.rs
|
|
crates/ksp-onchain-transport-lib/tests/public_api.rs
|
|
docs/plans/014-V0_2_7_ONCHAIN_WEBSOCKET_PLAN.md
|
|
docs/validation/010-V0_2_7_ONCHAIN_WEBSOCKET.md
|
|
```
|
|
|
|
Aucune dependency externe n'est ajoutée dans cette tranche.
|
|
|
|
## 9. Validation disponible dans le sandbox
|
|
|
|
Exécuté après modifications :
|
|
|
|
```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
|
|
```
|
|
|
|
Le sandbox ne fournit toujours pas `cargo`; les gates Rust compilés ne sont donc pas déclarés réussis ici.
|
|
|
|
Baseline opérateur reçue avant `pre.002` : `cargo fmt`, audit Python, `cargo check` et `cargo clippy` verts sur `0.2.7-pre.1`. `cargo test --workspace` n'échoue que sur le canari Config Desk qui compare encore la ressource packagée `0.2.6` à la version workspace `0.2.7-pre.1`; aucune régression WebSocket n'y est impliquée.
|
|
|
|
## 10. Gates opérateur 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
|
|
```
|
|
|
|
Le test workspace complet peut encore reproduire le canari de version packagée Config Desk tant que cette ressource n'est volontairement resynchronisée.
|
|
|
|
## 11. Suite
|
|
|
|
`0.2.7-pre.003` doit matérialiser :
|
|
|
|
```text
|
|
std.transport V2 HTTP + WS
|
|
backward read V1 HTTP-only
|
|
schema/fixtures V2
|
|
Config -> WsTransportSettings
|
|
ws_endpoints[].kind = solana_standard
|
|
```
|
|
|
|
La direction reste strictement `Config -> Transport`; aucun reverse dependency n'est autorisé.
|