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 中添加:
[]
= "0.1.0"
= "1.0"
= { = "1.0", = ["full"] }
= "0.1"
2. 编写客户端代码
use ;
use ;
use Arc;
use Mutex;
use info;
// 1. 定义你的全局状态
async
💡 进阶功能示例
发送带 Ack 的请求
use Duration;
// ...在 namespace 的注册回调中
socket.;
二进制大文件分片上传
为了避免大量发送二进制数据阻塞心跳导致断线,推荐使用分片和 Ack 机制进行自然背压:
// ...在 namespace 的注册回调中
let chunk = vec!; // 256KB 分片
let chunk_meta = json!;
if let Err = s.emit_binary_with_ack.await
提示:在服务端(如 socketioxide 0.18.x)可通过 Data::<(Value, bytes::Bytes)> 提取器同时接收 JSON 元数据与二进制块。
🧪 运行示例项目 (Examples)
本项目在 examples 目录下提供了完整的客户端和服务端联调示例。
examples/server_test: 基于 Leptos 和socketioxide搭建的测试服务端。examples/client_test: 基于本库搭建的测试客户端。
启动联调测试步骤:
- 进入服务端目录并启动服务端:
- 等待服务端启动完成(约 3 秒)。
- 新开一个终端,进入客户端目录并启动客户端:
🔗 参照项目
本项目的实现和 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>, andAck, eliminating the need to manually parse the context. - Comprehensive Event Sending & Receiving Mechanism:
- Supports
on_connectandon_disconnectto listen to the connection lifecycle. - Supports
onto listen for custom events. - Supports
emitandemit_argsto send JSON or multi-parameter events. - Supports
emit_with_ackwith an acknowledgment mechanism.
- Supports
- 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_intervalto 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:
[]
= "0.1.0"
= "1.0"
= { = "1.0", = ["full"] }
= "0.1"
2. Write Client Code
use ;
use ;
use Arc;
use Mutex;
use info;
// 1. Define your global state
async
💡 Advanced Features Examples
Send a Request with Ack
use Duration;
// ... inside the namespace registration callback
socket.;
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!; // 256KB chunk
let chunk_meta = json!;
if let Err = s.emit_binary_with_ack.await
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 andsocketioxide.examples/client_test: A test client built with this library.
Steps to start the integration test:
- Enter the server directory and start the server:
- Wait for the server to start (about 3 seconds).
- Open a new terminal, enter the client directory and start the client:
🔗 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.