khadhroony-solana-project/deltas/0.2.7/pre.002.md

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 :

0.2.7-pre.2

Livraison :

0.2.7-pre.002

Commit attendu :

v0.2.7-pre.002

Aucun tag prerelease.

2. Surface Transport ajoutée

Settings publics :

WsEndpointUrl
WsProviderName
WsClusterName
WsProtocolKind
WsReconnectSettings
WsResubscribePolicy
WsSessionSettings
WsEndpointSettings
WsTransportSettings

Lifecycle public :

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 :

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 :

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 :

Disconnected
Connecting
Active
Reconnecting { attempt }
Closing
Closed
Failed

États subscription matérialisés :

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 :

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 :

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 :

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 :

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 :

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 :

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 :

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 :

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é.