0.3.4-rc.1

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

@@ -0,0 +1,78 @@
+<!-- file: crates/common/game-realtime-websocket-lib/USAGE.md -->
+<!-- version: 1 -->
+
+# 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<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 :
+
+```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.