# Proxy Pool 统一领域语言

## 核心实体

- **Client**：使用 Gateway 或 Distribution API 的调用主体。认证关闭时，
  由可信来源 IP 形成匿名 Client。
- **Routing**：一组有序匹配规则和选择策略，决定某类请求使用哪些 Upstream。
- **Upstream**：一个供应商配置及其聚合代理池。Upstream 运行时全局共享，
  不随 Routing 重复创建。
- **Provider**：Upstream 背后的外部代理供应商及其获取接口能力。
- **Proxy**：从 Provider 获取并标准化后的代理资源，不等同于简单 IP。
- **Worker**：承载 Gateway 流量的数据面节点，仅使用本地快照选路。
- **Controller**：集中管理 Provider 获取、代理生命周期、Routing 状态、
  所有权和快照发布的控制面节点。
- **Checker**：执行基础、出口和目标级健康检查的可扩缩执行节点。
- **Extraction**：Distribution API 对一个或一组 Proxy 的一次性独占发放。
- **Extraction Record**：Extraction 的审计事实，不承担租约或释放语义。

## 状态与计数

- **Proxy State**：`FETCHED`、`CHECKING`、`AVAILABLE`、`SUSPECT`、
  `DRAINING`、`UNHEALTHY`、`EXTRACTED`、`EXPIRED`、`REMOVED`。
- **Active Concurrency**：已建立并正在使用 Proxy 的 Gateway 并发。
- **Reserved Concurrency**：已选中、正在建连但尚未转为 Active 的并发。
- **Available Slots**：所有可分配 Proxy 的有效并发上限减去 Active 与
  Reserved 后的总和。
- **Consecutive Empty Fetch**：Provider 调用成功且解析成功，但解析后没有
  任何合法代理的连续次数。
- **Fetch Error Count**：超时、DNS、HTTP、认证、解析或模板执行错误次数。
- **Current Upstream**：Sequential Routing 当前指向的 Upstream 索引。

## 行为术语

- **Gateway Allocation**：Worker 原子预留本地所有 Proxy 容量，建连成功后
  转为 Active，结束后释放。
- **Exclusive Extraction**：控制面原子把可提取 Proxy 从 `AVAILABLE` 改为
  `EXTRACTED`，成功后该 Proxy 永不再次被系统分配。
- **Drain**：停止新分配，等待 Reserved 与 Active 归零后转换状态或撤销所有权。
- **Empty Fetch**：不是错误、不是重复，而是有效 Provider 响应中没有任何
  合法 Proxy 候选。
- **Switch**：Routing 使用 CAS 从当前 Upstream 前进到下一个；不会销毁旧
  Upstream 已有 Proxy。
- **Snapshot**：Controller 发布给 Worker 的不可变、版本化 Routing、Proxy
  所有权和策略视图。

## 配置语义

- **pool.maxSize**：当前系统维护且尚未被提取的 Proxy 硬上限。
- **fetch.maxTotal**：可选的计费周期累计获取上限，和 pool.maxSize 无关。
- **allocationSafetyMargin**：距离过期不足此时间时停止新分配。
- **reserveForGateway**：共享池中不能被 Distribution 提取的最低可用数量。
- **fulfillment.partial**：尽量返回，允许少于请求数量。
- **fulfillment.allOrNothing**：不足时一个也不提取。