Skip to content

Commit 03afd7e

Browse files
committed
fix(ql3): isolate native console asynchronous sessions
1 parent 9708a37 commit 03afd7e

9 files changed

Lines changed: 538 additions & 126 deletions

docs/QINGLONG_3_0_ARCHITECTURE_RFC.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# QingLong 3.0 Architecture RFC
22

3+
- D-432/ADR-0534(原生 Console 源码候选):修复断开/重连后的异步结果污染。每次连接使用独立内存代次,统一请求与编辑/执行链拒绝旧成功、失败和 finally;旧响应不得重开编辑器、恢复 Secret catalog、覆盖 proof 或在新连接下发出后续请求。16 项针对性回归、完整 Local API 130/130、后端 1683 pass/2 环境 skip/0 fail,静态资产合计 114,042 bytes。断开不撤销已提交的服务端写入,重连须核对 durable 状态;不新增包、后台服务或后端权限。此修复尚未通过同源远端 CI/阶段实物验收,见 [ADR-0534](./adr/ADR-0534-native-console-session-isolation.md)。
4+
35
- D-431/ADR-0533(原生 Console 源码候选):Task、Trigger、Run 列表接入既有 keyset API,开放下一页、回到首页和当前页刷新,每次最多 64 条并替换 DOM,不缓存历史页、不轮询或扩大后端查询。验证规范 cursor、页内/跨页顺序与继续边界;请求/选择代次防止旧列表、错误、详情和 Secret catalog 覆盖当前页面。客户端与生产 HTTP parser 集成 15/15、完整 Local API 114/114,静态资产共 111,857 bytes;默认 headless/Cluster 不变。远端 CI、浏览器证据和 exact 阶段实物分别核验,不借用 D-430 archive。
46

57
- D-430/ADR-0532(exact Console 双架构阶段实物已交付):在原生运行详情中开放日志下一片段、回到开头与当前片段刷新,固定 32 KiB 替换窗口,不累计全文或后台轮询。严格验证响应身份、字节范围与前进 cursor,按不含凭据的选择代次丢弃过期响应,防止切换或断开后覆盖新详情。复用既有 API/Policy/Audit,不新增包、依赖、迁移或后端 authority;默认 headless 与 Cluster 不变。提交 `12ed38b7d72fe6366ad8f1ac84aebb1bb772f3b5` 主 CI run `33793623200` 为 42 success/3 expected skip/0 fail,独立 Kubernetes run `33793623184` 成功;Console artifact run `33793687627` 为 43 success/2 expected skip/0 fail。amd64/arm64/milestone artifact `9909229721`/`9909131639`/`9909265138` 实际下载后的 checksum、bundle v8 与 milestone v7 auditor 均通过;两个 archive 内的原生 JS 都与该提交逐字节一致。该实物不包含后续 D-431 列表分页,不等同完整 3.0 或 Public Release。

docs/adr/ADR-0533-native-console-ledger-pagination.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# ADR-0533:原生 Console 的任务、定时与运行列表分页
22

3-
- 状态:Accepted(D-431 源码候选;远端 CI 与阶段实物待验证
3+
- 状态:Accepted(D-431 远端 CI 与产物构建通过;下载实物复核待完成
44
- 日期:2026-09-04
55
- 关联:QL-RFC-0001 D-431、ADR-0532
66

@@ -28,3 +28,5 @@
2828
原生 JS 为 80,336 bytes,三项静态资产共 111,857 bytes,仍小于单文件 96 KiB / 合计 192 KiB。D-430 的 `12ed38b7` 构建不含本切片;本地测试不等于 exact 双架构产物交付。
2929

3030
真实 Chromium 使用当前原生静态资产与合成 HTTP 数据验证了 Task、Trigger、Run 的第 65 条可达,任务详情可从第二页打开,DOM 每次只保留当前页。请求记录包含三个规范 continuation URL,浏览期间没有自动列表轮询。该浏览器证据验证交互,不冒充真实数据库、Owner 写入或双架构镜像验收。
31+
32+
提交 `ce8c3a7d2afdbb11b2a33f4884702454d1d22a53` 的主 CI [run 33796190607](https://github.com/whyour/qinglong/actions/runs/33796190607) 与 Console artifact [run 33797144811](https://github.com/whyour/qinglong/actions/runs/33797144811) 均已完成并成功。上传清单包含 amd64 `9910148271`(239,038,659 bytes)、arm64 `9910153237`(234,438,339 bytes)及 milestone `9910185111`(6,797 bytes);本记录仅确认远端成功与上传存在,下载后的 checksum、离线 auditor 和 archive 源码复核尚未完成。这些归档不包含后续 ADR-0534 的客户端连接代次修复。
Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# ADR-0534:原生 Console 异步操作的连接代次隔离
2+
3+
- 状态:Accepted(D-432 源码候选;同源远端 CI 与阶段实物待验证)
4+
- 日期:2026-09-04
5+
- 关联:QL-RFC-0001 D-432、ADR-0533
6+
7+
## 问题
8+
9+
列表的请求代次不能覆盖所有编辑器调用链。已经复现:创建 Task 时读取 Secret 目录,用户断开连接后,迟到的响应仍会填充 catalog;完整 Task authoring、presence challenge 和写入后的刷新也可能把旧连接结果带入新页面。这个问题是客户端状态隔离缺陷,不是后端认证绕过。
10+
11+
## 决策
12+
13+
- 每次连接及断开都更换一个不含 credential 的内存代次对象;即使重新使用同一个 credential,也不是同一连接。
14+
- 统一 `api` 在网络异常、JSON 解码异常和解码完成处检查代次;过期结果统一拒绝为 `session_changed`,不能向调用者暴露旧成功内容或旧错误。
15+
- Task/Trigger/Secret 编辑、authoring、presence 提交和 Run 启停链在异步边界再次检查代次。旧调用不能重新打开对话框、写入 catalog/snapshot、覆盖新 proof、发布 toast,或在新连接下继续读取/写入。
16+
- 断开时同步清空既有敏感状态并恢复提交按钮基线;旧 finally 不能解锁新连接正在提交的按钮。跨连接检查不替代同一连接内的列表和选择代次。
17+
- 不增加 package、依赖、后台计时器、轮询或后端路由。默认 headless、Cluster、旧面板兼容入口和后端 Policy/presence/audit 规则不变。
18+
19+
## 不承诺的行为
20+
21+
丢弃页面响应不等于撤销已经发送的服务端操作。断开之前已提交的 Task/Trigger/Secret 写入、Run start 或 cancellation 仍可能成功;重连后应读取 durable 状态核对,不应自动重试或把断开视为取消。此切片不引入网络取消或事务回滚,也不把 Local Console 扩展为多用户远程会话产品。
22+
23+
## 替代方案
24+
25+
只比较 token 无法区分同一 credential 的重新连接;只加 AbortController 不能撤销已完成的解码、排队回调或服务端写入。逐页临时修补则容易遗漏编辑器和 finally。因此保留统一连接代次检查,并在会产生后续副作用的调用边界复核。
26+
27+
## 验证
28+
29+
测试直接执行发布的 `console.js`,通过 `test/support/consoleClient.cjs` 复用最小 DOM 夹具,不新增生产导出。16 项回归覆盖迟到目录、JSON 解码、网络错误、相同 credential 重连、authoring 全量定义、三种草稿、按钮 finally、Trigger pin 读取后的写入禁止,以及 Run 写入后的刷新/选择隔离。初始 13 项在修复前为 12 fail / 1 pass,修复后全部通过;新增 3 项也通过。
30+
31+
最终 Local API 130/130,完整后端 1685 项(1683 pass / 2 环境条件 skip / 0 fail)。Local image 与 18-package boundary audit 均 compatible;原生 JS 82,521 bytes,三项静态资产合计 114,042 bytes,仍在单文件 96 KiB / 合计 192 KiB 预算内。
32+
33+
真实 Chromium 使用当前静态资产和仅监听本机的合成 HTTP 服务完成连接、创建 Task、确认 Secret GET 挂起、断开、放行旧响应的交互;页面保持等待凭据且没有重开编辑器。测试没有真实数据库、生产 credential 或写入 authority,不能代替镜像端到端验收。
34+
35+
上述本地验证不代表修复已进入既有下载产物。D-431 的 `ce8c3a7d2afdbb11b2a33f4884702454d1d22a53` 产物也不包含本修复;本切片必须以自己的 source revision、CI 和阶段归档证据验收。

docs/adr/README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -537,6 +537,7 @@
537537
| [ADR-0531](./ADR-0531-canonical-run-log-bridge-for-legacy-panel.md) | 现有面板到规范 Run 日志的有界桥接 | Accepted(D-429 exact Console 双架构阶段实物已交付) |
538538
| [ADR-0532](./ADR-0532-native-console-log-window-navigation.md) | 原生 Console 日志窗口导航 | Accepted(D-430 exact Console 双架构阶段实物已交付) |
539539
| [ADR-0533](./ADR-0533-native-console-ledger-pagination.md) | 原生 Console 任务、定时与运行列表分页 | Accepted(D-431 源码候选;实物待验证) |
540+
| [ADR-0534](./ADR-0534-native-console-session-isolation.md) | 原生 Console 异步操作的连接代次隔离 | Accepted(D-432 源码候选;同源 CI 与实物待验证) |
540541

541542
## 规则
542543

docs/operations/ql3-local-web-console.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,8 @@ ssh -L 5701:127.0.0.1:5701 router.example
8383

8484
Credential 只存在当前页面内存,不进入 URL、Cookie 或 Web Storage。页面刷新会丢失 credential,需要重新输入;这是当前安全边界,不是缺陷。
8585

86+
断开连接不会撤销服务端已经收到的写入、启动或取消请求。重连后先核对 Task/Trigger/Secret revision 与 durable Run 状态,不要因为页面没有收到结果就直接重复提交。D-432 源码候选修复旧连接的慢响应重新打开编辑器、回填 Secret 目录或影响新提交的缺陷,见 [ADR-0534](../adr/ADR-0534-native-console-session-isolation.md);上述 D-429/D-430 归档及 D-431 构建均不包含这项修复,不能把本地回归通过当作已下载版本已更新。
87+
8688
## 当前阶段可用边界
8789

8890
D-424 阶段实物的原生 `/console` 可操作闭环是内建 argv command Task create/list/read/update/enable/disable/start、Task pinned Secret binding、Secret current metadata/create/rotate、`qinglong/cron@v1` Trigger list/read/create/update/enable/disable,以及 Run list/read/events/steps/log/cancel。Task 编辑器只修改当前展示字段并保留完整快照中的其他 config/labels;其他 Task kind 或 Trigger schema 继续使用受信管理入口。

0 commit comments

Comments
 (0)