# Proxy Pool 产品设计文案

## 1. 产品定位

Proxy Pool 把多个供应商的动态代理统一成一个可运营的资源系统。平台面对
两类不同使用方式：需要平台代转发流量的应用使用 Gateway；需要拿到真实
代理并自行建立连接的应用使用 Distribution API。

两类入口共享 Provider、健康、TTL 和路由配置，但资源分配语义不同：

- Gateway 只在一次请求或隧道生命周期内占用代理并发，结束后释放容量。
- Distribution 一旦返回代理，该代理即永久离开系统可分配池。

## 2. 目标用户

- **业务调用方**：通过稳定入口使用代理，不感知供应商差异。
- **代理直提调用方**：按协议、区域、运营商或 Upstream 条件独占提取。
- **平台管理员**：管理 Provider、Routing、容量、健康和故障切换。
- **SRE**：依据低基数指标、审计记录和运行手册进行容量与故障管理。

## 3. 核心价值

### 3.1 供应商差异收敛

Provider Adapter 负责请求格式、认证和响应解析。标准化后，Routing、健康、
容量和业务入口只依赖统一 Proxy 模型，不把供应商字段传入核心域。

### 3.2 高并发热路径隔离

Gateway Worker 只读取本地不可变快照并维护本地容量计数。供应商延迟、
数据库抖动和控制面重载不会成为每请求依赖。

### 3.3 明确且可审计的资源语义

系统区分“短时使用容量”和“一次性独占提取”。每次 Extraction 保存请求、
调用方、来源、Upstream、提取时间和过期时间审计事实，但不追踪提取后的
实际使用，也不存在归还接口。

## 4. 主要流程

### 4.1 Gateway 请求

1. 接入层完成认证、来源识别、限流和目标地址检查。
2. Routing 按配置顺序首条命中。
3. Dispatcher 从本地快照筛选 Upstream、协议、标签、TTL 和健康条件。
4. 原子预留 Proxy 容量，建立到上游代理的连接。
5. 建连成功后转为 Active，传输结束后释放；失败则取消预留。
6. GET/HEAD 仅在响应提交前按策略重试；CONNECT 建立后不重放。

### 4.2 独占提取

1. 调用方提交数量、过滤条件和 fulfillment。
2. Controller 校验调用方限额、TTL、健康新鲜度及 Gateway 保留量。
3. 在一个数据库事务中锁定候选并执行 `AVAILABLE -> EXTRACTED`。
4. `partial` 尽量返回；`allOrNothing` 数量不足时零提取。
5. 响应返回代理 URL、`expiresAt` 和 `remainingTtlSeconds`。

### 4.3 Sequential 切换

1. Provider 响应成功且解析成功，但合法候选为零，才累计 Empty。
2. 网络、认证、HTTP、模板或解析失败只计 Error。
3. 全部候选均重复时计 DuplicateOnly，并重置连续 Empty。
4. 达到阈值后，引用该 Upstream 的 Routing 原子前进一次。
5. 旧 Upstream 已有 Proxy 继续耗尽，不因切换被直接删除。

## 5. 失败体验

- 无候选时严格执行 Routing 的 `reject`、`wait` 或 `direct`，默认拒绝。
- Distribution 部分满足用 200 返回实际数量；全有或全无不足时返回冲突状态。
- Provider 故障进入退避，不让调用请求触发同步 Provider 获取。
- 快照版本断档时 Worker 保留最后一份完整快照并请求全量重同步。
- 控制面不可用时，现有 Worker 可在快照有效期内继续服务，停止接收新配置。

## 6. 容量目标与服务指标

- 集群峰值目标：100,000 QPS。
- Worker 副本数：

```text
required_workers = ceil(peak_qps / (measured_worker_qps * target_utilization))
                   + failure_domain_spares
```

- `measured_worker_qps` 必须来自目标协议占比、代理 RTT、连接复用率和安全策略
  均接近生产的压测。
- 设计阶段不承诺单 Worker QPS，也不以平均值替代 P95/P99 和错误率。

## 7. 首版范围

首版包含 HTTP 正向代理、HTTPS CONNECT、REST Distribution/Admin、Provider
适配、健康与生命周期、Sequential 等路由策略、PostgreSQL 权威状态、Redis
可重建协调和集群快照。SOCKS5、跨地域主动主动和高级成本优化保留扩展边界。