# Proxy Pool 项目架构

## 1. 仓库结构

```text
proxy-pool/
├── cmd/
│   ├── proxy-gateway/       # 数据面进程
│   ├── proxy-controller/    # 控制面与 HTTP API
│   ├── proxy-checker/       # 健康检查执行器
│   └── proxy-loadgen/       # 可复现容量测试
├── internal/
│   ├── config/              # 严格配置解析和校验
│   ├── domain/              # 无传输、无存储依赖的领域模型
│   ├── gateway/             # bootstrap、snapshot、dispatch、server、transport
│   ├── controller/          # provider、pool、extraction、operations、runtime、bootstrap
│   ├── adapters/            # PostgreSQL、Redis、Provider API、内存适配
│   └── platform/            # HTTP、安全、日志、指标、停机和进程装配
├── api/                     # OpenAPI 与 Protobuf 契约
├── configs/                 # 默认配置
├── examples/                # 可校验配置场景
├── deploy/                  # Compose 与 Kubernetes
├── docs/                    # 设计、开发、API、测试、运维
├── diagrams/                # Mermaid 图集
├── scripts/                 # 验证和生成脚本
└── test/                    # fixture、集成、端到端和负载测试
```

## 2. 进程边界

### proxy-gateway

`gateway -> dispatch -> transport` 是数据面主调用链。`dispatch` 包含筛选、
选择、session 与重试资格等热路径决策；`transport` 独占连接池、上游握手和
隧道生命周期。任何包都不得从热路径反向调用 Controller 存储。

`gateway/bootstrap` 只在进程启动时加载配置、建立 gRPC 控制面 Session、组装 HTTP
代理与 Metrics 监听；请求热路径只读取本地 Snapshot。`/readyz` 要求当前 Snapshot
尚未到期，控制面断开期间以有界退避重连而不访问 Redis/PostgreSQL。

### proxy-controller

Controller 是首版模块化单体。Provider、Pool、Routing 和 Extraction 共享
运行时策略和状态演进，但不建立 PostgreSQL/Redis 跨存储事务。对外端口定义
在领域或控制器模块，具体 PostgreSQL/Redis/HTTP 实现在 `adapters`。

### proxy-checker

Checker 只产生 Observation。它从认证 gRPC 流领取有界任务，用固定 worker-pool 在任务
deadline 内执行 HTTP/HTTPS/SOCKS5 BASIC、EGRESS 和 TARGET 探测并微批上报；EGRESS 的
任务 URL 仅在执行期使用，回传全局事实不包含该 URL。最终状态迁移仍由 Controller 的
确定性 reducer 完成，避免多个检查实例同时写 Proxy 状态。Checker 不访问 Redis 或 PostgreSQL。

### proxy-loadgen

负载工具当前生成有界 HTTP、CONNECT 长连接和 Extract 请求，支持经 Gateway 请求 HTTPS 目标、
固定请求数或时长、目标 QPS、可重复请求头和请求体、连接复用和 JSON 指标输出。延迟统计使用
固定大小直方图，不会因长时间高 QPS 运行积压样本。故障注入和代表性集群报告仍待补齐；它是
100k QPS 结论的证据工具，不是业务进程。

## 3. 依赖方向

```text
cmd -> controller/gateway/checker -> domain
                    |
                    +------------> port interfaces
adapters -------------------------> port interfaces
platform -------------------------> standard library / observability SDK
```

硬性规则：

1. `domain` 不导入 HTTP、SQL、Redis、配置或平台包。
2. `gateway/dispatch` 只依赖本地 Snapshot 与领域类型。
3. `adapters` 实现端口，不被领域层反向引用。
4. 配置先解析、校验、编译为运行时对象，再原子发布。
5. Secret 仅通过引用进入运行时，不进入唯一键、指标或日志字段。

## 4. 数据所有权

- PostgreSQL：配置版本、Upstream/Routing 管理状态、Admin 审计与 Outbox，
  以及可选的无 Proxy 明细聚合指标。
- Redis：带 TTL 的短效 Proxy 活动池及其状态、所有权和过期时间；同时保存
  Provider Leader、分布式速率、Worker 心跳和短期提取幂等结果。
- Worker：仅拥有分配给自己的 Proxy 本地容量计数和不可变快照。
- Controller：拥有 Provider 调度、Routing 运行态与 Worker 所有权编排。
- Checker：不拥有 Proxy 状态，只拥有执行中的检查任务。

Proxy 明细不进入 PostgreSQL。Redis 活动池丢失后由 Provider 重新获取并重建，
节点内存中的旧快照随版本或有效期失效，不能把 PostgreSQL 当成恢复来源。

## 5. 一致性边界

- Extraction 在 Redis 内原子完成候选筛选、排他状态迁移和短期幂等结果写入，
  成功后才响应；该路径不访问 PostgreSQL。
- Worker 所有权采用 `worker + epoch + version + expiry`，同一 Proxy 至多归属
  一个 Worker。
- 从 Worker 回收 Proxy 时先 Drain，等待 ACK 且 Active/Reserved 为零，再
  解除所有权；只有无所有权 Proxy 能被 Distribution 提取。
- Snapshot 为整代不可变对象，通过校验和和严格版本序列原子替换。
- PostgreSQL 故障会影响管理状态变更和 Admin 审计，但不应阻断 Redis 中可完成
  的独占提取；Redis 故障则使活动池暂不可用，并触发 Provider 重建。

## 6. 扩展规则

- 新 Provider：增加 Adapter，不修改 Proxy/Pool/Routing 领域语义。
- 新入口协议：在 Gateway 增加 ingress adapter；只有存在第二种上游协议
  执行方式时再抽象 egress adapter。
- 新路由策略：实现同一策略端口，并提供确定性单测和并发不变量测试。
- 新存储：实现已有 repository port，不把驱动类型泄漏到控制器。