317 lines
8.3 KiB
Markdown
317 lines
8.3 KiB
Markdown
<!-- file: deltas/0.3.15/pre.002.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# Delta `0.3.15-pre.002` — capability WebSocket typed par endpoint
|
|
|
|
## Base requise
|
|
|
|
```text
|
|
0.3.15-pre.001-fix.001 appliquée
|
|
workspace.package.version = 0.3.15-pre.1
|
|
deltas/0.3.15/pre.001-fix.001.md présent
|
|
```
|
|
|
|
## Gate de la base
|
|
|
|
Le gate opérateur communiqué après `pre.001-fix.001` est propre :
|
|
|
|
```text
|
|
cargo fmt --all -- --check : PASS
|
|
General Rust rule audit : clean
|
|
Rust export completeness audit : 0 candidate(s)
|
|
KSP workspace Rust rule audit : clean
|
|
Markdown table audit : clean (318 table(s), 185 file(s))
|
|
cargo check --workspace : PASS
|
|
```
|
|
|
|
Ce gate qualifie la base directe de `pre.002` avant toute modification Transport.
|
|
|
|
## Objectif
|
|
|
|
Implémenter strictement la tranche `pre.002` du plan `036` :
|
|
|
|
```text
|
|
ajouter une déclaration WebSocket typed exacte par subscription au niveau Transport
|
|
réutiliser WsSubscriptionKind comme identité de capability
|
|
conserver la compatibilité des WsEndpointSettings existants
|
|
faire de l'absence de déclaration un état fail-closed pour toute preuve de capability
|
|
valider les déclarations explicites sans inférence par provider
|
|
borner les capabilities à la surface réellement portée par WsProtocolKind
|
|
exposer la preuve via la façade crate-root déjà existante
|
|
documenter l'usage version-neutral
|
|
ajouter les tests unitaires/public API/release completeness
|
|
```
|
|
|
|
Cette tranche ne mappe encore aucun champ Config et ne modifie aucun constructeur Worker. Ces responsabilités restent respectivement `pre.003` et `pre.004`.
|
|
|
|
## Contrat `WsEndpointSettings`
|
|
|
|
`WsEndpointSettings` conserve son constructeur historique `new(...)` sans argument supplémentaire afin de ne pas forcer artificiellement Config à évoluer dans la même tranche.
|
|
|
|
Un endpoint possède désormais l'état privé :
|
|
|
|
```text
|
|
subscription_capabilities: Option<Vec<WsSubscriptionKind>>
|
|
```
|
|
|
|
Sémantique :
|
|
|
|
```text
|
|
None = capabilities non déclarées ; compatibilité legacy ; aucune preuve positive
|
|
Some(vec) = déclaration explicite des seules familles annoncées pour cet endpoint
|
|
```
|
|
|
|
Le builder public :
|
|
|
|
```text
|
|
with_subscription_capabilities(Vec<WsSubscriptionKind>)
|
|
```
|
|
|
|
permet d'attacher la déclaration exacte sans introduire de second enum ni de second registre de méthodes.
|
|
|
|
Les getters publics :
|
|
|
|
```text
|
|
subscription_capabilities() -> Option<&[WsSubscriptionKind]>
|
|
supports_subscription(WsSubscriptionKind) -> bool
|
|
```
|
|
|
|
restent accessibles via `WsEndpointSettings`, déjà réexporté depuis la racine de crate.
|
|
|
|
`supports_subscription(...)` est volontairement fail-closed :
|
|
|
|
```text
|
|
capability non déclarée -> false
|
|
capability incompatible avec le protocole -> false même avant validate()
|
|
capability explicitement déclarée et protocol-compatible -> true
|
|
```
|
|
|
|
## Validation Transport
|
|
|
|
`WsTransportSettings::validate()` rejette maintenant une déclaration explicite :
|
|
|
|
```text
|
|
vide
|
|
dupliquée
|
|
incompatible avec le WsProtocolKind de l'endpoint
|
|
```
|
|
|
|
Les erreurs réutilisent `ERROR_CODE_INVALID_SETTINGS` et n'exposent que :
|
|
|
|
```text
|
|
field
|
|
subscription_kind stable
|
|
protocol stable
|
|
```
|
|
|
|
Aucune URL, credential, source key ou payload n'est ajouté aux contextes d'erreur.
|
|
|
|
## Partition protocolaire
|
|
|
|
La validation est protocol-owned et ne branche jamais sur `provider`.
|
|
|
|
`SolanaStandard` admet les neuf familles standard actuelles :
|
|
|
|
```text
|
|
Account
|
|
Block
|
|
Logs
|
|
Program
|
|
Root
|
|
Signature
|
|
Slot
|
|
SlotsUpdates
|
|
Vote
|
|
```
|
|
|
|
`HeliusLaserStream` admet la surface déjà portée par sa façade typed :
|
|
|
|
```text
|
|
Account
|
|
Logs
|
|
Program
|
|
Root
|
|
Signature
|
|
Slot
|
|
SlotsUpdates
|
|
HeliusTransaction
|
|
```
|
|
|
|
Il n'admet donc pas `Block` ni `Vote`.
|
|
|
|
Cette partition est écrite positivement. Une future variante de `WsSubscriptionKind` ne devient donc pas implicitement compatible avec un protocole existant.
|
|
|
|
## Absence d'inférence provider
|
|
|
|
Aucune règle du type :
|
|
|
|
```text
|
|
provider == helius -> capability X
|
|
provider == publicnode -> capability Y
|
|
```
|
|
|
|
n'est ajoutée.
|
|
|
|
Le provider reste un descriptor ouvert. La preuve de capability est attachée explicitement à l'endpoint et devra être alimentée par Config en `pre.003`.
|
|
|
|
## Documentation d'usage
|
|
|
|
`ksp-onchain-transport-lib/USAGE.md` montre maintenant la déclaration typed sur un endpoint standard et documente les deux propriétés importantes :
|
|
|
|
```text
|
|
absence de déclaration != support implicite
|
|
validation explicite des listes vide/dupliquée/protocol-incompatible
|
|
```
|
|
|
|
Le guide reste version-neutral et ne sert pas de journal de gate.
|
|
|
|
## Tests ajoutés
|
|
|
|
Unitaires `ws_settings` :
|
|
|
|
```text
|
|
legacy undeclared reste structurally valide mais fail-closed
|
|
capabilities standard exactes et typed
|
|
liste explicite vide rejetée
|
|
capability dupliquée rejetée
|
|
HeliusTransaction rejeté sous SolanaStandard
|
|
Block rejeté sous HeliusLaserStream
|
|
Logs + HeliusTransaction admis sous HeliusLaserStream
|
|
Block/Vote restent non supportés sous HeliusLaserStream
|
|
supports_subscription reste false sur capability protocol-incompatible avant validate
|
|
```
|
|
|
|
Public API :
|
|
|
|
```text
|
|
builder/getter/support check consommables depuis la crate root
|
|
aucun nouveau module public requis
|
|
```
|
|
|
|
Release completeness :
|
|
|
|
```text
|
|
état capability porté par WsEndpointSettings
|
|
WsSubscriptionKind réutilisé directement
|
|
partition protocolaire présente
|
|
absence de branche provider-name pour attribuer des capabilities
|
|
```
|
|
|
|
## Fichiers ajoutés
|
|
|
|
```text
|
|
deltas/0.3.15/pre.002.md
|
|
```
|
|
|
|
## Fichiers modifiés
|
|
|
|
```text
|
|
Cargo.toml
|
|
crates/ksp-onchain-transport-lib/USAGE.md
|
|
crates/ksp-onchain-transport-lib/src/ws_settings.rs
|
|
crates/ksp-onchain-transport-lib/unit_tests/ws_settings.rs
|
|
crates/ksp-onchain-transport-lib/tests/public_api.rs
|
|
crates/ksp-onchain-transport-lib/tests/release_completeness.rs
|
|
```
|
|
|
|
## Fichiers supprimés
|
|
|
|
```text
|
|
aucun
|
|
```
|
|
|
|
## Version Cargo
|
|
|
|
Cette tranche modifie le contrat/runtime settings Transport. Conformément à la policy de versioning :
|
|
|
|
```text
|
|
header Cargo.toml : 594 -> 595
|
|
workspace.package.version : 0.3.15-pre.1 -> 0.3.15-pre.2
|
|
```
|
|
|
|
Versions des fichiers modifiés :
|
|
|
|
```text
|
|
ksp-onchain-transport-lib/USAGE.md : 26 -> 27
|
|
ksp-onchain-transport-lib/src/ws_settings.rs : 4 -> 5
|
|
ksp-onchain-transport-lib/unit_tests/ws_settings.rs : 2 -> 3
|
|
ksp-onchain-transport-lib/tests/public_api.rs : 54 -> 55
|
|
ksp-onchain-transport-lib/tests/release_completeness.rs : 46 -> 47
|
|
```
|
|
|
|
## Frontières préservées
|
|
|
|
```text
|
|
aucun changement Config/schema/composite
|
|
aucun changement Worker
|
|
aucun changement Store
|
|
aucune crate Desk ajoutée
|
|
aucun Start/Stop Worker applicatif
|
|
aucun I/O réseau supplémentaire
|
|
aucune nouvelle dépendance
|
|
aucune nouvelle feature
|
|
aucun provider SDK
|
|
aucune inférence capability par provider name
|
|
aucun nouveau type public nécessitant une réexportation lib.rs
|
|
```
|
|
|
|
## Audits statiques d'assemblage
|
|
|
|
Après modification et ajout du delta :
|
|
|
|
```text
|
|
General Rust rule audit : clean
|
|
Rust export completeness audit : 0 candidate(s)
|
|
KSP workspace Rust rule audit : clean
|
|
Markdown table audit : clean (318 table(s), 186 file(s))
|
|
```
|
|
|
|
## Gates Cargo non exécutés dans l'environnement d'assemblage
|
|
|
|
L'environnement d'assemblage ne fournit pas Cargo/Rustfmt. Aucun faux PASS n'est revendiqué pour :
|
|
|
|
```text
|
|
cargo fmt --all -- --check
|
|
cargo check --workspace
|
|
cargo clippy --workspace --all-targets --all-features -- -D warnings
|
|
cargo test -p ksp-onchain-transport-lib --all-targets --all-features
|
|
```
|
|
|
|
Ils doivent être exécutés par l'opérateur après application du delta.
|
|
|
|
## Archive d'échange
|
|
|
|
Livraison attendue selon `VER-ARCHIVE-004` :
|
|
|
|
```text
|
|
ksp-general-0.3.15-pre.002.zip
|
|
```
|
|
|
|
Contenu exact :
|
|
|
|
```text
|
|
Cargo.toml
|
|
crates/ksp-onchain-transport-lib/USAGE.md
|
|
crates/ksp-onchain-transport-lib/src/ws_settings.rs
|
|
crates/ksp-onchain-transport-lib/unit_tests/ws_settings.rs
|
|
crates/ksp-onchain-transport-lib/tests/public_api.rs
|
|
crates/ksp-onchain-transport-lib/tests/release_completeness.rs
|
|
deltas/0.3.15/pre.002.md
|
|
```
|
|
|
|
Aucun fichier stable inchangé, lockfile, cache, sortie de build ou artefact temporaire n'est inclus.
|
|
|
|
## Gate opérateur après application
|
|
|
|
```bash
|
|
cargo fmt --all
|
|
cargo fmt --all -- --check
|
|
python3 scripts/audit_rust_workspace_rules.py
|
|
python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas/0.3.15
|
|
cargo check --workspace
|
|
cargo clippy --workspace --all-targets --all-features -- -D warnings
|
|
cargo test -p ksp-onchain-transport-lib --all-targets --all-features
|
|
```
|
|
|
|
Si ce gate est propre, `pre.003` mappe cette capability depuis Config et prépare le composite/profils Raw Transaction Ingest Desk, sans frontend.
|