Module protocol

runecast_protocol

Module protocol 

Source
Expand description

Protocol module for RuneCast WebSocket communication.

This module defines all message types exchanged between the frontend client and backend server over WebSocket connections.

§Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                           Protocol Layer                             │
├─────────────────────────────────────────────────────────────────────┤
│  envelope.rs     - Message wrapper with seq/ack/timestamp           │
│  types.rs        - Shared data types (Grid, Position, etc.)         │
│  client_messages - Client → Server message definitions              │
│  server_messages - Server → Client message definitions              │
└─────────────────────────────────────────────────────────────────────┘

§Message Flow

Client                                Server
  │                                      │
  │──── Identify ──────────────────────▶│
  │◀─── Ready (LobbySnapshot) ──────────│
  │                                      │
  │──── JoinChannelLobby ──────────────▶│
  │◀─── LobbyJoined ────────────────────│
  │                                      │
  │──── StartGame ─────────────────────▶│
  │◀─── GameStarted ────────────────────│
  │                                      │
  │──── SubmitWord ────────────────────▶│
  │◀─── WordScored ─────────────────────│
  │◀─── TurnChanged ────────────────────│

§Envelope Format (Optional)

Messages can be sent raw (legacy) or wrapped in an envelope (new protocol):

// Legacy (still supported)
{"type": "heartbeat"}

// With envelope
{"seq": 42, "ack": 41, "ts": 1701234567890, "payload": {"type": "heartbeat"}}

§Migration Strategy

This module is designed to coexist with the legacy websocket/messages.rs. During migration:

  1. New code imports from protocol::
  2. Compatibility functions convert between old and new formats
  3. Once migration is complete, remove legacy module

Re-exports§

pub use client_messages::ClientMessage;
pub use envelope::Envelope;
pub use envelope::MaybeEnveloped;
pub use server_messages::LobbySnapshot;
pub use server_messages::ServerMessage;
pub use types::*;

Modules§

client_messages
Client-to-server messages.
compat
Module for converting between legacy and new message formats.
envelope
Message envelope for reliable delivery and synchronization.
server_messages
Server-to-client messages.
types
Shared types used in protocol messages.

Constants§

HEARTBEAT_INTERVAL_MS
Recommended heartbeat interval (client should send heartbeat this often).
HEARTBEAT_TIMEOUT_MS
Heartbeat timeout (server closes connection if no heartbeat received).
MAX_MESSAGE_SIZE
Maximum message size in bytes.
PROTOCOL_VERSION
Protocol version for compatibility checks.
RECONNECT_GRACE_MS
Grace period for reconnection before session expires.