games/crates/common/game-realtime-websocket-lib/USAGE.md

Utilisation — backend realtime WebSocket

Préconditions

Le consommateur possède le runtime Tokio. game-realtime-websocket-lib utilise Tokio pour les sockets et deadlines mais ne crée jamais son propre runtime.

Le contrat transport-neutral est fourni par game-realtime-transport-lib. Pour appeler split, send, receive et close, importer les traits correspondants dans le module consommateur selon les règles Rust du dépôt.

Client

Le point d'entrée simple est :

game_realtime_websocket_lib::connect("ws://host:port/path")

La fonction retourne une WebSocketConnection. La connexion est ensuite consommée par RealtimeConnection::split() pour obtenir un sender et un receiver indépendants.

Pour une configuration spécifique, construire WebSocketConfig, valider ses invariants puis utiliser :

game_realtime_websocket_lib::connect_with_config(endpoint, config)

Serveur

Créer d'abord une adresse SocketAddr, puis binder :

WebSocketListener::bind(address)

ou :

WebSocketListener::bind_with_config(address, config)

local_addr() permet de connaître l'adresse réellement allouée, notamment après bind sur 127.0.0.1:0. accept().await attend ensuite un peer TCP et effectue l'upgrade WebSocket dans la deadline configurée.

Émission et réception

Un message applicatif est encapsulé dans TransportMessage::new(Vec<u8>). Le sender refuse localement un payload dépassant les bornes configurées avant écriture.

receive() retourne :

• TransportReceive::Message pour un payload binaire ;
• TransportReceive::Closed pour une fermeture distante propre ;
• TransportError pour une erreur réseau/protocole, un timeout ou une limite dépassée.

Une frame Text reçue est une erreur de protocole : elle n'est jamais convertie en bytes métier.

Fermeture

RealtimeSender::close() initie un close WebSocket propre et applique la deadline de fermeture configurée. Une task/future annulée n'est pas assimilée à un close handshake réussi.

Smoke local

Le launcher de validation public utilise uniquement les API exposées par les deux crates realtime :

cargo run -p game-realtime-websocket-smoke

Il bind 127.0.0.1:0, connecte un client réel, échange un payload binaire dans les deux sens, initie un close propre et doit terminer avec :

game-realtime-websocket-smoke: PASS

Le smoke ne dépend ni d'Internet, ni d'un port fixe, ni d'un serveur externe.

Limites intentionnelles

Cette crate n'est pas un protocole multijoueur. Authentification, versionnement wire, session joueur/room, heartbeat métier, resynchronisation, snapshots/deltas et simulation authoritative appartiennent aux couches supérieures et restent hors de son contrat.