|
| 1 | +# NodePass AI Coding Agent Instructions |
| 2 | + |
| 3 | +## Project Overview |
| 4 | + |
| 5 | +NodePass is an enterprise-grade TCP/UDP network tunneling solution with a three-tier architecture supporting server, client, and master modes. The core is written in Go with a focus on performance, security, and minimal configuration. |
| 6 | + |
| 7 | +## Architecture Essentials |
| 8 | + |
| 9 | +### Three-Tier S/C/M Architecture |
| 10 | + |
| 11 | +1. **Server Mode** (`internal/server.go`): Accepts tunnel connections, manages connection pools, forwards traffic bidirectionally |
| 12 | +2. **Client Mode** (`internal/client.go`): Connects to servers, supports single-end forwarding or dual-end handshake modes |
| 13 | +3. **Master Mode** (`internal/master.go`): RESTful API for dynamic instance management with persistent state in `nodepass.gob` |
| 14 | + |
| 15 | +### Critical Design Patterns |
| 16 | + |
| 17 | +- **Separation of Control/Data Channels**: |
| 18 | + - Control channel: Unencrypted TCP for signaling (`np://` scheme with fragments) |
| 19 | + - Data channel: Configurable TLS (modes 0/1/2) for actual traffic |
| 20 | + |
| 21 | +- **Connection Pooling**: Pre-established connections via `github.com/NodePassProject/pool` library |
| 22 | + - Server controls `max` pool capacity, passes to client during handshake |
| 23 | + - Client manages `min` capacity for persistent connections |
| 24 | + |
| 25 | +- **Bidirectional Data Flow**: Automatic mode detection in `Common.runMode` |
| 26 | + - Mode 0: Auto-detect based on target address bindability |
| 27 | + - Mode 1: Reverse/single-end (server receives OR client listens locally) |
| 28 | + - Mode 2: Forward/dual-end (server sends OR client connects remotely) |
| 29 | + |
| 30 | +### External Dependencies (NodePassProject Ecosystem) |
| 31 | + |
| 32 | +All critical networking primitives are in separate libraries: |
| 33 | +- `github.com/NodePassProject/cert`: TLS certificate generation and management |
| 34 | +- `github.com/NodePassProject/conn`: Custom connection types (`StatConn`, `TimeoutReader`, `DataExchange`) |
| 35 | +- `github.com/NodePassProject/logs`: Structured logging with levels (None/Debug/Info/Warn/Error/Event) |
| 36 | +- `github.com/NodePassProject/pool`: Connection pool management for both server and client |
| 37 | + |
| 38 | +**Never modify these libraries directly** - they're external dependencies. Use their exported APIs only. |
| 39 | + |
| 40 | +## Configuration System |
| 41 | + |
| 42 | +### URL-Based Configuration |
| 43 | + |
| 44 | +All modes use URL-style configuration: `scheme://[password@]host:port/target?param=value` |
| 45 | + |
| 46 | +**Server**: `server://bind_addr:port/target_addr:port?max=1024&tls=1&log=debug` |
| 47 | +**Client**: `client://server_addr:port/local_addr:port?min=128&mode=0&rate=100` |
| 48 | +**Master**: `master://api_addr:port/prefix?log=info&tls=2&crt=path&key=path` |
| 49 | + |
| 50 | +### Query Parameters |
| 51 | + |
| 52 | +- `log`: none|debug|info|warn|error|event (default: info) |
| 53 | +- `tls`: 0=plain, 1=self-signed, 2=custom cert (server/master only) |
| 54 | +- `min`/`max`: Connection pool capacity (client sets min, server sets max) |
| 55 | +- `mode`: 0=auto, 1=reverse/single-end, 2=forward/dual-end |
| 56 | +- `read`: Timeout duration (e.g., 1h, 30m, 15s) |
| 57 | +- `rate`: Mbps bandwidth limit (0=unlimited) |
| 58 | +- `slot`: Max concurrent connections (default: 65536) |
| 59 | +- `proxy`: PROXY protocol v1 support (0=off, 1=on) |
| 60 | + |
| 61 | +### Environment Variables for Tuning |
| 62 | + |
| 63 | +See `internal/common.go` for all `NP_*` environment variables: |
| 64 | +- `NP_TCP_DATA_BUF_SIZE`: TCP buffer size (default: 16384) |
| 65 | +- `NP_UDP_DATA_BUF_SIZE`: UDP buffer size (default: 2048) |
| 66 | +- `NP_HANDSHAKE_TIMEOUT`: Handshake timeout (default: 5s) |
| 67 | +- `NP_POOL_GET_TIMEOUT`: Pool connection timeout (default: 5s) |
| 68 | +- `NP_REPORT_INTERVAL`: Health check interval (default: 5s) |
| 69 | +- `NP_RELOAD_INTERVAL`: TLS cert reload interval (default: 1h) |
| 70 | + |
| 71 | +## Development Workflow |
| 72 | + |
| 73 | +### Building |
| 74 | + |
| 75 | +```bash |
| 76 | +# Development build |
| 77 | +go build -o nodepass ./cmd/nodepass |
| 78 | + |
| 79 | +# Release build (mimics .goreleaser.yml) |
| 80 | +go build -trimpath -ldflags="-s -w -X main.version=dev" -o nodepass ./cmd/nodepass |
| 81 | +``` |
| 82 | + |
| 83 | +### Testing Manually |
| 84 | + |
| 85 | +No automated test suite exists currently. Test via real-world scenarios: |
| 86 | + |
| 87 | +```bash |
| 88 | +# Terminal 1: Server with debug logging |
| 89 | +./nodepass "server://0.0.0.0:10101/127.0.0.1:8080?log=debug&tls=1&max=256" |
| 90 | + |
| 91 | +# Terminal 2: Client |
| 92 | +./nodepass "client://localhost:10101/127.0.0.1:9090?log=debug&min=64" |
| 93 | + |
| 94 | +# Terminal 3: Master mode for API testing |
| 95 | +./nodepass "master://0.0.0.0:9090/api?log=debug&tls=0" |
| 96 | +``` |
| 97 | + |
| 98 | +Test all TLS modes (0, 1, 2) and protocol types (TCP, UDP). Verify graceful shutdown with SIGTERM/SIGINT. |
| 99 | + |
| 100 | +### Release Process |
| 101 | + |
| 102 | +Uses GoReleaser on tag push (`v*.*.*`). See `.goreleaser.yml` for build matrix (Linux, Windows, macOS, FreeBSD across multiple architectures). |
| 103 | + |
| 104 | +## Code Patterns & Conventions |
| 105 | + |
| 106 | +### Error Handling |
| 107 | + |
| 108 | +Always wrap errors with context using `fmt.Errorf("function: operation failed: %w", err)` |
| 109 | + |
| 110 | +### Logging |
| 111 | + |
| 112 | +Use the injected `logger` instance with appropriate levels: |
| 113 | +```go |
| 114 | +logger.Debug("Detailed info: %v", detail) // Verbose debugging |
| 115 | +logger.Info("Operation: %v", status) // Normal operations |
| 116 | +logger.Warn("Non-critical issue: %v", err) // Recoverable problems |
| 117 | +logger.Error("Critical error: %v", err) // Functionality affected |
| 118 | +logger.Event("Traffic stats: %v", stats) // Important events |
| 119 | +``` |
| 120 | + |
| 121 | +### Goroutine Management |
| 122 | + |
| 123 | +All long-running goroutines must: |
| 124 | +1. Check `ctx.Err()` regularly for cancellation |
| 125 | +2. Use proper cleanup with `defer` statements |
| 126 | +3. Handle panics in critical sections |
| 127 | +4. Release resources (slots, buffers, connections) on exit |
| 128 | + |
| 129 | +### Buffer Pooling |
| 130 | + |
| 131 | +Always use `Common.getTCPBuffer()` / `Common.putTCPBuffer()` or UDP equivalents to minimize allocations: |
| 132 | +```go |
| 133 | +buf := c.getTCPBuffer() |
| 134 | +defer c.putTCPBuffer(buf) |
| 135 | +// ... use buf |
| 136 | +``` |
| 137 | + |
| 138 | +### Connection Slot Management |
| 139 | + |
| 140 | +Before creating connections: |
| 141 | +```go |
| 142 | +if !c.tryAcquireSlot(isUDP) { |
| 143 | + return fmt.Errorf("slot limit reached") |
| 144 | +} |
| 145 | +defer c.releaseSlot(isUDP) |
| 146 | +``` |
| 147 | + |
| 148 | +### Comments Style |
| 149 | + |
| 150 | +Maintain bilingual (Chinese/English) comments for public APIs and exported functions: |
| 151 | +```go |
| 152 | +// NewServer 创建新的服务端实例 |
| 153 | +// NewServer creates a new server instance |
| 154 | +func NewServer(parsedURL *url.URL, ...) (*Server, error) { ... } |
| 155 | +``` |
| 156 | + |
| 157 | +## Master Mode Specifics |
| 158 | + |
| 159 | +### API Structure |
| 160 | + |
| 161 | +RESTful endpoints at `/{prefix}/*` (default `/api/*`): |
| 162 | +- Instance CRUD: POST/GET/PATCH/PUT/DELETE on `/instances` and `/instances/{id}` |
| 163 | +- Real-time events: SSE stream at `/events` (types: initial, create, update, delete, shutdown, log) |
| 164 | +- OpenAPI docs: `/openapi.json` and `/docs` (Swagger UI) |
| 165 | + |
| 166 | +### State Persistence |
| 167 | + |
| 168 | +All instances stored in `nodepass.gob` using Go's `encoding/gob`: |
| 169 | +- Auto-saved on instance changes via `saveMasterState()` |
| 170 | +- Restored on startup via `restoreMasterState()` |
| 171 | +- Mutex-protected writes with `stateMu` |
| 172 | + |
| 173 | +### API Authentication |
| 174 | + |
| 175 | +API Key in `X-API-Key` header. Special instance ID `********` for key regeneration via PATCH action `restart`. |
| 176 | + |
| 177 | +## Common Pitfalls |
| 178 | + |
| 179 | +1. **Don't modify NodePassProject libraries**: These are external dependencies, not internal packages |
| 180 | +2. **Always decode before using tunnel URLs**: Use `Common.decode()` for base64+XOR encoded data |
| 181 | +3. **TLS mode is server-controlled**: Clients receive TLS mode during handshake, don't override |
| 182 | +4. **Pool capacity coordination**: Server sets `max`, client sets `min` - they must align correctly |
| 183 | +5. **UDP session cleanup**: Sessions in `targetUDPSession` require explicit cleanup with timeouts |
| 184 | +6. **Certificate hot-reload**: Only applies to `tls=2` mode with periodic checks every `ReloadInterval` |
| 185 | +7. **Graceful shutdown**: Use context cancellation propagation, don't abruptly close connections |
| 186 | + |
| 187 | +## Key Files Reference |
| 188 | + |
| 189 | +- `cmd/nodepass/main.go`: Entry point, version variable injection |
| 190 | +- `cmd/nodepass/core.go`: Mode dispatch, TLS setup, CLI help formatting |
| 191 | +- `internal/common.go`: Shared primitives (buffer pools, slot management, encoding, config init) |
| 192 | +- `internal/server.go`: Server lifecycle, tunnel handshake, forward/reverse modes |
| 193 | +- `internal/client.go`: Client lifecycle, single-end/dual-end modes, tunnel connection |
| 194 | +- `internal/master.go`: HTTP API, SSE events, instance subprocess management, state persistence |
| 195 | +- `docs/en/how-it-works.md`: Detailed architecture documentation |
| 196 | +- `docs/en/configuration.md`: Complete parameter reference |
| 197 | +- `docs/en/api.md`: Master mode API specification |
| 198 | + |
| 199 | +## Documentation Requirements |
| 200 | + |
| 201 | +When adding features: |
| 202 | +1. Update relevant `docs/en/*.md` and `docs/zh/*.md` files |
| 203 | +2. Add examples to `docs/en/examples.md` |
| 204 | +3. Document new query parameters in `docs/en/configuration.md` |
| 205 | +4. Update API endpoints in `docs/en/api.md` if touching master mode |
| 206 | +5. Keep README.md feature list current |
| 207 | + |
| 208 | +## Additional Notes |
| 209 | + |
| 210 | +- Project uses Go 1.25+ features, maintain compatibility |
| 211 | +- Single binary with no external runtime dependencies (except TLS cert files for mode 2) |
| 212 | +- Focus on zero-configuration deployment - defaults should work for most use cases |
| 213 | +- Performance-critical paths: buffer allocation, connection pooling, data transfer loops |
| 214 | +- Security considerations: TLS mode selection, API key protection, input validation on master API |
0 commit comments