diff --git a/README.md b/README.md index d3317e5..d08d02e 100644 --- a/README.md +++ b/README.md @@ -71,18 +71,18 @@ flowchart LR ## 当前完成度 -截至 **2026-07-30**,实施计划检查项为 **52 / 74(70.3%)**。详情见 +截至 **2026-07-31**,实施计划检查项为 **53 / 74(71.6%)**。详情见 [实施计划](docs/development/implementation-plan.md)和 [交付完成度审计](docs/requirements/completion-audit.md)。 - **已完成**:严格配置、Provider 获取与协调、Redis 活动池、Distribution 原子 提取与限流、Controller 的 Admin/Distribution/Metrics 监听,以及 PostgreSQL - 管理状态。 + 管理状态;WorkerControlPlane 的 Register、Snapshot ACK、Runtime 心跳接收和 + Redis 会话栅栏。 - **部分完成**:Gateway 传输与调度组件、Snapshot 本地存储、Worker ownership 与运行态领域组件、Docker Compose/Kubernetes 静态部署清单和 protobuf 契约。 -- **待完成**:WorkerControlPlane gRPC session/snapshot/ACK 闭环、Checker 调度与 - 健康状态链、Gateway 进程与快照客户端、完整 Routing 运行链,以及 loadgen 和 - 代表性集群压测。 +- **待完成**:Worker Snapshot 下发流、Gateway 快照客户端、Outcome 上报、Checker + 调度与健康状态链、完整 Routing 运行链,以及 loadgen 和代表性集群压测。 检查项数量不等于生产就绪度。静态部署清单与 protobuf descriptor 验证也不代表 端到端拓扑已经完成;`100,000 QPS` 仍只是待验证的集群设计目标。 diff --git a/docs/adr/005-redis-activity-pool.md b/docs/adr/005-redis-activity-pool.md index 51a24b4..0539cab 100644 --- a/docs/adr/005-redis-activity-pool.md +++ b/docs/adr/005-redis-activity-pool.md @@ -66,6 +66,7 @@ var _ ownership.Repository = (*Adapter)(nil) var _ workerruntime.SessionWriter = (*Adapter)(nil) var _ workerruntime.ReportWriter = (*Adapter)(nil) var _ workerruntime.RuntimeReader = (*Adapter)(nil) +var _ workerruntime.ControlStore = (*Adapter)(nil) var _ pool.InventoryReader = (*Adapter)(nil) ``` @@ -103,6 +104,8 @@ pp:{activity}:epoch STRING ownership 全局递增代次 pp:{activity}:inventory HASH upstreamID -> 当前未提取库存 pp:{activity}:worker-sessions HASH workerID -> 当前 Worker session pp:{activity}:worker-session-expiry ZSET workerID -> session expiry milliseconds +pp:{activity}:worker-snapshots HASH workerID -> 最近签发且待确认的 Snapshot 引用 +pp:{activity}:worker-snapshot-expiry ZSET workerID -> Snapshot 引用 expiry milliseconds pp:{activity}:worker-runtime HASH workerID -> 完整稀疏运行态报告 pp:{activity}:worker-runtime-expiry ZSET workerID -> report expiry milliseconds pp:{activity}:owned: ZSET 单 Upstream 已分配 AVAILABLE Proxy diff --git a/docs/api/control-plane.md b/docs/api/control-plane.md index 1008c73..3180075 100644 --- a/docs/api/control-plane.md +++ b/docs/api/control-plane.md @@ -12,6 +12,23 @@ Proto 源文件位于 `api/proto/controlplane/v1/controlplane.proto`,包含两 该协议不承载 Client 的独占提取,也没有 extraction lease/release。Proxy 的 `AVAILABLE -> EXTRACTED` 只在 Controller 调用的 Redis 原子操作中完成。 +## 当前实现状态 + +Controller 已实现并验证 `RegisterWorker`、`AcknowledgeSnapshot` 和 +`ReportRuntime` 的一元 RPC。Register 创建带 Redis 服务端 TTL 的 session;ACK 只 +接受 Controller 已签发的 `(version, ownership_epoch, checksum)`;Runtime 的空 +`counters` 是完整稀疏替换,也续期 session。负向 ACK 会关闭该 session 的 Runtime +写入栅栏,直到收到新的正向 ACK,延迟的旧报告不能重新开启它。 + +生产配置使用 mTLS,并将叶子证书 SPIFFE URI 约束为 +`spiffe:////worker/`;仅经配置校验的回环 +监听允许明文 fixture 模式。单消息大小、并发流数和 gRPC keepalive 策略由 +`controlPlane` 配置限定。 + +`WatchSnapshots` 和 `ReportOutcomes` 当前明确返回 `Unimplemented`。 +Snapshot payload/stream、Gateway 客户端、Outcome 与 Checker 闭环尚未实现; +`100,000 QPS` 仍是未验证的设计目标。 + ## 2. Worker 会话 ```mermaid diff --git a/docs/development/implementation-plan.md b/docs/development/implementation-plan.md index e366cd4..f05b82b 100644 --- a/docs/development/implementation-plan.md +++ b/docs/development/implementation-plan.md @@ -176,7 +176,7 @@ Upstream、`endBehavior` 默认 `stop`,并覆盖列表末端停止;disabled sweep primitives with a monotonic global epoch. - [x] Implement Redis Provider leader, distributed request quota, Client limit and automatic Provider inventory rebuild after Redis state loss. -- [ ] Implement the Worker heartbeat receiving path and session lifecycle. +- [x] Implement the Worker heartbeat receiving path and session lifecycle. - [x] Keep Provider output in Redis TTL activity state and node memory only; keep the Gateway request path on immutable local snapshots with no Redis/PostgreSQL calls. - [x] Expose Distribution extraction/status and Admin status/enable/disable/switch/reload @@ -184,7 +184,7 @@ Upstream、`endBehavior` 默认 `stop`,并覆盖列表末端停止;disabled - [x] Add Compose-backed Redis 8.2 integration and shared Adapter contract tests. - [x] Add PostgreSQL management Adapter and Compose-backed integration tests. -当前进度(2026-07-30):已实现共享 `platform/httpapi`、Distribution +当前进度(2026-07-31):已实现共享 `platform/httpapi`、Distribution extract/live/ready Handler 与 Admin status/enable/disable/switch/reload Handler; 定向契约测试已覆盖严格 JSON、Body 上限、Request ID、幂等 Header、DTO 映射、 404/405 及业务错误映射。共享 `platform/httpsecurity` 已补齐 Basic/API Key/ @@ -203,11 +203,16 @@ Distribution/Admin 服务构造、错误合并和资源关闭。生产 Provider 权威管理状态动态装配 Upstream,并与 HTTP Runtime 通过公用 lifecycle Group 联动 停机;Admin disable 会取消 Runtime,reload 在提交前预检并在发布后替换运行实例。 组合 fixture 已验证隔离 Redis namespace 下的选主、Provider HTTP 调用、模板解析 -和活动池写入。Controller Metrics 独立入口现已提供 `/livez`、 -`/readyz` 与基础 Prometheus 运行时指标,三监听器隔离已通过测试;业务指标仍待 +和活动池写入。Controller Metrics 独立入口现已提供 `/livez`、`/readyz` 与基础 +Prometheus 运行时指标,三监听器隔离已通过测试;业务指标仍待 实现。双存储 bootstrap 已通过 PostgreSQL 18 + Redis 8.2 组合 fixture,覆盖 迁移、启动配置提交、Readiness、Admin Status 和 Metrics 探针。 +WorkerControlPlane 现已接入 Controller 生命周期:Register、ACK 和 Runtime +报告均经 Redis 服务端 TTL 的 session/issued-snapshot/ACK 栅栏校验;mTLS SPIFFE +身份、消息/流限制和有界停机已实现。Snapshot 下发流、Gateway 客户端与 Outcome +上报仍未实现。 + 已新增公用 `domain/activitypool` 契约及并发安全内存参考实现,Provider Reconciler 通过 `UpsertFetched` 写入带供应商 TTL 和分配安全余量的批次;已覆盖 `usableUntil` 向 Worker Snapshot 的传播与 Gateway 本地截止过滤、 diff --git a/docs/requirements/completion-audit.md b/docs/requirements/completion-audit.md index 2b02878..e0ce145 100644 --- a/docs/requirements/completion-audit.md +++ b/docs/requirements/completion-audit.md @@ -46,6 +46,11 @@ - `Redis Activity Adapter`:真实 Redis 8.2 已覆盖 Provider Upsert、健康更新、 原子独占提取、短期幂等、Worker ownership、库存和有界过期清理,Memory/Redis 运行同一公用契约。 +- `WorkerControlPlane`:Register、已签发 Snapshot 的 ACK 和完整稀疏 Runtime + 报告已通过 gRPC、Memory 与 Redis 8.2 契约验证;session、ACK、报告均使用 Redis + 服务端 TTL,负向 ACK 会关闭 Runtime 写入栅栏。Controller 已装配 loopback + plaintext fixture 与 SPIFFE mTLS 服务端;Snapshot 流、Gateway 客户端、Outcome 和 + Checker 尚未闭环。 - `PostgreSQL 管理面`:已定义 `adminstate` 事务 seam、并发安全 MemoryStore、 公用契约、100 并发 Routing CAS、租约 Outbox 和只含六张管理表的 Schema;pgx Adapter 已在真实 PostgreSQL 18 上通过同一契约、迁移幂等、审计/Outbox @@ -84,9 +89,11 @@ CI 已配置 Linux race job。PostgreSQL 18 和 Redis 8.2 的隔离 Adapter fixt 4. Controller 的 PostgreSQL 连接池、迁移和 pgx Adapter 启动装配已完成; 公用 bootstrap 已通过 PostgreSQL 18 + Redis 8.2 双存储集成,Controller 三监听器与探针集成已完成;可选聚合指标和完整容器进程部署验证仍待实现。 -5. Worker heartbeat gRPC 接收路径;Redis Provider Leader、分布式请求额度、 - Distribution Client 限制和 Provider 状态丢失重建已完成。 -6. Worker 网络快照流;Redis ownership drain/ACK/过期回收已完成。 +5. Worker Register/ACK/Runtime gRPC 接收路径、Redis 服务端 TTL 会话生命周期、 + SPIFFE mTLS 校验和 Controller 生命周期接线已完成;Redis Provider Leader、 + 分布式请求额度、Distribution Client 限制和 Provider 状态丢失重建已完成。 +6. Worker 网络快照流、Gateway Snapshot 客户端和 Outcome 上报仍待完成;Redis + ownership drain/ACK/过期回收已完成。 7. Checker 调度、探测器和健康 reducer。 8. Admin/Distribution 细粒度授权和审计查询;Distribution 分布式限流已完成。 9. 真实 Compose/Kubernetes 集成、故障演练和代表性集群负载测试。 diff --git a/docs/requirements/traceability.md b/docs/requirements/traceability.md index 61fbab1..6c1038e 100644 --- a/docs/requirements/traceability.md +++ b/docs/requirements/traceability.md @@ -7,7 +7,7 @@ | ID | 最终需求 | 来源 | 验证证据 | |---|---|---|---| -| ARCH-001 | 数据面 Worker 与控制面 Controller 分离 | 1-70 | 包、协议和部署拓扑已分离;Controller 命令已实现,Gateway/Checker/Loadgen 构建产物待实现 | +| ARCH-001 | 数据面 Worker 与控制面 Controller 分离 | 1-70 | 包、协议和部署拓扑已分离;Controller 已运行 Worker Register/ACK/Runtime gRPC 接收,Gateway/Checker/Loadgen 构建产物及 Snapshot 下发待实现 | | ARCH-002 | 热路径只做认证、本地路由和网络转发 | 1-70, 380-430 | Snapshot/Dispatch 及依赖边界已验证;完整 Gateway 进程与代表性性能剖析待完成 | | ARCH-003 | Gateway、Distribution、Admin、Metrics 独立入口 | 8904-8958 | Controller 命令已装配 Distribution/Admin/Metrics 三个独立监听及联动停机;Gateway 生产入口待装配 | | ARCH-004 | Controller 集中 Provider 获取与切换 | 1403-1580 | Redis Leader、动态 Provider Supervisor 与 Bootstrap 生产装配已完成;Admin disable/reload 驱动取消替换,多副本按权威 HMAC 指纹和 revision 栅栏收敛并拒绝旧配置换主;Routing 切换到 Drain 的编排待完成 | @@ -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 | `AvailableSlots`、显式 minimum/target 水位、pending 槽位和迟滞 Reconciler 已测试;Gateway 打包 Active/Reserved 报告、Worker session/ACK/sequence/TTL/ownership fence、单 Upstream 索引及 Redis 权威 Managed/Slots 汇总已通过内存与真实 Redis 测试;WorkerControlPlane 接线、目标健康和 Gateway reserve 策略仍待完成 | +| CAP-002 | 补池依据 Available Slots,不只看 Proxy 数量 | 1203-1402, 8530-8597 | `AvailableSlots`、显式 minimum/target 水位、pending 槽位和迟滞 Reconciler 已测试;Worker session/ACK/sequence/TTL/ownership fence 与 WorkerControlPlane Register/ACK/Runtime 接收已通过内存、Redis 8.2 和 gRPC 测试;Snapshot 下发、目标健康和 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 测试 |