mirror of
https://github.com/xtaci/kcp-go.git
synced 2026-10-20 08:16:39 +00:00
78 lines
4.8 KiB
Markdown
78 lines
4.8 KiB
Markdown
# 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.
|