diff --git a/docs/development/implementation-plan.md b/docs/development/implementation-plan.md index 6fb6fa9..8f9cb33 100644 --- a/docs/development/implementation-plan.md +++ b/docs/development/implementation-plan.md @@ -56,9 +56,9 @@ test/{fixtures,integration,e2e,load}/ - [ ] Create module `github.com/proxy-pool/proxy-pool` with Go 1.26. - [ ] Pin YAML v4, pgx/v5, go-redis/v9, gRPC, protobuf, Prometheus, and x/sync. -- [ ] Add `scripts/verify.ps1` that runs format check, `go vet`, unit tests, race tests, +- [x] Add `scripts/verify.ps1` that runs format check, `go vet`, unit tests, race tests, and builds all commands, each test command bounded to 60 seconds. -- [ ] Add CI for Windows and Linux with unit/race/build jobs. +- [x] Add CI for Windows and Linux with unit/race/build jobs. - [ ] Verify `go mod tidy`, `go test ./...`, and `go build ./cmd/...` succeed. ## Task 2: Strict Configuration @@ -214,7 +214,7 @@ Adapter 已通过真实 Redis 8.2 运行同一套公用契约；原子 Lua 覆 and idempotency behavior. - [x] Specify Worker register, snapshot, delta, ACK, report, heartbeat, ownership drain, and resync messages. -- [x] Validate OpenAPI and compile protobuf descriptors in CI. +- [ ] Validate OpenAPI and compile protobuf descriptors in CI. ## Task 13: Deployment and Observability diff --git a/docs/requirements/traceability.md b/docs/requirements/traceability.md index 2081322..4b15758 100644 --- a/docs/requirements/traceability.md +++ b/docs/requirements/traceability.md @@ -7,10 +7,10 @@ | ID | 最终需求 | 来源 | 验证证据 | |---|---|---|---| -| ARCH-001 | 数据面 Worker 与控制面 Controller 分离 | 1-70 | 进程结构、架构图、构建产物 | -| ARCH-002 | 热路径只做认证、本地路由和网络转发 | 1-70, 380-430 | 依赖规则、测试、性能剖析 | -| ARCH-003 | Gateway、Distribution、Admin、Metrics 独立入口 | 8904-8958 | 配置、监听装配、端口测试 | -| ARCH-004 | Controller 集中 Provider 获取与切换 | 1403-1580 | Leader、singleflight、集成测试 | +| ARCH-001 | 数据面 Worker 与控制面 Controller 分离 | 1-70 | 包、协议和部署拓扑已分离；四个 `cmd/proxy-*` 构建产物待实现 | +| ARCH-002 | 热路径只做认证、本地路由和网络转发 | 1-70, 380-430 | Snapshot/Dispatch 及依赖边界已验证；完整 Gateway 进程与代表性性能剖析待完成 | +| ARCH-003 | Gateway、Distribution、Admin、Metrics 独立入口 | 8904-8958 | Distribution/Admin 独立监听已测试；Gateway/Metrics 生产入口待装配 | +| ARCH-004 | Controller 集中 Provider 获取与切换 | 1403-1580 | 单进程 Reconciler、合并通知和切换领域契约已完成；分布式 Leader 与运行装配待完成 | | ARCH-005 | 100k QPS 峰值使用多 Worker 集群 | 当前会话 | 未验证设计目标；待代表性集群负载报告 | ## Routing 与 Upstream @@ -22,7 +22,7 @@ | ROUTE-003 | 支持 sequential、random、roundRobin、weighted、leastConnections | 5825-6467 | 五种领域策略及单测已完成；配置到 Gateway/Distribution 运行链的接线待完成 | | ROUTE-004 | Sequential 连续空结果达到阈值后原子切换一次 | 5295-5824, 6520-6617 | 进程内 `RoutingCursor` 版本 CAS 与 100 并发测试已完成；持久化恢复和跨实例 CAS 待完成 | | ROUTE-005 | 空计数属于 Upstream，当前选择属于 Routing | 8442-8529 | 共享 `UpstreamEmptyState` 双 Routing 测试 | -| ROUTE-006 | 旧 Upstream 已有 Proxy 继续耗尽，不因切换直接丢弃 | 6618-6641 | Drain 测试 | +| ROUTE-006 | 旧 Upstream 已有 Proxy 继续耗尽，不因切换直接丢弃 | 6618-6641 | 通用 ownership Drain/ACK 原语已测试；Routing 切换到 Drain 的编排待完成 | | ROUTE-007 | 无可用 Upstream 时显式 reject、wait 或 direct，默认 reject | 5075-5294, 6743-6760 | 三种动作的配置校验已完成；Gateway 当前仅返回 503，默认化及 wait/direct 运行时待完成 | ## Provider 与补池 @@ -32,7 +32,7 @@ | FETCH-001 | 每个 Provider 有独立 requestInterval、maxInFlight、timeout 和 retry | 968-2394 | `provider/reconciler_test.go` | | FETCH-002 | 大量缺池信号合并为 singleflight/容量 1 通知 | 2067-2136, 8808-8849 | `coalesce.Signal` 与 100 并发通知测试 | | FETCH-003 | 错误使用指数退避和抖动，429 尊重 Retry-After | 1601-1831, 8808-8856 | `provider/reconciler_test.go` 与 `providerapi/http_adapter_test.go` | -| FETCH-004 | Provider 获取由单逻辑 Leader 执行 | 1403-1580 | 多实例锁测试 | +| FETCH-004 | Provider 获取由单逻辑 Leader 执行 | 1403-1580 | 单进程 Reconciler 已完成；Redis Leader 租约及多实例互斥测试待完成 | | FETCH-005 | Empty 与 Error 分开；只有合法候选为零时 Empty++ | 8442-8529 | `fetch_result_test.go` 分类矩阵 | | FETCH-006 | 重复候选不当作 Empty，记录独立指标 | 8442-8480 | DuplicateOnly 分类与 Provider 测试 | | FETCH-007 | 模板限制响应大小、执行时间、函数集和外部访问 | 8808-8856 | `providerapi/template_parser_test.go` 输入、输出、候选、超时、递归与函数白名单测试 | @@ -46,7 +46,7 @@ | PROXY-002 | 唯一键包含 scheme、host、port、username、credentialVersion | 6655-6727, 8605-8678 | 去重单测 | | PROXY-003 | TTL 来源优先级明确并统一 UTC | 681-747, 8655-8678 | TTL 表驱动测试 | | CAP-001 | Gateway 分配使用 Reserved -> Active 原子转换 | 1203-1467, 8530-8597 | 固定 Max 下打包 CAS 与 1,000 并发不超卖已完成；动态降容和完整生命周期证据待完成 | -| CAP-002 | 补池依据 Available Slots，不只看 Proxy 数量 | 1203-1402, 8530-8597 | `Inventory.AvailableSlots` 与 Pool Reconciler 测试 | +| CAP-002 | 补池依据 Available Slots，不只看 Proxy 数量 | 1203-1402, 8530-8597 | TTL/状态/Active/Reserved 的 `AvailableSlots` 与 Reconciler 已测试；ownership、目标健康及 Gateway reserve 聚合待完成 | | CAP-003 | pool.maxSize 包括 FETCHED/CHECKING/AVAILABLE/SUSPECT/DRAINING 与 pending expected | 3001-3533, 6642-6680 | `FetchBudget` 100 并发额度预占测试 | | CAP-004 | TTL safety margin 内禁止新分配 | 173-220, 6728-6741 | 时钟测试 | | CAP-005 | 多 Worker 不在热路径访问 Redis 计数 | 1403-1467 | Gateway 包依赖审计、Snapshot/Dispatch 测试 | @@ -78,13 +78,13 @@ | ID | 最终需求 | 来源 | 验证证据 | |---|---|---|---| -| HEALTH-001 | 全局健康与 Routing/目标健康分离 | 221-270, 8679-8708 | 健康 reducer 测试 | -| HEALTH-002 | 健康调度有 jitter、maxInFlight 和分级频率 | 8679-8736 | 调度测试 | -| HEALTH-003 | 失败分级 SUSPECT -> UNHEALTHY -> REMOVE | 8679-8736 | 状态机测试 | +| HEALTH-001 | 全局健康与 Routing/目标健康分离 | 221-270, 8679-8708 | Protobuf/配置契约已定义；目标 Profile 与健康 Reducer 待实现 | +| HEALTH-002 | 健康调度有 jitter、maxInFlight 和分级频率 | 8679-8736 | 配置校验已完成；有界调度器、抖动和分级频率测试待实现 | +| HEALTH-003 | 失败分级 SUSPECT -> UNHEALTHY -> REMOVE | 8679-8736 | Proxy 状态迁移骨架已完成；连续失败 Reducer 与活动池原子提交待实现 | | SEC-001 | API 认证与 Proxy 认证分离，Secret 统一脱敏 | 7528-8111, 8904-8945 | Config 脱敏、Provider Store -> SecretRef -> Gateway Resolver 跨包测试与格式化泄漏回归测试 | | SEC-002 | 非回环监听无保护时严格模式启动失败 | 8112-8441 | 配置校验测试 | | OPS-001 | 配置校验后构建不可变快照并原子替换 | 8959-8999 | 100k 索引、版本/epoch 与并发 Apply/Acquire 测试 | | OPS-002 | 优雅停机停止新请求/Fetch，等待现有流量后超时关闭 | 8981-9000 | Provider Run 收敛与 `Handler.Shutdown` HTTP 排空、Hijacked CONNECT 超时关闭测试 | | OPS-003 | PostgreSQL 只保存管理修订、Upstream/Routing 状态、Admin 审计与 Outbox | 当前会话 | ADR-006、`adminstate` 公用契约和六表 Schema 边界测试；真实 PostgreSQL 契约待完成 | -| OBS-001 | 指标禁止 Proxy IP、session、Client、完整 URL 高基数标签 | 9001-9029 | 指标描述符测试 | +| OBS-001 | 指标禁止 Proxy IP、session、Client、完整 URL 高基数标签 | 9001-9029 | 文档和配置已约束；Prometheus 指标模块及描述符测试待实现 | | TEST-001 | 覆盖对话中列出的 11 个关键并发与故障场景 | 9030-9082 | 测试清单；Redis 活动池由 Memory/Redis 公用契约覆盖，跨进程故障场景仍按清单推进 | diff --git a/findings.md b/findings.md index 59af8b9..e7cb00c 100644 --- a/findings.md +++ b/findings.md @@ -128,3 +128,39 @@ Routing 自上而下匹配，首条命中停止；支持 Gateway 与 Extract 两 需要先确定“拒绝降容”或“允许排空”的正式契约。 - Snapshot Store 永久保留见过的 Proxy ID 对应 Capacity；短 TTL、高换 IP 场景下 需要排空后回收，避免运行态注册表长期增长。 + +## Routing Runtime 设计输入（2026-07-29） + +- `对话内容.md` 最后一个明确建议将 Sequential `endBehavior` 默认设为 `stop`； + 当前领域构造器默认 `stayLast`，配置参考只展示显式值，三者需要统一。 +- 产品安全默认已确定为 `onUnavailable=reject`，但当前严格配置要求字段必填； + 需要确认省略时自动补 reject，还是继续拒绝启动。 +- disabled Upstream 的确定语义是停止 Fetch、健康检查和新分配，已有 Proxy/连接 + 自然排空；Sequential 是临时跳过还是永久推进尚需固化。 +- `direct` 对 Gateway 表示经过目标安全策略后绕过代理直连；对独占提取没有可返回 + 的 Proxy，推荐在 `purpose=extract` 时拒绝 `direct` 配置。 +- 推荐采用混合 Routing Runtime：Controller 维护 Sequential 权威游标和跨实例 + CAS；Gateway 消费不可变路由快照并在本地执行 random/roundRobin/weighted/ + leastConnections，热路径不访问 Redis/PostgreSQL；Distribution 在 Controller + 内复用同一编译策略并交给 Redis 原子提取执行。 +- Gateway 当前没有完整进程装配，`RulesRouter` 仅存在于领域/Handler 测试； + Distribution 只接受调用方 `allowedUpstreams`，尚未把 `purpose=extract` 路由与 + Client 许可集求交。 + +## 架构证据一致性审计（2026-07-29） + +- `.github/workflows/ci.yml` 已覆盖 Windows/Linux vet、unit、build 及 Linux race； + `scripts/verify.ps1` 也覆盖格式、vet、60 秒单测、条件 race 和 build，因此两项 + 基础工程验收应计为完成。 +- OpenAPI 通过 Go 测试执行结构/路径/响应码检查，Protobuf descriptor 曾手工编译 + 通过，但 CI 没有安装/调用 `protoc`；“在 CI 编译 descriptor”仍未完成。 +- `cmd/proxy-gateway`、`proxy-controller`、`proxy-checker`、`proxy-loadgen` 均不存在； + Docker/Kubernetes 当前只是目标拓扑，不能作为构建产物或运行验证证据。 +- Provider Reconciler 的合并通知和请求约束已完成，但没有 Redis Leader Adapter + 或多实例锁测试；FETCH-004 仍是未完成要求。 +- Checker/Health 当前只有配置、Protobuf 和 Proxy 状态迁移骨架，没有 Scheduler、 + Reducer 或目标 Profile；HEALTH-001..003 不能记为已实现。 +- 当前没有 Prometheus 指标模块或描述符测试；OBS-001 只有文档约束，运行时证据 + 缺失。 +- Available Slots 当前纳入 AVAILABLE、TTL、安全余量、Max、Active、Reserved； + ownership、route/target health 与 Gateway reserve 尚未进入同一聚合模型。 diff --git a/progress.md b/progress.md index ca0e69d..dadd8ae 100644 --- a/progress.md +++ b/progress.md @@ -4,7 +4,8 @@ - 已复核 `implementation-plan.md` 的验收项：机器契约、OpenAPI/Protobuf 验证、 完整文档导航、20 份配置示例和 35 张 Mermaid 图已有仓库及验证证据，修正 - 6 个滞后勾选；当前为 48/73，约 66%。 + 滞后勾选；进一步核对发现 descriptor 编译尚未进入 CI，同时验证脚本和双平台 + CI 已完成，最终校正为 49/73，约 67%。 - 正在并行审计 Routing/Sequential 与 Proxy Capacity 的剩余边界；本轮只收敛 已确认公共接口和既有需求，不把 Checker、pgx 或 100,000 QPS 目标提前记为完成。 - Routing 审计确认五种策略尚未进入真实请求链、`onUnavailable` 只有配置校验、 @@ -15,6 +16,17 @@ 该结果只证明现有行为基线，不替代上述缺失运行链的验收。 - 一次组合检索因包含不存在的 `config` 路径返回退出码 1；有效输出已保留， 后续检索改用实际目录 `internal/config`，未重复原命令。 +- Routing Runtime 设计核对确认采用 Controller 权威状态 + Gateway 不可变本地 + 快照的混合模型；已定位 Extract direct、默认值、disabled 推进和单 Upstream + Sequential 四项需确认语义，尚未在未批准设计上开始实现。 +- 一次读取误用了不存在的 `controller/runtime/bootstrap.go` 路径；实际文件为 + `runtime.go`，Gateway 构建辅助位于 `gateway/server/bootstrap.go`，已改用真实 + 文件继续核对，未重复失败命令。 +- 架构证据审计确认 Provider 分布式 Leader、Health Reducer/Checker、Prometheus + 指标模块和四个生产命令仍缺实现；追踪矩阵已把这些条目的配置/领域基础与 + 完整运行时证据拆开描述。 +- 一次 `rg` 同时包含不存在的 `cmd` 路径，以及两次使用 PowerShell 不展开的 + 通配路径，分别返回退出码 2/123；后续改用实际目录和 `-g` 过滤，不重复原命令。 - 已实现共享 `httpapi`、`httpsecurity` 与 `httpserver`，统一严格 JSON、Problem、 Request ID、认证、可信代理、Client ID、准入、多监听器生命周期和优雅停机。 - Distribution/Admin Handler 已装配到独立监听器；Gateway 配置认证统一复用 diff --git a/task_plan.md b/task_plan.md index 21e315c..6118efc 100644 --- a/task_plan.md +++ b/task_plan.md @@ -55,5 +55,5 @@ 目标运行拓扑。 - `cmd/proxy-*`、PostgreSQL 管理面 Adapter、Provider Leader/分布式限流、 Checker 运行时、Redis 故障转移验证与代表性集群压测属于后续实施范围。 -- `implementation-plan.md` 当前按 73 个验收项统计；已校正为 48 项完成， - 验收项完成率约 66%，不等同于生产就绪度。 +- `implementation-plan.md` 当前按 73 个验收项统计；已校正为 49 项完成， + 验收项完成率约 67%，不等同于生产就绪度。