Skip to content

feat: web warning + generic diagnostics reporting when SQLite degrades to legacy-only (#3040) - #3041

Merged
ranxianglei merged 6 commits into
masterfrom
2026-10-13_storage-degraded-web-warning
Oct 14, 2026
Merged

ranxianglei merged 6 commits into
masterfrom
2026-10-13_storage-degraded-web-warning

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Closes #3040

What

Before the upcoming full-mode default flip (#2960 roadmap), environments where the SQLite engine ladder lands on none — or where a corrupt index.db trips the 3-strike guard (#2771) — silently ran on legacy JSON: one-time log lines, no persistent user-actionable surface, so we would never learn which environments fail before they become a support wave. Per owner direction in-thread (「最好这个复制错误到github反馈做成通用功能,以后错误都这样」), this ships a generic "copy diagnostics → prefilled GitHub issue" facility whose first consumer is the storage-degradation banner:

  1. Structured runtime status (src/storage/runtime-status.ts): records the requested mode (SessionStore ctor), sidecar open failure/instance (UnifiedShadow.maybeOpen), and the ensureSqliteEngine outcome (cli.ts). Derives requested vs effective, degraded, intentionalOptOut (BILI_ENCRYPTION_KEY excluded by design), and a human-readable reason from the ladder outcome / bootstrap failure payload / 3-strike state.
  2. One shared wire helper (storageStatusWire()) feeds BOTH /__bili/status and /__bili/overview — the [web] advisory banner 是死代码:/__bili/overview 不含 advisory 字段,web 客户端从不调用 /__bili/status #2152 parity discipline; the two surfaces can never drift apart.
  3. Generic endpoint GET /__bili/diagnostics?topic=… (loopback-only, same gate as all /__bili/*): returns {blob, title, url} — a copyable blob (bili version+commit, node version, platform/arch, OS, uptime, session count + topic section) and a prefilled https://github.com/ranxianglei/billion-context/issues/new?title=&body= link whose body decodes back to the exact blob. Unknown topics fall back to the base blob, so any future warning only needs one entry in the topic table. First topic: storage-legacy-only (raw knob stack env+file verbatim, engine-ladder outcome+reason, bootstrap failure marker with cooldown remaining, [storage] log tail).
  4. Web banner (zh/en i18n, existing .banner.warn style) shown iff requested ≠ effective and not an intentional opt-out, with copy-diagnostics + report-on-GitHub buttons wired to the generic endpoint. Copy per issue spec, {reason} interpolated.

Config surface

None. No new config keys, env vars, or CLI flags — reuses the existing knobs (BILI_STORAGE_UNIFIED/storage.unified, BILI_STORAGE_JSON_WRITER/storage.jsonWriter, BILI_SQLITE_AUTO_DOWNLOAD/storage.sqliteAutoDownload, BILI_ENCRYPTION_KEY) through the existing three-level resolution in src/knobs.ts. knobs.ts now exports the file-tier readers (fileStorageUnified/fileStorageJsonWriter/fileStorageAutoDownload) so diagnostics report raw values; persist.ts drops its private duplicates (identical behavior — same loadConfigFile() source, same guards).

Behavior changes (disclosed)

  • Additive: /__bili/status and /__bili/overview gain a storage field (new key; existing consumers unaffected).
  • New endpoint: GET /__bili/diagnostics?topic= — loopback-only like every other /__bili/* route; never throws (all fs/session access guarded).
  • New UI element: #storage-degraded-banner renders only when degraded=true; hidden for healthy shadow/full, explicit legacy, and the encryption opt-out (reported as intentionalOptOut: true, never warned).
  • The fail-open contract itself is UNCHANGED (fix(storage): drop better-sqlite3 optional dep (#2823) #2825): degradation behavior, one-time log lines, and the 3-strike guard all work exactly as before — this work only records what already happens and surfaces it.

Verification

Local targeted runs green on the rebased head (merged with current master incl. #3019): typecheck + build + tests/web-storage-banner.test.ts (new: forced none-engine wire contract incl. status/overview parity, blob contents, URL body-decode round-trip, unknown-topic fallback, page/client markers; healthy shadow; explicit legacy; encryption opt-out; corrupt index.db #2771) + web-i18n (catalog parity/lint over the new keys) + web-update-banner + storage-engine-bootstrap + storage-json-writer-off + merged-in issue3004-nudge-decide-selfheal. Full-suite verdict = remote CI on the pushed head.

ework-agent added 2 commits October 13, 2026 20:55
…s to legacy-only (#3040)

Before the upcoming full-mode default flip, environments where the engine ladder lands on 'none' (or the corrupt-index.db guard trips) silently ran on legacy JSON and were never learned about. This makes the condition persistent and user-actionable in the web UI, per owner direction as a GENERIC reporting facility ('copy error to GitHub' for all future errors):

- storage runtime status registry (src/storage/runtime-status.ts): records the requested mode (SessionStore ctor), sidecar open failure/instance (UnifiedShadow.maybeOpen), and the ensureSqliteEngine outcome (cli.ts); derives requested vs effective + degraded + intentionalOptOut (BILI_ENCRYPTION_KEY excluded by design) + human-readable reason.
- one shared storageStatusWire() feeds BOTH /__bili/status and /__bili/overview (#2152 parity discipline).
- generic GET /__bili/diagnostics?topic= (loopback-only): copyable blob (bili version/commit, node, platform/arch, OS, uptime, session count + topic section) and a prefilled github.com/ranxianglei/billion-context/issues/new URL whose body decodes back to the exact blob; unknown topics fall back to the base blob. First topic: storage-legacy-only (knob stack verbatim, ladder outcome, bootstrap failure payload w/ cooldown, [storage] log tail).
- web banner (zh/en i18n, existing banner styles) shown iff requested != effective and not an intentional opt-out, with copy-diagnostics + report-on-GitHub buttons wired to the generic endpoint.
- knobs.ts exports the file-tier readers (fileStorageUnified/fileStorageJsonWriter/fileStorageAutoDownload) so diagnostics reports raw values; persist.ts drops its private duplicates.
- tests/web-storage-banner.test.ts: forced none-engine (banner wire contract + blob + encoded link + page/client markers), healthy shadow, explicit legacy, encryption opt-out, corrupt index.db (#2771).
@github-actions

github-actions Bot commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-13_storage-degraded-web-warning (cdd6e83)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.3454-pr.3041.cffee4f

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-pr3041.tgz
npm install -g package

Install instructions are refreshed on each push.

ework-agent added 2 commits October 13, 2026 21:00
…(follow-up to #3040)

knobs.ts now exports fileStorageUnified/fileStorageAutoDownload (added for the #3040 diagnostics blob); the private copies here wrapped loadConfigFile() in a try/catch that can never fire (it catches internally) — same source, same guards.
…follow-up to #3040)

The reason string is error-derived text composed into innerHTML by the client; the template suite (web-update-banner) pins exactly this property for its banner — mirror it here.
StorageRuntimeStatus / getStorageRuntimeStatus / StorageStatusWire
(runtime-status.ts) and DiagnosticsReport (diagnostics.ts) are consumed
only within their own modules — the public surface is the exported
functions (storageStatusWire / storageDiagnosticsLines / buildDiagnostics).
The unused-exports gate flagged them, which under #2637 fail-fast tiering
cascaded to SKIP the full test + typecheck + build legs in CI, so the PR
head was never actually validated by the suite. Dropping the leading
`export` resolves the gate so CI re-runs on the pushed head. Review fix for #3041.
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

Reviewed PR #3041 against issue #3040 (direction) + full diff + CI. One real blocker found and fixed+pushed; otherwise ready to merge once CI lands green on the new head.

先说结论:方向对、代码干净、测试有牙。唯一拦路的是 unused-exports 门禁失败,它把 CI 的 test / static-gates(typecheck+kernel/pi 套件+build)三条腿全跳过了(#2637 fail-fast 级联)——所以这个 PR head 其实从没被完整跑过。已修掉并推上分支(78c063b1f),CI 正在重跑。

八问:

  1. 是什么问题:给「SQLite 统一存储降级到 legacy-only」做一个 Web 横幅 + 可复制诊断信息 + 一键预填 GitHub issue 的能力;按你 floor-2 的意见做成了通用设施(以后任何警告都能挂),SQLite 降级是第一个接入方。

  2. 什么原因导致的:降级路径(engine ladder 耗尽 / 自下载被挡 / index.db 损坏守卫 [Bug][storage] corrupt index.db bricks SessionStore construction in shadow/full mode (violates the sidecar never-breaks-legacy policy) #2771 / 三振侧车禁用)按 fail-open 契约 fix(storage): drop better-sqlite3 optional dep (#2823) #2825 静默回退 JSON——只留一次性日志行、没有持续的用户可见面,所以在 full-mode 默认翻转前根本学不到哪些环境跑不了 SQLite。(注:CI 拦截是另一码事——4 个 INTERNAL_ONLY 导出触发了 unused-exports 门禁,见第 4 问。)

  3. 影响范围与严重程度:纯增量——/__bili/status、/__bili/overview 各加一个 storage 字段(既有消费者不受影响)、新增 loopback-only 的 GET /__bili/diagnostics?topic=、Web 多一个只在 degraded 时显示的横幅。fail-open 契约本身零改动(降级行为、一次性日志、三振守卫全照旧)。CI 拦截的严重度 = PR head 未被完整套件验证过,不是代码 bug。

  4. 怎么修复的:①设计上共享一个 wire helper storageStatusWire() 喂两个 surface([web] advisory banner 是死代码:/__bili/overview 不含 advisory 字段,web 客户端从不调用 /__bili/status #2152 parity,永不再漂移);通用 endpoint 用 topic 表驱动,未知 topic 回落到 base blob;endpoint 永不抛错(fs/session 访问全部 guard)。②我这边的修复:把 4 个只在模块内部被用到的导出(StorageRuntimeStatus / getStorageRuntimeStatus / StorageStatusWire / DiagnosticsReport)去掉 export(它们的公共面是 storageStatusWire/storageDiagnosticsLines/buildDiagnostics 那批函数),门禁转绿后 CI 才会真正跑全套。已 rebase 到你最新的两笔 follow-up 之上再推,快进干净无冲突。

  5. 是否有回归问题:逐文件过了既有行为——knobs.ts 新增 file-tier readers,persist.ts / engine-bootstrap.ts 删掉各自的私有重复副本(同源同 guard,且 loadConfigFile() 本身 total 永不抛,去外层 try/catch 安全);persist.ts SessionStore ctor 只多一次 record 调用;admin.ts 只加字段 + 新路由(loopback+trusted-origin 门在 handleAdminRoute 入口统一拦截,新路由天然受保护);shadow.ts 加 getter + record 调用、导出 MAX_CONSECUTIVE_FAILURES;page/client/i18n 纯增量(zh/en 四键对齐)。无语义漂移、无阈值/时序/输出格式变化、wire 形状纯加键。未发现回归。

  6. 是否破坏缓存:不涉及——没碰任何缓存/重试/游标/去重键逻辑。

  7. 是否改了设计方向:新增了一个跨切面通用能力(诊断→GitHub 反馈)+ storage runtime-status 注册表作为记录 seam。这是你 floor-2 明确要的扩展,与现有架构一致(knobs.ts 当 knob 家、[web] advisory banner 是死代码:/__bili/overview 不含 advisory 字段,web 客户端从不调用 /__bili/status #2152 parity、/__bili/* loopback 门),不污染边界。

  8. 是否引入了新的配置:不涉及——没有新 key/env/flag,复用现有三层旋钮(PR 声明如此,已核对 BILI_STORAGE_* / storage.* / BILI_ENCRYPTION_KEY)。

测试有效性(④):tests/web-storage-banner.test.ts 是真测试——parity 用 deepEqual(status.storage, overview.storage) 钉死、URL body 能解码回精确 blob、用了 issue 点名的 hook setSqliteEnginesUnavailableForTests(true)、覆盖全部 4 条降级路径 + 3 条不告警场景(健康 shadow / 显式 legacy / 加密 opt-out)+ 未知 topic 回落;端口走 listen(0) 确定性。两条需真实引擎的用例诚实跳过(CI node 22/24 有 node:sqlite,会真跑)。

diff 整洁度(⑤):干净,每行都跟本 PR 目的相关;无空行/重排噪声;lockfile 未动。

顺带核到的两笔 follow-up(已在分支上,均合理):52ff122d5 删掉 engine-bootstrap 里重复的 file-tier reader(loadConfigFile() internal catch 使外层 try/catch 永不触发,判断正确);f0fc906c4 补了「degrade reason 进 innerHTML 前必须 escapeHtml」的断言——正好把我担心的 XSS 面钉住了。

一个非阻塞小观察(不拦、不立项):diagnostics.ts 的 storageLogTail() 每次请求整读两个轮转日志文件(≤~20MB)。对 loopback-only 的按需端点可接受,非缺陷。

判定:可合。 唯一拦截项(unused-exports)已修并推送(78c063b1f),等 CI 在新 head 上把之前被跳过的 test/typecheck/build 腿跑绿即可。合并动作留给你——系统规则禁止 agent 合并 PR:#3041

…er test

tests/web-storage-banner.test.ts built SessionStore({enabled:true}) instances
whose unified shadow sidecar opens index.db inside the per-test temp dir, but
only closed the HTTP server before rmrf(base). Windows cannot delete a
directory while index.db is open, so the leaked handle pinned the tree past
every retry window in tmp-rm.ts -> EPERM in teardown. The 'healthy sidecar'
case is the only one that acquires a live engine (the others force engines
unavailable / opt out via BILI_ENCRYPTION_KEY / fail to open a corrupt db).
Hoist each store and call closeQuietly() in the finally before rmrf.
Review fix for #3041.
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

跟进:CI 跑完了,发现并修掉了一个真实缺陷(仅 Windows)。 上一轮我判「可合 pending CI 绿」,但 CI 回来发现 test 的 windows-latest(node 22+24) 两条腿红,而 ubuntu 全绿、static-gates(typecheck+build+kernel/pi 套件)四平台全绿、其余 e2e 全绿——只有主测试套件的 Windows 腿挂了一条:

✖ #3040 healthy sidecar and explicit legacy: no degraded flag (banner stays hidden)
  Error: EPERM, Permission denied: ...\Temp\bili-storage-banner-XXXX
    at rmSync → defaultRm (tests/tmp-rm.ts:30) → rmrf (tmp-rm.ts:45)
    at tests/web-storage-banner.test.ts:247 (teardown)

6771 例里 fail 1。根因(不是断言失败,是清理阶段):这条用例用 new SessionStore({ enabled:true }) 起了一个真实的 unified shadow sidecar,它在临时目录里打开了 index.db(SQLite);但 teardown 只关了 HTTP server,没关 store 持有的 SQLite 连接。Windows 不能在 index.db 仍被打开时删除该目录,泄漏的句柄把整棵 temp 树钉死,超过了 tmp-rm.ts 的全部重试窗口(~9.7s)→ EPERM。Linux 允许「打开中删除」,所以 ubuntu 绿。四个用例里只有这条真拿到活动引擎(另三条分别强制引擎不可用 / BILI_ENCRYPTION_KEY 主动退出 / corrupt db 打不开,都不留句柄),所以只挂这一条。

怎么修的:persist.ts 本来就有专门的 SessionStore.closeQuietly()(它的注释就写着「Windows 不能在 index.db 打开时删目录,泄漏句柄会钉住调用方的清理」)。我把每个用例的 store 提到 try 之外(let store —— 因为 finally 与 try 不是同一作用域),在 finally 里 rmrf(base) 之前先 store?.closeQuietly() 释放句柄;第二个用例的两个 store 都释放。四个用例统一处理,让 teardown 不依赖宿主引擎可用性(确定性)。断言零改动,diff 纯增量(+22/-5)。已推 cdd6e834b,与分支最新 tip 无冲突快进。

回归:不涉及——只动了这个新测试文件自己的 teardown,没碰任何 src/ 生产代码、wire、配置或既有行为;closeQuietly() never-throws 且对未开 sidecar 的 store 是 no-op。

判定:维持可合。 两个拦截项(unused-exports 门禁 + Windows 测试句柄泄漏)都已修并推送(78c063b1f、cdd6e834b)。等 CI 在 cdd6e834b 上把之前红的 windows test 两条腿跑绿即可合并。合并留给你——系统规则禁止 agent 合并 PR:#3041

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

CI 全绿,收工确认。 在推送的 cdd6e834b 上,该 head 的全部 12 条 workflow run 全部 success(0 failure):

  • 主 CI run:typecheck+build+kernel/pi 套件(static-gates)四平台全绿、test 四腿全绿——包括之前红的 windows-latest node 22/24(closeQuietly 修复生效,teardown 不再 EPERM);unused-exports、config-surface-guard、lane-guard、docs-sync、version-guard、kernel-guard、pi-subagents-guard、lock-sync、test-import-graph 全部绿。
  • 其余 e2e 各腿(dsh/opencode/pi/codex/persona/fake-codex/local-registry/Windows codex overlay)+ PR Build Artifact 全绿。

两个审查拦截项都已修并验证:

  1. 78c063b1f —— 去掉 4 个 INTERNAL_ONLY 导出,过 unused-exports 门禁;
  2. cdd6e834b —— Surface a web warning (copyable diagnostics + GitHub prefilled issue link) when SQLite storage degrades to legacy-only — before the unified default flip #3040 web banner 测试在 teardown 里先 store.closeQuietly() 释放 SQLite 句柄再 rmrf,修掉 Windows-only 的目录删除 EPERM。

最终判定:可合(ready to merge)。 无回归——两处改动一处是纯导出收敛、一处只动新测试自身的清理逻辑,均未触碰 src/ 生产路径、wire、配置或既有行为。合并留给你(系统规则禁止 agent 合并):#3041

@ranxianglei
ranxianglei merged commit 25d2539 into master Oct 14, 2026
33 checks passed
@github-actions

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.398-master.25d2539 (rolling master tag).

npm install -g billion-context@0.0.398-master.25d2539  # this exact build
npm install -g billion-context@master  # always the newest merged build

npm view billion-context@master prints the current version at any time.

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

Labels

None yet

Projects

None yet

1 participant