Skip to content

feat: Responses WS lane observability under /__bili/stats (part of #1926) - #1936

Closed
ranxianglei wants to merge 5 commits into
masterfrom
2026-10-02_ws-idle-observability
Closed

ranxianglei wants to merge 5 commits into
masterfrom
2026-10-02_ws-idle-observability

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Part of #1926 — implements step (c): lane observability for the Responses WebSocket proxy added by #1859.

Stacked on #1859 (read first)

This branch sits directly on #1859's latest verified integration state (323f37bb = master 8ae9225a + the three rebased #1859 commits + the buffered-auxiliary fix). Until #1859 lands on master this PR cannot merge cleanly; once it does, this becomes a single small commit rebased onto master.

The real delta is the top commit only (45aef9f, 5 files, +172/-15):

File Change
src/responses-ws.ts per-peer lifecycle records (conn id, session prefix <=128, timestamps, request count, busy flag); installResponsesWebSocket returns { upgrade, stats }; stats() reports peers + lane totals
src/server.ts threads the accessor into handle() as an explicit parameter (matching existing per-instance threading); /__bili/stats gains a responsesWs key
tests/responses-websocket.test.ts +unit (retained-bytes formula, socket liveness) +integration (empty -> turn -> active-hold -> growth -> second peer -> drain lifecycle through the real HTTP endpoint)
docs/opencode-responses-websocket(.zh-CN).md one bullet each documenting the on-demand stats surface

What it exposes

GET /__bili/stats -> responsesWs:

  • per peer: conn, session (same <=128-char prefix already logged at connect time), connectedAt, lastActivityAt, idleSeconds, active, requests, upstreamConnected, retainedBytes (client-leg + upstream-leg checkpoint bytes)
  • lane totals: peerCount, activePeers, totalRetainedBytes

This is exactly the visibility the OS-snapshot workaround in #1926 currently stands in for: which client sockets are pinned, how long idle, how much checkpoint memory is retained, and whether the upstream leg is still attached.

Design constraints honored

  • No timers. Pure on-demand read at request time - no new leak surface, nothing to clear on shutdown, no interaction with the _liveUpstreamTimersForTest() === 0 contract.
  • No configuration surface. No env var / CLI flag / config field; the owner-gated surface is untouched.
  • No wire behavior change. Framing, checkpoints, retry-full, and connection-limit rotation are byte-identical; the upgrade handler gained bookkeeping only.
  • Privacy per feat: ACP-aware OpenCode V2 Responses WebSocket proxy #1859 diagnostics conventions. Only the session prefix already present in connect logs; no payloads, URLs, or credentials. Pinned by a doesNotMatch assertion.

Behavior change disclosure

/__bili/stats gains one additive key, responsesWs. Existing consumers verified: tests read fields structurally (no whole-object equality), the web UI reads keys leniently. No other endpoint touched.

Verification (on the stacked tree: master 8ae9225 + #1859 @ 323f37b)

  • npm run typecheck - clean
  • node --import tsx --test tests/responses-websocket.test.ts - 37/37 (35 pre-existing + 2 new)
  • node --import tsx --test tests/blind-tunnel-stats.test.ts - 1/1 (stats-consumer regression)
  • npm run build - success

Full regression is left to CI on the rebased head after #1859 merges.

Steps (a)/(b) of #1926 (idle-close / checkpoint eviction) remain deferred per the issue's own gating: they need E2E-verified OpenCode host recovery after previous_response_not_found (harness lives in #1859, unmerged) plus an owner decision on any idle threshold (config surface).

@github-actions

github-actions Bot commented Oct 2, 2026

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-02_ws-idle-observability (45aef9f)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.1935-pr.1936.a15b4fb

This exact version is immutable and reproducible. The rolling pr tag tracks the newest test build across all PRs.

Option B — Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr1936.tgz
npm install -g package

Install instructions are refreshed on each push.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 收到。这是带 ework-agent-pr 标记的 [PR],按协议不重做,走 review 流程:分支已拉取核对(merge-base = 8ae9225a,与 issue 所述一致;实际 delta 仅顶提交 45aef9f4,5 文件 +172/-15)。正在:①核对代码与声明的约束(no timers / no config surface / wire byte-identical);②跑定向测试(responses-websocket、blind-tunnel-stats)+ typecheck/build;③查 CI 状态。结论稍后按结构化七问补在本线程。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 独立复审完成(不采信实现方自述,全部重新验证)。结论:审查通过,达到可合并标准;合并顺序被 #1859 阻塞——#1859 合入 master(且必须含其集成分支内容,见下「关键依赖」)后,本 PR rebase 到 master 收敛为单提交小 PR 即可合并。

结构化七问

  1. 是什么问题:不是缺陷修复,是补可见性——feat: ACP-aware OpenCode V2 Responses WebSocket proxy #1859 引入的双端 WS 通道里,每个存活客户端 socket 钉住一条活的上游 WS 连接 + 两侧检查点,除客户端断开/服务关闭外无回收路径,bili 自身没有任何表面能观测这个状态(Responses WS lane: idle client sockets pin live upstream connections and checkpoints with no reclamation #1926 步骤 c)。
  2. 什么原因导致的:feat: ACP-aware OpenCode V2 Responses WebSocket proxy #1859 的有意设计边界——上游连接跨轮次保留(continuity 契约)、模块刻意无定时器(idle 清理拆为独立失败域)。缺的是任何安全清理策略的前置条件:可见性。
  3. 怎么修复的:纯被动观测面。per-peer 生命周期簿记(conn 编号、会话前缀 ≤128、时间戳、请求计数、busy、上游 socket 存活、双侧检查点字节)+ GET /__bili/stats 新增 responsesWs 键按需暴露。零新 timer、零配置面、wire 路径逐字节不变。
  4. 是否有回归问题:逐项过完,均保持——
    • installResponsesWebSocket 返回值从函数变 {upgrade, stats} 对象:全仓唯一生产调用点(src/server.ts:455)已同步更新,测试/e2e 无直接调用者(grep 全仓核实);
    • upgrade handler 内 busy 标志从闭包变量移入 record:同一事件循环内同生命周期,语义不变;close 路径仅追加 peers.delete(record),既有 transport/history 回收不动;server shutdown teardown 不变(peers Set 随闭包 GC,无 timer 引用,无泄漏面);
    • 准入门(loopback / x-bili-plugin=opencode / conversation header)、426 未认领升级回落、framing/checkpoint/retry-full/connection-limit 轮换:diff 核实全部未动;
    • /__bili/stats 纯增量键:全部消费者逐一验证为结构化/宽松读取(4 个测试文件 + web UI 的 ?? 回退模式),无任何整对象相等断言受冲击;
    • _liveUpstreamTimersForTest() === 0 契约:模块内 grep 确认零新增 timer/setInterval;
    • 双压缩模式:WS lane 结构上只服务 plugin mode(准入要求 x-bili-plugin),proxy mode 不受影响;stats 读取不触碰 kernel 状态。
  5. 是否破坏缓存:不涉及。未触碰缓存/重试/增量游标/去重键;wire 字节不变,前缀缓存不受影响。
  6. 是否改了设计方向:没有。(a)/(b)(idle-close / 检查点驱逐)有意未实现,与 Responses WS lane: idle client sockets pin live upstream connections and checkpoints with no reclamation #1926 自身的门槛一致:需 E2E 验证 OpenCode 宿主对 previous_response_not_found 的恢复行为(harness 在未合并的 feat: ACP-aware OpenCode V2 Responses WebSocket proxy #1859 内)+ owner 对 idle 阈值的决策(属配置面,不可自启)。issue 保持 open 等 (a)/(b) 是正确的。
  7. 是否引入了新的配置:没有。responsesWs 是响应字段扩展,不是配置项;owner-gated 配置面未动。

验证证据(本地 + CI 双重)

  • 本地(worktree @ pr-1936):npm run typecheck 干净;tests/responses-websocket.test.ts + tests/blind-tunnel-stats.test.ts 38/38 通过(与 PR 自述一致);npm run build 成功且 dist-import-annotations OK;
  • CI @ 45aef9f4:16/16 check runs 全绿(含 OpenCode V2 Responses WebSocket ACP e2e job、四平台矩阵、real-client lanes、hermetic registry、version-guard);
  • 新测试有效性:非恒真——单元钉死 retainedBytes 精确公式与 socketOpen 读取;集成走真实 HTTP 端点跑 drain→turn→hold(active 标记)→finish(计数+字节增长)→双 peer→drain 全生命周期,drain 断言能抓住 peers.delete 缺失或 busy 残留;隐私 doesNotMatch 钉死 payload/credential 不外泄。有牙。

Rebase 风险评估(#1859 合入后)

master 已从 8ae9225a 推进到 9c608fc3(zcode #1892、fold-reconcile #1924、image/codex-overlay/#1882 等 21 commits)。逐 hunk 比对:该区间在本 PR 触碰的文件中只有 src/server.ts 有变更(+40/−3,位于 import 区 ~51/~68 与 prepare*/injectSystem 区 3516–4771),与本 PR 的 server.ts hunk(130/431/455/1170/1211/6869/6899)完全不重叠;responses-ws.ts 在 master 不存在(#1859 新增文件,冲突不可能)。结论:#1859 按集成分支树合入后,本 PR rebase 预期文本级干净,rebase 时再复核一次即可。

关键依赖(需 owner 知悉,#1859 线程已催办,此处重申)

#1859 当前 PR head(1e282e91)尚未包含 buffered-auxiliary 请求的 Buffer-body 修复(323f37bb,现仅在作者集成分支 darkness-A:2026-10-02_local-ws-v180 上;已用 diff 逐行核实两树差异恰好就是那 4 行 fetch() 改动 + 21 行回归测试)。#1859 线程 floor 14/17 已请作者把集成分支内容推上 PR 分支,尚待执行;且 #1859 现在 GitHub 报 mergeable=False(master 前进导致 server.ts 冲突,需作者 rebase 解冲突)。若 #1859 最终以不含 aux 修复的树合入,本 PR 声明的堆叠基点即发生语义漂移(其树内含该修复,且修复的回归测试会随之消失)——届时 rebase 前必须先确认,不能默认干净。

小问题(不阻塞,记录在案,理由如下)

  1. retainedBytes() 每次 stats 调用重算 JSON.stringify 两侧检查点,与 commit() 处已有的字节计算重复(src/responses-ws.ts:104 附近)。值完全一致(同一对象确定性序列化),正确性无损;成本 O(checkpoint 大小)/peer/次,发生在 loopback-only 的按需管理端点上,现实用量(KB–MB 级检查点、无 UI 轮询该端点)下可忽略。若未来 stats 成为高频轮询面,可在 commit() 时把字节数存入 Checkpoint 直接返回。
  2. 集成测试里一处冗余双读(lane = await readLane(); lane = await readLane();),纯观感。

两条都不在本轮直接修:本 PR 是叠在外部贡献者未合并 PR 之上的栈式工作,分支注定在 #1859 落地后 rebase 收敛,此刻推 cosmetic commit 只会触发一轮全矩阵 CI 并增加 rebase 摩擦;留给收敛 pass 一并处理(已在上面留痕,不会丢)。

判定

审查通过:方向正确(严格实现 #1926 步骤 c,零契约风险)、回归审计干净、测试有牙、CI 全绿、diff 整洁(5 文件全部与目的相关,docs en/zh 同步)。合并路径唯一阻塞项是 #1859 的落地顺序与上述 aux 修复依赖——#1859 带完整集成分支内容合入后,把本 PR rebase 到 master(单提交、预期干净)即可走合并流程。

@ranxianglei

Copy link
Copy Markdown
Owner Author

Closing as superseded.

The owner landed option (c) of #1926 independently as commit d599370b ("feat(#1926): WS bridge observability") on branch 2026-10-02_opencode-responses-ws-generic — implemented at the generic bridge level (src/ws-bridge.ts, optional WsBridgeSession.stats() hook, /__bili/stats → wsBridge, one-shot idle-retention warns gated by BILI_WS_IDLE_WARN_SECONDS). That design supersedes this PR's Responses-specific responsesWs shape, which was also stacked on the pre-generalization structure (installResponsesWebSocket) that no longer exists on master after #1968.

See the discussion in #1926 for the follow-up needed to land d599370b (it sits past the #1968 merge point with no open PR yet).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants