Go Proxy Server Project Guide
This skill provides comprehensive guidance for working with a dual-protocol proxy server implementation in Go that supports both SOCKS5 and HTTP/HTTPS protocols.
Project Overview
A production-ready proxy server with:
SOCKS5 and HTTP/HTTPS protocol supportUsername/password authenticationIP whitelist access controlSQLite database storageSpecial bind-listen mode for multi-IP exit routingWeb management interface (React + TypeScript + Ant Design)Windows system tray applicationConnection rate limiting and SSRF protectionKey Architecture Components
Entry Point & CLI
**cmd/server/main.go**: CLI routing, database initialization, platform-specific defaultsNo arguments: Windows starts system tray, Linux/macOS starts web server on port 9090Auto-starts proxies based on saved configuration (`AutoStart` flag)Proxy Implementations
**internal/proxy/socks5.go**: SOCKS5 protocol with authentication flow, bind-listen support**internal/proxy/http.go**: HTTP/HTTPS proxy with CONNECT tunneling, Basic auth**internal/proxy/limiter.go**: Per-IP and global connection rate limiting**internal/proxy/copy.go**: Bidirectional TCP relay with proper half-close handlingAuthentication & Security
**internal/auth/auth.go**: Credential verification with timing attack protection**internal/auth/user.go**: User management with password strength validation**internal/auth/whitelist.go**: IP whitelist with thread-safe atomic storage**internal/security/security.go**: SSRF/DNS rebinding prevention, DNS cachingWeb Management
**internal/web/manager.go**: Proxy lifecycle management (start/stop/restart)**internal/web/handlers.go**: RESTful API (status, users, whitelist, config)**web-ui/**: React SPA with TypeScript, Vite build systemPlatform-Specific
**internal/tray/**: Windows system tray (notification area) integration**internal/autostart/**: Windows startup folder management via COM**internal/singleinstance/**: Windows named mutex for single-instance enforcementBuild Commands
Using Makefile (Recommended)
```bash
make build # Current platform → bin/go-proxy-server
make build-windows # Console mode → bin/go-proxy-server.exe
make build-windows-gui # System tray mode → bin/go-proxy-server-gui.exe
make build-linux # Linux → bin/go-proxy-server-linux-amd64
make build-darwin # macOS → bin/go-proxy-server-darwin-amd64
make build-all # All platforms
make clean # Remove bin/
```
Direct Go Build
```bash
Current platform
mkdir -p bin && go build -o bin/go-proxy-server ./cmd/server
Windows GUI (system tray)
mkdir -p bin && GOOS=windows GOARCH=amd64 go build -ldflags "-H=windowsgui" -o bin/go-proxy-server-gui.exe ./cmd/server
```
Running the Server
Default Behavior (No Arguments)
```bash
./bin/go-proxy-server
Windows: System tray application
Linux/macOS: Web server on http://localhost:9090
```
Proxy Modes
```bash
SOCKS5 only
./bin/go-proxy-server socks -port 1080
HTTP only
./bin/go-proxy-server http -port 8080
Both simultaneously
./bin/go-proxy-server both -socks-port 1080 -http-port 8080
Bind-listen mode (multi-IP routing)
./bin/go-proxy-server socks -port 8888 -bind-listen
```
User Management
```bash
Add user (IP optional, for audit only)
./bin/go-proxy-server adduser -username alice -password secret123 -ip 192.168.1.100
Delete user
./bin/go-proxy-server deluser -username alice
List users
./bin/go-proxy-server listuser
```
IP Whitelist
```bash
Add IP
./bin/go-proxy-server addip -ip 192.168.1.100
```
Development Guidelines
When Adding Features
1. **Database Changes**: Update `internal/models/` GORM models first
2. **API Endpoints**: Add handlers to `internal/web/handlers.go` following RESTful conventions
3. **Frontend**: Update `web-ui/src/` React components, rebuild with `npm run build`
4. **Security**: Always validate input, use constant-time comparisons for auth, check SSRF
Configuration Constants
All timing/capacity constants live in **internal/constants/constants.go**:
`ConfigReloadInterval`: 30s (hot-reload interval)`DNSCacheTTL`: 5 minutes`MaxDNSCacheSize`: 10,000 entries`AuthCacheTTL`: 5 minutesThread Safety
Use `atomic.Value` for lock-free reads (credentials, whitelist)Use `sync.RWMutex` for proxy state managementUse `ShardedLRU` (16 shards) for high-concurrency cachingCross-Platform Considerations
Data directory: Use `config.GetDataDir()` (Windows/macOS/Linux/XDG)Windows-specific code: Use build tags `// +build windows`System tray: Windows-only, requires `github.com/getlantern/systray`Frontend Development
```bash
cd web-ui
npm install
npm run dev # Dev server with hot reload
npm run build # Production build → dist/
```
Copy `dist/` to `internal/web/dist/` for embedding.
Testing Checklist
[ ] Test SOCKS5 authentication flow (correct/incorrect credentials)[ ] Test HTTP CONNECT tunneling (HTTPS sites)[ ] Test bind-listen mode with multiple local IPs[ ] Test IP whitelist enforcement[ ] Test rate limiting (per-IP and global)[ ] Test SSRF protection (attempt to connect to 127.0.0.1, 169.254.0.0/16)[ ] Test web UI (start/stop proxies, add users/IPs)[ ] Test Windows system tray (right-click menu, open browser)[ ] Test config hot-reload (change DB, wait 30s)Common Tasks
Add New Proxy Protocol
1. Create `internal/proxy/newprotocol.go` with `HandleConnection()`
2. Add command to `cmd/server/main.go`
3. Update `ProxyConfig` model with new fields
4. Add API endpoints in `internal/web/handlers.go`
5. Add UI controls in `web-ui/src/components/`
Add New Authentication Method
1. Extend `internal/auth/auth.go` with new verification logic
2. Update `User` model if schema changes needed
3. Add API endpoint for configuration
4. Update frontend settings page
Debug Connection Issues
Check logs: Windows GUI mode writes to `%APPDATA%\go-proxy-server\server.log`Verify credentials: `./bin/go-proxy-server listuser`Check whitelist: `SELECT * FROM whitelists;` in SQLite DBTest with `curl -x socks5h://user:pass@localhost:1080 https://example.com`Important Notes
Database path: Auto-determined via `config.GetDataDir()`, no manual config neededPassword format: `$sha256$<salt>$<hash>` (SHA-256 with random salt)Username is globally unique across all usersIP field in users table is for audit/logging only, not authenticationWhitelist has no automatic local bypass (127.0.0.1 must be explicitly added)Windows single instance check prevents port conflicts