43 lines
2.3 KiB
Markdown
43 lines
2.3 KiB
Markdown
<!-- file: crates/common/game-realtime-transport-lib/README.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# game-realtime-transport-lib
|
|
|
|
Contrat realtime transport-neutral de `games.sasedev`. La crate définit uniquement la forme minimale d'une connexion établie, de ses moitiés d'envoi/réception, des payloads binaires opaques et des erreurs stables visibles par les couches supérieures.
|
|
|
|
## Responsabilité
|
|
|
|
La crate possède :
|
|
|
|
- `TransportMessage`, buffer binaire possédé ;
|
|
- `TransportReceive`, qui distingue message reçu et fermeture distante propre ;
|
|
- `RealtimeConnection`, `RealtimeSender` et `RealtimeReceiver` ;
|
|
- `TransportError` et `TransportErrorKind` comme catégories backend-neutral.
|
|
|
|
Elle ne possède pas :
|
|
|
|
- l'établissement d'une connexion réseau ;
|
|
- Tokio ou un autre runtime ;
|
|
- WebSocket, WebTransport, QUIC, HTTP ou TLS ;
|
|
- un codec wire ;
|
|
- une session joueur/room ;
|
|
- la synchronisation gameplay ou la simulation authoritative.
|
|
|
|
## Contrat async
|
|
|
|
`RealtimeConnection::split()` consomme une connexion établie et retourne des moitiés d'envoi et de réception indépendantes. Les opérations async sont exposées par des futures associées GAT plutôt que par `async-trait` ou `Box<dyn Future>`.
|
|
|
|
Le contrat n'impose volontairement aucune borne `Send` aux futures. Un backend natif peut fournir des futures `Send`, tandis qu'un futur backend navigateur/WASM ne doit pas être exclu par une contrainte de threading qui ne relève pas de l'abstraction transport.
|
|
|
|
## Sémantique
|
|
|
|
Les payloads sont toujours binaires et opaques. Une couche supérieure pourra ultérieurement leur appliquer un codec wire ou un protocole de session sans modifier cette crate.
|
|
|
|
Une fermeture distante propre est représentée par `TransportReceive::Closed`. Elle n'est pas convertie en erreur I/O générique. Les erreurs utilisent une catégorie stable (`Timeout`, `MessageTooLarge`, `Backpressure`, `Protocol`, etc.) et un détail de diagnostic, sans exposer le type d'erreur du backend concret.
|
|
|
|
## Dépendances et sens d'ownership
|
|
|
|
Cette crate ne dépend d'aucun backend realtime. Les implémentations concrètes dépendent d'elle, jamais l'inverse.
|
|
|
|
Le premier backend de référence est `game-realtime-websocket-lib`. Le POC WebTransport/QUIC prévu ensuite doit d'abord challenger cette même frontière avant toute généralisation supplémentaire.
|