5.3 KiB
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 à :
0.3.4-alpha.3
Dépendances tierces centralisées au workspace :
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 :
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 :
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
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 :
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 :
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
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
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.