Table of Contents
Introduction
kcp-go is a Reliable-UDP library for golang.
This library provides a reliable, ordered byte-stream transport over UDP. Optional FEC and packet encryption are available. Encryption can hide packet contents, but random per-packet nonces do not make network traffic anonymous: endpoints, packet sizes, timing, and traffic volume may still be observable. It has been deployed across a range of devices and applications, including online games, live broadcasting, file synchronization, and network acceleration.
Latest Release
Quick Start
kcp-go implements net.Conn and net.Listener, so applications can use familiar stream I/O. These standalone examples show a basic echo server and client; they use no packet encryption or FEC.
Echo server:
package main
import (
"io"
"log"
"net"
"github.com/xtaci/kcp-go/v5"
)
func main() {
ln, err := kcp.Listen("127.0.0.1:12345")
if err != nil {
log.Fatal(err)
}
defer ln.Close()
for {
conn, err := ln.Accept()
if err != nil {
log.Fatal(err)
}
go func(conn net.Conn) {
defer conn.Close()
if _, err := io.Copy(conn, conn); err != nil {
log.Println(err)
}
}(conn)
}
}
Echo client:
package main
import (
"fmt"
"io"
"log"
"github.com/xtaci/kcp-go/v5"
)
func main() {
conn, err := kcp.Dial("127.0.0.1:12345")
if err != nil {
log.Fatal(err)
}
defer conn.Close()
payload := []byte("hello over KCP")
if _, err := conn.Write(payload); err != nil {
log.Fatal(err)
}
reply := make([]byte, len(payload))
if _, err := io.ReadFull(conn, reply); err != nil {
log.Fatal(err)
}
fmt.Println(string(reply))
}
For optional packet encryption or FEC, use ListenWithOptions and DialWithOptions; both peers must use matching encryption keys and FEC shard settings. See Godoc for configuration details.
Features
- Reliable, ordered byte-stream delivery over UDP with configurable latency/throughput trade-offs.
net.Conn and net.Listener APIs; the familiar interface does not make the transport TCP.- Optional Reed-Solomon FEC to recover some packet loss, with configurable data/parity shard counts.
- Optional packet encryption, including AEAD for packet-level integrity and authentication.
- SNMP statistics are enabled by default. To disable statistics collection, build with
go build -tags kcp_no_snmp ./...; in this build, Snmp is an empty placeholder and its statistics fields and reporting methods are unavailable.
- A shared timer scheduler and batched, platform-specific UDP I/O to support many sessions efficiently.
- Designed for high concurrency; capacity depends on workload, configuration, and hardware.
- Based on skywind3000's KCP, with additional features and optimizations.
Documentation
For complete documentation, see the associated Godoc.
Layer-Model of KCP-GO
Design and Tuning Notes
1. Slice vs. Container/List
The KCP flush path scans the in-flight send buffer to find segments that need transmission or retransmission. The ring-buffer representation supports sequential traversal with good locality; the scan cost depends on the number of in-flight segments and how often the session is updated.
I wrote a benchmark comparing sequential loops through a slice and a container/list here:
BenchmarkLoopSlice-4 2000000000 0.39 ns/op
BenchmarkLoopList-4 100000000 54.6 ns/op
The list structure introduces heavy cache misses compared to the slice, which offers better locality. In the linked benchmark, for 5,000 connections with a 32-window size and a 20 ms update interval, using a slice costs 6 μs (0.03% CPU) per kcp.flush(), whereas using a list costs 8.7 ms (43.5% CPU). These figures are benchmark-specific; actual cost depends on workload and hardware.
2. Timing Accuracy and RTT Estimation
Timing is critical for the RTT estimator. Inaccurate timing can cause premature or delayed retransmissions. KCP uses currentMs(), which derives elapsed monotonic time from a package reference point. The time.Now() numbers below are measurements from a historical benchmark on the listed hardware, not portable performance guarantees.
The benchmark for time.Now() is here:
This is the beginning of the README. Read the rest at the original. Read the full README ↗
