mirror of
https://github.com/xtaci/smux.git
synced 2026-10-20 00:17:08 +00:00
94 lines
3.2 KiB
Markdown
94 lines
3.2 KiB
Markdown
# AGENTS.md - smux Project Context
|
|
|
|
## Project Overview
|
|
**smux** (Simple Multiplexing) is a multiplexing library for Golang. It allows multiple logical streams to share a single underlying connection (like TCP or KCP). It is designed for reliability and ordering, and is a core component of [kcp-go](https://github.com/xtaci/kcp-go) and [kcptun](https://github.com/xtaci/kcptun).
|
|
|
|
## Key Features
|
|
- **Multiplexing**: Multiple streams over one connection.
|
|
- **Flow Control**: Token bucket controlled receiving and per-stream sliding window (protocol v2+).
|
|
- **Memory Efficiency**: Shared receive buffer among streams to control overall memory usage.
|
|
- **Low Overhead**: Minimized header (8 bytes).
|
|
- **Traffic Shaping**: Built-in fair queue traffic shaping.
|
|
|
|
## Architecture & Core Components
|
|
|
|
### 1. Session (`session.go`)
|
|
The `Session` struct is the main manager for a multiplexed connection.
|
|
- Manages the underlying `io.ReadWriteCloser`.
|
|
- Handles the creation and acceptance of streams.
|
|
- Manages the shared receive buffer and token bucket.
|
|
- **Key Methods**: `Client`, `Server`, `OpenStream`, `AcceptStream`.
|
|
|
|
### 2. Stream (`stream.go`)
|
|
The `Stream` struct represents a logical stream within a session.
|
|
- Implements `net.Conn` interface (Read, Write, Close, etc.).
|
|
- Handles data buffering and flow control.
|
|
- **Key Methods**: `Read`, `Write`, `Close`.
|
|
|
|
### 3. Frame (`frame.go`)
|
|
Defines the wire format for data transmission.
|
|
- **Header Format** (8 bytes):
|
|
- `VERSION` (1 byte): Protocol version (1 or 2).
|
|
- `CMD` (1 byte): Command type (`SYN`, `FIN`, `PSH`, `NOP`, `UPD`).
|
|
- `LENGTH` (2 bytes): Payload length.
|
|
- `STREAMID` (4 bytes): Stream identifier.
|
|
- **Commands**:
|
|
- `cmdSYN`: Stream open.
|
|
- `cmdFIN`: Stream close (EOF).
|
|
- `cmdPSH`: Data push.
|
|
- `cmdNOP`: No operation (keep-alive).
|
|
- `cmdUPD`: Window update (v2 only).
|
|
|
|
### 4. Configuration (`mux.go`)
|
|
The `Config` struct allows tuning the session.
|
|
- **Key Fields**: `Version`, `KeepAliveInterval`, `MaxFrameSize`, `MaxReceiveBuffer`, `MaxStreamBuffer`.
|
|
|
|
### 5. Traffic Shaping (`shaper.go`)
|
|
Implements traffic shaping logic to ensure fair bandwidth usage among streams.
|
|
|
|
## Development Guidelines
|
|
|
|
### Testing
|
|
- Run all tests:
|
|
```bash
|
|
go test -v .
|
|
```
|
|
- Run benchmarks:
|
|
```bash
|
|
go test -v -run=^$ -bench .
|
|
```
|
|
|
|
### Coding Conventions
|
|
- Follow standard Go coding conventions (formatting, naming, etc.).
|
|
- Ensure backward compatibility when modifying protocol-related code.
|
|
- Pay attention to concurrency and locking, as `Session` and `Stream` are heavily concurrent.
|
|
|
|
## Common Tasks
|
|
|
|
### Creating a Client Session
|
|
```go
|
|
conn, _ := net.Dial(...)
|
|
session, _ := smux.Client(conn, nil) // nil for default config
|
|
stream, _ := session.OpenStream()
|
|
```
|
|
|
|
### Creating a Server Session
|
|
```go
|
|
conn, _ := listener.Accept()
|
|
session, _ := smux.Server(conn, nil)
|
|
stream, _ := session.AcceptStream()
|
|
```
|
|
|
|
### Protocol Versions
|
|
- **Version 1**: Basic multiplexing.
|
|
- **Version 2**: Adds `cmdUPD` for flow control (window updates).
|
|
|
|
## File Structure
|
|
- `alloc.go`: Memory allocation utilities.
|
|
- `frame.go`: Frame definition and parsing.
|
|
- `mux.go`: Configuration and entry points.
|
|
- `session.go`: Session logic.
|
|
- `stream.go`: Stream logic.
|
|
- `shaper.go`: Traffic shaping logic.
|
|
- `*_test.go`: Tests for respective components.
|