wormhole-client/docs/api.md

# Wormhole SOCKS5 Client API

## 概述

Wormhole SOCKS5 Client 在HTTP代理模式下提供了内置的API端点，用于监控和管理代理服务。

## 端点

### 代理功能

所有非API请求都会通过SOCKS5代理转发：

- **HTTP 代理**: 处理普通HTTP请求
- **HTTPS 代理**: 处理CONNECT方法的HTTPS隧道

### 监控API

#### GET /stats

获取详细的代理统计信息。

**响应示例:**
```json
{
  "start_time": "2024-01-01T12:00:00Z",
  "uptime": "2h30m15s",
  "total_connections": 150,
  "active_connections": 5,
  "successful_requests": 145,
  "failed_requests": 5,
  "bytes_sent": 1024000,
  "bytes_received": 2048000,
  "socks5_errors": {
    "connection_failed": 3,
    "auth_failed": 1,
    "timeout": 1
  }
}
```

**字段说明:**
- `start_time`: 代理启动时间
- `uptime`: 运行时间
- `total_connections`: 总连接数
- `active_connections`: 当前活跃连接数
- `successful_requests`: 成功请求数
- `failed_requests`: 失败请求数
- `bytes_sent`: 发送字节数
- `bytes_received`: 接收字节数
- `socks5_errors`: SOCKS5错误分类统计

#### GET /health

获取代理健康状态信息。

**响应示例:**
```json
{
  "status": "healthy",
  "uptime": "2h30m15s",
  "active_connections": 5,
  "success_rate": 96.67
}
```

**字段说明:**
- `status`: 健康状态 ("healthy")
- `uptime`: 运行时间
- `active_connections`: 当前活跃连接数
- `success_rate`: 成功率百分比

## 使用示例

### 基本用法

1. **启动HTTP代理模式:**
   ```bash
   ./bin/wormhole-client -mode http -config configs/client.yaml
   ```

2. **配置浏览器代理:**
   - HTTP代理: `127.0.0.1:8080`
   - HTTPS代理: `127.0.0.1:8080`

3. **访问统计信息:**
   ```bash
   curl http://127.0.0.1:8080/stats
   ```

4. **检查健康状态:**
   ```bash
   curl http://127.0.0.1:8080/health
   ```

### 监控脚本示例

#### Bash监控脚本

```bash
#!/bin/bash

PROXY_URL="http://127.0.0.1:8080"

echo "=== Wormhole SOCKS5 Client Status ==="

# 健康检查
health=$(curl -s "$PROXY_URL/health")
echo "Health: $health"

# 统计信息
stats=$(curl -s "$PROXY_URL/stats")
echo "Stats: $stats"

# 提取关键指标
success_rate=$(echo "$health" | jq -r '.success_rate')
active_conn=$(echo "$health" | jq -r '.active_connections')

echo "Success Rate: ${success_rate}%"
echo "Active Connections: $active_conn"
```

#### Python监控脚本

```python
import requests
import json
import time

def get_proxy_stats():
    try:
        response = requests.get('http://127.0.0.1:8080/stats')
        return response.json()
    except Exception as e:
        print(f"Error getting stats: {e}")
        return None

def get_proxy_health():
    try:
        response = requests.get('http://127.0.0.1:8080/health')
        return response.json()
    except Exception as e:
        print(f"Error getting health: {e}")
        return None

def monitor_proxy():
    while True:
        health = get_proxy_health()
        if health:
            print(f"Status: {health['status']}")
            print(f"Success Rate: {health['success_rate']:.2f}%")
            print(f"Active Connections: {health['active_connections']}")
            print(f"Uptime: {health['uptime']}")
        
        print("-" * 40)
        time.sleep(30)  # 每30秒检查一次

if __name__ == "__main__":
    monitor_proxy()
```

## SOCKS5协议支持

### 地址类型支持

- ✅ **IPv4地址** (0x01): `192.168.1.1:80`
- ✅ **域名** (0x03): `example.com:80`
- ✅ **IPv6地址** (0x04): `[2001:db8::1]:80`

### 认证方法支持

- ✅ **无认证** (0x00)
- ✅ **用户名密码认证** (0x02)

### 错误处理

代理能够处理并报告以下SOCKS5错误：

| 错误码 | 含义 | 统计字段 |
|--------|------|----------|
| 0x01 | 一般SOCKS服务器故障 | `general_failure` |
| 0x02 | 连接不被规则集允许 | `not_allowed` |
| 0x03 | 网络不可达 | `network_unreachable` |
| 0x04 | 主机不可达 | `host_unreachable` |
| 0x05 | 连接被拒绝 | `connection_refused` |
| 0x06 | TTL过期 | `ttl_expired` |
| 0x07 | 不支持的命令 | `command_not_supported` |
| 0x08 | 不支持的地址类型 | `address_not_supported` |

## 性能特性

### 连接管理
- 异步处理多个并发连接
- 自动资源清理
- 超时管理

### 统计精度
- 原子操作保证并发安全
- 实时字节传输统计
- 详细的错误分类

### HTTP服务器配置
- 读取超时: 30秒
- 写入超时: 30秒
- 空闲超时: 120秒
- 最大头部大小: 1MB

## 故障排除

### 常见问题

1. **无法访问统计API**
   - 确认代理运行在HTTP模式
   - 检查端口是否正确
   - 确认防火墙设置

2. **统计数据不准确**
   - 重启代理服务
   - 检查并发连接情况

3. **高错误率**
   - 检查SOCKS5服务器状态
   - 验证认证信息
   - 查看网络连接质量

### 日志级别

设置 `logLevel: debug` 可以获得详细的调试信息：

```yaml
logLevel: debug  # debug, info, warn, error
```