v0.2.7-pre.002
This commit is contained in:
263
deltas/0.2.7/pre.002.md
Normal file
263
deltas/0.2.7/pre.002.md
Normal file
@@ -0,0 +1,263 @@
|
||||
<!-- 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é.
|
||||
Reference in New Issue
Block a user