0.3.5-alpha.6
This commit is contained in:
@@ -1,6 +1,10 @@
|
||||
# file: .cargo/config.toml
|
||||
# version: 1
|
||||
# version: 2
|
||||
|
||||
[build]
|
||||
target-dir = "../builds/sasedev-games/target" # path of where to place generated artifacts
|
||||
build-dir = "../builds/sasedev-games/target" # path of where to place intermediate build artifacts
|
||||
|
||||
[target.wasm32-unknown-unknown]
|
||||
rustflags = ["--cfg=web_sys_unstable_apis"]
|
||||
rustdocflags = ["--cfg=web_sys_unstable_apis"]
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
# file: Cargo.toml
|
||||
# version: 101
|
||||
# version: 102
|
||||
|
||||
[workspace]
|
||||
resolver = "3"
|
||||
@@ -26,7 +26,7 @@ members = [
|
||||
]
|
||||
|
||||
[workspace.package]
|
||||
version = "0.3.5-alpha.5"
|
||||
version = "0.3.5-alpha.6"
|
||||
edition = "2024"
|
||||
license = "MIT"
|
||||
repository = "https://git.sasedev.com/Sasedev/games"
|
||||
@@ -50,6 +50,7 @@ tokio-tungstenite = { version = "0.30.0", default-features = false }
|
||||
url = "2.5.8"
|
||||
wasm-bindgen = "0.2"
|
||||
web-transport-quinn = { version = "0.12.1", default-features = false }
|
||||
web-transport-wasm = "0.6.0"
|
||||
|
||||
[workspace.lints.rust]
|
||||
missing_docs = "warn"
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: README.md -->
|
||||
<!-- version: 69 -->
|
||||
<!-- version: 70 -->
|
||||
|
||||
# games.sasedev
|
||||
|
||||
@@ -27,9 +27,9 @@ Workspace expérimental puis productif pour des jeux multiplateformes principale
|
||||
|
||||
Version stable de référence : `0.3.4`.
|
||||
|
||||
Version active : `0.3.5-alpha.5`. `0.3.2` reste différée.
|
||||
Version active : `0.3.5-alpha.6`. `0.3.2` reste différée.
|
||||
|
||||
La stable `0.3.4` livre la première baseline realtime : contrat binaire transport-neutral, backend WebSocket Tokio/tokio-tungstenite, limites et deadlines, tests loopback/robustesse, smoke runtime localhost public et frontières de dépendances empêchant moteurs et gameplay de dépendre d'un backend concret. `0.3.5-alpha.5` ajoute au backend WebTransport natif déjà robuste un smoke runtime localhost hors harness : identité TLS locale en mémoire, pin SHA-256 exact, session WebTransport réelle, stream fiable principal, round-trip binaire bidirectionnel et fermeture propre avec verdict `PASS` déterministe. Navigateur/WASM, fallback et datagrams restent réservés aux tranches suivantes.
|
||||
La stable `0.3.4` livre la première baseline realtime : contrat binaire transport-neutral, backend WebSocket Tokio/tokio-tungstenite, limites et deadlines, tests loopback/robustesse, smoke runtime localhost public et frontières de dépendances empêchant moteurs et gameplay de dépendre d'un backend concret. `0.3.5-alpha.6` conserve le backend WebTransport natif et son smoke `PASS`, puis ajoute un client WebTransport `wasm32-unknown-unknown` compilable fondé sur l'API navigateur : pin SHA-256 explicite, session, stream bidirectionnel primaire et framing fiable adapté au même contrat realtime. Le smoke navigateur réel, le fallback et les datagrams restent réservés aux tranches suivantes.
|
||||
|
||||
Les deux premiers jeux sont des POC structurels : `game-reflex-poc` et `game-snake-poc`. Ils existent d'abord pour valider les frontières du workspace, le moteur, les assets et le packaging multiplateforme.
|
||||
|
||||
@@ -45,4 +45,4 @@ Les deux premiers jeux sont des POC structurels : `game-reflex-poc` et `game-sna
|
||||
|
||||
## Diagnostics et tests
|
||||
|
||||
Les socles transverses `crates/common/game-assets-lib` et `crates/common/game-logging-lib` fournissent respectivement la résolution logique des assets et le tracing commun. Le realtime est séparé entre `game-realtime-transport-lib`, contrat binaire transport-neutral, `game-realtime-websocket-lib`, backend Tokio/tokio-tungstenite, et `game-realtime-webtransport-lib`, backend WebTransport/QUIC candidat dont le chemin natif couvre désormais TLS/pinning, établissement de session et stream fiable principal adapté au contrat commun. Leurs responsabilités sont documentées dans leurs README/USAGE locaux lorsqu'un guide d'usage est justifié. `game-realtime-websocket-smoke` et `game-realtime-webtransport-smoke` fournissent les preuves runtime localhost hors harness des deux backends fiables natifs. Les tests unitaires résident hors `src/` sous `unit_tests/`; les tests d’intégration/environnement résident sous `tests/`.
|
||||
Les socles transverses `crates/common/game-assets-lib` et `crates/common/game-logging-lib` fournissent respectivement la résolution logique des assets et le tracing commun. Le realtime est séparé entre `game-realtime-transport-lib`, contrat binaire transport-neutral, `game-realtime-websocket-lib`, backend Tokio/tokio-tungstenite, et `game-realtime-webtransport-lib`, backend WebTransport/QUIC candidat dont le chemin natif couvre TLS/pinning, établissement de session et stream fiable principal, tandis que son chemin client WASM compile contre l'API WebTransport du navigateur avec le même framing fiable et le même contrat commun. Leurs responsabilités sont documentées dans leurs README/USAGE locaux lorsqu'un guide d'usage est justifié. `game-realtime-websocket-smoke` et `game-realtime-webtransport-smoke` fournissent les preuves runtime localhost hors harness des deux backends fiables natifs. Les tests unitaires résident hors `src/` sous `unit_tests/`; les tests d’intégration/environnement résident sous `tests/`.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
# file: crates/common/game-realtime-webtransport-lib/Cargo.toml
|
||||
# version: 2
|
||||
# version: 3
|
||||
|
||||
[package]
|
||||
name = "game-realtime-webtransport-lib"
|
||||
@@ -12,13 +12,18 @@ publish.workspace = true
|
||||
|
||||
[dependencies]
|
||||
game-realtime-transport-lib = { path = "../game-realtime-transport-lib" }
|
||||
rcgen = { workspace = true, features = ["ring"] }
|
||||
tokio = { workspace = true, features = ["time"] }
|
||||
tracing.workspace = true
|
||||
url.workspace = true
|
||||
|
||||
[target.'cfg(not(target_arch = "wasm32"))'.dependencies]
|
||||
rcgen = { workspace = true, features = ["ring"] }
|
||||
tokio = { workspace = true, features = ["time"] }
|
||||
web-transport-quinn = { workspace = true, features = ["ring"] }
|
||||
|
||||
[dev-dependencies]
|
||||
[target.'cfg(target_arch = "wasm32")'.dependencies]
|
||||
web-transport-wasm.workspace = true
|
||||
|
||||
[target.'cfg(not(target_arch = "wasm32"))'.dev-dependencies]
|
||||
tokio = { workspace = true, features = ["macros", "rt", "time"] }
|
||||
|
||||
[lints]
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: crates/common/game-realtime-webtransport-lib/README.md -->
|
||||
<!-- version: 3 -->
|
||||
<!-- version: 4 -->
|
||||
|
||||
# game-realtime-webtransport-lib
|
||||
|
||||
@@ -7,9 +7,9 @@ Backend WebTransport/QUIC candidat pour le realtime de `games.sasedev`.
|
||||
|
||||
## Responsabilité
|
||||
|
||||
La crate possède le transport WebTransport concret sans introduire de sémantique gameplay, room, joueur, tick ou snapshot. Son chemin natif repose sur `web-transport-quinn` et conserve les erreurs publiques dans `game-realtime-transport-lib`.
|
||||
La crate possède le transport WebTransport concret sans introduire de sémantique gameplay, room, joueur, tick ou snapshot. Le chemin natif repose sur `web-transport-quinn`; le chemin client `wasm32-unknown-unknown` repose sur `web-transport-wasm` et l'API WebTransport du navigateur. Les deux conservent les erreurs publiques dans `game-realtime-transport-lib`.
|
||||
|
||||
La frontière native disponible couvre désormais :
|
||||
La frontière fiable disponible couvre désormais :
|
||||
|
||||
- configuration client HTTPS avec pin SHA-256 exact ;
|
||||
- identité serveur X.509 DER + clé privée PKCS#8 DER injectables ;
|
||||
@@ -19,14 +19,26 @@ La frontière native disponible couvre désormais :
|
||||
- sélection d'un unique stream bidirectionnel fiable comme chemin realtime principal ;
|
||||
- framing privé `u32` big-endian + payload binaire ;
|
||||
- limite de message configurable, 1 MiB par défaut, vérifiée avant allocation côté réception et avant écriture côté émission ;
|
||||
- deadlines configurables pour la connexion, l'ouverture/accept du stream primaire et un envoi complet ;
|
||||
- deadlines configurables sur le chemin natif pour la connexion, l'ouverture/accept du stream primaire et un envoi complet ;
|
||||
- adaptation `RealtimeConnection` / `RealtimeSender` / `RealtimeReceiver` ;
|
||||
- FIN propre via `RealtimeSender::close()` ;
|
||||
- reset/STOP_SENDING backend-spécifiques via `WebTransportSender::abort(...)` et `WebTransportReceiver::abort(...)` ;
|
||||
- cancellation/drop terminale : un sender abandonné est reset plutôt que transformé implicitement en FIN ;
|
||||
- parseur de framing réception incrémental conservant son état si une future `receive()` est annulée ;
|
||||
- mapping stable des erreurs reset/close/session/protocole vers `TransportErrorKind` ;
|
||||
- tracing sous `games::realtime::webtransport`.
|
||||
- tracing sous `games::realtime::webtransport`;
|
||||
- client WASM avec endpoint HTTPS, hash certificat SHA-256 explicite, établissement de session navigateur et ouverture du stream bidirectionnel primaire;
|
||||
- adaptation WASM du framing `u32` big-endian et des traits realtime, y compris FIN, reset/STOP et réception incrémentale.
|
||||
|
||||
## Chemin navigateur/WASM
|
||||
|
||||
Pour `wasm32-unknown-unknown`, la crate remplace les dépendances natives Quinn/Tokio/rcgen par `web-transport-wasm`. Le build final reçoit `--cfg=web_sys_unstable_apis` uniquement pour cette cible via `.cargo/config.toml`, conformément à l'exigence actuelle des bindings WebTransport de `web-sys`.
|
||||
|
||||
L'API client garde les mêmes noms de surface que le client natif : `WebTransportCertificateHash`, `WebTransportClientConfig`, `connect`, `WebTransportSession`, `WebTransportConnection`, `WebTransportSender` et `WebTransportReceiver`. Le navigateur ouvre toujours le stream bidirectionnel primaire côté client ; le serveur reste le backend Rust natif.
|
||||
|
||||
Le pin SHA-256 est transmis à `WebTransportOptions.serverCertificateHashes`; aucune variante navigateur sans validation TLS n'est ajoutée. Le framing applicatif reste strictement identique au natif.
|
||||
|
||||
`alpha.6` ferme uniquement la preuve de compilation de ce chemin. La limite de message de `WebTransportConfig` est appliquée immédiatement, mais les deadlines opérationnelles de cette configuration restent une différence explicite : le wrapper navigateur conserve les opérations Web API abandonnées de manière cancel-safe, et la tranche `alpha.7` doit décider puis prouver la politique de timer/runtime avant de déclarer la parité comportementale navigateur. Aucun smoke runtime navigateur n'est attribué à `alpha.6`.
|
||||
|
||||
## TLS de développement
|
||||
|
||||
@@ -57,7 +69,7 @@ one WebTransport session
|
||||
|
||||
`WebTransportConfig::default()` conserve la baseline de 1 MiB par message. La limite peut être réduite ou augmentée tant qu'elle reste strictement positive et représentable dans le champ de longueur `u32` du framing.
|
||||
|
||||
Les deadlines configurables couvrent :
|
||||
Sur le chemin natif, les deadlines configurables couvrent :
|
||||
|
||||
- connexion client et réponse finale à une requête WebTransport déjà surfacée côté serveur ;
|
||||
- ouverture ou accept du stream bidirectionnel principal ;
|
||||
@@ -65,7 +77,7 @@ Les deadlines configurables couvrent :
|
||||
|
||||
L'attente d'un nouveau pair sur le listener reste volontairement non bornée : un serveur inactif ne doit pas produire périodiquement une erreur uniquement parce qu'aucun client ne se présente.
|
||||
|
||||
QUIC applique sa propre flow-control. Le backend n'ajoute pas une seconde file applicative : si un envoi reste bloqué par flow-control/réseau au-delà de `send_timeout`, l'opération retourne `TransportErrorKind::Timeout` et le stream est reset afin qu'une frame partiellement transmise ne puisse pas être suivie d'une nouvelle frame invalide.
|
||||
QUIC applique sa propre flow-control. Le backend natif n'ajoute pas une seconde file applicative : si un envoi reste bloqué par flow-control/réseau au-delà de `send_timeout`, l'opération retourne `TransportErrorKind::Timeout` et le stream est reset afin qu'une frame partiellement transmise ne puisse pas être suivie d'une nouvelle frame invalide. Le chemin navigateur conserve la même politique de reset sur cancellation, mais son timer `send_timeout` reste explicitement différé à `alpha.7`.
|
||||
|
||||
## Lifecycle, abort et cancellation
|
||||
|
||||
@@ -91,7 +103,7 @@ Le backend distingue notamment :
|
||||
- fermeture de session WebTransport explicite -> `Closed` ;
|
||||
- erreur de session/connexion non classée comme fermeture propre -> `Io` ;
|
||||
- reset/stop invalide ou framing tronqué -> `Protocol` ;
|
||||
- deadline dépassée -> `Timeout`.
|
||||
- deadline dépassée -> `Timeout` sur le chemin natif ; la matérialisation des timers navigateur reste différée à `alpha.7`.
|
||||
|
||||
Une longueur entrante hors limite ou un framing tronqué provoque aussi l'arrêt de la direction de réception afin d'éviter de poursuivre sur un flux désynchronisé.
|
||||
|
||||
@@ -100,11 +112,11 @@ Une longueur entrante hors limite ou un framing tronqué provoque aussi l'arrêt
|
||||
La crate ne possède toujours pas :
|
||||
|
||||
- d'API datagram transport-neutral ;
|
||||
- de chemin navigateur/WASM ;
|
||||
- de smoke executable public WebTransport ;
|
||||
- de serveur WebTransport WASM ;
|
||||
- de preuve runtime navigateur ;
|
||||
- de fallback WebSocket ;
|
||||
- de benchmark WebSocket/WebTransport.
|
||||
|
||||
Ces responsabilités restent réservées aux tranches suivantes du plan `0.3.5`.
|
||||
|
||||
Le chemin natif s'exécute sous un runtime Tokio fourni par le consommateur ; la crate ne crée ni runtime ni thread privé. Le chemin navigateur/WASM est distinct : aucun `cfg` WASM ni dépendance navigateur n'est requis par le backend natif actuel.
|
||||
Le chemin natif s'exécute sous un runtime Tokio fourni par le consommateur ; la crate ne crée ni runtime ni thread privé. Les dépendances navigateur sont target-specific et ne sont donc pas tirées par le backend natif. Réciproquement, `web-transport-quinn`, Tokio et rcgen ne sont pas requis pour construire la crate en `wasm32-unknown-unknown`.
|
||||
|
||||
@@ -1,13 +1,13 @@
|
||||
<!-- file: crates/common/game-realtime-webtransport-lib/USAGE.md -->
|
||||
<!-- version: 2 -->
|
||||
<!-- version: 3 -->
|
||||
|
||||
# Utilisation de game-realtime-webtransport-lib
|
||||
|
||||
Ce guide décrit le chemin natif fiable exposé par `game-realtime-webtransport-lib`. Il ne décrit ni gameplay, ni protocole wire métier, ni datagrams.
|
||||
Ce guide décrit les chemins fiables natif et client navigateur/WASM exposés par `game-realtime-webtransport-lib`. Il ne décrit ni gameplay, ni protocole wire métier, ni datagrams.
|
||||
|
||||
## Configuration transport
|
||||
|
||||
`WebTransportConfig` porte les limites et deadlines du chemin fiable. La configuration par défaut garde une limite de 1 MiB par message et des deadlines bornées pour connexion, stream primaire et send.
|
||||
`WebTransportConfig` porte les limites et deadlines du chemin fiable. La configuration par défaut garde une limite de 1 MiB par message. Les deadlines sont appliquées par le chemin natif ; le client navigateur les valide mais leur matérialisation par timer reste différée à `alpha.7`.
|
||||
|
||||
Exemple de configuration plus stricte :
|
||||
|
||||
@@ -19,7 +19,7 @@ let transport = game_realtime_webtransport_lib::WebTransportConfig::default()
|
||||
.with_send_timeout(std::time::Duration::from_secs(2));
|
||||
```
|
||||
|
||||
La validation effective se fait lors du bind serveur ou de la connexion client. Une limite nulle, une limite non représentable en `u32` ou une deadline nulle est rejetée comme `InvalidConfiguration`.
|
||||
La validation effective se fait lors du bind serveur ou de la connexion client. Une limite nulle, une limite non représentable en `u32` ou une deadline nulle est rejetée comme `InvalidConfiguration`, y compris côté navigateur même lorsque le timer correspondant n'est pas encore matérialisé.
|
||||
|
||||
## Serveur natif
|
||||
|
||||
@@ -77,6 +77,35 @@ let connection = match session.open_primary_connection().await {
|
||||
|
||||
Le pinning est obligatoire dans cette API native ; il n'existe pas de variante qui désactive globalement la vérification TLS.
|
||||
|
||||
## Client navigateur/WASM
|
||||
|
||||
Pour `wasm32-unknown-unknown`, les mêmes noms `WebTransportCertificateHash`, `WebTransportClientConfig`, `connect` et `WebTransportSession::open_primary_connection()` sont disponibles. Le serveur reste natif ; le navigateur est uniquement client.
|
||||
|
||||
Exemple de séquence Rust côté WASM :
|
||||
|
||||
```rust
|
||||
let certificate_hash = game_realtime_webtransport_lib::WebTransportCertificateHash::from_sha256(server_sha256);
|
||||
let config = match game_realtime_webtransport_lib::WebTransportClientConfig::new(
|
||||
"https://127.0.0.1:4433/game",
|
||||
certificate_hash,
|
||||
) {
|
||||
Ok(value) => value.with_transport_config(transport),
|
||||
Err(error) => return Err(error),
|
||||
};
|
||||
let session = match game_realtime_webtransport_lib::connect(&config).await {
|
||||
Ok(value) => value,
|
||||
Err(error) => return Err(error),
|
||||
};
|
||||
let connection = match session.open_primary_connection().await {
|
||||
Ok(value) => value,
|
||||
Err(error) => return Err(error),
|
||||
};
|
||||
```
|
||||
|
||||
Le build workspace fournit `web_sys_unstable_apis` uniquement à `wasm32-unknown-unknown`. Le hash SHA-256 est transmis au navigateur comme `serverCertificateHashes`. La limite de message configurée est appliquée au framing WASM. Les deadlines `connect_timeout`, `primary_stream_timeout` et `send_timeout` restent validées mais ne sont pas encore appliquées par un timer navigateur dans la tranche de compilation ; cette politique est fermée avec le smoke runtime de la tranche suivante.
|
||||
|
||||
Aucun `wasm-bindgen` frontend ou host Vite n'est requis pour simplement vérifier la compilation de la bibliothèque.
|
||||
|
||||
## Contrat realtime
|
||||
|
||||
Une fois le stream primaire sélectionné, utiliser les traits de `game-realtime-transport-lib` pour le chemin fiable normal :
|
||||
@@ -101,7 +130,7 @@ if let Err(error) = game_realtime_transport_lib::RealtimeSender::close(&mut send
|
||||
|
||||
Le backend encode chaque `TransportMessage` sous la forme `u32` big-endian + payload. Le consommateur ne doit pas reproduire ce framing lui-même.
|
||||
|
||||
La flow-control QUIC est respectée naturellement par l'écriture asynchrone. Un send qui dépasse sa deadline est considéré terminal : le stream est reset et le même sender ne doit pas être réutilisé.
|
||||
La flow-control QUIC est respectée naturellement par l'écriture asynchrone. Sur le chemin natif, un send qui dépasse sa deadline est considéré terminal : le stream est reset et le même sender ne doit pas être réutilisé. Sur le chemin navigateur de `alpha.6`, une cancellation du send reste terminale et reset le stream, mais le timer `send_timeout` est différé à `alpha.7`.
|
||||
|
||||
## Fermeture et abort
|
||||
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
// file: crates/common/game-realtime-webtransport-lib/src/config.rs
|
||||
// version: 1
|
||||
// version: 2
|
||||
|
||||
const DEFAULT_CONNECT_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(10);
|
||||
const DEFAULT_MAX_MESSAGE_SIZE: usize = 1024 * 1024;
|
||||
const DEFAULT_PRIMARY_STREAM_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(5);
|
||||
const DEFAULT_SEND_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(5);
|
||||
|
||||
/// Product-facing limits and operation deadlines for the native WebTransport reliable path.
|
||||
/// Product-facing limits and operation deadlines for the WebTransport reliable path.
|
||||
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
|
||||
pub struct WebTransportConfig {
|
||||
connect_timeout: std::time::Duration,
|
||||
|
||||
@@ -1,34 +1,68 @@
|
||||
// file: crates/common/game-realtime-webtransport-lib/src/lib.rs
|
||||
// version: 3
|
||||
// version: 4
|
||||
|
||||
#![warn(missing_docs)]
|
||||
#![deny(unreachable_pub)]
|
||||
#![forbid(unsafe_code)]
|
||||
|
||||
//! Native WebTransport/QUIC backend candidate for the transport-neutral realtime contract.
|
||||
//! WebTransport/QUIC backend candidate for the transport-neutral realtime contract.
|
||||
|
||||
mod config;
|
||||
#[cfg(not(target_arch = "wasm32"))]
|
||||
mod webtransport;
|
||||
#[cfg(target_arch = "wasm32")]
|
||||
mod webtransport_wasm;
|
||||
|
||||
/// Re-export of product-facing limits and operation deadlines for the reliable WebTransport path.
|
||||
pub use self::config::WebTransportConfig;
|
||||
#[cfg(not(target_arch = "wasm32"))]
|
||||
/// Re-export of the pinned SHA-256 certificate fingerprint used by the native client.
|
||||
pub use self::webtransport::WebTransportCertificateHash;
|
||||
#[cfg(not(target_arch = "wasm32"))]
|
||||
/// Re-export of native WebTransport client configuration.
|
||||
pub use self::webtransport::WebTransportClientConfig;
|
||||
#[cfg(not(target_arch = "wasm32"))]
|
||||
/// Re-export of an established WebTransport connection adapted to the transport-neutral realtime contract.
|
||||
pub use self::webtransport::WebTransportConnection;
|
||||
#[cfg(not(target_arch = "wasm32"))]
|
||||
/// Re-export of the bound native WebTransport listener.
|
||||
pub use self::webtransport::WebTransportListener;
|
||||
#[cfg(not(target_arch = "wasm32"))]
|
||||
/// Re-export of the receive half of the primary reliable WebTransport stream.
|
||||
pub use self::webtransport::WebTransportReceiver;
|
||||
#[cfg(not(target_arch = "wasm32"))]
|
||||
/// Re-export of the send half of the primary reliable WebTransport stream.
|
||||
pub use self::webtransport::WebTransportSender;
|
||||
#[cfg(not(target_arch = "wasm32"))]
|
||||
/// Re-export of native WebTransport server configuration.
|
||||
pub use self::webtransport::WebTransportServerConfig;
|
||||
#[cfg(not(target_arch = "wasm32"))]
|
||||
/// Re-export of native WebTransport server TLS identity material.
|
||||
pub use self::webtransport::WebTransportServerIdentity;
|
||||
#[cfg(not(target_arch = "wasm32"))]
|
||||
/// Re-export of an established native WebTransport session.
|
||||
pub use self::webtransport::WebTransportSession;
|
||||
#[cfg(not(target_arch = "wasm32"))]
|
||||
/// Re-export of the native WebTransport client establishment function.
|
||||
pub use self::webtransport::connect;
|
||||
#[cfg(target_arch = "wasm32")]
|
||||
/// Re-export of the pinned SHA-256 certificate fingerprint used by the browser WebTransport client.
|
||||
pub use self::webtransport_wasm::WebTransportCertificateHash;
|
||||
#[cfg(target_arch = "wasm32")]
|
||||
/// Re-export of browser WebTransport client configuration.
|
||||
pub use self::webtransport_wasm::WebTransportClientConfig;
|
||||
#[cfg(target_arch = "wasm32")]
|
||||
/// Re-export of an established browser WebTransport connection adapted to the transport-neutral realtime contract.
|
||||
pub use self::webtransport_wasm::WebTransportConnection;
|
||||
#[cfg(target_arch = "wasm32")]
|
||||
/// Re-export of the receive half of the browser primary reliable WebTransport stream.
|
||||
pub use self::webtransport_wasm::WebTransportReceiver;
|
||||
#[cfg(target_arch = "wasm32")]
|
||||
/// Re-export of the send half of the browser primary reliable WebTransport stream.
|
||||
pub use self::webtransport_wasm::WebTransportSender;
|
||||
#[cfg(target_arch = "wasm32")]
|
||||
/// Re-export of an established browser WebTransport session.
|
||||
pub use self::webtransport_wasm::WebTransportSession;
|
||||
#[cfg(target_arch = "wasm32")]
|
||||
/// Re-export of the browser WebTransport client establishment function.
|
||||
pub use self::webtransport_wasm::connect;
|
||||
|
||||
@@ -0,0 +1,519 @@
|
||||
// file: crates/common/game-realtime-webtransport-lib/src/webtransport_wasm.rs
|
||||
// version: 1
|
||||
|
||||
const CERTIFICATE_HASH_SIZE: usize = 32;
|
||||
const FRAME_PROTOCOL_ERROR_CODE: u32 = 0x10;
|
||||
const FRAME_TOO_LARGE_ERROR_CODE: u32 = 0x11;
|
||||
const PRIMARY_FRAME_HEADER_SIZE: usize = 4;
|
||||
const STREAM_CANCELLED_ERROR_CODE: u32 = 0x14;
|
||||
const TRACING_TARGET: &str = "games::realtime::webtransport";
|
||||
|
||||
/// SHA-256 fingerprint of one certificate accepted by the browser WebTransport client.
|
||||
#[derive(Clone, Debug, Eq, PartialEq)]
|
||||
pub struct WebTransportCertificateHash {
|
||||
bytes: [u8; CERTIFICATE_HASH_SIZE],
|
||||
}
|
||||
|
||||
impl WebTransportCertificateHash {
|
||||
/// Creates a fingerprint from an already-computed SHA-256 digest.
|
||||
#[must_use]
|
||||
pub fn from_sha256(bytes: [u8; CERTIFICATE_HASH_SIZE]) -> Self {
|
||||
return Self { bytes };
|
||||
}
|
||||
|
||||
/// Returns the exact 32-byte SHA-256 digest.
|
||||
#[must_use]
|
||||
pub fn as_bytes(&self) -> &[u8; CERTIFICATE_HASH_SIZE] {
|
||||
return &self.bytes;
|
||||
}
|
||||
}
|
||||
|
||||
/// Browser WebTransport endpoint, certificate pin and reliable-path configuration.
|
||||
#[derive(Clone, Debug, Eq, PartialEq)]
|
||||
pub struct WebTransportClientConfig {
|
||||
endpoint: url::Url,
|
||||
certificate_hash: WebTransportCertificateHash,
|
||||
transport: crate::WebTransportConfig,
|
||||
}
|
||||
|
||||
impl WebTransportClientConfig {
|
||||
/// Parses and validates a secure WebTransport endpoint with one pinned SHA-256 certificate fingerprint.
|
||||
pub fn new(endpoint: &str, certificate_hash: WebTransportCertificateHash) -> Result<Self, game_realtime_transport_lib::TransportError> {
|
||||
let parsed = match url::Url::parse(endpoint) {
|
||||
Ok(value) => value,
|
||||
Err(error) => return Err(invalid_configuration(error.to_string())),
|
||||
};
|
||||
if parsed.scheme() != "https" {
|
||||
return Err(invalid_configuration("WebTransport endpoint scheme must be https"));
|
||||
}
|
||||
if parsed.host().is_none() {
|
||||
return Err(invalid_configuration("WebTransport endpoint must contain a host"));
|
||||
}
|
||||
return Ok(Self { endpoint: parsed, certificate_hash, transport: crate::WebTransportConfig::default() });
|
||||
}
|
||||
|
||||
/// Returns a copy with explicit reliable-path limits and deadlines.
|
||||
///
|
||||
/// The browser compile path applies the message-size limit immediately. Browser-side operation deadlines are
|
||||
/// validated here but remain a runtime-interoperability concern for the dedicated browser smoke tranche.
|
||||
#[must_use]
|
||||
pub fn with_transport_config(mut self, transport: crate::WebTransportConfig) -> Self {
|
||||
self.transport = transport;
|
||||
return self;
|
||||
}
|
||||
|
||||
/// Returns the validated WebTransport endpoint URL.
|
||||
#[must_use]
|
||||
pub fn endpoint(&self) -> &str {
|
||||
return self.endpoint.as_str();
|
||||
}
|
||||
|
||||
/// Returns the pinned SHA-256 server-certificate fingerprint.
|
||||
#[must_use]
|
||||
pub fn certificate_hash(&self) -> &WebTransportCertificateHash {
|
||||
return &self.certificate_hash;
|
||||
}
|
||||
|
||||
/// Returns the reliable-path limits and deadlines.
|
||||
#[must_use]
|
||||
pub fn transport_config(&self) -> crate::WebTransportConfig {
|
||||
return self.transport;
|
||||
}
|
||||
}
|
||||
|
||||
/// Established browser WebTransport session before the primary application stream is selected.
|
||||
pub struct WebTransportSession {
|
||||
inner: web_transport_wasm::Session,
|
||||
transport: crate::WebTransportConfig,
|
||||
}
|
||||
|
||||
impl WebTransportSession {
|
||||
fn new(inner: web_transport_wasm::Session, transport: crate::WebTransportConfig) -> Self {
|
||||
return Self { inner, transport };
|
||||
}
|
||||
|
||||
/// Opens the single primary bidirectional stream and adapts it to the transport-neutral realtime contract.
|
||||
pub async fn open_primary_connection(self) -> Result<WebTransportConnection, game_realtime_transport_lib::TransportError> {
|
||||
let (sender, receiver) = match self.inner.open_bi().await {
|
||||
Ok(value) => value,
|
||||
Err(error) => {
|
||||
let mapped = transport_error(game_realtime_transport_lib::TransportErrorKind::Protocol, error.to_string());
|
||||
tracing::warn!(target: TRACING_TARGET, detail = mapped.detail(), "browser WebTransport primary bidirectional stream open failed");
|
||||
return Err(mapped);
|
||||
},
|
||||
};
|
||||
tracing::debug!(target: TRACING_TARGET, endpoint = self.inner.url().as_str(), "browser WebTransport primary bidirectional stream opened");
|
||||
return Ok(WebTransportConnection::new(self.inner, sender, receiver, self.transport));
|
||||
}
|
||||
|
||||
/// Returns the endpoint URL backing this browser WebTransport session.
|
||||
#[must_use]
|
||||
pub fn endpoint(&self) -> &str {
|
||||
return self.inner.url().as_str();
|
||||
}
|
||||
}
|
||||
|
||||
/// Established browser WebTransport connection carrying the single reliable primary stream.
|
||||
pub struct WebTransportConnection {
|
||||
receiver: web_transport_wasm::RecvStream,
|
||||
sender: web_transport_wasm::SendStream,
|
||||
session: web_transport_wasm::Session,
|
||||
transport: crate::WebTransportConfig,
|
||||
}
|
||||
|
||||
impl WebTransportConnection {
|
||||
fn new(
|
||||
session: web_transport_wasm::Session,
|
||||
sender: web_transport_wasm::SendStream,
|
||||
receiver: web_transport_wasm::RecvStream,
|
||||
transport: crate::WebTransportConfig,
|
||||
) -> Self {
|
||||
return Self { receiver, sender, session, transport };
|
||||
}
|
||||
}
|
||||
|
||||
impl game_realtime_transport_lib::RealtimeConnection for WebTransportConnection {
|
||||
type Receiver = crate::WebTransportReceiver;
|
||||
type Sender = crate::WebTransportSender;
|
||||
|
||||
fn split(self) -> (Self::Sender, Self::Receiver) {
|
||||
let receiver_session = self.session.clone();
|
||||
return (
|
||||
crate::WebTransportSender {
|
||||
inner: self.sender,
|
||||
_session: self.session,
|
||||
max_message_size: self.transport.max_message_size(),
|
||||
terminal: false,
|
||||
},
|
||||
crate::WebTransportReceiver {
|
||||
inner: self.receiver,
|
||||
_session: receiver_session,
|
||||
max_message_size: self.transport.max_message_size(),
|
||||
header: [0_u8; PRIMARY_FRAME_HEADER_SIZE],
|
||||
header_read: 0,
|
||||
payload: Vec::new(),
|
||||
payload_read: 0,
|
||||
clean_closed: false,
|
||||
terminal: false,
|
||||
},
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
/// Receive half of the browser primary reliable WebTransport stream.
|
||||
pub struct WebTransportReceiver {
|
||||
inner: web_transport_wasm::RecvStream,
|
||||
_session: web_transport_wasm::Session,
|
||||
max_message_size: usize,
|
||||
header: [u8; PRIMARY_FRAME_HEADER_SIZE],
|
||||
header_read: usize,
|
||||
payload: Vec<u8>,
|
||||
payload_read: usize,
|
||||
clean_closed: bool,
|
||||
terminal: bool,
|
||||
}
|
||||
|
||||
impl WebTransportReceiver {
|
||||
/// Abruptly stops the reliable receive direction with one WebTransport application error code.
|
||||
pub fn abort(&mut self, code: u32) -> Result<(), game_realtime_transport_lib::TransportError> {
|
||||
if self.clean_closed || self.terminal {
|
||||
return Err(transport_error(game_realtime_transport_lib::TransportErrorKind::Closed, "browser WebTransport receiver is already terminal"));
|
||||
}
|
||||
self.inner.stop(code);
|
||||
self.terminal = true;
|
||||
tracing::debug!(target: TRACING_TARGET, code = code, "browser WebTransport primary receive stream aborted");
|
||||
return Ok(());
|
||||
}
|
||||
|
||||
async fn receive_frame(&mut self) -> Result<game_realtime_transport_lib::TransportReceive, game_realtime_transport_lib::TransportError> {
|
||||
if self.clean_closed {
|
||||
return Ok(game_realtime_transport_lib::TransportReceive::Closed);
|
||||
}
|
||||
if self.terminal {
|
||||
return Err(transport_error(
|
||||
game_realtime_transport_lib::TransportErrorKind::Aborted,
|
||||
"browser WebTransport receiver is unavailable after a terminal stream failure or abort",
|
||||
));
|
||||
}
|
||||
loop {
|
||||
if self.header_read < PRIMARY_FRAME_HEADER_SIZE {
|
||||
let remaining = PRIMARY_FRAME_HEADER_SIZE - self.header_read;
|
||||
let read = self.inner.read(remaining).await;
|
||||
match read {
|
||||
Ok(Some(chunk)) => {
|
||||
if chunk.is_empty() {
|
||||
return self.fail_protocol("browser WebTransport primary stream returned an empty read in the middle of a frame header");
|
||||
}
|
||||
let end = self.header_read + chunk.len();
|
||||
self.header[self.header_read..end].copy_from_slice(chunk.as_ref());
|
||||
self.header_read = end;
|
||||
continue;
|
||||
},
|
||||
Ok(None) => {
|
||||
if self.header_read == 0 {
|
||||
self.clean_closed = true;
|
||||
tracing::debug!(target: TRACING_TARGET, "remote browser WebTransport primary stream closed cleanly");
|
||||
return Ok(game_realtime_transport_lib::TransportReceive::Closed);
|
||||
}
|
||||
return self.fail_protocol("browser WebTransport primary stream closed in the middle of a frame header");
|
||||
},
|
||||
Err(error) => return self.fail_read(error),
|
||||
}
|
||||
}
|
||||
if self.payload.is_empty() && self.payload_read == 0 {
|
||||
let payload_len = u32::from_be_bytes(self.header) as usize;
|
||||
if payload_len > self.max_message_size {
|
||||
let error = message_too_large(payload_len, self.max_message_size);
|
||||
self.stop_after_failure(FRAME_TOO_LARGE_ERROR_CODE);
|
||||
return Err(error);
|
||||
}
|
||||
if payload_len == 0 {
|
||||
self.reset_frame_state();
|
||||
tracing::trace!(target: TRACING_TARGET, payload_len = 0, "framed browser WebTransport payload received");
|
||||
return Ok(game_realtime_transport_lib::TransportReceive::Message(game_realtime_transport_lib::TransportMessage::new(Vec::new())));
|
||||
}
|
||||
self.payload = vec![0_u8; payload_len];
|
||||
}
|
||||
if self.payload_read < self.payload.len() {
|
||||
let remaining = self.payload.len() - self.payload_read;
|
||||
let read = self.inner.read(remaining).await;
|
||||
match read {
|
||||
Ok(Some(chunk)) => {
|
||||
if chunk.is_empty() {
|
||||
return self.fail_protocol("browser WebTransport primary stream returned an empty read in the middle of a frame payload");
|
||||
}
|
||||
let end = self.payload_read + chunk.len();
|
||||
self.payload[self.payload_read..end].copy_from_slice(chunk.as_ref());
|
||||
self.payload_read = end;
|
||||
if self.payload_read < self.payload.len() {
|
||||
continue;
|
||||
}
|
||||
},
|
||||
Ok(None) => return self.fail_protocol("browser WebTransport primary stream closed in the middle of a frame payload"),
|
||||
Err(error) => return self.fail_read(error),
|
||||
}
|
||||
}
|
||||
let payload = core::mem::take(&mut self.payload);
|
||||
self.reset_frame_state();
|
||||
tracing::trace!(target: TRACING_TARGET, payload_len = payload.len(), "framed browser WebTransport payload received");
|
||||
return Ok(game_realtime_transport_lib::TransportReceive::Message(game_realtime_transport_lib::TransportMessage::new(payload)));
|
||||
}
|
||||
}
|
||||
|
||||
fn fail_protocol(&mut self, detail: &str) -> Result<game_realtime_transport_lib::TransportReceive, game_realtime_transport_lib::TransportError> {
|
||||
let error = protocol_error(detail);
|
||||
self.stop_after_failure(FRAME_PROTOCOL_ERROR_CODE);
|
||||
return Err(error);
|
||||
}
|
||||
|
||||
fn fail_read(
|
||||
&mut self,
|
||||
error: web_transport_wasm::Error,
|
||||
) -> Result<game_realtime_transport_lib::TransportReceive, game_realtime_transport_lib::TransportError> {
|
||||
self.terminal = true;
|
||||
let mapped = map_read_error(error);
|
||||
tracing::warn!(target: TRACING_TARGET, kind = %mapped.kind(), detail = mapped.detail(), "browser WebTransport primary stream receive failed");
|
||||
return Err(mapped);
|
||||
}
|
||||
|
||||
fn reset_frame_state(&mut self) {
|
||||
self.header = [0_u8; PRIMARY_FRAME_HEADER_SIZE];
|
||||
self.header_read = 0;
|
||||
self.payload.clear();
|
||||
self.payload_read = 0;
|
||||
}
|
||||
|
||||
fn stop_after_failure(&mut self, code: u32) {
|
||||
self.inner.stop(code);
|
||||
self.terminal = true;
|
||||
}
|
||||
}
|
||||
|
||||
impl Drop for WebTransportReceiver {
|
||||
fn drop(&mut self) {
|
||||
if !self.clean_closed && !self.terminal {
|
||||
self.inner.stop(STREAM_CANCELLED_ERROR_CODE);
|
||||
self.terminal = true;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl game_realtime_transport_lib::RealtimeReceiver for WebTransportReceiver {
|
||||
type ReceiveFuture<'a>
|
||||
= std::pin::Pin<
|
||||
Box<dyn core::future::Future<Output = Result<game_realtime_transport_lib::TransportReceive, game_realtime_transport_lib::TransportError>> + 'a>,
|
||||
>
|
||||
where
|
||||
Self: 'a;
|
||||
|
||||
fn receive(&mut self) -> Self::ReceiveFuture<'_> {
|
||||
return Box::pin(async move { return self.receive_frame().await });
|
||||
}
|
||||
}
|
||||
|
||||
/// Send half of the browser primary reliable WebTransport stream.
|
||||
pub struct WebTransportSender {
|
||||
inner: web_transport_wasm::SendStream,
|
||||
_session: web_transport_wasm::Session,
|
||||
max_message_size: usize,
|
||||
terminal: bool,
|
||||
}
|
||||
|
||||
impl WebTransportSender {
|
||||
/// Abruptly resets the reliable send direction with one WebTransport application error code.
|
||||
pub fn abort(&mut self, code: u32) -> Result<(), game_realtime_transport_lib::TransportError> {
|
||||
if self.terminal {
|
||||
return Err(transport_error(game_realtime_transport_lib::TransportErrorKind::Closed, "browser WebTransport sender is already terminal"));
|
||||
}
|
||||
self.inner.reset(code);
|
||||
self.terminal = true;
|
||||
tracing::debug!(target: TRACING_TARGET, code = code, "browser WebTransport primary send stream aborted");
|
||||
return Ok(());
|
||||
}
|
||||
}
|
||||
|
||||
impl Drop for WebTransportSender {
|
||||
fn drop(&mut self) {
|
||||
if !self.terminal {
|
||||
self.inner.reset(STREAM_CANCELLED_ERROR_CODE);
|
||||
self.terminal = true;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl game_realtime_transport_lib::RealtimeSender for WebTransportSender {
|
||||
type CloseFuture<'a>
|
||||
= std::pin::Pin<Box<dyn core::future::Future<Output = Result<(), game_realtime_transport_lib::TransportError>> + 'a>>
|
||||
where
|
||||
Self: 'a;
|
||||
type SendFuture<'a>
|
||||
= std::pin::Pin<Box<dyn core::future::Future<Output = Result<(), game_realtime_transport_lib::TransportError>> + 'a>>
|
||||
where
|
||||
Self: 'a;
|
||||
|
||||
fn close(&mut self) -> Self::CloseFuture<'_> {
|
||||
return Box::pin(async move {
|
||||
if self.terminal {
|
||||
return Err(transport_error(game_realtime_transport_lib::TransportErrorKind::Closed, "browser WebTransport sender is already terminal"));
|
||||
}
|
||||
self.terminal = true;
|
||||
return match self.inner.finish() {
|
||||
Ok(()) => {
|
||||
tracing::debug!(target: TRACING_TARGET, "local browser WebTransport primary stream close initiated");
|
||||
Ok(())
|
||||
},
|
||||
Err(error) => {
|
||||
let mapped = map_write_error(error);
|
||||
tracing::warn!(target: TRACING_TARGET, detail = mapped.detail(), "browser WebTransport primary stream close failed");
|
||||
Err(mapped)
|
||||
},
|
||||
};
|
||||
});
|
||||
}
|
||||
|
||||
fn send(&mut self, message: game_realtime_transport_lib::TransportMessage) -> Self::SendFuture<'_> {
|
||||
return Box::pin(async move {
|
||||
if self.terminal {
|
||||
return Err(transport_error(
|
||||
game_realtime_transport_lib::TransportErrorKind::Aborted,
|
||||
"browser WebTransport sender is unavailable after close, abort, cancellation or terminal send failure",
|
||||
));
|
||||
}
|
||||
let payload_len = message.len();
|
||||
let frame_header = match frame_header(payload_len, self.max_message_size) {
|
||||
Ok(value) => value,
|
||||
Err(error) => return Err(error),
|
||||
};
|
||||
let mut guard = SendOperationGuard::new(&mut self.inner, &mut self.terminal);
|
||||
if let Err(error) = guard.write_frame(&frame_header, message.as_bytes()).await {
|
||||
let mapped = map_write_error(error);
|
||||
guard.abort();
|
||||
tracing::warn!(target: TRACING_TARGET, kind = %mapped.kind(), detail = mapped.detail(), "browser WebTransport framed send failed");
|
||||
return Err(mapped);
|
||||
}
|
||||
guard.disarm();
|
||||
tracing::trace!(target: TRACING_TARGET, payload_len = payload_len, "framed browser WebTransport payload sent");
|
||||
return Ok(());
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
struct SendOperationGuard<'a> {
|
||||
inner: &'a mut web_transport_wasm::SendStream,
|
||||
terminal: &'a mut bool,
|
||||
armed: bool,
|
||||
}
|
||||
|
||||
impl<'a> SendOperationGuard<'a> {
|
||||
fn new(inner: &'a mut web_transport_wasm::SendStream, terminal: &'a mut bool) -> Self {
|
||||
return Self { inner, terminal, armed: true };
|
||||
}
|
||||
|
||||
fn abort(&mut self) {
|
||||
if self.armed {
|
||||
self.inner.reset(STREAM_CANCELLED_ERROR_CODE);
|
||||
*self.terminal = true;
|
||||
self.armed = false;
|
||||
}
|
||||
}
|
||||
|
||||
fn disarm(&mut self) {
|
||||
self.armed = false;
|
||||
}
|
||||
|
||||
async fn write_frame(&mut self, frame_header: &[u8; PRIMARY_FRAME_HEADER_SIZE], payload: &[u8]) -> Result<(), web_transport_wasm::Error> {
|
||||
match self.inner.write(frame_header).await {
|
||||
Ok(()) => {},
|
||||
Err(error) => return Err(error),
|
||||
}
|
||||
if !payload.is_empty() {
|
||||
match self.inner.write(payload).await {
|
||||
Ok(()) => {},
|
||||
Err(error) => return Err(error),
|
||||
}
|
||||
}
|
||||
return Ok(());
|
||||
}
|
||||
}
|
||||
|
||||
impl Drop for SendOperationGuard<'_> {
|
||||
fn drop(&mut self) {
|
||||
self.abort();
|
||||
}
|
||||
}
|
||||
|
||||
/// Establishes one browser WebTransport session using an exact SHA-256 certificate pin.
|
||||
pub async fn connect(config: &WebTransportClientConfig) -> Result<WebTransportSession, game_realtime_transport_lib::TransportError> {
|
||||
if let Err(error) = config.transport.validate() {
|
||||
return Err(error);
|
||||
}
|
||||
let client = web_transport_wasm::ClientBuilder::new()
|
||||
.with_pooling(false)
|
||||
.with_unreliable(true)
|
||||
.with_server_certificate_hashes(vec![config.certificate_hash.as_bytes().to_vec()]);
|
||||
let session = match client.connect(config.endpoint.clone()).await {
|
||||
Ok(value) => value,
|
||||
Err(error) => {
|
||||
let mapped = transport_error(game_realtime_transport_lib::TransportErrorKind::Connect, error.to_string());
|
||||
tracing::warn!(
|
||||
target: TRACING_TARGET,
|
||||
endpoint = config.endpoint.as_str(),
|
||||
detail = mapped.detail(),
|
||||
"browser WebTransport client connection failed"
|
||||
);
|
||||
return Err(mapped);
|
||||
},
|
||||
};
|
||||
tracing::info!(target: TRACING_TARGET, endpoint = config.endpoint.as_str(), "browser WebTransport client connected");
|
||||
return Ok(WebTransportSession::new(session, config.transport));
|
||||
}
|
||||
|
||||
fn frame_header(payload_len: usize, max_message_size: usize) -> Result<[u8; PRIMARY_FRAME_HEADER_SIZE], game_realtime_transport_lib::TransportError> {
|
||||
if payload_len > max_message_size {
|
||||
return Err(message_too_large(payload_len, max_message_size));
|
||||
}
|
||||
let payload_len = match u32::try_from(payload_len) {
|
||||
Ok(value) => value,
|
||||
Err(_) => return Err(message_too_large(payload_len, max_message_size)),
|
||||
};
|
||||
return Ok(payload_len.to_be_bytes());
|
||||
}
|
||||
|
||||
fn invalid_configuration(detail: impl Into<String>) -> game_realtime_transport_lib::TransportError {
|
||||
return transport_error(game_realtime_transport_lib::TransportErrorKind::InvalidConfiguration, detail);
|
||||
}
|
||||
|
||||
fn map_read_error(error: web_transport_wasm::Error) -> game_realtime_transport_lib::TransportError {
|
||||
let kind = match &error {
|
||||
web_transport_wasm::Error::Closed => game_realtime_transport_lib::TransportErrorKind::Closed,
|
||||
web_transport_wasm::Error::Session { .. } => game_realtime_transport_lib::TransportErrorKind::Closed,
|
||||
web_transport_wasm::Error::Stream(_) => game_realtime_transport_lib::TransportErrorKind::Aborted,
|
||||
web_transport_wasm::Error::Unknown(_) => game_realtime_transport_lib::TransportErrorKind::Io,
|
||||
};
|
||||
return transport_error(kind, error.to_string());
|
||||
}
|
||||
|
||||
fn map_write_error(error: web_transport_wasm::Error) -> game_realtime_transport_lib::TransportError {
|
||||
let kind = match &error {
|
||||
web_transport_wasm::Error::Closed => game_realtime_transport_lib::TransportErrorKind::Closed,
|
||||
web_transport_wasm::Error::Session { .. } => game_realtime_transport_lib::TransportErrorKind::Closed,
|
||||
web_transport_wasm::Error::Stream(_) => game_realtime_transport_lib::TransportErrorKind::Aborted,
|
||||
web_transport_wasm::Error::Unknown(_) => game_realtime_transport_lib::TransportErrorKind::Io,
|
||||
};
|
||||
return transport_error(kind, error.to_string());
|
||||
}
|
||||
|
||||
fn message_too_large(payload_len: usize, max_message_size: usize) -> game_realtime_transport_lib::TransportError {
|
||||
return transport_error(
|
||||
game_realtime_transport_lib::TransportErrorKind::MessageTooLarge,
|
||||
format!("WebTransport framed payload length {payload_len} exceeds configured maximum {max_message_size}"),
|
||||
);
|
||||
}
|
||||
|
||||
fn protocol_error(detail: impl Into<String>) -> game_realtime_transport_lib::TransportError {
|
||||
return transport_error(game_realtime_transport_lib::TransportErrorKind::Protocol, detail);
|
||||
}
|
||||
|
||||
fn transport_error(kind: game_realtime_transport_lib::TransportErrorKind, detail: impl Into<String>) -> game_realtime_transport_lib::TransportError {
|
||||
return game_realtime_transport_lib::TransportError::new(kind, detail);
|
||||
}
|
||||
155
deltas/0.3.5/alpha.6.md
Normal file
155
deltas/0.3.5/alpha.6.md
Normal file
@@ -0,0 +1,155 @@
|
||||
<!-- file: deltas/0.3.5/alpha.6.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Delta 0.3.5-alpha.6
|
||||
|
||||
## Base requise
|
||||
|
||||
`0.3.5-alpha.5`, validée par l'utilisateur le 2026-09-21 avec fmt, audits, `cargo check`, Clippy strict, les sept tests du contrat realtime commun, les vingt tests WebTransport, le smoke natif hors harness avec verdict `PASS` et les graphes de dépendances attendus.
|
||||
|
||||
La preuve est enregistrée dans `history/0.3.5/alpha.5.md`.
|
||||
|
||||
## Objectif
|
||||
|
||||
Fermer la preuve de compilation du client WebTransport Rust en `wasm32-unknown-unknown` sans encore créer de host navigateur ni attribuer un smoke runtime.
|
||||
|
||||
Cette tranche doit conserver le backend natif intact tout en donnant au navigateur le même contrat fiable : pin SHA-256 explicite, session WebTransport, stream bidirectionnel primaire, framing `u32` big-endian + payload et `RealtimeConnection`.
|
||||
|
||||
## Version
|
||||
|
||||
La version workspace passe à :
|
||||
|
||||
```text
|
||||
0.3.5-alpha.6
|
||||
```
|
||||
|
||||
## Dépendances et cfg
|
||||
|
||||
La contrainte workspace suivante est ajoutée :
|
||||
|
||||
```text
|
||||
web-transport-wasm = 0.6.0
|
||||
```
|
||||
|
||||
Dans `game-realtime-webtransport-lib` :
|
||||
|
||||
- `rcgen`, Tokio et `web-transport-quinn` deviennent des dépendances uniquement non-WASM ;
|
||||
- `web-transport-wasm` est tirée uniquement pour `target_arch = "wasm32"` ;
|
||||
- les dev-dependencies Tokio de la suite native restent elles aussi non-WASM.
|
||||
|
||||
`.cargo/config.toml` fournit uniquement à `wasm32-unknown-unknown` :
|
||||
|
||||
```text
|
||||
--cfg=web_sys_unstable_apis
|
||||
```
|
||||
|
||||
Le flag est déclaré pour rustc et rustdoc ; aucun build natif ne le reçoit.
|
||||
|
||||
## Client WASM
|
||||
|
||||
Le module WASM expose sous le même nom que le client natif :
|
||||
|
||||
```text
|
||||
WebTransportCertificateHash
|
||||
WebTransportClientConfig
|
||||
connect
|
||||
WebTransportSession
|
||||
WebTransportConnection
|
||||
WebTransportSender
|
||||
WebTransportReceiver
|
||||
```
|
||||
|
||||
Les types serveur natifs restent absents du target WASM.
|
||||
|
||||
Le client navigateur :
|
||||
|
||||
1. valide un endpoint `https://` ;
|
||||
2. transmet le hash SHA-256 exact via `serverCertificateHashes` ;
|
||||
3. exige le chemin WebTransport/QUIC sans fallback TCP implicite du wrapper ;
|
||||
4. établit une session navigateur ;
|
||||
5. ouvre le stream bidirectionnel primaire ;
|
||||
6. adapte le stream au contrat `game-realtime-transport-lib`.
|
||||
|
||||
Le framing reste :
|
||||
|
||||
```text
|
||||
u32 big-endian payload length
|
||||
payload bytes
|
||||
```
|
||||
|
||||
La limite configurée est contrôlée avant écriture et avant allocation. Le sender applique FIN et reset ; le receiver applique STOP_SENDING et conserve un parseur incrémental compatible avec l'abandon/reprise d'une future de réception.
|
||||
|
||||
Les types navigateur sont `!Send`, mais le contrat `RealtimeConnection` n'impose volontairement aucun bound `Send`; aucune modification du contrat commun n'est donc nécessaire.
|
||||
|
||||
## Différence runtime explicitement différée
|
||||
|
||||
`WebTransportConfig` continue de valider `connect_timeout`, `primary_stream_timeout` et `send_timeout` afin de ne pas accepter une configuration incohérente. Dans `alpha.6`, ces deadlines ne sont cependant pas encore matérialisées par un timer côté navigateur.
|
||||
|
||||
Le wrapper `web-transport-wasm` conserve ses opérations Web API abandonnées dans son état de polling ; la tranche `alpha.7` doit fixer puis prouver la politique de timeout/runtime avec un vrai navigateur avant de déclarer la parité comportementale avec le chemin natif.
|
||||
|
||||
Cette différence est documentée et n'est pas masquée comme une validation runtime.
|
||||
|
||||
## Fichiers modifiés
|
||||
|
||||
```text
|
||||
.cargo/config.toml
|
||||
Cargo.toml
|
||||
README.md
|
||||
crates/common/game-realtime-webtransport-lib/Cargo.toml
|
||||
crates/common/game-realtime-webtransport-lib/README.md
|
||||
crates/common/game-realtime-webtransport-lib/USAGE.md
|
||||
crates/common/game-realtime-webtransport-lib/src/config.rs
|
||||
crates/common/game-realtime-webtransport-lib/src/lib.rs
|
||||
docs/plans/005-V0_3_5_WEBTRANSPORT_QUIC_POC_PLAN.md
|
||||
```
|
||||
|
||||
Nouveaux fichiers :
|
||||
|
||||
```text
|
||||
crates/common/game-realtime-webtransport-lib/src/webtransport_wasm.rs
|
||||
deltas/0.3.5/alpha.6.md
|
||||
history/0.3.5/alpha.5.md
|
||||
```
|
||||
|
||||
## Validation attendue
|
||||
|
||||
Gate native de non-régression :
|
||||
|
||||
```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 Android Web deltas history
|
||||
python3 scripts/audit_distribution_layout.py
|
||||
|
||||
cargo check --workspace
|
||||
cargo clippy --workspace --all-targets --all-features -- -D warnings
|
||||
|
||||
cargo test -p game-realtime-transport-lib --all-targets --all-features
|
||||
cargo test -p game-realtime-webtransport-lib --all-targets --all-features
|
||||
cargo run -p game-realtime-webtransport-smoke
|
||||
```
|
||||
|
||||
Gate WASM ciblée :
|
||||
|
||||
```bash
|
||||
cargo check -p game-realtime-webtransport-lib --target wasm32-unknown-unknown
|
||||
cargo clippy -p game-realtime-webtransport-lib --target wasm32-unknown-unknown --lib -- -D warnings
|
||||
cargo build -p game-realtime-webtransport-lib --target wasm32-unknown-unknown
|
||||
|
||||
cargo tree -p game-realtime-webtransport-lib --target wasm32-unknown-unknown --edges normal
|
||||
cargo tree -i web-transport-wasm --workspace --target wasm32-unknown-unknown --edges normal
|
||||
```
|
||||
|
||||
Le build WASM ne doit tirer ni `web-transport-quinn`, ni rcgen, ni le runtime Tokio du backend natif.
|
||||
|
||||
Le smoke natif doit toujours se terminer par :
|
||||
|
||||
```text
|
||||
game-realtime-webtransport-smoke: PASS
|
||||
```
|
||||
|
||||
## Après validation
|
||||
|
||||
Créer `history/0.3.5/alpha.6.md` à partir des sorties réellement fournies, puis ouvrir `0.3.5-alpha.7` pour le smoke navigateur/TLS local réel et la fermeture de la politique de deadlines navigateur.
|
||||
@@ -1,11 +1,11 @@
|
||||
<!-- file: docs/plans/005-V0_3_5_WEBTRANSPORT_QUIC_POC_PLAN.md -->
|
||||
<!-- version: 7 -->
|
||||
<!-- version: 8 -->
|
||||
|
||||
# Plan 0.3.5 — POC WebTransport/QUIC et fallback WebSocket
|
||||
|
||||
## Statut
|
||||
|
||||
Plan actif créé pendant `0.3.5-alpha.1` à partir de l'archive taggée `v0.3.4`, puis réconcilié pour l'implémentation native de `0.3.5-alpha.2`, son correctif de validation `0.3.5-alpha.2.fix.1`, le chemin fiable validé de `0.3.5-alpha.3`, la robustesse validée par `0.3.5-alpha.4.fix.1` et le smoke natif candidat de `0.3.5-alpha.5`.
|
||||
Plan actif créé pendant `0.3.5-alpha.1` à partir de l'archive taggée `v0.3.4`, puis réconcilié pour l'implémentation native de `0.3.5-alpha.2`, son correctif de validation `0.3.5-alpha.2.fix.1`, le chemin fiable validé de `0.3.5-alpha.3`, la robustesse validée par `0.3.5-alpha.4.fix.1`, le smoke natif validé de `0.3.5-alpha.5` et le chemin client WASM candidat de `0.3.5-alpha.6`.
|
||||
|
||||
Le cadrage détaillé et la comparaison des stacks actuelles sont conservés dans `docs/studies/026-V0_3_5_WEBTRANSPORT_QUIC_STACK_AUDIT.md`. Le présent document porte les décisions opérationnelles, le scope, les gates et le forecast vivant de la version.
|
||||
|
||||
@@ -461,7 +461,7 @@ La gate utilisateur de `alpha.4` a confirmé fmt, audits, `cargo check`, tous le
|
||||
|
||||
### `0.3.5-alpha.5` — smoke natif hors harness
|
||||
|
||||
Tranche candidate matérialisée avec :
|
||||
Tranche validée avec :
|
||||
|
||||
- nouvelle app technique `game-realtime-webtransport-smoke` ;
|
||||
- bind UDP loopback sur port éphémère ;
|
||||
@@ -473,20 +473,29 @@ Tranche candidate matérialisée avec :
|
||||
- timeout global du launcher et verdict terminal déterministe `game-realtime-webtransport-smoke: PASS` ;
|
||||
- aucune nouvelle dépendance externe et aucun couplage engine/gameplay.
|
||||
|
||||
Cette tranche reste distincte pour ne pas mélanger robustesse de bibliothèque et preuve runtime publique. La gate doit exécuter le smoke hors harness puis contrôler les graphes direct et inverse : l'inverse de `game-realtime-webtransport-lib` peut désormais contenir le launcher technique, mais aucune crate engine ou gameplay.
|
||||
Cette tranche reste distincte pour ne pas mélanger robustesse de bibliothèque et preuve runtime publique. La gate utilisateur du 2026-09-21 a confirmé fmt, audits, check workspace, Clippy strict, les sept tests du contrat commun, les vingt tests WebTransport, le smoke hors harness avec verdict `PASS` et les graphes direct/inverse attendus. La preuve est conservée dans `history/0.3.5/alpha.5.md`.
|
||||
|
||||
### `0.3.5-alpha.6` — chemin WASM compilable
|
||||
|
||||
- activer `web_sys_unstable_apis` uniquement pour `wasm32-unknown-unknown` ;
|
||||
- implémenter/adapter le client WASM ;
|
||||
- prouver le build/check WASM ciblé ;
|
||||
- ne pas modifier Snake ou Reflex ;
|
||||
- documenter les différences native/WASM réellement rencontrées.
|
||||
Tranche candidate matérialisée avec :
|
||||
|
||||
Si la famille `web-transport` échoue ici, évaluer `wtransport` serveur + API navigateur directe avant de conclure.
|
||||
- `web-transport-wasm 0.6.0` comme dépendance exclusivement `wasm32` ;
|
||||
- `web_sys_unstable_apis` ciblé par Cargo uniquement sur `wasm32-unknown-unknown`, y compris rustdoc ;
|
||||
- dépendances Quinn/Tokio/rcgen du backend déplacées dans la branche native afin que le build WASM ne tire pas la stack serveur ;
|
||||
- même surface client publique qu'en natif pour hash SHA-256, config endpoint, `connect`, session et stream primaire ;
|
||||
- pin navigateur transmis via `serverCertificateHashes` ;
|
||||
- même framing fiable `u32` big-endian + payload et même limite avant allocation/écriture ;
|
||||
- `RealtimeConnection`, sender et receiver adaptés à des types navigateur `!Send`, ce que le contrat commun autorise déjà ;
|
||||
- FIN, reset/STOP, cancellation de send terminale et réception incrémentale conservés sur le chemin navigateur ;
|
||||
- aucun changement Snake/Reflex et aucun host frontend.
|
||||
|
||||
Différence explicitement ouverte pour `alpha.7` : les deadlines `WebTransportConfig` sont validées côté WASM mais aucun timer navigateur n'est encore appliqué. Le wrapper amont conserve les opérations Web API abandonnées de manière cancel-safe ; la preuve runtime doit fixer la politique de timer avant de déclarer la parité comportementale.
|
||||
|
||||
La gate de cette tranche doit prouver le host natif inchangé puis `cargo check`, Clippy `--lib` et build réel de `game-realtime-webtransport-lib` sur `wasm32-unknown-unknown`. Si la famille `web-transport` échoue à cette gate, évaluer `wtransport` serveur + API navigateur directe avant de conclure.
|
||||
|
||||
### `0.3.5-alpha.7` — interop navigateur et TLS local
|
||||
|
||||
- fixer puis prouver la politique de deadlines navigateur réellement nécessaire ;
|
||||
- host technique minimal si nécessaire ;
|
||||
- navigateur récent -> serveur Rust WebTransport ;
|
||||
- hash certificat W3C ;
|
||||
|
||||
88
history/0.3.5/alpha.5.md
Normal file
88
history/0.3.5/alpha.5.md
Normal file
@@ -0,0 +1,88 @@
|
||||
<!-- file: history/0.3.5/alpha.5.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Historique 0.3.5-alpha.5
|
||||
|
||||
## Statut
|
||||
|
||||
`0.3.5-alpha.5` a été validée par l'utilisateur le 2026-09-21. Le backend WebTransport natif est donc prouvé hors harness avec identité TLS locale, pin SHA-256 exact, session HTTP/3/WebTransport réelle, stream fiable principal, round-trip bidirectionnel et fermeture propre.
|
||||
|
||||
La suite peut ouvrir `0.3.5-alpha.6` pour le chemin client WASM compilable sans réouvrir la preuve native.
|
||||
|
||||
## Gates statiques et compilation
|
||||
|
||||
Les commandes utilisateur ont terminé proprement :
|
||||
|
||||
```text
|
||||
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 Android Web deltas history
|
||||
python3 scripts/audit_distribution_layout.py
|
||||
cargo check --workspace
|
||||
cargo clippy --workspace --all-targets --all-features -- -D warnings
|
||||
```
|
||||
|
||||
La sortie confirme :
|
||||
|
||||
```text
|
||||
General Rust rule audit: clean
|
||||
Rust export completeness audit: 0 candidate(s)
|
||||
games.sasedev workspace audit: clean
|
||||
Markdown table audit: clean (5 table(s), 294 file(s))
|
||||
Distribution layout audit: clean (50 required path(s), 8 forbidden path(s) absent)
|
||||
cargo check --workspace: clean
|
||||
cargo clippy --workspace --all-targets --all-features -- -D warnings: clean
|
||||
```
|
||||
|
||||
## Tests realtime
|
||||
|
||||
Le contrat commun reste entièrement propre :
|
||||
|
||||
```text
|
||||
game-realtime-transport-lib: 7 passed; 0 failed
|
||||
```
|
||||
|
||||
La suite WebTransport reste entièrement propre :
|
||||
|
||||
```text
|
||||
unit tests: 11 passed; 0 failed
|
||||
establishment integration tests: 2 passed; 0 failed
|
||||
realtime_connection integration tests: 1 passed; 0 failed
|
||||
robustness integration tests: 6 passed; 0 failed
|
||||
```
|
||||
|
||||
Soit vingt tests WebTransport verts.
|
||||
|
||||
## Smoke runtime natif
|
||||
|
||||
La commande :
|
||||
|
||||
```bash
|
||||
cargo run -p game-realtime-webtransport-smoke
|
||||
```
|
||||
|
||||
établit le listener loopback sur un port éphémère, connecte le client avec le hash certificat exact, effectue le round-trip prévu et se termine par :
|
||||
|
||||
```text
|
||||
game-realtime-webtransport-smoke: PASS
|
||||
```
|
||||
|
||||
Le tracing observé confirme aussi l'accept serveur et la connexion client WebTransport réels.
|
||||
|
||||
## Graphe de dépendances
|
||||
|
||||
Le graphe direct du smoke contient uniquement les briques techniques attendues, dont `game-realtime-webtransport-lib`, `game-realtime-transport-lib`, le logging et Tokio.
|
||||
|
||||
Le graphe inverse de `game-realtime-webtransport-lib` contient désormais exactement le consommateur technique attendu :
|
||||
|
||||
```text
|
||||
game-realtime-webtransport-lib
|
||||
└── game-realtime-webtransport-smoke
|
||||
```
|
||||
|
||||
Aucune crate engine ou gameplay n'est remontée dans ce graphe.
|
||||
|
||||
## Conséquence
|
||||
|
||||
`alpha.6` peut introduire la dépendance navigateur de façon strictement target-specific, adapter le client WASM au même contrat fiable et prouver sa compilation `wasm32-unknown-unknown`. Le runtime navigateur, le host frontend et la preuve TLS W3C restent réservés à `alpha.7`.
|
||||
Reference in New Issue
Block a user