145 lines
5.3 KiB
Markdown
145 lines
5.3 KiB
Markdown
<!-- file: deltas/0.3.4/alpha.3.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# Delta 0.3.4-alpha.3
|
|
|
|
## Mission
|
|
|
|
Introduire le premier backend concret de la frontière realtime validée en `alpha.2` : WebSocket async natif avec Tokio + `tokio-tungstenite`, sans TLS, sans protocole session/gameplay et sans dépendance backend dans les moteurs ou jeux.
|
|
|
|
## Historique fermé
|
|
|
|
`history/0.3.4/alpha.2.md` enregistre la validation utilisateur : audits propres, workspace/Clippy strict propres et `7` tests sur `game-realtime-transport-lib` passés.
|
|
|
|
Aucun `alpha.2.fix.N` n'est requis.
|
|
|
|
## Version et dépendances
|
|
|
|
Le workspace passe à :
|
|
|
|
```text
|
|
0.3.4-alpha.3
|
|
```
|
|
|
|
Dépendances tierces centralisées au workspace :
|
|
|
|
```text
|
|
futures-util 0.3.34
|
|
tokio 1.53.1
|
|
tokio-tungstenite 0.30.0
|
|
```
|
|
|
|
`game-realtime-websocket-lib` active uniquement les features dont elle a besoin :
|
|
|
|
```text
|
|
futures-util: default-features=false, sink, std
|
|
tokio: net
|
|
tokio-tungstenite: default-features=false, connect, handshake
|
|
```
|
|
|
|
Le harness de test ajoute localement les features Tokio `macros`, `rt` et `time`. Aucune feature TLS n'est activée.
|
|
|
|
## Nouvelle crate WebSocket
|
|
|
|
Ajout :
|
|
|
|
```text
|
|
crates/common/game-realtime-websocket-lib/Cargo.toml
|
|
crates/common/game-realtime-websocket-lib/src/lib.rs
|
|
crates/common/game-realtime-websocket-lib/src/websocket.rs
|
|
crates/common/game-realtime-websocket-lib/tests/loopback.rs
|
|
```
|
|
|
|
La crate implémente le contrat `game-realtime-transport-lib` sans en modifier l'API.
|
|
|
|
### Client
|
|
|
|
`connect(&str)` établit une connexion WebSocket cliente à partir d'un endpoint `ws://`. Un endpoint hors baseline, notamment `wss://`, est rejeté comme `InvalidConfiguration` au lieu d'activer implicitement un backend TLS.
|
|
|
|
### Serveur
|
|
|
|
`WebSocketListener::bind(SocketAddr)` bind un `tokio::net::TcpListener`; `127.0.0.1:0` permet au système de choisir un port de test éphémère. `accept()` accepte le TCP puis effectue le handshake WebSocket serveur.
|
|
|
|
### Connexion
|
|
|
|
Client et serveur retournent le même `WebSocketConnection` public. Les représentations `tokio_tungstenite::WebSocketStream<...>` restent privées.
|
|
|
|
`RealtimeConnection::split()` produit `WebSocketSender` et `WebSocketReceiver`. Les futures concrètes sont boxées uniquement dans ce backend afin d'implémenter les associated futures GAT du contrat. Les représentations WebSocket/Tungstenite restent privées ; l'alias public `LocalBoxFuture` de `futures-util` sert uniquement de représentation concrète des associated futures du backend.
|
|
|
|
### Mapping WebSocket
|
|
|
|
```text
|
|
Binary -> TransportReceive::Message
|
|
Close -> TransportReceive::Closed
|
|
Ping / Pong -> détail de contrôle backend, non remonté au gameplay
|
|
Text -> TransportErrorKind::Protocol
|
|
Frame -> TransportErrorKind::Protocol
|
|
WriteBufferFull -> TransportErrorKind::Backpressure
|
|
Capacity -> TransportErrorKind::MessageTooLarge
|
|
I/O -> TransportErrorKind::Io
|
|
closed/already -> TransportErrorKind::Closed
|
|
```
|
|
|
|
Les erreurs de connect/bind/accept restent catégorisées au niveau de l'opération qui échoue et aucun `tungstenite::Error` ne fuit dans l'API publique.
|
|
|
|
## Tracing
|
|
|
|
Le target backend est :
|
|
|
|
```text
|
|
games::realtime::websocket
|
|
```
|
|
|
|
Les événements couvrent connect, bind, accept, send, receive, close et erreurs. Le contenu brut des payloads n'est jamais loggué ; seule leur longueur peut apparaître au niveau trace.
|
|
|
|
La crate ne configure aucun subscriber global.
|
|
|
|
## Preuve loopback
|
|
|
|
Le test d'intégration public :
|
|
|
|
```text
|
|
binary_round_trip_and_clean_close_work_on_loopback
|
|
```
|
|
|
|
utilise `127.0.0.1:0`, établit client et serveur sans Internet ni port fixe, puis vérifie :
|
|
|
|
- payload binaire client vers serveur ;
|
|
- payload binaire serveur vers client ;
|
|
- fermeture locale cliente observée comme fermeture distante propre côté serveur.
|
|
|
|
Une borne de trois secondes entoure les étapes asynchrones uniquement pour rendre le test déterministe en cas de régression ; elle ne constitue pas encore le timeout de transport produit, réservé à `alpha.4`.
|
|
|
|
## Documentation locale
|
|
|
|
Aucun `README.md` ou `USAGE.md` local n'est ajouté pour cette nouvelle crate pendant `alpha.3`. Le contrat reste petit, la rustdoc décrit l'API et le plan central porte les décisions d'architecture. Cette décision sera réévaluée pendant la consolidation finale conformément à `DOC-CRATE-*`.
|
|
|
|
## Fichiers existants modifiés
|
|
|
|
```text
|
|
Cargo.toml
|
|
README.md
|
|
docs/plans/004-V0_3_4_REALTIME_TRANSPORT_WEBSOCKET_PLAN.md
|
|
```
|
|
|
|
`ROADMAP.md` et `CHANGELOG.md` restent inchangés : le scope macro de `0.3.4` n'a pas changé et une alpha n'ajoute pas encore de changelog de release.
|
|
|
|
## Validation attendue
|
|
|
|
```bash
|
|
cargo fmt --all
|
|
cargo fmt --all -- --check
|
|
|
|
python3 scripts/audit_rust_workspace_rules.py
|
|
python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates Android Web deltas history
|
|
python3 scripts/audit_distribution_layout.py
|
|
|
|
cargo check --workspace
|
|
cargo clippy --workspace --all-targets --all-features -- -D warnings
|
|
cargo test -p game-realtime-transport-lib --all-targets --all-features
|
|
cargo test -p game-realtime-websocket-lib --all-targets --all-features
|
|
cargo tree -p game-realtime-websocket-lib --edges normal
|
|
```
|
|
|
|
`cargo test --workspace --all-targets --all-features` reste réservé à la beta conformément au plan.
|