socket_io_client 0.3.0

A Socket.IO client implemented in Rust.
Documentation

socket_io_client

socket_io_client 是一个用 Rust 编写的简易 Socket.IO 客户端库。

⚠️ 兼容性提示: 本客户端目前主要针对 socketioxide 服务端进行适配与测试,致力于在 Rust 生态中提供首尾一致的、符合人体工程学的开发体验。它支持通过 ClientApp 管理全局状态,能够方便地注册不同命名空间(Namespace),并采用了基于 Extractor(提取器)机制的事件路由注册方法,让事件处理函数的签名更加灵活清晰。

✨ 核心特性

  • 全局状态与命名空间管理:通过 ClientApp 轻松管理客户端全局状态,并支持多命名空间(如 /、/admin)的独立事件注册。
  • Axum 风格的 Extractor(提取器):事件回调函数支持灵活的参数提取,例如 CSocket<State>、CData<Value>、CState<State> 和 Ack,无需手动解析上下文。
  • 完善的事件收发机制:
    • 支持 on_connect、on_disconnect 监听连接生命周期。
    • 支持 on 监听自定义事件。
    • 支持 emit、emit_args 发送 JSON 或多参数事件。
    • 支持带确认机制的 emit_with_ack。
  • 大文件/二进制数据分片上传(防断线背压):支持 emit_binary_with_ack,结合 Ack 机制实现天然背压,可防止在发送大体积二进制文件(如 Zip 压缩包)时阻塞 Ping/Pong 心跳导致断线。
  • 定时任务集成:提供 socket.run_interval 轻松注册与 Socket 生命周期绑定的定时循环任务。
  • 自动重连:可自定义重连间隔(set_reconnect_interval)与超时时间(set_pong_timeout)。

🚀 快速开始

1. 添加依赖

在 Cargo.toml 中添加:

[dependencies]
socket_io_client = "0.1.0"
serde_json = "1.0"
tokio = { version = "1.0", features = ["full"] }
tracing = "0.1"

2. 编写客户端代码

use serde_json::{json, Value};
use socket_io_client::{ClientApp, ClientSocketRef, Data as CData, Socket as CSocket, State as CState};
use std::sync::Arc;
use tokio::sync::Mutex;
use tracing::info;

// 1. 定义你的全局状态
#[derive(Clone)]
pub struct AppState {
    pub message_count: Arc<Mutex<usize>>,
}

#[tokio::main]
async fn main() {
    tracing_subscriber::fmt::init();

    let state = AppState {
        message_count: Arc::new(Mutex::new(0)),
    };

    // 2. 初始化 ClientApp
    let mut app = ClientApp::new(state);
    app.set_reconnect_interval(3);
    app.set_pong_timeout(8);

    // 3. 注册命名空间与事件路由
    app.ns("/", |socket: ClientSocketRef<AppState>| async move {
        
        // 监听连接成功事件
        socket.on_connect::<CSocket<AppState>, CState<AppState>, _, _>(
            |CSocket(s), CState(_)| async move {
                info!("连接成功!");
                let _ = s.emit("hello_server", json!({"msg": "hello from client"})).await;
            }
        );

        // 监听断开连接事件
        socket.on_disconnect::<CSocket<AppState>, CState<AppState>, _, _>(
            |CSocket(_), CState(_)| async move {
                info!("连接断开!");
            }
        );

        // 监听自定义事件,并使用 Extractor 提取数据和状态
        socket.on::<CSocket<AppState>, CData<Value>, CState<AppState>, _, _>(
            "server_msg",
            |CSocket(s), CData(data), CState(state)| async move {
                info!("收到服务器消息: {:?}", data);
                
                let mut count = state.message_count.lock().await;
                *count += 1;
                info!("总共收到 {} 条消息", *count);
                
                // 响应消息
                let _ = s.emit("client_reply", json!({"reply": "got it"})).await;
            }
        );
    });

    // 4. 启动并连接到服务端
    app.run("http://127.0.0.1:3000").await;
}

💡 进阶功能示例

发送带 Ack 的请求

use std::time::Duration;

// ...在 namespace 的注册回调中
socket.on::<CSocket<AppState>, CData<Value>, CState<AppState>, _, _>(
    "get_user_info",
    |CSocket(s), CData(data), CState(_)| async move {
        // 发送带 Ack 的请求,超时时间设为 3 秒
        match s.emit_with_ack("get_user", json!(123), Duration::from_secs(3)).await {
            Ok(res) => info!("成功收到服务端的 ACK 响应: {}", res),
            Err(e) => info!("等待服务端 ACK 超时或失败: {:?}", e),
        }
    }
);

二进制大文件分片上传

为了避免大量发送二进制数据阻塞心跳导致断线,推荐使用分片和 Ack 机制进行自然背压:

// ...在 namespace 的注册回调中
let chunk = vec![0u8; 256 * 1024]; // 256KB 分片
let chunk_meta = json!({ "file_name": "test.zip", "chunk_index": 0 });

if let Err(e) = s.emit_binary_with_ack(
    "upload_zip_chunk",
    vec![chunk_meta],
    vec![chunk], // 二进制负载
    Duration::from_secs(5),
).await {
    tracing::warn!("分片上传失败: {}", e);
}

提示:在服务端(如 socketioxide 0.18.x)可通过 Data::<(Value, bytes::Bytes)> 提取器同时接收 JSON 元数据与二进制块。

🧪 运行示例项目 (Examples)

本项目在 examples 目录下提供了完整的客户端和服务端联调示例。

  • examples/server_test: 基于 Leptos 和 socketioxide 搭建的测试服务端。
  • examples/client_test: 基于本库搭建的测试客户端。

启动联调测试步骤:

  1. 进入服务端目录并启动服务端:
    cd examples/server_test
    cargo leptos watch
    
  2. 等待服务端启动完成(约 3 秒)。
  3. 新开一个终端,进入客户端目录并启动客户端:
    cd examples/client_test
    cargo run
    

🔗 参照项目

本项目的实现和 API 设计主要参考了官方 Socket.IO 客户端和 Rust 生态优秀的库:

📄 许可证

本项目基于 MIT 许可证开源。详细信息请参阅 LICENSE 文件。

socket_io_client

socket_io_client is a simple Socket.IO client library written in Rust.

⚠️ Compatibility Note: This client is currently mainly adapted and tested against the socketioxide server. It is dedicated to providing an ergonomic, end-to-end consistent development experience within the Rust ecosystem. It supports managing global state via ClientApp, allows for convenient registration of different namespaces, and adopts an event routing registration method based on an Extractor mechanism, making the event handler signatures more flexible and clear.

✨ Core Features

  • Global State & Namespace Management: Easily manage the global state of the client through ClientApp, and support independent event registration for multiple namespaces (e.g., /, /admin).
  • Axum-style Extractors: Event callback functions support flexible parameter extraction, such as CSocket<State>, CData<Value>, CState<State>, and Ack, eliminating the need to manually parse the context.
  • Comprehensive Event Sending & Receiving Mechanism:
    • Supports on_connect and on_disconnect to listen to the connection lifecycle.
    • Supports on to listen for custom events.
    • Supports emit and emit_args to send JSON or multi-parameter events.
    • Supports emit_with_ack with an acknowledgment mechanism.
  • Large File/Binary Data Chunk Upload (Anti-Disconnect Backpressure): Supports emit_binary_with_ack, combined with the Ack mechanism to achieve natural backpressure. This prevents blocking Ping/Pong heartbeats and causing disconnections when sending large binary files (like Zip archives).
  • Scheduled Task Integration: Provides socket.run_interval to easily register scheduled loop tasks tied to the Socket lifecycle.
  • Auto Reconnection: Customizable reconnection interval (set_reconnect_interval) and timeout (set_pong_timeout).

🚀 Quick Start

1. Add Dependencies

Add the following to your Cargo.toml:

[dependencies]
socket_io_client = "0.1.0"
serde_json = "1.0"
tokio = { version = "1.0", features = ["full"] }
tracing = "0.1"

2. Write Client Code

use serde_json::{json, Value};
use socket_io_client::{ClientApp, ClientSocketRef, Data as CData, Socket as CSocket, State as CState};
use std::sync::Arc;
use tokio::sync::Mutex;
use tracing::info;

// 1. Define your global state
#[derive(Clone)]
pub struct AppState {
    pub message_count: Arc<Mutex<usize>>,
}

#[tokio::main]
async fn main() {
    tracing_subscriber::fmt::init();

    let state = AppState {
        message_count: Arc::new(Mutex::new(0)),
    };

    // 2. Initialize ClientApp
    let mut app = ClientApp::new(state);
    app.set_reconnect_interval(3);
    app.set_pong_timeout(8);

    // 3. Register namespace and event routes
    app.ns("/", |socket: ClientSocketRef<AppState>| async move {
        
        // Listen for the connection success event
        socket.on_connect::<CSocket<AppState>, CState<AppState>, _, _>(
            |CSocket(s), CState(_)| async move {
                info!("Connected successfully!");
                let _ = s.emit("hello_server", json!({"msg": "hello from client"})).await;
            }
        );

        // Listen for the disconnection event
        socket.on_disconnect::<CSocket<AppState>, CState<AppState>, _, _>(
            |CSocket(_), CState(_)| async move {
                info!("Disconnected!");
            }
        );

        // Listen for custom events and use Extractors to extract data and state
        socket.on::<CSocket<AppState>, CData<Value>, CState<AppState>, _, _>(
            "server_msg",
            |CSocket(s), CData(data), CState(state)| async move {
                info!("Received server message: {:?}", data);
                
                let mut count = state.message_count.lock().await;
                *count += 1;
                info!("Total messages received: {}", *count);
                
                // Respond to the message
                let _ = s.emit("client_reply", json!({"reply": "got it"})).await;
            }
        );
    });

    // 4. Start and connect to the server
    app.run("http://127.0.0.1:3000").await;
}

💡 Advanced Features Examples

Send a Request with Ack

use std::time::Duration;

// ... inside the namespace registration callback
socket.on::<CSocket<AppState>, CData<Value>, CState<AppState>, _, _>(
    "get_user_info",
    |CSocket(s), CData(data), CState(_)| async move {
        // Send a request with Ack, set timeout to 3 seconds
        match s.emit_with_ack("get_user", json!(123), Duration::from_secs(3)).await {
            Ok(res) => info!("Successfully received ACK response from server: {}", res),
            Err(e) => info!("Timeout or failed waiting for server ACK: {:?}", e),
        }
    }
);

Binary Large File Chunk Upload

To avoid sending massive binary data blocking the heartbeat and causing a disconnection, it's recommended to use chunking and the Ack mechanism for natural backpressure:

// ... inside the namespace registration callback
let chunk = vec![0u8; 256 * 1024]; // 256KB chunk
let chunk_meta = json!({ "file_name": "test.zip", "chunk_index": 0 });

if let Err(e) = s.emit_binary_with_ack(
    "upload_zip_chunk",
    vec![chunk_meta],
    vec![chunk], // Binary payload
    Duration::from_secs(5),
).await {
    tracing::warn!("Chunk upload failed: {}", e);
}

Tip: On the server side (e.g., socketioxide 0.18.x), you can use the Data::<(Value, bytes::Bytes)> extractor to simultaneously receive JSON metadata and binary chunks.

🧪 Run Example Projects (Examples)

This project provides complete client and server integration testing examples in the examples directory.

  • examples/server_test: A test server built with Leptos and socketioxide.
  • examples/client_test: A test client built with this library.

Steps to start the integration test:

  1. Enter the server directory and start the server:
    cd examples/server_test
    cargo leptos watch
    
  2. Wait for the server to start (about 3 seconds).
  3. Open a new terminal, enter the client directory and start the client:
    cd examples/client_test
    cargo run
    

🔗 Reference Projects

The implementation and API design of this project are mainly inspired by the official Socket.IO client and excellent libraries in the Rust ecosystem:

📄 License

This project is open-sourced under the MIT License. See the LICENSE file for details.