proxy-pool/CONTEXT.md

Proxy Pool 统一领域语言

核心实体

• Client：使用 Gateway 或 Distribution API 的调用主体。认证关闭时， 由可信来源 IP 形成匿名 Client。
• Routing：一组有序匹配规则和选择策略，决定某类请求使用哪些 Upstream。
• Upstream：一个供应商配置及其聚合代理池。Upstream 运行时全局共享， 不随 Routing 重复创建。
• Provider：Upstream 背后的外部代理供应商及其获取接口能力。
• Proxy：从 Provider 获取并标准化后的短效代理资源，不等同于简单 IP。 Proxy 明细不进入 PostgreSQL，只存在于带 TTL 的 Redis 活动池和持有其快照的 节点内存；丢失后由 Provider 重新获取。
• Worker：承载 Gateway 流量的数据面节点，仅使用本地快照选路。
• Controller：集中管理 Provider 获取、代理生命周期、Routing 状态、 所有权和快照发布的控制面节点。
• Checker：执行基础、出口和目标级健康检查的可扩缩执行节点。
• Extraction：Distribution API 对一个或一组 Proxy 的一次性独占发放。
• Activity Pool：Redis 中带 TTL 的短效 Proxy 运行时集合，是分配、所有权 和独占提取的原子操作位置，可在丢失后由 Provider 重建。
• Extraction Result：Redis 中短期保存的幂等响应，不承担租约、释放或 长期审计语义。
• Persistent Management State：PostgreSQL 中的配置版本、Upstream/Routing 管理状态、Admin 审计与 Outbox，以及可选聚合指标；不包含 Proxy 明细或逐次 提取记录。

状态与计数

• 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：控制面通过 Redis 原子操作把可提取 Proxy 从 AVAILABLE 改为不可再次分配，并在有限 TTL 内保存幂等结果；成功后该 Proxy 在当前 TTL 生命周期内不再被系统分配。Redis 整体丢失后的 Provider 重建属于新的活动池代次，不承诺延续已丢失代次的排他状态。
• 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：不足时一个也不提取。