79 lines
2.8 KiB
Markdown
79 lines
2.8 KiB
Markdown
<!-- 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.
|