proxy-pool/docs/api/distribution.md

Distribution API

1. 行为契约

Distribution API 只提供一次性独占提取：

读取 Redis TTL 活动池中的 AVAILABLE 候选
  -> 校验 Gateway 预留、TTL、健康、所有权与过滤条件
  -> Redis 原子移出可分配池并写入短期幂等结果
  -> 返回真实代理地址

Redis 原子操作成功前不得把地址写给 Client。返回成功后，该 Proxy 在当前 TTL 生命周期中不再参与 Gateway、再次提取或可用库存统计。系统不跟踪 Client 是否 使用、使用并发或何时停止，也不提供 release、renew、status 或租约端点。短效 Proxy 明细只存在于 Redis TTL 活动池和节点内存；PostgreSQL 不保存 Proxy 明细 或逐次提取记录。

HTTP 契约源文件：api/openapi/proxy-pool.yaml。

2. 提取请求

POST /api/v1/proxies/extract HTTP/1.1
Host: 127.0.0.1:8081
Content-Type: application/json
X-API-Key: TOKEN
X-Request-ID: req_01J4EXAMPLE
Idempotency-Key: extract-01J4EXAMPLE

{
  "count": 5,
  "fulfillment": "partial",
  "filters": {
    "protocols": ["http"],
    "regions": ["shanghai"],
    "carriers": ["telecom"],
    "allowedUpstreams": ["provider-a"]
  }
}

PowerShell 调用示例：

$body = @{
  count = 5
  fulfillment = "partial"
  filters = @{ protocols = @("http"); regions = @("shanghai") }
} | ConvertTo-Json -Depth 4

Invoke-RestMethod `
  -Method Post `
  -Uri http://127.0.0.1:8081/api/v1/proxies/extract `
  -Headers @{ "X-API-Key" = "TOKEN"; "Idempotency-Key" = "extract-SERIAL" } `
  -ContentType application/json `
  -Body $body

请求约束：

• count 至少为 1，且不超过服务端 maxCountPerRequest。
• fulfillment 省略时使用服务端配置，默认 partial。
• 所有过滤数组执行“数组内 OR、不同维度 AND”。空数组等同不限制。
• 每个过滤维度最多包含 64 个值，且数组内不得重复。
• allowedUpstreams 只能缩小 Client 可访问的 Upstream 集，不能扩大权限。

3. 成功响应

{
  "requestId": "req_01J4EXAMPLE",
  "requested": 5,
  "returned": 2,
  "proxies": [
    {
      "id": "px_01J4A",
      "protocol": "http",
      "host": "192.0.2.10",
      "port": 8080,
      "username": "USER",
      "password": "PASSWORD",
      "url": "http://USER:PASSWORD@192.0.2.10:8080",
      "region": "shanghai",
      "carrier": "telecom",
      "upstream": "provider-a",
      "expiresAt": "2026-07-28T10:30:00Z",
      "remainingTtlSeconds": 83,
      "extractedAt": "2026-07-28T10:28:37Z"
    }
  ]
}

returned 必须等于 proxies 数组长度。partial 模式中 returned 可以为 零；这仍表示请求语法有效，只是当前没有可提取库存。

返回的 password 和 url 含真实凭据。Client 必须限制日志、追踪和错误上报 对响应体的采集。服务端访问日志只记录数量、过滤摘要、Client、Upstream 和 Request ID，不记录地址或凭据。

4. 数量语义

4.1 partial

符合条件数量少于 count 时，原子提交实际数量：

requested=10, eligible=6, reserve=0 -> returned=6

4.2 allOrNothing

锁定数量不足时整个事务回滚：

{
  "type": "https://proxy-pool.local/problems/insufficient-proxies",
  "title": "Insufficient proxies",
  "status": 409,
  "code": "INSUFFICIENT_PROXIES",
  "detail": "requested 10 proxies but only 6 are currently eligible",
  "requestId": "req_01J4EXAMPLE"
}

冲突响应后，候选 Proxy 仍在 Redis TTL 活动池中保持 AVAILABLE。

5. 资格过滤与 Gateway 预留

候选必须同时满足：

1. Redis TTL 活动池条目仍为 AVAILABLE，且当前时间早于按供应商安全余量计算的 usableUntil。
2. 没有 Worker 所有权，或已完成 Drain 且 Active/Reserved 均为零。
3. 剩余 TTL 不低于 minRemainingTTL。
4. 最近健康检查不早于 maxHealthCheckAge。
5. protocol、region、carrier、Upstream 满足过滤与 Client 权限。
6. 提取后符合条件的共享库存不低于 reserveForGateway。

Worker-owned Proxy 不得直接提取。Controller 需要先发布 DRAINING，等待 Worker 确认没有 Active/Reserved，再清除 Redis 中的所有权并进入原子提取。快照延迟时 仍禁止 Gateway 与 Client 同时获得同一 Proxy。

6. 并发与原子性

Redis Adapter 应通过单个 Lua 脚本、Redis Function 或等价的原子原语完成候选 筛选、TTL/健康/所有权复核、Gateway 预留计算、满足模式判断、从可分配池移除 所选条目，并写入短期幂等结果。提取过程中不访问 PostgreSQL。

关键不变量：

• 两个并发成功响应的 Proxy ID 集合交集为空。
• 原子操作失败时整个批次不返回，也不得留下部分移除结果。
• allOrNothing 不足时零个条目退出活动池。
• Redis 活动池或分布式限流不可用时返回 503，不以内存副本冒充成功。
• PostgreSQL 不可用不阻断提取；需要 PostgreSQL 的 Admin 管理写入单独降级。

7. 幂等

提取是消耗库存的写操作。客户端收到超时后盲目重试可能再次提取一批不同 Proxy，因此自动重试应提供稳定的 Idempotency-Key。

服务端在 Redis 中保存有界 TTL 的幂等记录，至少包含 Client ID、Key、请求体 摘要、提交结果和过期时间。同一 Client、同一 Key、相同摘要返回首次结果； 摘要不同返回 409。幂等结果必须和活动池状态变更处于同一个 Redis 原子操作。 TTL 到期或 Redis 数据丢失后不再保证旧 Key 去重，系统不回退到 PostgreSQL 保存逐次提取事实。

8. 认证、识别与限制

认证由部署配置决定，OpenAPI 同时声明 API Key、Basic、Bearer 和无认证场景。 无认证并不关闭来源 CIDR、Client 识别和限流：

• 直连请求使用来源 IP 形成匿名 Client。
• 只有来源属于 trustedProxies 时才接受转发头。
• 全局和每 Client 限流在查询库存前执行；本地监听器先做早期拒绝，Redis 使用 服务端时间和单个 Lua 原子操作执行跨 Controller 副本的权威额度。
• Client 身份进入 Redis 前转换为定长摘要，窗口切换时原子删除上一窗口字段。
• 过滤条件、数量、请求体和 Header 都有长度/数量上限。

9. 错误模型

所有非 2xx 响应使用 application/problem+json：

• 400：JSON、Header 或基本格式无效。
• 401：认证失败。
• 403：来源控制、权限或 Upstream 访问被拒绝。
• 409：allOrNothing 库存不足，或幂等 Key 冲突。
• 413：请求体超过 Distribution 配置上限。
• 415：请求体不是 application/json。
• 422：数量、枚举或过滤组合违反业务约束。
• 429：全局或 Client 速率限制，响应 Retry-After。
• 503：Redis 活动池/分布式限流不可用、原子提取不可执行或服务正在排空。
• 500：未分类的内部错误；响应不包含底层错误文本。

错误响应不得包含 Provider Secret、Proxy 凭据、SQL 或内部拓扑。

10. 短期运行记录与数据最小化

Redis 幂等结果只在配置的 TTL 窗口内保留重放响应所需的数据：

clientId, idempotencyKey, requestDigest, response, expiresAt

无认证时 clientId 使用可信代理链解析后的规范化来源 IP 稳定标识。应用日志 仅记录 Request ID、数量、结果码和过滤摘要，不记录 Proxy 地址或凭据。需要长期 分析时只向 PostgreSQL 写入不含 Proxy 明细的可选聚合指标；系统不创建或归档 逐个 Proxy 的 Extraction Record。

11. 运行时实现边界

distribution.Handler 是薄 HTTP Adapter，只负责严格解码、Header/DTO 校验、 身份结果注入、错误映射和健康探针。独占提取、TTL、Gateway 预留及幂等事务 继续由 extraction.Service 和 Redis 活动池 Adapter 承担。当前内存 Store 仅作为 原子行为的参考实现与测试替身，不是生产持久化层。

请求体解码、Request ID 与 Problem JSON 统一复用 platform/httpapi。认证、 可信代理、来源控制、Client ID 和准入限流由必需的 IdentityResolver 注入， 标准装配使用 httpsecurity.Protection；解析结果至少包含稳定 Client ID 或 Source IP，且安全检查先于请求体解析。controller/runtime 将 Distribution 与 Admin 装配到不同 net.Listener，健康端点保持公开，提取端点执行独立认证。