0.3.5-alpha.3

crates/common/game-realtime-webtransport-lib/USAGE.md

@@ -0,0 +1,89 @@
+<!-- file: crates/common/game-realtime-webtransport-lib/USAGE.md -->
+<!-- version: 1 -->
+
+# Utilisation de game-realtime-webtransport-lib
+
+Ce guide décrit le chemin natif fiable actuellement exposé par `game-realtime-webtransport-lib`. Il ne décrit ni gameplay, ni protocole wire métier, ni datagrams.
+
+## Serveur natif
+
+Créer d'abord l'identité TLS et le listener :
+
+```rust
+let identity = match game_realtime_webtransport_lib::WebTransportServerIdentity::generate_loopback() {
+    Ok(value) => value,
+    Err(error) => return Err(error),
+};
+let config = game_realtime_webtransport_lib::WebTransportServerConfig::new(
+    std::net::SocketAddr::from(([127, 0, 0, 1], 4433)),
+    identity,
+);
+let mut listener = match game_realtime_webtransport_lib::WebTransportListener::bind(config) {
+    Ok(value) => value,
+    Err(error) => return Err(error),
+};
+let session = match listener.accept().await {
+    Ok(value) => value,
+    Err(error) => return Err(error),
+};
+let connection = match session.accept_primary_connection().await {
+    Ok(value) => value,
+    Err(error) => return Err(error),
+};
+```
+
+`open_primary_connection()` écrit l'en-tête WebTransport requis pour identifier le stream avant de retourner. Le serveur peut donc attendre `accept_primary_connection()` puis commencer les échanges applicatifs ; aucune frame artificielle n'est nécessaire pour rendre le stream visible.
+
+## Client natif
+
+Le client doit connaître le SHA-256 exact du certificat serveur :
+
+```rust
+let config = match game_realtime_webtransport_lib::WebTransportClientConfig::new(
+    "https://127.0.0.1:4433/game",
+    certificate_hash,
+) {
+    Ok(value) => value,
+    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 pinning est obligatoire dans cette API native ; il n'existe pas de variante qui désactive globalement la vérification TLS.
+
+## Contrat realtime
+
+Une fois le stream primaire sélectionné, utiliser uniquement les traits de `game-realtime-transport-lib` :
+
+```rust
+let (mut sender, mut receiver) = game_realtime_transport_lib::RealtimeConnection::split(connection);
+
+let message = game_realtime_transport_lib::TransportMessage::new(vec![1, 2, 3, 4]);
+if let Err(error) = game_realtime_transport_lib::RealtimeSender::send(&mut sender, message).await {
+    return Err(error);
+}
+
+let received = match game_realtime_transport_lib::RealtimeReceiver::receive(&mut receiver).await {
+    Ok(value) => value,
+    Err(error) => return Err(error),
+};
+
+if let Err(error) = game_realtime_transport_lib::RealtimeSender::close(&mut sender).await {
+    return Err(error);
+}
+```
+
+Le backend encode chaque `TransportMessage` sous la forme `u32` big-endian + payload. Le consommateur ne doit pas reproduire ce framing lui-même.
+
+## Fermeture actuelle
+
+`RealtimeSender::close()` termine proprement la direction d'émission du stream primaire. Le pair observe ensuite `TransportReceive::Closed` lorsqu'il atteint le FIN après les messages déjà écrits.
+
+La fermeture de session complète, les resets, les aborts, les timeouts et les cas d'annulation appartiennent à la tranche de robustesse suivante et ne doivent pas être simulés par le consommateur.