docs: describe egress task execution contract
Some checks failed
ci / proto (push) Has been cancelled
ci / test (ubuntu-latest) (push) Has been cancelled
ci / test (windows-latest) (push) Has been cancelled
ci / race (push) Has been cancelled
ci / integration (push) Has been cancelled

This commit is contained in:
youfak 2026-07-31 22:38:16 +08:00
parent 84b564ba9c
commit 7e3228f36a
3 changed files with 14 additions and 9 deletions

View File

@ -159,7 +159,7 @@ PostgreSQL Proxy 明细。Gateway 将每次尝试写入进程内有界队列,
Checker 注册自身最大并发与支持层级Controller 发送有 deadline 的任务:
- `BASIC`:基础连通和协议握手。
- `EGRESS`出口身份与匿名性。
- `EGRESS`通过任务级 HTTP/HTTPS URL 检查出口可达性。
- `TARGET`:针对 Routing/目标组的可达性。
Checker 只返回 `HealthObservation`。Controller reducer 按 Proxy、检查层级和
@ -170,10 +170,12 @@ Routing 决定 AVAILABLE、SUSPECT 或 UNHEALTHY并更新 Redis 活动池,
限制,且同一 `checker_id` 的未完成租约会占用该窗口,重连不会扩大并发。任务仅在
被领取时通过认证的 mTLS 流携带 endpoint、`secret_ref`、版本和任务期凭据Checker
不访问 Redis 或 PostgreSQL。`ReportObservations` 在调用 Reducer 前校验 task、Proxy、
检查层级、目标 Profile 与领取者一致Reducer 成功后才确认任务;相同领取者对已确认
任务的同一事实可重放,由活动池摘要幂等处理。生产 Controller 装配 Redis 共享
broker按启用 Upstream 的有效检查策略调度 BASIC 任务;未装配 broker 的 fixture
服务仍会以 `Unavailable` 拒绝任务流而不下发无租约任务。EGRESS 和 TARGET 的
检查层级、仅属于 TARGET 的目标 Profile 与领取者一致Reducer 成功后才确认任务;
相同领取者对已确认任务的同一事实可重放由活动池摘要幂等处理。EGRESS 的探测 URL
只存在于下发任务Checker 回传时不携带 URL 或 Routing Profile因此它只归并 Proxy
全局健康。生产 Controller 装配 Redis 共享 broker按启用 Upstream 的有效检查策略
调度 BASIC 任务;未装配 broker 的 fixture 服务仍会以 `Unavailable` 拒绝任务流,
而不下发无租约任务。EGRESS 和 TARGET 的
任务索引及调度策略尚未实现。
每次 Claim 还会签发新的不可预测 `lease_token`Observation 必须回传该值。任务被重新
领取后,旧 token 即使拥有相同 `task_id``checker_id` 也会被拒绝,避免过期实例的
@ -182,8 +184,9 @@ broker按启用 Upstream 的有效检查策略调度 BASIC 任务;未装配
`proxy-checker` 使用固定大小 worker-pool 执行每个 pull 批次,任务数不超过该请求的
`max_in_flight`;每次尝试都受 `deadline``timeout` 的较小值约束,失败可在同一
deadline 内最多执行到 `max_attempts`。BASIC 针对 HTTP/HTTPS Proxy 验证到 Proxy 的
请求/认证握手TARGET 通过 Proxy 请求指定目标并将非成功状态作为事实。SOCKS5 与
EGRESS 的专用出口语义仍待后续探测器扩展。
请求/认证握手EGRESS 与 TARGET 通过 Proxy 请求任务指定的 HTTP/HTTPS 目标并将
非成功状态作为事实。EGRESS 的出口身份响应解析、SOCKS5 与 EGRESS/TARGET 生产调度
仍待后续实现。
## 7. 兼容与演进

View File

@ -47,7 +47,8 @@ Controller 是首版模块化单体。Provider、Pool、Routing 和 Extraction
### proxy-checker
Checker 只产生 Observation。它从认证 gRPC 流领取有界任务,用固定 worker-pool 在任务
deadline 内执行 HTTP/HTTPS BASIC/TARGET 探测并微批上报;最终状态迁移仍由 Controller 的
deadline 内执行 HTTP/HTTPS BASIC、EGRESS 和 TARGET 探测并微批上报EGRESS 的
任务 URL 仅在执行期使用,回传全局事实不包含该 URL。最终状态迁移仍由 Controller 的
确定性 reducer 完成,避免多个检查实例同时写 Proxy 状态。Checker 不访问 Redis 或 PostgreSQL。
### proxy-loadgen

View File

@ -285,7 +285,8 @@ Checker Observation 上报 RPC 已复用既有控制面监听接入 Controller
Redis 共享 due-index/租约持久化、每 Upstream 的跨副本 in-flight 限制和生产 broker 已完成;
`proxy-checker` 独立进程、固定大小 worker-pool、任务期重试/微批上报和 HTTP/HTTPS
BASIC 探测器已完成并有测试。TARGET 探测器具备任务执行能力,但尚无生产任务调度;
SOCKS5、EGRESS 专用出口探测、EGRESS/TARGET 多维任务索引及部署运行态仍未实现,
EGRESS 已具备任务 URL 传输、HTTP/HTTPS 探测和全局事实回传契约,但出口身份响应解析、
SOCKS5、EGRESS/TARGET 多维任务索引及部署运行态仍未实现,
因此本任务保持未完成。
## Task 12: Machine-readable Contracts