# 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.