43 lines
2.5 KiB
Markdown
43 lines
2.5 KiB
Markdown
<!-- file: crates/common/game-realtime-transport-lib/README.md -->
|
||
<!-- version: 2 -->
|
||
|
||
# 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.
|
||
|
||
Les deux implémentations concrètes retenues à l’issue de `0.3.5` sont `game-realtime-websocket-lib`, baseline/fallback de référence, et `game-realtime-webtransport-lib`, second backend fiable. Les datagrams WebTransport restent volontairement hors de cette crate parce qu’ils ne partagent ni la fiabilité ni l’ordre garantis par `RealtimeConnection`.
|