Sasedev/khadhroony-solana-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.2.7-pre.002

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-22 16:39:13 +02:00
parent cf4b28df2b
commit b64a799c85
11 changed files with 1491 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

55
docs/plans/014-V0_2_7_ONCHAIN_WEBSOCKET_PLAN.md
View File

@@ -1,9 +1,9 @@
<!-- file: docs/plans/014-V0_2_7_ONCHAIN_WEBSOCKET_PLAN.md -->
<!-- version: 3 -->
<!-- version: 4 -->
# Plan `0.2.7` — WebSocket Solana standard
> **Statut : actif, gate `0.2.7-pre.001`.** Cette première tranche fixe l'inventaire normatif, les frontières, le threat model, le modèle session/subscription, la stratégie de dépendances et le sizing. Elle ne matérialise pas encore le client WebSocket runtime.
> **Statut : actif, `0.2.7-pre.002`.** Le gate `pre.001` est clos. `pre.002` matérialise les settings WebSocket Transport, la redaction URL, le discriminateur de protocole, les identités locales, les états lifecycle et les snapshots sûrs. Le socket physique reste différé à `pre.004`.
## 1. Objet et base vérifiée
@@ -412,6 +412,40 @@ Les wrappers `WsProviderName`/`WsClusterName` sont parallèles aux `Http*` pour
`WsSessionSettings` porte les bornes runtime nécessaires : command timeout, close timeout, reconnect, resubscribe, capacités de queues, maximum de subscriptions actives, maximum de requests JSON-RPC en vol, maximum de message/frame/write buffer. Pas de rôle HTTP ni de scheduler.
Checkpoint `pre.002` matérialisé :
```text
WsEndpointUrl
WsProviderName
WsClusterName
WsProtocolKind
WsReconnectSettings
WsResubscribePolicy
WsSessionSettings
WsEndpointSettings
WsTransportSettings
```
Defaults Transport initiaux, explicitement **policy KSP locale** et non limites Solana :
```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
```
Les bornes message/frame/write buffer sont seulement **contractuelles** dans `pre.002`; leur raccordement à la crate WebSocket et les tests oversized restent les gates `pre.004`/`pre.005`. Elles peuvent être recalibrées avant `rel.001` si les fixtures adversariales ou les formes `blockSubscribe` démontrent qu'une autre valeur KSP est préférable.
### 9.2 Cardinalité
Contrat :
@@ -446,6 +480,8 @@ WsSubscriptionId # KSP local, stable malgré reconnect
remote id u64 # strictement runtime/interne, remappable
```
`pre.002` matérialise les deux IDs locaux comme wrappers de `NonZeroU64`. La génération est volontairement laissée au futur actor ; aucun compteur global ni singleton n'est introduit dans cette tranche.
Une `WsSubscription<T>` typée contient l'identité locale, la projection de lifecycle et un receiver bounded de notifications typées. L'ID remote ne devient pas un identifiant métier/public de contrôle.
## 10. State machines retenues
@@ -680,7 +716,18 @@ remote request body complet
Snapshot public cible : état session, endpoint name/provider/cluster, counts, reconnect state, continuity gaps, subscription IDs locaux + kinds + states. L'ID serveur peut rester interne ; un booléen `remote_bound` suffit pour diagnostiquer le binding sans faire croire à sa stabilité.
Tests dédiés : URL `wss://user:pass@host/path?api-key=secret` ne doit apparaître ni dans `Debug`, ni erreurs, ni logs capturés, ni snapshots.
`pre.002` matérialise `WsSessionSnapshot` et `WsSubscriptionSnapshot`. Leurs constructeurs restent crate-internal : les consumers ne peuvent pas fabriquer une fausse projection runtime. Aucun des deux types ne contient URL, credential, request body, raw notification ou remote subscription id.
Observabilité `pre.002` :
- `constants.rs` conserve le `TRACING_TARGET = "ksp-onchain-transport-lib"` crate-wide ;
- toute émission ajoutée passe par les macros `ksp-logging-lib`, jamais par `tracing` directement ;
- `trace` couvre les validations de settings et metadata sûres ;
- `debug` confirme les settings validés avec uniquement des compteurs/bornes et descriptors sûrs ;
- `warn` qualifie les rejets de settings/URL sans inclure la valeur URL ;
- aucun `error` n'est ajouté artificiellement pour une simple erreur de validation caller. Les erreurs runtime terminales seront instrumentées quand l'actor/socket existera.
Tests dédiés : URL `wss://user:pass@host/path?api-key=secret` ne doit apparaître ni dans `Debug`, ni erreurs, ni logs capturés, ni snapshots. `pre.002` couvre déjà `Debug`, erreur de validation et forme des snapshots ; la capture de logs runtime reste à compléter avec l'actor.
## 16. DTOs et losslessness
@@ -805,7 +852,7 @@ L'inventaire officiel n'impose que 9 familles de subscriptions, mais le lifecycl
```text
pre.001 audit interne/externe + matrice 18 méthodes + bot3 + dependencies + threat model + plan/sizing
pre.002 settings WS Transport + URL redaction + IDs/states/snapshots + tests de settings
pre.002 DONE — settings WS Transport + URL redaction + IDs/states/snapshots + tests de settings
pre.003 std.transport V2 HTTP+WS + backward V1 + discriminateur WS + schema/fixtures + Config -> WsTransportSettings
pre.004 deps tokio-tungstenite/futures-util + actor physique + handshake/read/write + pending JSON-RPC + serveur local
pre.005 limites frame/message/request + control frames + cancellation/close/shutdown + adversarial socket tests

85
docs/validation/010-V0_2_7_ONCHAIN_WEBSOCKET.md
View File

@@ -1,9 +1,9 @@
<!-- file: docs/validation/010-V0_2_7_ONCHAIN_WEBSOCKET.md -->
<!-- version: 3 -->
<!-- version: 4 -->
# Validation `0.2.7` — WebSocket Solana standard
> **Statut : matrice initiale ouverte par `0.2.7-pre.001`.** Les colonnes de preuve seront consolidées au fil des prereleases puis fermées avant `0.2.7-rel.001`.
> **Statut : matrice active, `0.2.7-pre.002`.** Le gate normatif `pre.001` est clos ; les settings, identités, états lifecycle et snapshots sûrs sont maintenant matérialisés. Les preuves runtime socket/subscription restent ouvertes.
## 1. Baseline normative
@@ -195,8 +195,8 @@ Les votes observés sont gossip/pre-consensus ; aucune garantie d'entrée dans l
| plusieurs subs / session | registry actor par session | `pre.006` |
| ID public subscription | local KSP stable | `pre.006` |
| ID serveur | éphémère interne et remappé | `pre.006`/`pre.007` |
| session states | Disconnected/Connecting/Active/Reconnecting/Closing/Closed/Failed | `pre.002` |
| subscription states | Requested/Active/Resubscribing/Cancelling/Closed/Failed | `pre.002` |
| session states | Disconnected/Connecting/Active/Reconnecting/Closing/Closed/Failed | **Done `pre.002`** |
| subscription states | Requested/Active/Resubscribing/Cancelling/Closed/Failed | **Done `pre.002`** |
| reconnect | physique uniquement, budget/backoff finis | `pre.007` |
| resubscribe | policy `Never` ou `ActiveSubscriptions`, ordre local déterministe | `pre.007` |
| continuity | gap observable, aucune promesse lossless | `pre.007` |
@@ -206,22 +206,22 @@ Les votes observés sont gossip/pre-consensus ; aucune garantie d'entrée dans l
## 7. Threat/security compliance initiale
| Invariant | Preuve attendue | Statut |
|---------------------------------------------------|-----------------------------------|---------|
| URL/credentials absents de `Debug` | unit tests URL wrapper | Planned |
| URL/credentials absents des erreurs | adversarial connection errors | Planned |
| URL/credentials absents des logs | writer/capture KSP logging | Planned |
| snapshots sans URL/raw payload | public API canary | Planned |
| frame/message finis | oversized server fixture | Planned |
| JSON borné indirectement par message | oversized + malformed fixture | Planned |
| queues notifications bornées | slow consumer fixture | Planned |
| pending RPC borné + timeout | no-response fixture | Planned |
| reconnect loop bornée | repeated disconnect fixture | Planned |
| unsubscribe pendant reconnect ne resubscribe pas | race fixture | Planned |
| signature terminale ne resubscribe pas | terminal fixture | Planned |
| shutdown ne bloque pas | peer hostile/no close ack fixture | Planned |
| no Store/Program/Wallet/Config dep dans Transport | cargo tree + source canary | Planned |
| no direct `tracing` dans Transport | workspace audit/canary | Planned |
| Invariant | Preuve attendue | Statut |
|---------------------------------------------------|---------------------------------------------|--------------------|
| URL/credentials absents de `Debug` | unit tests URL wrapper | **Done `pre.002`** |
| URL/credentials absents des erreurs | validation URL + future connection errors | Partial `pre.002` |
| URL/credentials absents des logs | safe fields `pre.002`, capture actor future | Partial `pre.002` |
| snapshots sans URL/raw payload | unit shape + public contract | **Done `pre.002`** |
| frame/message finis | settings bornés, enforcement socket futur | Partial `pre.002` |
| JSON borné indirectement par message | oversized + malformed fixture | Planned |
| queues notifications bornées | capacité settings, channel futur | Partial `pre.002` |
| pending RPC borné + timeout | settings bornés, runtime futur | Partial `pre.002` |
| reconnect loop bornée | repeated disconnect fixture | Planned |
| unsubscribe pendant reconnect ne resubscribe pas | race fixture | Planned |
| signature terminale ne resubscribe pas | terminal fixture | Planned |
| shutdown ne bloque pas | peer hostile/no close ack fixture | Planned |
| no Store/Program/Wallet/Config dep dans Transport | cargo tree + source canary | Planned |
| no direct `tracing` dans Transport | workspace audit + source audit | **Done `pre.002`** |
## 8. Dependency compliance initiale
@@ -268,6 +268,51 @@ Le type Transport correspondant au discriminateur est prévu `#[non_exhaustive]`
La schema V1 n'est pas assouplie. Une schema V2 explicite remplace la fixture standard au moment où l'adapter est matérialisé.
## 9.1 Checkpoint settings/lifecycle `pre.002`
Surface publique matérialisée :
```text
WsEndpointUrl
WsProviderName
WsClusterName
WsProtocolKind::SolanaStandard
WsReconnectSettings
WsResubscribePolicy::{Never, ActiveSubscriptions}
WsSessionSettings
WsEndpointSettings
WsTransportSettings
WsSessionId
WsSubscriptionId
WsSessionState
WsSubscriptionState
WsSubscriptionKind
WsSessionSnapshot
WsSubscriptionSnapshot
```
Gates déterministes ajoutés :
```text
ws:// et wss:// acceptés
HTTP rejeté par WsEndpointUrl
Debug URL redacted
erreur de scheme sans URL/credential
settings session default bornés
zero runtime bound rejeté
reconnect backoff inversé rejeté
endpoint names uniques
au moins un endpoint enabled
Debug WsTransportSettings sans URL/credential
9 familles standard WsSubscriptionKind
snapshots sans URL ni remote subscription id
public API canary crate-root
```
Logging : `TRACING_TARGET` reste défini dans `constants.rs`; les nouveaux événements utilisent exclusivement `ksp_logging_lib::trace!`, `debug!` et `warn!` avec des fields sûrs. Aucun `tracing` direct n'est ajouté.
Les defaults de taille/queue sont des **policies KSP locales**, pas des limites Solana. Leur enforcement réel et leurs tests oversized/slow-consumer restent attendus dans les tranches socket/backpressure.
## 10. Validation du gate `pre.001`
Exécuté dans le sandbox :