0.3.5-alpha.4

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

@@ -1,5 +1,5 @@
 <!-- file: crates/common/game-realtime-webtransport-lib/README.md -->
-<!-- version: 2 -->
+<!-- version: 3 -->
 
 # game-realtime-webtransport-lib
 
@@ -18,9 +18,14 @@ La frontière native disponible couvre désormais :
 - établissement HTTP/3 WebTransport client/server natif ;
 - sélection d'un unique stream bidirectionnel fiable comme chemin realtime principal ;
 - framing privé `u32` big-endian + payload binaire ;
-- borne POC de 1 MiB vérifiée avant allocation côté réception et avant écriture côté émission ;
+- 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 ;
 - adaptation `RealtimeConnection` / `RealtimeSender` / `RealtimeReceiver` ;
-- fermeture propre du chemin logique par FIN du stream primaire ;
+- 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`.
 
 ## TLS de développement
@@ -48,23 +53,56 @@ one WebTransport session
 
 `RealtimeConnection::split()` conserve la session WebTransport dans les deux moitiés afin que la session ne soit pas fermée au moment où l'objet connexion est consommé.
 
-## Limite de frame POC
+## Limites et deadlines
 
-La borne actuelle du framing fiable est volontairement interne à cette tranche : 1 MiB par message. Elle empêche une longueur `u32` hostile de provoquer une allocation arbitraire et rejette aussi l'émission hors limite avec `TransportErrorKind::MessageTooLarge`.
+`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.
 
-Cette valeur n'est pas encore une configuration produit. La tranche de robustesse suivante doit décider si la limite devient configurable avec les deadlines, la backpressure, les resets, l'abort/cancellation et le mapping d'erreurs détaillé.
+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 ;
+- écriture complète header + payload d'une frame.
+
+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.
+
+## Lifecycle, abort et cancellation
+
+`RealtimeSender::close()` reste la fermeture propre de la direction d'émission et produit un FIN. À l'inverse :
+
+- `WebTransportSender::abort(code)` envoie un `RESET_STREAM` WebTransport ;
+- `WebTransportReceiver::abort(code)` envoie un `STOP_SENDING` WebTransport ;
+- dropper un `WebTransportSender` encore actif provoque un reset explicite ;
+- dropper un `WebTransportReceiver` encore actif provoque un stop explicite ;
+- annuler une future `send()` en cours provoque également un reset via une garde de cancellation.
+
+Une erreur terminale de lecture/écriture rend la moitié concernée indisponible pour une réutilisation silencieuse.
+
+La réception n'utilise plus une lecture exacte monolithique. Le header et le payload sont lus progressivement avec l'API de lecture cancel-safe de Quinn ; `header_read`/`payload_read` restent dans le receiver. Une future `receive()` annulée peut donc être relancée sans perdre les octets déjà consommés ni décaler le framing.
+
+## Mapping d'erreurs
+
+Le backend distingue notamment :
+
+- payload hors limite -> `MessageTooLarge` ;
+- reset/STOP_SENDING valide -> `Aborted` ;
+- stream déjà fermé -> `Closed` ;
+- 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`.
+
+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é.
 
 ## Frontières actuelles
 
 La crate ne possède toujours pas :
 
 - d'API datagram transport-neutral ;
-- de deadlines applicatives WebTransport ;
-- de politique de backpressure explicite ;
-- de reset/abort/cancellation produit ;
-- de mapping fin de toutes les erreurs Quinn/WebTransport ;
 - de chemin navigateur/WASM ;
 - de smoke executable public WebTransport ;
+- de fallback WebSocket ;
 - de benchmark WebSocket/WebTransport.
 
 Ces responsabilités restent réservées aux tranches suivantes du plan `0.3.5`.