games/crates/common/game-realtime-transport-lib/README.md

game-realtime-transport-lib

Contrat realtime transport-neutral de games.sasedev. La crate définit uniquement la forme minimale d'une connexion établie, de ses moitiés d'envoi/réception, des payloads binaires opaques et des erreurs stables visibles par les couches supérieures.

Responsabilité

La crate possède :

• TransportMessage, buffer binaire possédé ;
• TransportReceive, qui distingue message reçu et fermeture distante propre ;
• RealtimeConnection, RealtimeSender et RealtimeReceiver ;
• TransportError et TransportErrorKind comme catégories backend-neutral.

Elle ne possède pas :

• l'établissement d'une connexion réseau ;
• Tokio ou un autre runtime ;
• WebSocket, WebTransport, QUIC, HTTP ou TLS ;
• un codec wire ;
• une session joueur/room ;
• la synchronisation gameplay ou la simulation authoritative.

Contrat async

RealtimeConnection::split() consomme une connexion établie et retourne des moitiés d'envoi et de réception indépendantes. Les opérations async sont exposées par des futures associées GAT plutôt que par async-trait ou Box<dyn Future>.

Le contrat n'impose volontairement aucune borne Send aux futures. Un backend natif peut fournir des futures Send, tandis qu'un futur backend navigateur/WASM ne doit pas être exclu par une contrainte de threading qui ne relève pas de l'abstraction transport.

Sémantique

Les payloads sont toujours binaires et opaques. Une couche supérieure pourra ultérieurement leur appliquer un codec wire ou un protocole de session sans modifier cette crate.

Une fermeture distante propre est représentée par TransportReceive::Closed. Elle n'est pas convertie en erreur I/O générique. Les erreurs utilisent une catégorie stable (Timeout, MessageTooLarge, Backpressure, Protocol, etc.) et un détail de diagnostic, sans exposer le type d'erreur du backend concret.

Dépendances et sens d'ownership

Cette crate ne dépend d'aucun backend realtime. Les implémentations concrètes dépendent d'elle, jamais l'inverse.

Le premier backend de référence est game-realtime-websocket-lib. Le POC WebTransport/QUIC prévu ensuite doit d'abord challenger cette même frontière avant toute généralisation supplémentaire.