kcp-go/AGENTS.md

kcp-go Project Guide for AI Agents

1. Project Overview

kcp-go is a production-grade, reliable UDP library for Go. It implements the KCP protocol, providing a stream-based interface (like TCP) over UDP with low latency, high throughput, and packet-level control. It is widely used in gaming, streaming, and network acceleration (e.g., kcptun).

Key Features:

• Reliable ARQ: Automatic Repeat reQuest for reliable delivery.
• FEC (Forward Error Correction): Reed-Solomon codes to recover lost packets without retransmission.
• Encryption: Packet-level encryption (AES, TEA, Salsa20, etc.).
• Performance: Optimized for high concurrency and low memory footprint using buffer pools and platform-specific syscalls (sendmmsg/recvmmsg).

2. Architecture

The project is layered as follows:

1. Application Layer: Uses net.Conn interface (UDPSession) to Read/Write streams.
2. Session Layer (sess.go): Manages the connection lifecycle, encryption/decryption, and FEC encoding/decoding. It acts as the glue between the raw UDP socket and the KCP protocol state.
3. Protocol Layer (kcp.go): The core KCP state machine. Handles sequence numbers, retransmission queues, flow control, and congestion control.
4. Transport Layer: Raw UDP sockets (net.PacketConn).

Data Pipeline

Outgoing (Write): App Stream -> UDPSession.Write -> KCP.Send -> KCP.flush -> UDPSession.output -> chPostProcessing -> postProcess (FEC Encode -> Encrypt) -> UDP Socket

Incoming (Read): UDP Socket -> readLoop -> packetInput (Decrypt -> FEC Decode) -> KCP.Input -> UDPSession.Read -> App Stream

3. Key Files & Components

File	Component	Description
kcp.go	Core Protocol	Implements the KCP protocol logic (ARQ, RTO calculation, window management). Pure logic, no I/O.
sess.go	Session Management	Defines UDPSession (implements net.Conn) and Listener. Handles the "plumbing" of data.
fec.go	FEC	Forward Error Correction implementation using Reed-Solomon codes.
crypt.go	Encryption	Block ciphers and stream ciphers wrapper for packet encryption.
tx.go	Transmission	Platform-specific packet transmission logic (e.g., tx_linux.go uses sendmmsg).
readloop.go	Reception	Platform-specific packet reception loops (e.g., readloop_linux.go uses recvmmsg).
timedsched.go	Scheduler	A global timer scheduler to drive KCP.update for all sessions, reducing goroutine overhead.
bufferpool.go	Memory Management	sync.Pool wrappers to minimize GC pressure during high-throughput data transfer.

4. Core Concepts

KCP Protocol

• Conversation ID (conv): Uniquely identifies a session.
• Command (cmd): PUSH (data), ACK (acknowledgment), WASK (window probe), WINS (window size).
• Fast Retransmit: Retransmits lost packets faster than RTO if out-of-order packets are received.
• No Delay: Configurable mode to minimize RTO and disable congestion control for lowest latency.

FEC (Forward Error Correction)

• Splits data into shards and generates parity shards.
• Allows recovery of N lost packets if N <= parity_shards.
• Increases bandwidth usage but reduces latency caused by retransmissions.

Concurrency Model

• Per-Session Goroutines:
  • readLoop: Reads from the UDP socket (for clients).
  • postProcess: Handles encryption and FEC encoding before sending.
• Global Scheduler: SystemTimedSched (in timedsched.go) manages the update tick for all sessions to avoid creating a ticker goroutine per session.
• Locking: UDPSession uses a sync.Mutex to protect KCP state.

5. Development Guidelines for AI

1. Context Awareness: When modifying kcp.go, remember it is a pure state machine. Do not introduce I/O operations directly into KCP methods.
2. Performance: Be mindful of memory allocations. Use defaultBufferPool (bufferpool.go) for temporary byte slices.
3. Platform Compatibility: If modifying network I/O, check platform_*.go, tx_*.go, and readloop_*.go to ensure cross-platform compatibility (Linux, BSD, Windows, Generic).
4. Testing:
   • Use kcp_test.go for protocol logic tests.
   • Use sess_test.go for integration tests involving UDPSession.
   • Use examples/ to verify end-to-end functionality.
5. Encryption: New encryption methods should implement the BlockCrypt or aeadCrypt interfaces in crypt.go.

6. Common Tasks

• Tuning Parameters: Look at SetNoDelay, SetWindowSize, SetMtu in sess.go.
• Debugging: KCP struct has reserved fields and logging constants (IKCP_LOG_*) that can be enabled for tracing.
• Adding Metrics: snmp.go contains the Snmp struct for global statistics. Update this struct to add new metrics.