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、可选心跳确认回调
- **消息队列**：离线时自动缓存消息，连接后自动发送
- **调试模式**：可选的日志输出

## 快速开始

```rust
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` 回调，通知应用层延迟和服务器时间

### 使用方式

```rust
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 格式：

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

## 集成到项目

在 `Cargo.toml` 中添加：

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

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