proxy-pool/docs/api/distribution.md

Distribution API

1. 行为契约

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

筛选 AVAILABLE
  -> 锁定候选
  -> 校验 Gateway 预留、TTL、健康与过滤条件
  -> 原子 AVAILABLE -> EXTRACTED
  -> 写 Extraction Record
  -> 提交事务
  -> 返回真实代理地址

事务提交前不得把地址写给 Client。返回成功后，该 Proxy 不再参与 Gateway、 再次提取或可用库存统计。系统不跟踪 Client 是否使用、使用并发或何时停止， 也不提供 release、renew、status 或租约端点。

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 仍为 AVAILABLE。

5. 资格过滤与 Gateway 预留

候选必须同时满足：

1. 权威状态是 AVAILABLE。
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，再清除所有权并进入提取事务。快照延迟时仍禁止 Gateway 与 Client 同时获得同一 Proxy。

6. 并发与事务

PostgreSQL Adapter 应在一个事务内使用 FOR UPDATE SKIP LOCKED 获取候选， 更新状态并写审计记录。所有状态更新必须包含 state = 'AVAILABLE' 前置条件。

关键不变量：

• 两个并发成功响应的 Proxy ID 集合交集为空。
• 状态更新或审计写入任一步失败，整个批次不返回。
• allOrNothing 不足时零行变为 EXTRACTED。
• PostgreSQL 不可写时返回 503，不以内存结果冒充成功。

7. 幂等

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

服务端幂等记录至少包含：Client ID、Key、请求体摘要、提交结果和过期时间。 同一 Client、同一 Key、相同摘要返回首次结果；摘要不同返回 409。幂等记录和 Extraction Record 必须与状态更新处在相同事务边界或由同一权威恢复流程保证。

8. 认证、识别与限制

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

• 直连请求使用来源 IP 形成匿名 Client。
• 只有来源属于 trustedProxies 时才接受转发头。
• 全局和每 Client 限流在查询库存前执行。
• 过滤条件、数量、请求体和 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：PostgreSQL 不可写、服务排空或权威状态不可用。
• 500：未分类的内部错误；响应不包含底层错误文本。

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

10. 审计记录

每个被提交的 Proxy 对应一条 Extraction Record：

proxyId, clientId, sourceIP, requestId, upstream, extractedAt, expiresAt

无认证时 clientId 使用可信代理链解析后的规范化来源 IP 稳定标识，并保留 sourceIP。记录只用于审计、排错和计费事实，不承担资源归还语义。Proxy 到期后可以清理运行记录，但 Extraction Record 按审计保留策略归档。

11. 运行时实现边界

distribution.Handler 是薄 HTTP Adapter，只负责严格解码、Header/DTO 校验、 身份结果注入、错误映射和健康探针。独占提取、TTL、Gateway 预留及幂等事务 继续由 extraction.Service 和持久化 Store 承担。

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