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

game-realtime-websocket-lib

Backend WebSocket de référence pour le contrat game-realtime-transport-lib, fondé sur Tokio et tokio-tungstenite.

Responsabilité

La crate possède :

• connexion client ws:// ;
• listener serveur TCP + upgrade WebSocket ;
• types concrets WebSocketConnection, WebSocketSender et WebSocketReceiver ;
• mapping WebSocket vers le contrat binaire transport-neutral ;
• limites de message/frame/write-buffer ;
• deadlines connect/handshake, send et close ;
• tracing du domaine games::realtime::websocket ;
• mapping des erreurs Tungstenite vers TransportErrorKind.

Elle ne possède pas le runtime Tokio : le consommateur crée et exécute son runtime. La crate ne lance ni runtime global, ni thread runtime privé, ni task backend détachée pour une connexion de base.

Frontières

Le backend transporte des octets opaques. Il ne connaît ni joueur, ni room, ni tick, ni snapshot, ni codec wire, ni protocole de session.

Les messages Text ne font pas partie du contrat et sont rejetés comme erreur de protocole. Ping/Pong reste un détail WebSocket. Une fermeture distante propre devient TransportReceive::Closed.

La baseline active utilise ws://. Aucune feature TLS de tokio-tungstenite n'est activée ; une politique wss:// directe n'est pas introduite tant qu'un besoin produit et une stratégie de certificats ne sont pas démontrés.

Configuration

WebSocketConfig::default() fournit des bornes produit explicites :

message maximum      1 MiB
frame maximum        1 MiB
write buffer target  64 KiB
write buffer maximum 2 MiB
connect/handshake    10 s
send                  5 s
close                 2 s

Les builders with_* permettent d'adapter ces limites avant connect_with_config ou WebSocketListener::bind_with_config. validate() refuse les configurations incohérentes avant l'établissement réseau.

Utilisation

Voir USAGE.md pour les points d'entrée client/serveur, la configuration et le smoke de référence.