Easytier/docs/easytier-web-managed-config-sync-plan.md

EasyTier Web Managed Config Incremental Sync Plan

Status

• 状态：Implemented（核心协议、持久化与 Session 增量收敛）
• 实施范围：EasyTier Web 的 HTTP 接收、校验、SQLite 持久化和 Session 运行态收敛
• 上游依赖：后续由 Console 计算并发送 Patch
• 兼容要求：保留现有 Full PUT

本文记录当前接收端方案。Session 在能够证明 Patch base 与已应用 revision 连续时 只收敛 touched instances；重启、通知丢失、revision 断链或并发积压时沿用 Full reconcile。

1. 背景与结论

当前 /validate-token webhook 已经只交换 token、机器信息和 revision，不再 携带完整 managed config 集合。剩余的大集合位于独立的配置发布路径：

PUT /api/internal/users/:user-id/machines/:machine-id/networks

Console 每次发布都会向该路径发送完整 Exact Set。实例很多时，请求体、JSON 解析、现有配置扫描和逐条 SQLite 写入都随实例总数增长。

第一阶段采用以下方案：

1. 保留 PUT，作为完整发布、首次同步和冲突恢复路径。
2. 在同一路径增加 PATCH；普通变更只发送完整的单实例 upsert 和删除 ID。
3. PATCH 使用 expected_config_revision 做 compare-and-swap（CAS）。
4. Full/Patch 的配置变更与 revision 更新在一个 SQLite transaction 中提交。
5. Patch 只查询和写入 touched instances，不扫描完整 Target。
6. 写入成功后通知 Session 本次 base、target 和 touched instance IDs。
7. Session 仅在 applied revision 精确匹配 base 时增量收敛，否则安全回退 Full。

普通变更的接收端成本由：

O(total instances)

降为：

wire / JSON / persistence transaction / runtime config apply = O(changed instances)

冷启动或 revision 冲突仍需要 O(total) 的 Full。这是没有可用基线时传递完整 目标状态所必需的成本；如果 Full 超过安全的单请求上限，需另行设计 staged snapshot，而不是直接分页写入 live rows。

2. 目标与非目标

2.1 目标

1. 普通新增、更新和删除只传输、解析、查询并写入变化实例。
2. Config rows 与 persisted revision 原子提交。
3. Patch 可安全重试，并能确定性处理并发或乱序请求。
4. 保持 user-owned 与 web-owned 配置的 ownership 规则。
5. 保持 Full Exact Set 的删除和显式空集合语义。
6. 为 Full 和 Patch 设置显式且可测试的容量限制。
7. 先部署接收端，再允许 Console 使用 Patch。

2.2 非目标

1. 修改 /validate-token request/response。
2. 在本阶段实现 Console 的 diff/cache 逻辑。
3. 优化 Core heartbeat 中的完整运行实例上报。
4. 实现 Full 分页、上传会话或持久化 delivery FSM。
5. 让冷启动 Full 的成本低于 O(total)。

3. 必须保持的语义

3.1 Full Exact Set

Full 表示一个 (user_id, machine_id) 下全部期望的 web-owned configs：

• 请求中存在的实例应被创建或更新；
• 已存在但请求中缺失的 web-owned 实例应被删除；
• 空集合应删除该 Target 下全部 web-owned 实例；
• user-owned 实例不能被覆盖或删除。

3.2 Patch

Patch 只描述从一个已知 revision 到另一个 revision 的变化：

• upserts：新增或变化实例的完整 config；
• delete_instance_ids：从目标集合中删除的实例 ID；
• expected_config_revision：receiver 必须已经处于的 base revision；
• config_revision：提交完成后的 target revision。

Patch 不是独立的完整目标。当前 revision 与 expected revision 不一致时，必须 返回冲突且不做任何写入。

3.3 Revision invariants

1. 一个 persisted revision 只对应与其一起提交的 web-owned projection。
2. Config mutation 和 revision advancement 必须位于同一 transaction。
3. Patch 只能应用在完全匹配的 expected revision 上。
4. 当前 revision 已等于 target revision 时，返回幂等成功且不重复写入。
5. Publisher 不得为不同目标状态复用同一个 target revision。
6. 任何其他写路径只要改变 web-owned row，就必须在同一 transaction 中清除 managed revision；否则未来 Patch 会基于错误的 base。
7. Persisted revision 与 Session applied revision 保持为两个不同事实。HTTP 成功只代表本地持久化完成，不代表 Core 已经应用。

4. HTTP contract

4.1 保留 Full PUT

路径不变：

PUT /api/internal/users/:user-id/machines/:machine-id/networks

现有 JSON shape 保持兼容：

{
  "managed_network_configs": [
    {
      "instance_id": "11111111-1111-1111-1111-111111111111",
      "network_config": {}
    }
  ],
  "config_revision": "target-revision",
  "expected_config_revision": "base-revision"
}

expected_config_revision 保持当前含义：

• 字段缺失：兼容旧调用者，不检查 base；
• 空字符串：要求当前 persisted revision 不存在；
• 非空字符串：要求当前 revision 与该值相等。

新 Console 必须发送 expected revision。省略 expected 的形式只用于旧版本兼容 和明确的运维修复。

config_revision 的处理：

• 非空：配置与 target revision 原子提交；
• 缺失：保留旧 Full 请求兼容，但清除已有 managed revision，因此该结果不能 作为后续 Patch base；
• 空字符串：拒绝为 400。

Revisioned Full 遇到 user-owned instance ID 冲突时整体失败。Legacy unrevisioned Full 保持当前兼容行为：跳过 user-owned row，且绝不覆盖它。

4.2 新增 Patch

同一资源增加：

PATCH /api/internal/users/:user-id/machines/:machine-id/networks

请求格式：

{
  "upserts": [
    {
      "instance_id": "11111111-1111-1111-1111-111111111111",
      "network_config": {}
    }
  ],
  "delete_instance_ids": [
    "22222222-2222-2222-2222-222222222222"
  ],
  "config_revision": "target-revision",
  "expected_config_revision": "base-revision"
}

Patch contract：

1. 两个 revision 字段均必填、非空且不能相同。
2. upserts 中的 instance ID 不得重复。
3. delete_instance_ids 中的 ID 不得重复。
4. 同一个 ID 不得同时出现在 upsert 和 delete 中。
5. 每个 upsert 必须携带该实例的完整 NetworkConfig，不支持字段级 JSON Patch。
6. network_config 内部的 instance ID 不受信任，receiver 使用 envelope 中的 instance_id 进行归一化。
7. 删除不存在的 ID 是幂等 no-op。
8. Upsert 或 delete 碰到 user-owned row 时，整个 Patch 返回冲突且不写入。
9. 不允许从“receiver revision 不存在”的未知状态直接 Patch；使用 Full 建立 Exact Set 和首个 revision。
10. 空 Patch 不能把 revision 改成另一个值；这通常表示 publisher revision 计算错误，因此返回 400。

4.3 HTTP outcomes

条件	HTTP	语义
Full/Patch 新提交成功	204	Config 和 revision 已持久化
Target revision 已经存在	204	幂等成功，无 row mutation
Expected revision 不匹配	409	零写入，调用者重新观察或发送 Full
User-owned ownership 冲突	409	零写入，不能自动覆盖
非法 ID、重复、交集或非法 config	400	调用 contract 错误
请求超过 byte limit	413	未进入 reconciliation
条目数或单 config 超过限制	422	超出接收端容量 contract
SQLite 错误	500	Transaction rollback

409 返回机器可读字段：revision 冲突为 code=managed_config_revision_conflict 并在已知时带 current_config_revision；ownership 冲突为 code=managed_config_ownership_conflict。响应不得返回配置内容。日志不得记录 token、secret 或完整 config JSON。

5. Receiver architecture

5.1 Module responsibilities

Module	本阶段职责
Internal HTTP Adapter	内部鉴权、body/count limit、DTO 解析、HTTP 状态映射
ClientManager	解析 Target，调用 managed-config Interface，成功后通知 Session
client_manager::managed_config	Full/Patch 规则、归一化、typed outcome
Db Adapter	CAS、ownership fence、批量 mutation、revision transaction
Session runtime reconciliation	校验 applied/base/target fence，增量收敛 touched instances；断链时 Full

HTTP Adapter 不实现 ownership、diff 或 transaction 逻辑。PUT 和 PATCH 共用 managed-config Module，避免两套规则逐渐分叉。

5.2 Internal Interface

Module 接收两种 intent：

Full {
  desired_configs,
  target_revision: Option<Revision>,
  expected_revision: Any | Exact(Option<Revision>)
}

Patch {
  upserts,
  delete_instance_ids,
  target_revision: Revision,
  expected_revision: Revision
}

返回 typed outcome：

Applied {
  previous_revision,
  target_revision
}

AlreadyApplied {
  target_revision
}

RevisionConflict {
  expected_revision,
  current_revision
}

OwnershipConflict {
  instance_id
}

Validation error 与 database error 保持独立类型。HTTP handler 只负责将这些结果 映射到 section 4.3 的状态码。

6. Receiver implementation

6.1 Validation and normalization

在打开 SQLite write transaction 之前完成：

• request byte/count/per-entry limit；
• UUID、重复 ID 和 upsert/delete 交集校验；
• config key 拼写归一化；
• envelope instance ID 覆盖 nested identity；
• NetworkConfig 反序列化。

这样非法大请求不会长时间占用 SQLite writer lock。Ownership 必须在 transaction 内重新查询，因为 transaction 外的结果可能已过期。

当 request 带 target revision 时，可以先做一次 O(1) revision read；如果当前值 已经等于 target，可直接返回 AlreadyApplied，避免完整 config 归一化。任何可能 写入的请求仍必须在 transaction 内再次检查 revision。

6.2 Full transaction

在同一个 SQLite connection 上执行：

1. BEGIN IMMEDIATE。
2. 读取 (user_id, machine_id) 当前 persisted revision。
3. 若 supplied target 已经是 current，返回 AlreadyApplied。
4. 检查 optional expected revision。
5. 只读取现有 row 的 (instance_id, source)；不加载无关 config JSON。
6. 执行 user-owned ownership fence。
7. 批量 upsert 全部 desired web-owned rows。
8. 计算并批量删除 existing_web_ids - desired_ids。
9. 最后写入 supplied target revision；legacy unrevisioned Full 则删除旧 revision。
10. Commit。

任一步骤失败都 rollback。Full 仍是 O(total)，但不会再逐条独立提交，也不会 出现“部分 rows 已更新、revision 仍是旧值”的中间持久状态。

6.3 Patch transaction

在同一个 SQLite connection 上执行：

1. BEGIN IMMEDIATE。
2. 读取 current revision。
3. 如果 current 等于 target，返回 AlreadyApplied。
4. 如果 current 不等于 expected，返回 RevisionConflict。
5. 只查询 upsert/delete IDs 的 source。
6. 任一 touched ID 属于 user 时，返回 OwnershipConflict。
7. 批量 upsert changed configs。
8. 批量删除 requested web-owned IDs。
9. 最后写入 target revision。
10. Commit。

Patch 禁止：

• list 全部 Target rows；
• 重算完整 Target digest；
• 根据 touched IDs 之外的数据做 stale-row scan。

因此其数据库工作量只随 upserts + deletes 增长。

6.4 Bounded batch SQL

批量操作不构造无限长 SQL。根据 SQLite bind-variable limit 选取固定 batch size， 并在同一个 transaction 内分批执行：

• multi-row INSERT ... ON CONFLICT DO UPDATE；
• 带 source = web 条件的 batch delete；
• 只返回 instance ID/source 的 ownership query。

Patch statement 数量应为 O(ceil(delta / batch_size))；Full 为 O(ceil(total / batch_size))。每个 accepted request 只有一个 transaction 和 一次 revision 写入。

6.5 Alternate-write revision invalidation

现有其他路径可能 save、delete、disable 或改变 web-owned row。若这些路径修改 rows 后仍保留旧 managed revision，Patch CAS 会把错误状态当作正确 base。

因此所有 config mutation Adapter 必须遵守：

1. 判断 mutation 是否改变 web-owned row；
2. 在一个 transaction 中执行 mutation；
3. 在 commit 前删除该 Target 的 managed revision。

Managed Full/Patch 在同一 transaction 内先完成 mutation，最后写入新的 target revision。只影响 user-owned rows 的操作不清除 managed revision。

本方案不在 /validate-token 读取 revision 时重算完整 digest，否则周期性验证会 重新变成 O(total)。Revision 完整性由所有写入 Adapter 局部维护。

6.6 Locking, cancellation and notification

现有 per-target process-local lock 可以保留，用于减少同进程的重复工作，但它不 承担正确性。正确性由 SQLite transaction 和 CAS 提供。

• Transaction 内不执行 Session RPC、网络请求或无关 async 工作。
• HTTP future 在 commit 前取消时，transaction drop 必须 rollback。
• Commit 后即使 response 或 notification 丢失，persisted state 仍然有效；调用者 用同一 target retry 会得到幂等成功。
• 只有带 target revision 的 Applied 才通知匹配的 live Session； AlreadyApplied、legacy unrevisioned Full、conflict 和失败不重复通知。
• Notification 必须发生在 commit 之后。
• Full notification 清除任何 pending delta，触发完整收敛。
• Patch notification 携带 expected revision、target revision、upsert IDs 和本次 transaction 实际接受删除的 web-owned IDs。请求删除但数据库原本不存在的 ID 仍是 no-op，不能借机删除 Core 中同 ID 的 user-owned 实例。只有 Session applied revision 精确等于 expected revision，且没有更早的 Patch 等待处理时，才保留该 delta。
• 两次 Patch 在前一次完成前积压时不合并 delta；Session 清除 pending delta，并在 最新 heartbeat/revision 上执行一次 Full。这避免引入 Patch queue 或 delivery FSM。
• 增量 round 只读取 upsert rows，只删除本次 delete IDs，只对 touched running instances 执行 runtime Patch/Run。完成前再次校验 persisted target revision；只有 全部 touched instances 成功且 target 仍相同，才推进 applied revision。
• 任何通过 EasyTier Web mutation route 直接 Run、Save、Delete 或切换实例状态的 操作在执行前和结束后（包括部分 side effect 后返回错误）都清除 Session applied revision 与 pending delta、增加运行配置 cache epoch，并唤醒一次 Full reconcile。旧 round 只有 epoch 仍匹配时才能推进 applied revision；新一轮不得 信任 mutation 前缓存的 runtime config。否则 runtime-only mutation 或 Core 成功、 SQLite 失败的复合 mutation 可能在 persisted revision 不变时破坏 Patch base 的 完整性。

7. Capacity contract

当前 route 没有显式 body limit，Axum Json 使用依赖版本的默认 2 MiB 限制。 生产容量不应依赖框架隐式默认值。

本阶段定义并测试四个独立限制：

• decoded request 最大 bytes；
• Full entries / Patch upserts 最大数量；
• Patch deletes 最大数量；
• 单个 network_config 最大 bytes。

限制只应用于 internal managed-config route，不提高其他 public route 的 limit。 具体默认值不能拍脑袋确定：先采集 1k/10k representative configs 的 encoded size 和 peak memory，再选择有明确 headroom 的默认值及硬上限。

提高 Full limit 只是确保 fallback 覆盖已支持的生产规模，不是稳态优化。请求压缩 同样只能降低 wire bytes，不能降低 JSON materialization 和 SQLite 工作量，因此 不作为 Patch 的前置条件。

8. Failure and recovery

Failure	Receiver state	Caller action
Invalid payload	Unchanged	修复请求，不重试相同 payload
Capacity exceeded	Unchanged	使用较小 Patch；Full 需检查支持规模
Revision conflict	Unchanged	重新观察；有 base 时重算 Patch，否则 Full
Ownership conflict	Unchanged	解决 ownership，不能自动覆盖
SQLite error before commit	Rolled back	从相同 observed revision 重试
Response lost after commit	Target committed	同一 target retry，幂等成功
Process exits before revisioned Session notify	Target committed	现有 revision reconciliation 恢复
Alternate web-row mutation	Revision atomically cleared	下一次观察触发 Full 修复
Console cache loss	Receiver unchanged	Console 发布 Full

Receiver 不保存 Patch delivery ledger。Publisher 根据自己的完整目标和 receiver 当前 revision 重算 Patch 或选择 Full。

9. Rollout and rollback

9.1 Receiver-first rollout

1. 为现有 Full 行为增加 characterization tests。
2. 将 Full rows/revision 改为一个 atomic transaction。
3. 为 alternate web-row mutation 增加 revision invalidation。
4. 增加 PATCH、typed conflict、capacity limits 和 metrics。
5. 在 Console 仍只发送 PUT 时部署到全部 EasyTier Web 实例。
6. 完成旧 Console PUT、新 Console PUT/PATCH contract 测试。
7. 最后启用 Console Patch 发布。

Patch capability 不通过 /validate-token 协商。部署顺序就是 compatibility gate； 这样不会把配置能力重新耦合回鉴权 Interface。

Console 遇到 409 可以 re-observe 后发送 Full。它不能把 404、401 或 malformed response 当作旧 receiver 并静默换一种 mutation contract；出现 404 表示接收端 部署门禁未满足。

9.2 Rollback

• Console 尚未发送 Patch 时，EasyTier Web 可正常回滚。
• Console 已发送 Patch 后，先回滚 Console，使调用恢复为 PUT，再回滚 Web。
• PUT 在整个发布周期保持兼容。
• Patch 和 Full 写入相同 rows/revision，不需要格式级数据迁移。

本方案不新增 persistent table。现有 Target/instance unique index 应覆盖 touched-ID 查询；若实现时需要新 index，必须先用实际 SQLite query plan 证明。

10. Verification

10.1 Contract tests

• 现有 Full JSON 继续接受。
• 空 Full 删除所有 web-owned rows，保留 user-owned rows。
• Patch add/update/delete 与等价 Full 得到相同最终 projection。
• Duplicate/overlap/invalid config 返回 400 且零写入。
• Patch 缺少 revision 返回 400。
• Revision conflict 返回 409 和 current revision，不返回 config。
• Byte/count/per-entry limits 分别有确定性测试。

10.2 Transaction and ownership tests

• 在 upsert 后、delete 后、revision write 前注入错误，rows/revision 全部 rollback。
• Revisioned Full/Patch 的 user-owned collision 整体 rollback。
• 删除不存在的 ID 幂等成功。
• 两个 target 从同一 base 并发时，一个成功、一个 409。
• 相同 target retry 只有第一次写入，第二次为 no-op success。
• Alternate save/delete/disable web row 与 revision invalidation 原子提交。
• User-owned-only mutation 不清除 managed revision。
• 数据库重连后，任一 persisted revision 都对应完整一致的 rows。

10.3 Scale tests

至少使用 1k 和 10k representative entries：

• 单实例 Patch 的 decoded bytes、row reads、writes 和 statement count 不随 Target 总实例数增长；
• Patch 不执行 list-all query；
• Full 使用 bounded batches 和一个 transaction；
• Revision read 保持 O(1)；
• 超限 Full 稳定返回 413/422，而不是耗尽进程内存；
• 并发请求无 deadlock，且 CAS 结果确定。

Session 测试还必须验证：精确 base/target 使用 touched-instance reconcile；base 不匹配、目标 revision 已变化、Full notification 和 Patch backlog 都使用 Full； touched runtime apply 失败不推进 applied revision；删除只作用于本次 delete IDs。 运行态 Config Get/Patch/Run/Delete 数量应随 touched instances 增长。为确认运行实例 身份而进行的一次 list/meta RPC 可以保留，它不发送或重写所有实例配置。

11. Observability

每个请求记录结构化字段，但不记录 config 内容：

• mode：full / patch；
• user/machine scope；
• request bytes；
• desired/upsert/delete count；
• normalization、target-lock wait、transaction duration；
• SQL statement/batch count；
• result：applied、already-applied、revision-conflict、ownership-conflict、 invalid、oversized、database-error；
• Session notification 是否发送。

Rollout acceptance：

• Console 启用后 Patch 占普通变更的绝大多数；
• 单实例变化的 request size 与 SQLite cost 与单实例成比例；
• conflict rate 可解释且稳定；
• 支持规模内的 Full 没有 413/422；
• validate-token latency 不随 Target 实例数增长。

12. 后续优化

12.1 Session runtime delta apply（已实现）

Patch commit outcome 已携带 touched IDs。Session 只在 applied revision 正好等于 Patch base 时执行 touched-instance reconcile；重启、revision 断链、通知丢失或 并发 Patch backlog 都退回 Full。接收端不保存 Patch queue，也不合并 delta。

12.2 Chunked Full

不能把 Full Exact Set 直接分页写入 live rows：接收端无法在中间页判断哪些旧 实例最终应删除，crash 也会暴露半套目标。

如果测量证明单请求 Full 无法覆盖必须支持的冷恢复规模，需要单独设计带 snapshot ID、staging rows、expiry、finalize 和 atomic swap 的协议。在出现数据 证明前不新增该状态机。

13. Implementation files and checklist

主要涉及：

• easytier-web/src/restful/network.rs
• easytier-web/src/client_manager/mod.rs
• easytier-web/src/client_manager/managed_config.rs
• easytier-web/src/db/mod.rs
• 对应 contract、database 和 managed-config tests

完成条件：

• 现有 Full compatibility tests 固定。
• Full config rows 与 revision 原子提交。
• Alternate web-owned mutations 原子清除 revision。
• PATCH contract 和 typed 409 实现。
• Patch 只查询、写入 touched IDs。
• Bulk SQL 遵守 tested bind-count bound。
• Route byte/count/per-entry limits 有文档和测试。
• User-owned rows 不能被 Full/Patch 覆盖或删除。
• Empty Full 语义保持。
• Applied/AlreadyApplied/conflict 的通知行为符合设计。
• Session 在 revision 连续时只收敛 touched instances，断链时使用 Full。
• 1k/10k scale 与 concurrent CAS tests 通过。
• Receiver-first compatibility matrix 通过。