🚀 KCP协议的纯Rust实现 - 快速可靠的ARQ协议，比TCP降低30%-40%延迟

📖 简介

kcp-ovo 是一个快速可靠的ARQ（Automatic Repeat-reQuest）协议的纯Rust实现。KCP是一个低延迟、高可靠性的传输层协议，相比传统TCP可以降低30%-40%的延迟，最大RTT减少三倍。

本项目完整复刻了skywind3000/kcp的原版C代码，使用纯Rust重写，充分利用Rust的类型安全和内存安全特性，同时提供类似TCP的Stream API简化使用。

✨ 特性

核心特性

• ✅ 纯Rust实现 - 无FFI依赖，完全使用Rust重写
• ✅ 内存优化 - 使用mimalloc全局分配器优化内存性能
• ✅ 类型安全 - 充分利用Rust类型系统，防止内存错误
• ✅ 零成本抽象 - 性能接近原版C实现
• ✅ 双API设计 - 提供底层API和Stream API（高级API）

Stream API（推荐）

• ✅ 简单易用 - 类似TCP的使用体验
• ✅ 自动管理 - 自动处理update和socket读写
• ✅ 标准trait - 实现Read/Write trait
• ✅ 开箱即用 - 几行代码即可使用

底层API

• ✅ 完全控制 - 精确控制KCP行为
• ✅ 零开销 - 无额外抽象层
• ✅ 易于集成 - 适合集成到现有事件循环

🚀 快速开始

安装

在Cargo.toml中添加：

[dependencies]
kcp-ovo = "0.1"

Stream API（推荐）

Echo服务器

use kcp_ovo::KcpListener;
use std::io::{Read, Write};

fn main() -> std::io::Result<()> {
    let mut listener = KcpListener::bind("0.0.0.0:8888")?;
    println!("服务器启动在 0.0.0.0:8888");

    let (mut stream, addr) = listener.accept()?;
    println!("客户端 {} 已连接", addr);

    let mut buffer = [0u8; 1024];
    loop {
        match stream.read(&mut buffer) {
            Ok(0) => break,
            Ok(n) => {
                stream.write_all(&buffer[..n])?;
            }
            Err(e) => {
                eprintln!("错误: {}", e);
                break;
            }
        }
    }
    Ok(())
}

Echo客户端

use kcp_ovo::KcpStream;
use std::io::{Read, Write};

fn main() -> std::io::Result<()> {
    let mut stream = KcpStream::connect("127.0.0.1:8888")?;
    stream.write_all(b"Hello, KCP!")?;

    let mut buffer = [0u8; 1024];
    let n = stream.read(&mut buffer)?;
    println!("收到: {}", String::from_utf8_lossy(&buffer[..n]));
    Ok(())
}

底层API

use kcp_ovo::{Kcp, KcpConfig};

fn main() -> kcp_ovo::KcpResult<()> {
    // 创建KCP实例
    let mut kcp = Kcp::new(0x11223344, KcpConfig::default())?;

    // 设置输出回调
    kcp.set_output(|data, _kcp| {
        // 通过UDP socket发送
        udp_socket.send_to(data, &remote_addr)?;
        Ok(data.len())
    });

    // 发送数据
    kcp.send(b"Hello, KCP!")?;
    kcp.flush();

    // 接收UDP数据并输入到KCP
    let (len, _) = udp_socket.recv_from(&mut buf)?;
    kcp.input(&buf[..len])?;

    // 更新KCP状态
    kcp.update(current_timestamp_ms);

    // 接收数据
    let mut recv_buf = [0u8; 4096];
    let recv_len = kcp.recv(&mut recv_buf)?;
    println!("收到: {}", String::from_utf8_lossy(&recv_buf[..recv_len]));

    Ok(())
}

📊 性能

性能对比

适用场景

🔧 配置选项

预定义配置

use kcp_ovo::KcpConfig;

// 默认配置（平衡模式）
let config = KcpConfig::default();

// 快速模式（最低延迟）
let config = KcpConfig::fast_mode();

// 自定义配置
let config = KcpConfig {
    mtu: 1400,           // 最大传输单元
    interval: 20,        // 内部更新间隔(ms)
    nodelay: true,       // 无延迟模式
    fastresend: 2,       // 快速重传触发次数
    stream: false,       // 流式模式
    nocwnd: true,        // 禁用拥塞控制
    rcv_wnd: 128,        // 接收窗口大小
    ..Default::default()
};

参数说明

详细配置说明请参考：性能优化指南

📚 文档

• 入门教程 - 5分钟快速入门
• API指南 - 完整API参考
• 性能优化 - 性能调优指南
• 故障排查 - 常见问题解决

生成API文档：

cargo doc --open

💡 示例程序

项目包含丰富的示例程序：

更多示例请查看 examples/ 目录。

🏗️ 模块结构

src/
├── lib.rs          # 库入口，全局分配器
├── error.rs        # 错误类型定义
├── queue/          # 队列管理模块
│   ├── segment.rs  # 数据段结构
│   └── deque.rs    # 双向队列
├── codec/          # 编解码模块
│   └── mod.rs     # 大端序编解码工具
├── config/         # 配置模块
│   └── params.rs   # KcpConfig配置
├── core/           # 核心协议模块
│   └── kcp.rs      # KCP控制块（主要实现）
└── stream.rs       # Stream API（可选feature）

🎯 API选择指南

Stream API（推荐大多数应用）

何时使用:

• ✅ 新项目开发
• ✅ 需要快速上手
• ✅ 类似TCP的使用体验
• ✅ 不需要精细控制KCP

优点:

• 简单易用，几行代码即可使用
• 自动管理KCP状态更新
• 实现标准IO trait
• 自动处理socket读写

示例:

use kcp_ovo::KcpStream;
use std::io::{Read, Write};

let mut stream = KcpStream::connect("127.0.0.1:8888")?;
stream.write_all(b"Hello")?;
let mut buffer = [0u8; 1024];
stream.read(&mut buffer)?;

底层API（推荐高级用户）

何时使用:

• ✅ 需要精细控制KCP行为
• ✅ 集成到现有事件循环（如tokio）
• ✅ 需要零开销抽象
• ✅ 复杂的网络场景

优点:

• 完全控制KCP行为
• 精确管理update()时机
• 可以自定义输出逻辑
• 更灵活，无额外抽象层

示例:

use kcp_ovo::{Kcp, KcpConfig};

let mut kcp = Kcp::new(0x11223344, KcpConfig::fast_mode())?;
kcp.set_output(|data, _| udp_socket.send(data))?;
kcp.send(b"Hello")?;
kcp.flush();

📦 Feature Flags

使用方式:

# 默认配置（包含Stream API）
kcp-ovo = "0.1"

# 仅使用底层API
kcp-ovo = { version = "0.1", default-features = false }

# 显式启用Stream API
kcp-ovo = { version = "0.1", features = ["stream"] }

🧪 测试

运行测试：

# 运行所有测试
cargo test

# 运行测试并显示输出
cargo test -- --nocapture

# 运行特定测试
cargo test test_kcp_new

测试覆盖：

• ✅ 24个核心单元测试
• ✅ 2个Stream API测试
• ✅ 所有测试通过

🔄 开发路线图

已完成 ✅

• Phase 1-9: 项目初始化和基础结构
• Phase 10-16: 核心KCP协议实现
• Phase 17: 测试基础设施
  • 单元测试（24个核心测试）
  • 测试依赖配置
• Phase 18: Stream API实现
  • KcpStream客户端封装
  • KcpListener服务端封装
  • Read/Write trait实现
• Phase 19: 文档和示例
  • 入门教程
  • API指南
  • 性能优化指南
  • 故障排查指南
  • 3个示例程序

计划中 📋

• Phase 20: 集成测试和边界测试
• Phase 21: 性能基准测试
  • 性能基准测试
• 更多......

📄 许可证

MIT License

本项目基于skywind3000/kcp（MIT License），使用相同的许可证。

详见 LICENSE 文件。

🙏 致谢

• skywind3000/kcp - 原版KCP协议实现
• mimalloc-rust - Rust内存分配器

🤝 贡献

欢迎提交Issue和Pull Request！

贡献指南

1. Fork本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启Pull Request

开发规范

• 遵循Rust代码风格（cargo fmt）
• 通过Clippy检查（cargo clippy）
• 添加单元测试（cargo test）
• 更新相关文档

📮 联系方式

• GitHub: cherish-ltt/kcp-ovo
• Issues: 提交Issue

🌟 Star History

如果这个项目对你有帮助，请给一个Star⭐️