KCP Rust

A high-performance async Rust implementation of KCP - A Fast and Reliable ARQ Protocol built on top of Tokio.

Features

• Async-First Design: Built from ground up for async/await with Tokio integration
• Zero-Copy: Efficient buffer management using the bytes crate
• Lock-Free Buffer Pool: High-performance memory management with crossbeam
• Connection-Oriented: High-level connection abstractions (KcpStream, KcpListener)
• Protocol Compatible: Compatible with original C KCP implementation
• Observability: Integrated tracing and metrics support
• Memory Efficient: Object pooling and buffer reuse
• Multiple Performance Modes: Normal, Fast, Turbo, Gaming presets

Installation

Add this to your Cargo.toml:

[dependencies]
kcp-tokio = "0.3.4"
tokio = { version = "1.0", features = ["full"] }

Quick Start

Client

use kcp_tokio::{KcpConfig, async_kcp::KcpStream};
use tokio::io::{AsyncReadExt, AsyncWriteExt};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = KcpConfig::new().fast_mode();
    let mut stream = KcpStream::connect("127.0.0.1:12345".parse()?, config).await?;

    // Send data
    stream.write_all(b"Hello, KCP!").await?;

    // Receive response
    let mut buffer = [0u8; 1024];
    let n = stream.read(&mut buffer).await?;
    println!("Received: {}", String::from_utf8_lossy(&buffer[..n]));

    Ok(())
}

Server

use kcp_tokio::{KcpConfig, async_kcp::KcpListener};
use tokio::io::{AsyncReadExt, AsyncWriteExt};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = KcpConfig::realtime();
    let mut listener = KcpListener::bind("127.0.0.1:12345".parse()?, config).await?;

    println!("Server listening on 127.0.0.1:12345");

    while let Ok((mut stream, addr)) = listener.accept().await {
        println!("New connection from {}", addr);
        tokio::spawn(async move {
            let mut buf = [0u8; 1024];
            while let Ok(n) = stream.read(&mut buf).await {
                if n == 0 { break; }
                let _ = stream.write_all(&buf[..n]).await;
            }
        });
    }

    Ok(())
}

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Application Layer                         │
│              (User code using KcpStream/KcpListener)         │
├─────────────────────────────────────────────────────────────┤
│                    High-Level API Layer                      │
│                  KcpStream    KcpListener                    │
│           (AsyncRead/AsyncWrite, TCP-like interface)         │
├─────────────────────────────────────────────────────────────┤
│                    Protocol Core Layer                       │
│                       KcpEngine                              │
│        (ARQ logic, congestion control, retransmission)       │
├─────────────────────────────────────────────────────────────┤
│                    Common Layer                              │
│         KcpSegment, KcpHeader, BufferPool, Constants         │
├─────────────────────────────────────────────────────────────┤
│                    Transport Layer                           │
│                   UDP Socket (Tokio)                         │
└─────────────────────────────────────────────────────────────┘

Configuration

Performance Presets

// Gaming - ultra-low latency (3ms update interval)
let config = KcpConfig::gaming();

// Real-time communication (8ms update interval)
let config = KcpConfig::realtime();

// File transfer - high throughput
let config = KcpConfig::file_transfer();

// Testing with packet loss simulation
let config = KcpConfig::testing(0.1); // 10% packet loss

Performance Modes

Custom Configuration

use std::time::Duration;

let config = KcpConfig::new()
    .fast_mode()
    .window_size(128, 128)
    .mtu(1400)
    .connect_timeout(Duration::from_secs(10))
    .keep_alive(Some(Duration::from_secs(30)))
    .stream_mode(true);

Examples

# Run performance test server
cargo run --example perf_test_server -- 127.0.0.1:12345 gaming

# Run performance test client
cargo run --example perf_test_client -- 127.0.0.1:12345

# Run simple echo example
cargo run --example simple_echo

Testing

# Run all tests
cargo test

# Run with logging
RUST_LOG=debug cargo test -- --nocapture

# Run specific test
cargo test test_echo_debug -- --nocapture

# Run clippy
cargo clippy --all-targets

Documentation

Detailed documentation is available in the doc/ directory:

Performance

KCP provides significant latency improvements over TCP:

• 30-40% lower latency in typical network conditions
• Better performance on lossy networks
• Configurable trade-offs between latency and bandwidth

Optimizations in this Implementation

• Lock-free buffer pools using crossbeam::queue::ArrayQueue
• Zero-copy packet handling with bytes crate
• Grouped state structs for better cache locality
• Configurable update intervals (3-40ms)
• Batch ACK processing

Use Cases

• Gaming: Ultra-low latency for real-time multiplayer
• VoIP/Video: Real-time communication
• Live Streaming: Low-latency data delivery
• File Transfer: Reliable bulk data transfer
• IoT: Efficient communication for constrained devices

Compatibility

• Protocol: Compatible with original C KCP
• Rust: Edition 2021, stable toolchain
• Tokio: 1.0+

License

MIT License - see LICENSE file.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Resources

• Original KCP Protocol
• KCP Protocol Documentation
• Tokio Documentation

Version History

• v0.3.4: Engine refactoring, lock-free buffer pools, documentation
• v0.3.3: Performance optimizations, sub-millisecond latency
• v0.3.1: Full async support, comprehensive configuration
• v0.2.x: Performance improvements and bug fixes
• v0.1.x: Initial implementation