kcptun-rs ⚡

Disclaimer — This project is a Vibe Coding porting test, for educational purposes only.

This project is a Vibe Coding experiment — using AI-assisted programming to port an existing codebase. The core focus is exploring and validating the Vibe Coding workflow itself, not producing a production-grade software port. This is not production software. No guarantees are made regarding correctness, stability, or security.

It is strictly prohibited for any illegal use, including but not limited to circumventing censorship, illegal data transmission, network attacks, etc. Any illegal activities by users are not related to this project or its author. Users bear all legal responsibilities.

See DISCLAIMER.md for the full disclaimer.

kcptun-rs outperforms Go kcptun across nearly every cipher and compression setting, while maintaining full wire compatibility — meaning you can replace one side of a Go kcptun tunnel with the Rust binary and get an instant speed boost.

Benchmarked on Apple M1, 10 concurrent connections × 1 MB each. Full matrix below.

kcptun is a stable & secure TCP-over-UDP tunnel that uses KCP (a fast ARQ protocol) to accelerate TCP streams over high-latency or lossy networks. It features SMUX multiplexing, Reed-Solomon FEC, Snappy compression, and optional encryption — all wrapped in a single binary.

kcptun-rs is a complete Rust reimplementation that is:

• ✅ Wire-compatible with Go kcptun (kcp-go v5) — Rust ↔ Go, Go → Rust, Rust → Rust all work
• ⚡ Faster than Go on most cipher/mode combinations (up to 5.38×)
• 🧩 13 encryption backends + AES-128-GCM: AES, SM4, Salsa20, Blowfish, Twofish, CAST5, 3DES, TEA, XTEA, XOR, and more
• 🔧 Dual async runtimes: tokio (high-concurrency) and smol (lightweight, ARM)
• 🎯 Production-ready features: FEC, SMUX v1/v2, QPP obfuscation, SNMP stats, rate limiting, pprof profiling
• 🔄 Cross-platform: macOS, Linux, ARMv7 (Raspberry Pi), ARM64 (Graviton)

# Build (optimized release with LTO)
cargo build --release
# Binary: target/release/kcptun-server, target/release/kcptun-client

# Start server (listens on UDP :29900, forwards to local HTTP :8080)
./target/release/kcptun-server -t "127.0.0.1:8080" -l ":29900" --key "my-secret"

# Start client (listens on :12948, tunnels to remote server)
./target/release/kcptun-client -r "server-ip:29900" -l ":12948" --key "my-secret"

Now point your application at 127.0.0.1:12948 — all TCP data is encrypted, compressed, and accelerated over KCP to the remote server.

kcptun-server -c config.json
kcptun-client -c config.json

{
    "localaddr": ":12948",
    "remoteaddr": "vps:29900",
    "key": "my-secret",
    "crypt": "aes-128",
    "mode": "fast2",
    "conn": 2,
    "sndwnd": 1024,
    "rcvwnd": 1024,
    "datashard": 10,
    "parityshard": 3,
    "nocomp": false,
    "smuxver": 2,
    "keepalive": 10
}

⚠️ --key, --crypt, --mode, and --nocomp must match between server and client. Compression is enabled by default.

Path labels are Client → Server (bulk data leaves the client toward the server; from bench/run_bench.sh).

Same-stack Rust paths are clearly faster than Go→Go on this M1 host. The smol runtime's lightweight architecture gives it an edge in single-stream bulk transfer.

Tests: 10 concurrent connections, 1 MB each, all 30+ runs per cell passed (0 failures).

Without compression (--nocomp):

With compression (Snappy):

SM4 is the standout: Rust outperforms Go by 4.6–5.4× because the Go implementation uses a pure software S-box while Rust benefits from compiler auto-vectorization and pre-computed lookup tables.

All 8 stress tests pass — verifying byte-for-byte accuracy under concurrent load:

kcptun-rs is fully wire-compatible with Go kcptun (kcp-go v5). All 68 end-to-end interop tests pass across every combination:

Encryption:  15/15 ciphers passed (Go→Rust + Rust→Go)
KCP Modes:   4/4 passed
SMUX:        2/2 versions passed
Compression: 8/8 cipher×compression combos passed
FEC:         2/2 configurations passed
Total:       68 passed, 0 failed, 0 skipped 🎉

┌──────────────────────────────────┐
│         TCP / UNIX Socket        │
├──────────────────────────────────┤
│        SMUX Stream (mux)         │
├──────────────────────────────────┤
│       SMUX Session (mux)         │
├──────────────────────────────────┤
│  Snappy Compression (session)    │  ← byte-identical to Go
├──────────────────────────────────┤
│  BlockCrypt / FEC / KCP (ARQ)    │
├──────────────────────────────────┤
│           UDP / TCPraw           │
└──────────────────────────────────┘

kcptun-rs/
├── kcp-rs/          — KCP ARQ protocol state machine
├── kcrypt-rs/       — 13 block ciphers + AES-128-GCM
├── smux-rs/         — SMUX stream multiplexer (v1/v2)
├── qpp-rs/          — Quantum Permutation Pad obfuscation
├── kio-rs/          — Async runtime abstraction (tokio / smol)
├── kpprof-rs/       — Go-compatible pprof HTTP server
├── kcptun-common/   — Shared client/server helpers
├── kcptun-client/   — Client binary
└── kcptun-server/   — Server binary + stress tests

• tokio (default) — multi-threaded, high-concurrency, production-scaled
• smol (--no-default-features --features smol) — lightweight, minimal binary, ARM-optimized
• Mutually exclusive features — pick one per build
• Business code uses kio::* abstractions only — never raw tokio/smol APIs

The flush loop is split into 4 phases to minimize KCP mutex hold time:

This allows the UDP recv loop to feed data into KCP while the flush loop prepares the next batch of frames — eliminating lock contention under high concurrency.

make build          # Debug build (tokio)
make release        # Release build (LTO, stripped, panic=abort)
make test           # All unit tests
make stress         # Data integrity stress tests (needs release first)
make e2e            # Go↔Rust interop (needs Go kcptun binaries)
make clippy         # Lint (warnings = errors)
make fmt            # Format all Rust code
make profile        # Flamegraph profiling (samply → Speedscope)

make install-cross     # Install cross toolchains (one-time)
make release-armv7     # Raspberry Pi 2/3, OpenWrt (~1.3M binary)
make release-arm64     # Raspberry Pi 4/5, AWS Graviton
make linux             # x86_64 Linux musl (from macOS)
make linux-aarch64     # ARM64 Linux musl (from macOS)

ARM cross builds use the smol runtime with pprof disabled for minimal binary size.

Build fully static musl binaries directly from macOS — ideal for CI or deployment testing:

make linux              # x86_64 musl (smol, ~1.3M)
make linux-aarch64      # ARM64 musl (smol)
make linux-full         # x86_64 musl + QPP

On macOS, the default UDP socket buffer sizes are small (typically 256 KB for send, 256 KB for receive). Under high-throughput KCP workloads — especially with large windows (sndwnd/rcvwnd ≥ 512) or high concurrency — the kernel UDP receive buffer can overflow, causing silent packet drops that inflate P99/P999 tail latency and trigger KCP retransmit storms.

Increasing the kernel socket buffer limits eliminates this bottleneck. This is the single most effective OS-level tuning for P99/P999 latency on macOS:

# Raise max socket buffer to 8 MB (default ~256 KB)
sudo sysctl -w kern.ipc.maxsockbuf=8388608

# Raise UDP receive buffer to 4 MB (default ~256 KB)
sudo sysctl -w net.inet.udp.recvspace=4194304

Effect on P99/P999 (measured): With these settings applied, the raw KCP layer's max sustainable throughput on loopback improved from 2975 → 3802 req/s (tokio, +28%) and 2411 → 2921 req/s (Go, +21%), with P99 latency dropping from 14.2 ms → 10.5 ms (tokio) and 20.3 ms → 15.9 ms (Go). See bench/LATENCY_P99_REPORT.md for full numbers.

To make the change persistent across reboots, add to /etc/sysctl.conf:

kern.ipc.maxsockbuf=8388608
net.inet.udp.recvspace=4194304

Linux equivalent: net.core.rmem_max, net.core.rmem_default, net.core.wmem_max, net.core.wmem_default — set to 4194304 or higher. Some distributions also require net.core.netdev_max_backlog.

The project evolved from 5.4 MB/s to over 108 MB/s through evidence-driven profiling:

Symptom: the raw kcp-rs KcpConn (no tunnel layers) collapsed on large payloads under sustained load — 256KB round-trip at RPS=300 went from ~4ms to p50=3.2s, while Go with the identical 512/512 window + Fast3 config stayed at 19ms. Single-request latency was already fast (4.3ms); the pipeline stalled only when requests overlapped.

Root cause: every received KCP segment triggered a full flush_with_current() (kcp.input → parse_una>0 → iterate the whole snd_buf ~500 segments for retransmit checks). At 50k+ pkt/s that is ~30M snd_buf iterations/s, inflating per-segment cost to ~680µs and driving a fast/early retransmit storm (~20K/2s).

Effective fixes (kept):

Tunnel comparison (why the raw lib's extreme-load queueing isn't a lib defect): the same kcp_rs::KcpConn sustains 256KB@RPS=500 at ~11ms, 100% ok when used the way the product uses it (the default shared-session tunnel, copy_bidirectional two-task per conn) — vs Go tunnel 30.5ms. The raw benchmark's residual RPS=500 deep-queue is the single-task serial-echo worst case at 131 MB/s on one connection; the tunnel's SMUX/TCP layers decouple read from write. macOS exposes no public sendmmsg/recvmmsg (libSystem has no symbols), so batch I/O there would require raw syscalls (not implemented).

Rust now sustains 300 RPS of 256KB at ~2.1ms — ~9× faster than Go's 19ms. Wire format unchanged; verified by Go↔Rust interop (both directions 500/500).

Ineffective approaches tested and reverted (recorded so they aren't re-attempted):

• Memory safety — no dangling pointers, no buffer overflows, no use-after-free
• Zero-cost abstractions — enum dispatch eliminates vtable overhead on hot crypto paths
• True parallelism — std::thread::scope for parallel batch encryption, no GIL
• Compile-time guarantees — the borrow checker catches data races before they happen
• ARM ecosystem — Rust is a first-class citizen on aarch64, with hardware AES available (aes_armv8)
• Small binaries — stripped release binary is ~2 MB, far smaller than Go's statically linked blobs
• Cross-compilation — build ARM Linux binaries from macOS with a single make command

MIT — see LICENSE for details.

This is a Rust port of kcptun by xtaci.
Source: github.com/xsean2020/kcptun-rs