JoyD/Windows/Rust/CubeLib/README.md

CubeLib - Rust WebSocket Library

Rust 版本的 CubeLib，提供 WebSocket 通信功能。

结构

CubeLib/
├── Cargo.toml
├── src/
│   ├── lib.rs              # 库入口
│   └── websocket/
│       ├── mod.rs          # 模块定义
│       ├── client.rs       # WebSocket 客户端
│       ├── config.rs        # 配置类
│       ├── message.rs       # 消息类型
│       └── error.rs        # 错误类型
└── README.md

功能特性

• 事件驱动：支持 Connected、Disconnected、Message、Error 等回调
• 自动重连：支持指数退避的重连机制
• 自定义头：支持设置 ClientType 等 HTTP 头
• 心跳保活：可配置的心跳间隔，自动发送 ping、自动回复 pong、可选心跳确认回调
• 消息队列：离线时自动缓存消息，连接后自动发送
• 调试模式：可选的日志输出

快速开始

use cube_lib::websocket::{WebSocketClient, WebSocketConfig};

#[tokio::main]
async fn main() {
    let config = WebSocketConfig::new("ws://localhost:8087/ws")
        .with_client_type("Updater")
        .with_debug(true);

    let mut client = WebSocketClient::new(config);

    // 设置事件回调
    client.on_connected(|url| {
        println!("Connected to: {}", url);
    });

    client.on_message(|msg_type, data| {
        println!("Received [{}]: {:?}", msg_type, data);
    });

    client.on_disconnected(|| {
        println!("Disconnected");
    });

    // 连接
    client.connect().await;

    // 发送消息（格式与 MasterSuite 后端兼容）
    client.send("ping", serde_json::json!({
        "timestamp": "2024-01-01 00:00:00"
    })).await;

    // 保持运行
    tokio::signal::ctrl_c().await.ok();
    client.disconnect().await;
}

WebSocketConfig 配置项

字段	类型	默认值	说明
ws_url	String	ws://localhost:8087/ws	服务器地址
auto_connect	bool	true	初始化时自动连接
reconnect	bool	true	断开时自动重连
max_reconnect_delay_ms	u64	30000	最大重连延迟(毫秒)
reconnect_delay_ms	u64	1000	初始重连延迟(毫秒)
debug_mode	bool	false	调试模式
heartbeat_interval_ms	u64	30000	心跳间隔(毫秒)，0=禁用

心跳机制

CubeLib 内置完整的心跳保活机制：

自动行为

• 发送 ping：按配置的间隔自动向服务器发送 ping 消息
• 回复 pong：收到服务器的 ping 后自动回复 pong，无需应用层处理
• 心跳回调：收到 pong 后触发 on_heartbeat_ack 回调，通知应用层延迟和服务器时间

使用方式

use cube_lib::websocket::{WebSocketClient, WebSocketConfig};

#[tokio::main]
async fn main() {
    let config = WebSocketConfig::new("ws://localhost:8087/ws")
        .with_heartbeat(30000); // 30秒心跳间隔

    let mut client = WebSocketClient::new(config);

    // 设置心跳确认回调（可选）
    client.on_heartbeat_ack(|latency_ms, server_timestamp| {
        println!("心跳延迟: {}ms, 服务端时间: {}", latency_ms, server_timestamp);
        // 可根据延迟判断连接质量
    });

    client.connect().await;
}

消息格式

• 发送的 ping：{"Type":"ping","Data":{"timestamp":"2024-01-01 12:00:00.000"}}
• 回复的 pong：{"Type":"pong","Data":{"timestamp":"2024-01-01 12:00:00.000"}} | connect_timeout_ms | u64 | 10000 | 连接超时(毫秒) | | max_queue_size | usize | 100 | 消息队列最大长度 | | client_type | Option<String> | None | 客户端类型标识 | | custom_headers | Vec<(String, String)> | [] | 自定义 HTTP 头 |

消息格式

与 MasterSuite 后端兼容的 JSON 格式：

{
    "Type": "message_type",
    "Data": { ... },
    "MessageId": "optional_id"
}

集成到项目

在 Cargo.toml 中添加：

[dependencies]
cube_lib = { path = "../Rust/CubeLib" }

或从 Git 引用（待发布后）。