# 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 : ```text 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 : ```text game_realtime_websocket_lib::connect_with_config(endpoint, config) ``` ## Serveur Créer d'abord une adresse `SocketAddr`, puis binder : ```text WebSocketListener::bind(address) ``` ou : ```text 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)`. 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 : ```bash 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 : ```text 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.