rhttp/doc/require.md

# Rust HTTP服务器实现需求

## 项目概述
使用Rust实现一个高性能、可配置的HTTP服务器，支持多站点托管、多种代理类型和JavaScript动态配置。

## 核心功能需求

### 1. 多站点支持
- 在单个端口（如80/443）上服务多个独立站点
- 基于HTTP `Host`头部进行站点路由
- 每个站点有独立配置和资源隔离

### 2. 路径配置系统
```
站点配置示例结构：
{
  "example.com": {
    "/api/*": "反向代理到 http://backend:3000",
    "/static/*": "静态目录 ./public",
    "/blog": "正向代理处理",
    "/ws/*": "TCP代理到 ws://chat-server:8080"
  }
}
```

### 3. 请求处理类型
- **静态资源服务**：
  - 文件系统映射
  - MIME类型自动识别
  - 缓存控制头支持
  - 目录列表（可选）

- **反向代理**：
  - 支持HTTP/HTTPS后端
  - 连接池管理
  - 请求/响应头重写
  - 负载均衡（轮询/最少连接）

- **正向代理**：
  - CONNECT方法支持
  - 认证机制
  - 访问控制列表

- **TCP代理**：
  - 原始TCP流量转发
  - WebSocket协议支持
  - 自定义协议代理

### 4. JavaScript配置引擎
- 嵌入V8/Deno或QuickJS引擎
- 支持热重载配置
- 配置验证和错误报告
- 运行时动态路由修改

## 技术栈建议

### HTTP服务器框架
```toml
[dependencies]
# 选择以下之一作为基础：
tokio = { version = "1.0", features = ["full"] }
async-std = "1.0"
# HTTP库
hyper = "1.0"
warp = "0.3"
axum = "0.7"
# 或更底层的
tower = "0.4"
```

### JavaScript引擎选项
```toml
# 选项1: Deno核心（V8）
deno_core = "0.200"
# 选项2: QuickJS（轻量级）
rquickjs = "0.4"
# 选项3: Boa（纯Rust实现）
boa_engine = "0.17"
```

### 其他关键依赖
```toml
[dependencies]
# 配置管理
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
toml = "0.7"
# 静态文件服务
tower-http = { version = "0.4", features = ["fs", "trace"] }
mime_guess = "2.0"
# 代理功能
hyper-reverse-proxy = "0.5"
reqwest = { version = "0.11", features = ["json"] }
# TCP处理
tokio-util = { version = "0.7", features = ["codec"] }
tokio-native-tls = "0.3"
# 路由
matchit = "0.7"
regex = "1.0"
```

## 架构设计要点

### 1. 核心组件结构
```rust
struct ProxyServer {
    config: Arc<RwLock<ServerConfig>>,
    sites: HashMap<String, Site>,
    js_engine: JsEngine,
    runtime: Runtime,
}

struct Site {
    hostname: String,
    routes: Vec<RouteRule>,
    certificates: Option<TlsConfig>,
}

enum RouteRule {
    Static {
        path_pattern: String,
        directory: PathBuf,
        options: StaticOptions,
    },
    ReverseProxy {
        path_pattern: String,
        upstreams: Vec<Upstream>,
        options: ProxyOptions,
    },
    TcpProxy {
        path_pattern: String,
        target: SocketAddr,
        protocol: ProtocolType,
    },
}
```

### 2. 配置系统
```javascript
// config.js 示例
export default {
  port: 8080,
  sites: {
    "api.example.com": {
      "/v1/*": {
        type: "reverse_proxy",
        target: "http://localhost:3001",
        rewrite: {
          "^/v1": "/api/v1"
        }
      }
    },
    "static.example.com": {
      "/*": {
        type: "static",
        root: "./static",
        index: ["index.html"]
      }
    }
  },
  
  // JavaScript中间件
  middleware: async function(req) {
    console.log(`Request: ${req.method} ${req.url}`);
    return null; // 返回null继续处理，或返回Response直接响应
  }
}
```

### 3. 请求处理流程
```
请求接收 → 解析Host头 → 查找站点配置 → 匹配路由规则 → 
JavaScript中间件处理 → 执行对应处理器 → 返回响应
```

## 实现优先级建议

### Phase 1: 基础框架
1. 基本HTTP服务器
2. 基于Host头的路由
3. 静态文件服务
4. 简单配置（JSON/TOML）

### Phase 2: 代理功能
1. 反向代理实现
2. TCP代理基础
3. 连接池和超时控制

### Phase 3: JavaScript集成
1. 嵌入JS引擎
2. JS配置文件支持
3. 动态路由更新

### Phase 4: 高级特性
1. SSL/TLS支持
2. 健康检查
3. 监控和日志
4. 性能优化

## 关键难点解决方案

### 1. 热重载配置
- 使用inotify/watch监听配置文件变化
- 原子配置切换避免锁竞争
- 优雅关闭旧连接

### 2. 内存安全
- 合理使用Arc/RwLock共享配置
- 连接数限制和超时
- 防范DDoS攻击

### 3. 性能优化
- 连接复用（keep-alive）
- 零拷贝文件传输（sendfile）
- 异步I/O和并行处理

## 测试要点
1. 多站点路由正确性
2. 代理功能完整性
3. JS配置热更新
4. 并发性能和内存使用
5. 错误处理和恢复