From 8203d016e0c6a143a5ac83623b4a2e0a28b66892 Mon Sep 17 00:00:00 2001 From: ework-agent Date: Tue, 13 Oct 2026 20:55:55 +0800 Subject: [PATCH 1/5] feat: web warning + generic diagnostics reporting when SQLite degrades 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). --- src/cli.ts | 4 +- src/knobs.ts | 18 ++ src/persist.ts | 21 +-- src/server/admin.ts | 19 +- src/storage/engine-bootstrap.ts | 20 +- src/storage/runtime-status.ts | 233 +++++++++++++++++++++++ src/storage/shadow.ts | 14 +- src/web/client.ts | 35 ++++ src/web/diagnostics.ts | 111 +++++++++++ src/web/i18n.ts | 8 + src/web/page.ts | 1 + tests/web-storage-banner.test.ts | 310 +++++++++++++++++++++++++++++++ 12 files changed, 771 insertions(+), 23 deletions(-) create mode 100644 src/storage/runtime-status.ts create mode 100644 src/web/diagnostics.ts create mode 100644 tests/web-storage-banner.test.ts diff --git a/src/cli.ts b/src/cli.ts index 9969cf73b3..9b3ee461fe 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -25,6 +25,7 @@ import { loadOptions, ensureConfigTemplate } from "./config.js"; import { startServer, restartForceCloseOf } from "./server.js"; import { ensureSqliteEngine } from "./storage/engine-bootstrap.js"; +import { recordEngineBootstrap } from "./storage/runtime-status.js"; import { configFile as defaultConfigFile } from "./paths.js"; import { log as loggerLog } from "./logger.js"; import { createAutoRestartHandler } from "./restart.js"; @@ -597,9 +598,10 @@ export async function main(): Promise { // fetches when unified storage is requested AND no builtin/host engine // exists, so the common case costs nothing. Must complete before the first // session store opens (the store resolves its engine at construction). - await ensureSqliteEngine({ + const bootstrapOutcome = await ensureSqliteEngine({ resolveProxy: (url) => resolveProxy(opts.routes, opts.proxy, url, opts.proxyFallback), }); + recordEngineBootstrap(bootstrapOutcome); const server = await startServer(opts); // Start background auto-update after the server is listening so a slow diff --git a/src/knobs.ts b/src/knobs.ts index 187a474177..a16b096e7d 100644 --- a/src/knobs.ts +++ b/src/knobs.ts @@ -477,6 +477,24 @@ export function fakeBufCapBytes(): number { return Number.isFinite(v) && v > 0 ? v : 16 * 1024 * 1024; } +/** Config-file tiers of the storage knobs (#3040): single readers so the + * runtime-status surface and the store constructor report exactly what the + * file says (moved out of persist.ts, which used to be the only home). */ +export function fileStorageUnified(): string | undefined { + const v = loadConfigFile().storage?.unified; + return typeof v === "string" ? v : undefined; +} + +export function fileStorageJsonWriter(): string | undefined { + const v = loadConfigFile().storage?.jsonWriter; + return typeof v === "string" ? v : undefined; +} + +export function fileStorageAutoDownload(): boolean | undefined { + const v = loadConfigFile().storage?.sqliteAutoDownload; + return typeof v === "boolean" ? v : undefined; +} + /** Tiered storage-migration switch (#2671): legacy | shadow | full. Lives here * per the env-var discipline — env tier BILI_STORAGE_UNIFIED (1/true = shadow, * full/unified = full, 0/false/legacy/garbage = legacy) wins over the diff --git a/src/persist.ts b/src/persist.ts index 7916221456..42e3ac9e32 100644 --- a/src/persist.ts +++ b/src/persist.ts @@ -12,9 +12,11 @@ import { persistEpermAlertThreshold as knobPersistEpermAlertThreshold, persistEpermAlertRepeatMs as knobPersistEpermAlertRepeatMs, resolveJsonWriterOff as knobResolveJsonWriterOff, + fileStorageUnified, + fileStorageJsonWriter, } from "./knobs.js"; import { log as loggerLog } from "./logger.js"; -import { loadConfigFile } from "./config.js"; +import { recordRequestedMode } from "./storage/runtime-status.js"; import { VERSION } from "./version.js"; import { createStorageCodec, parseEncryptionKey } from "./encrypt.js"; import { PersistEpermAlert } from "./persist-eperm.js"; @@ -367,6 +369,7 @@ export class SessionStore { baseLog("warn", "[storage] unified sidecar DISABLED: BILI_ENCRYPTION_KEY is active and index.db would hold cleartext ingest payloads — staying legacy-only"); } this.storageMode = storageMode; + recordRequestedMode(storageMode, unifiedBlockedByEncryption); // Phase 3 (#2960): stop writing the legacy JSON envelope while the // unified store runs in effective-full mode. Ignored (warned once) // under shadow/legacy/encryption — there the JSON file is the sole @@ -1630,22 +1633,6 @@ function viewToRecord(view: LegacySessionLike): PersistedSession { return record; } -/** File-config `storage.unified` value for this lane, when present and - * string-shaped (#2671). The config reader caches on file content, so this - * is a page-cache-hot read at store construction; mode itself is - * boot-decided and does not follow hot reloads. */ -function fileStorageUnified(): string | undefined { - const section = (loadConfigFile() as { storage?: { unified?: unknown; jsonWriter?: unknown } }).storage; - return typeof section?.unified === "string" ? section.unified : undefined; -} - -/** Config-file tier for the Phase 3 JSON-envelope switch (#2960): - * storage.jsonWriter = "on" | "off" (env tier wins; see knobs.ts). */ -function fileStorageJsonWriter(): string | undefined { - const section = (loadConfigFile() as { storage?: { jsonWriter?: unknown } }).storage; - return typeof section?.jsonWriter === "string" ? section.jsonWriter : undefined; -} - /** resolveStorageMode guarded for the constructor: env parsing cannot throw * (resolveStorageMode is total), so this only exists to keep the call site * honest about the default when the knob is absent. */ diff --git a/src/server/admin.ts b/src/server/admin.ts index 9f51be005c..cb9cd77d18 100644 --- a/src/server/admin.ts +++ b/src/server/admin.ts @@ -30,6 +30,8 @@ import { detectStaleInstall } from "../update.js"; import { PACKAGE_NAME, VERSION, BUILD_COMMIT } from "../version.js"; import { buildOverview, buildSessionDetail, buildSessionList, buildSessionPage, handleConfigGet, handleConfigPut, hiddenEmptyCount, renderUI } from "../web/index.js"; import { queryLogLines } from "../web/logs-query.js"; +import { buildDiagnostics } from "../web/diagnostics.js"; +import { storageStatusWire } from "../storage/runtime-status.js"; interface AdminCtx { opts: ProxyOptions; @@ -155,6 +157,7 @@ export async function handleAdminRoute(req: http.IncomingMessage, res: http.Serv if (req.method === "GET" && req.url === "/__bili/overview") return sendOverview(res, opts); if (req.method === "GET" && (req.url === "/__bili/sessions" || req.url?.startsWith("/__bili/sessions?"))) return sendWebSessions(res, req); if (req.method === "GET" && req.url?.startsWith("/__bili/logs")) return sendWebLogs(res, req); + if (req.method === "GET" && req.url?.startsWith("/__bili/diagnostics")) return sendDiagnostics(res, req.url); if (req.method === "GET" && req.url?.startsWith("/__bili/sessions/") && req.url.endsWith("/detail")) return sendWebSessionDetail(res, req.url); if (req.method === "GET" && req.url === "/") { // Browser visits root → redirect to the web UI. curl / health probes @@ -783,7 +786,7 @@ async function sendStatus(res: http.ServerResponse, opts: ProxyOptions): Promise loggerLog("warn", `split-session canary (#2170): conversation ${w.base} has live traffic under multiple session keys (design persona forks are excluded): ${w.sessions.map((s) => `${s.id} (requests=${s.requests})`).join("; ")}. For a non-persona host this is the #2165 failure shape (stolen anchor / never-compressing split) — investigate if unexpected.`); } } - res.end(JSON.stringify({ version: VERSION, commit: BUILD_COMMIT, diskVersion, stale, updateReady: updateReadyPayload(), autoRestartOnUpdate: opts.autoRestartOnUpdate, advisory: currentAdvisoryPayload(), pluginAdvisories: detectCostAdvisories(process.env), inFlight: totalInFlight(), splitSessions: splitWarnings, conflicts: summarizeConflicts(listSessions()) }, null, 2)); + res.end(JSON.stringify({ version: VERSION, commit: BUILD_COMMIT, diskVersion, stale, updateReady: updateReadyPayload(), autoRestartOnUpdate: opts.autoRestartOnUpdate, advisory: currentAdvisoryPayload(), pluginAdvisories: detectCostAdvisories(process.env), inFlight: totalInFlight(), splitSessions: splitWarnings, conflicts: summarizeConflicts(listSessions()), storage: storageStatusWire() }, null, 2)); } // #2090 plan A — read-only view backing the web UI's "Signed upstreams" card: @@ -841,9 +844,23 @@ async function sendOverview(res: http.ServerResponse, opts: ProxyOptions): Promi conflicts: summarizeConflicts(listSessions()), passthrough: { enabled: !!opts.passthrough, source: opts.passthroughSource }, alerts: getUpstreamAlerts(), + storage: storageStatusWire(), }, null, 2)); } +/** #3040: generic diagnostics report — copyable blob + prefilled GitHub issue + * link. Loopback-gated like every other /__bili/* route; never throws. */ +function sendDiagnostics(res: http.ServerResponse, url: string | null): void { + let topic: string | undefined; + try { + topic = new URL(url ?? "/__bili/diagnostics", "http://localhost").searchParams.get("topic") ?? undefined; + } catch { + topic = undefined; + } + res.writeHead(200, { "content-type": "application/json" }); + res.end(JSON.stringify(buildDiagnostics(topic), null, 2)); +} + /** #1937: optional ?q= / ?page= / ?pageSize= (≤200) switch the endpoint to * server-side filtered paging. Without params the response shape is unchanged * ({sessions, hiddenEmpty} + additive total) so older UIs keep working. */ diff --git a/src/storage/engine-bootstrap.ts b/src/storage/engine-bootstrap.ts index 767b4e1e89..865b77aa67 100644 --- a/src/storage/engine-bootstrap.ts +++ b/src/storage/engine-bootstrap.ts @@ -26,7 +26,7 @@ */ import { createHash, randomBytes } from "node:crypto"; -import { existsSync } from "node:fs"; +import { existsSync, readFileSync } from "node:fs"; import { promises as fsp } from "node:fs"; import { createRequire } from "node:module"; import path from "node:path"; @@ -59,7 +59,7 @@ const SUPPORTED_TARGETS = [ ]; const BOOTSTRAP_TIMEOUT_MS = 10_000; -const COOLDOWN_MS = 6 * 60 * 60 * 1000; +export const COOLDOWN_MS = 6 * 60 * 60 * 1000; type BootstrapStatus = | "not-needed" @@ -128,11 +128,25 @@ function cooldownFile(): string { return path.join(cacheRoot(), ".bootstrap-failed.json"); } -interface CooldownMarker { +export interface CooldownMarker { atMs: number; reason: string; } +/** Sync read of the failure marker for status surfaces (#3040): same file and + * shape validation as readCooldown, but synchronous so the web endpoints can + * report remaining cooldown without awaiting. */ +export function readBootstrapFailureMarker(): CooldownMarker | null { + try { + const raw = readFileSync(cooldownFile(), "utf8"); + const j = JSON.parse(raw) as Partial; + if (typeof j.atMs === "number" && typeof j.reason === "string") return { atMs: j.atMs, reason: j.reason }; + return null; + } catch { + return null; // corrupt/absent marker: fail open toward retrying + } +} + async function readCooldown(): Promise { try { const raw = await fsp.readFile(cooldownFile(), "utf8"); diff --git a/src/storage/runtime-status.ts b/src/storage/runtime-status.ts new file mode 100644 index 0000000000..7b1c28a9a9 --- /dev/null +++ b/src/storage/runtime-status.ts @@ -0,0 +1,233 @@ +/** + * Runtime storage status registry (#3040). + * + * The unified-store degradation paths (engine ladder exhausted, self-download + * blocked/corrupt-platform, corrupt index.db guard #2771, 3-strike sidecar + * disable) are all fail-open by contract (#2825): the proxy keeps running on + * legacy JSON. That is correct — but until now the condition was only visible + * as one-time log lines. This module records the runtime facts from their + * single production seams and derives one structured status that feeds BOTH + * web surfaces (the #2152 parity discipline: /__bili/status and + * /__bili/overview share one helper) plus the diagnostics blob builder. + * + * Recording seams (each fires exactly once per process in production): + * - cli.ts: recordEngineBootstrap(ensureSqliteEngine outcome) + * - shadow.ts: recordSidecarOpenFailure / recordSidecarInstance + * (inside UnifiedShadow.maybeOpen) + * - persist.ts: recordRequestedMode(mode, encryptionBlocked) — the + * SessionStore constructor is the single mode-resolution + * seam, so it also owns the requested-mode record. + * + * The BILI_ENCRYPTION_KEY opt-out is INTENTIONAL legacy-only (index.db would + * hold cleartext payloads); it is reported as intentionalOptOut and must NOT + * raise the degraded warning. + */ + +import type { BootstrapOutcome, CooldownMarker } from "./engine-bootstrap.js"; +import { COOLDOWN_MS, readBootstrapFailureMarker } from "./engine-bootstrap.js"; +import { fileStorageAutoDownload, fileStorageJsonWriter, fileStorageUnified, resolveStorageMode } from "../knobs.js"; +import { MAX_CONSECUTIVE_FAILURES, type UnifiedShadow } from "./shadow.js"; +import type { StorageMode } from "./shadow.js"; + +interface RuntimeState { + /** Recorded by the SessionStore constructor; null only before first store build. */ + requested: StorageMode | null; + encryptionBlocked: boolean; + sidecar: UnifiedShadow | null; + sidecarOpenError: string | null; + bootstrap: BootstrapOutcome | null; +} + +function freshState(): RuntimeState { + return { requested: null, encryptionBlocked: false, sidecar: null, sidecarOpenError: null, bootstrap: null }; +} + +let state: RuntimeState = freshState(); + +export function recordEngineBootstrap(outcome: BootstrapOutcome): void { + state.bootstrap = outcome; +} + +export function recordSidecarOpenFailure(error: string): void { + state.sidecar = null; + state.sidecarOpenError = error; +} + +export function recordSidecarInstance(shadow: UnifiedShadow): void { + state.sidecar = shadow; + state.sidecarOpenError = null; +} + +export function recordRequestedMode(mode: StorageMode, encryptionBlocked: boolean): void { + state.requested = mode; + state.encryptionBlocked = encryptionBlocked; +} + +export function _resetStorageRuntimeStatusForTest(): void { + state = freshState(); + cooldownCache = null; +} + +/** Short one-line form of a raw error for interpolation into banner text. */ +function shortenError(err: string): string { + const oneLine = err.replace(/\s+/g, " ").trim(); + return oneLine.length > 160 ? `${oneLine.slice(0, 157)}...` : oneLine; +} + +function degradeReason(): string { + const sidecar = state.sidecar; + if (sidecar && sidecar.stats.disabled) { + const last = sidecar.stats.lastError ? shortenError(sidecar.stats.lastError) : "unknown"; + return `unified store auto-disabled after ${MAX_CONSECUTIVE_FAILURES} consecutive failures (last: ${last})`; + } + if (state.sidecarOpenError) { + const e = shortenError(state.sidecarOpenError); + // The driver's no-engine error surfaces through the same open path — + // say what it actually is instead of "index database failed to open". + if (/no SQLite engine available/i.test(e)) { + return "no SQLite engine available (node:sqlite missing, better-sqlite3 not installed)"; + } + return `index database failed to open (${e})`; + } + const b = state.bootstrap; + if (b) { + switch (b.status) { + case "cooldown": + return `SQLite self-download blocked (${b.detail ?? "unknown"}), retrying after cooldown`; + case "unsupported-platform": + return `unsupported platform for SQLite self-download (${b.detail ?? "?"})`; + case "disabled": + return "SQLite self-download disabled by configuration"; + case "failed": + return `SQLite self-download failed (${b.detail ?? "unknown"})`; + default: + break; + } + } + return "no SQLite engine available (node:sqlite missing, better-sqlite3 not installed)"; +} + +const COOLDOWN_CACHE_MS = 30_000; +let cooldownCache: { at: number; marker: CooldownMarker | null } | null = null; + +function cooldownState(): { marker: CooldownMarker | null; remainingMs: number | null } { + const now = Date.now(); + if (cooldownCache && now - cooldownCache.at < COOLDOWN_CACHE_MS) { + return { marker: cooldownCache.marker, remainingMs: cooldownCache.marker ? Math.max(0, cooldownCache.marker.atMs + COOLDOWN_MS - now) : null }; + } + const marker = readBootstrapFailureMarker(); + cooldownCache = { at: now, marker }; + return { marker, remainingMs: marker ? Math.max(0, marker.atMs + COOLDOWN_MS - now) : null }; +} + +export interface StorageRuntimeStatus { + requested: StorageMode; + effective: "legacy" | "shadow" | "full"; + /** Requested a unified mode but the sidecar is not carrying data. */ + degraded: boolean; + /** BILI_ENCRYPTION_KEY opt-out — intentional legacy-only, never warns. */ + intentionalOptOut: boolean; + /** Human-readable degrade cause (set iff degraded). */ + reason: string | null; + engine: { name: string; source: string } | null; + bootstrap: string | null; + bootstrapFailure: { atMs: number; reason: string } | null; + cooldownRemainingMs: number | null; + sidecarDisabled: boolean; + sidecarLastError: string | null; + indexDbOpenError: string | null; +} + +export function getStorageRuntimeStatus(): StorageRuntimeStatus { + // Fallback before the first SessionStore build: full knob resolution + // (a running server always has a store, so this path is defensive). + const requested = state.requested ?? resolveStorageMode(process.env, fileStorageUnified()); + const intentionalOptOut = state.encryptionBlocked; + const sidecar = state.sidecar; + const disabled = !!sidecar?.stats.disabled; + // healthy sidecar ⇒ its mode === requested (maybeOpen opens only under + // shadow/full); anything else means SQLite carries no data right now. + const effective: "legacy" | "shadow" | "full" = + requested !== "legacy" && !intentionalOptOut && sidecar && !disabled ? requested : "legacy"; + const degraded = requested !== "legacy" && !intentionalOptOut && (sidecar === null || disabled); + const cd = cooldownState(); + return { + requested, + effective, + degraded, + intentionalOptOut, + reason: degraded ? degradeReason() : null, + engine: sidecar ? { name: sidecar.engine, source: sidecar.engineSource } : null, + bootstrap: state.bootstrap?.status ?? null, + bootstrapFailure: cd.marker, + cooldownRemainingMs: cd.remainingMs, + sidecarDisabled: disabled, + sidecarLastError: sidecar?.stats.disabled ? sidecar.stats.lastError : null, + indexDbOpenError: state.sidecarOpenError, + }; +} + +/** Wire payload shared by /__bili/status and /__bili/overview (#2152 parity: + * one helper, two surfaces — they can never drift apart again). */ +export interface StorageStatusWire { + requested: StorageMode; + effective: "legacy" | "shadow" | "full"; + degraded: boolean; + intentionalOptOut: boolean; + reason: string | null; + engine: { name: string; source: string } | null; + bootstrap: string | null; + bootstrapFailure: { atMs: number; reason: string } | null; + cooldownRemainingMs: number | null; + sidecarDisabled: boolean; +} + +export function storageStatusWire(): StorageStatusWire { + const st = getStorageRuntimeStatus(); + return { + requested: st.requested, + effective: st.effective, + degraded: st.degraded, + intentionalOptOut: st.intentionalOptOut, + reason: st.reason, + engine: st.engine, + bootstrap: st.bootstrap, + bootstrapFailure: st.bootstrapFailure, + cooldownRemainingMs: st.cooldownRemainingMs, + sidecarDisabled: st.sidecarDisabled, + }; +} + +/** Extra diagnostics-blob lines for the `storage-legacy-only` topic (#3040): + * the resolved knob stack (env + file tiers verbatim), ladder outcome, + * failure payload, and the recent [storage] log tail supplied by the caller + * (kept out of this module so it stays free of logger/session imports). */ +export function storageDiagnosticsLines(ctx: { sessions: number; storageLogLines: string[] }): string[] { + const st = getStorageRuntimeStatus(); + const env = process.env; + const fileUnified = fileStorageUnified(); + const fileJsonWriter = fileStorageJsonWriter(); + const fileAutoDownload = fileStorageAutoDownload(); + const lines: string[] = [ + "--- storage ---", + `requested mode: ${st.requested}`, + `effective mode: ${st.effective}${st.intentionalOptOut ? " (BILI_ENCRYPTION_KEY opt-out — intentional)" : ""}`, + ...(st.degraded && st.reason ? [`degrade reason: ${st.reason}`] : []), + `engine: ${st.engine ? `${st.engine.name}/${st.engine.source}` : "none"}`, + `engine bootstrap: ${st.bootstrap ?? "not run"}`, + ...(st.bootstrapFailure ? [`bootstrap failure marker: at=${new Date(st.bootstrapFailure.atMs).toISOString()} reason="${st.bootstrapFailure.reason}"${st.cooldownRemainingMs ? ` (cooldown ~${Math.round(st.cooldownRemainingMs / 60_000)}m remaining)` : ""}`] : []), + `BILI_STORAGE_UNIFIED: ${env.BILI_STORAGE_UNIFIED ?? "(unset)"}`, + `storage.unified (config file): ${fileUnified ?? "(unset)"}`, + `BILI_STORAGE_JSON_WRITER: ${env.BILI_STORAGE_JSON_WRITER ?? "(unset)"}`, + `storage.jsonWriter (config file): ${fileJsonWriter ?? "(unset)"}`, + `BILI_SQLITE_AUTO_DOWNLOAD: ${env.BILI_SQLITE_AUTO_DOWNLOAD ?? "(unset)"}`, + `storage.sqliteAutoDownload (config file): ${fileAutoDownload ?? "(unset)"}`, + `BILI_ENCRYPTION_KEY set: ${env.BILI_ENCRYPTION_KEY !== undefined && env.BILI_ENCRYPTION_KEY !== "" ? "yes" : "no"}`, + `sessions on disk: ${ctx.sessions}`, + ]; + if (ctx.storageLogLines.length > 0) { + lines.push("last [storage] log lines:"); + lines.push(...ctx.storageLogLines.map((l) => ` ${l}`)); + } + return lines; +} diff --git a/src/storage/shadow.ts b/src/storage/shadow.ts index d03df578c6..3ad59d854b 100644 --- a/src/storage/shadow.ts +++ b/src/storage/shadow.ts @@ -26,9 +26,11 @@ import { planIngest, loadLegacyView, completeBlockContents, type LegacySessionLi import { resolveStorageMode, type StorageMode } from "../knobs.ts"; import { UnifiedStore, type CheckpointRow, type SessionSummaryRow, type WebSummaryRow } from "./store.ts"; import { canonicalize, sha256 } from "./canonical.ts"; +import { recordSidecarInstance, recordSidecarOpenFailure } from "./runtime-status.ts"; +import type { SqliteEngineName, SqliteEngineSource } from "./driver.ts"; import type { CoreMessage, MessageContentStore } from "acp-kernel"; -const MAX_CONSECUTIVE_FAILURES = 3; +export const MAX_CONSECUTIVE_FAILURES = 3; // Canonical home for StorageMode/resolveStorageMode is src/knobs.ts (env-var // discipline, #2030); re-exported here for the storage-layer importers. @@ -77,9 +79,11 @@ export class UnifiedShadow { "warn", `[storage] unified sidecar failed to open ${dir}/index.db (${String(err)}) — staying legacy-only; delete the file to reset the index`, ); + recordSidecarOpenFailure(String(err)); return null; } const shadow = new UnifiedShadow(mode, store, legacyLoad ?? (() => null)); + recordSidecarInstance(shadow); const engineTag = ` [engine: ${store.engine}/${store.engineSource}]`; loggerLog( "info", @@ -95,6 +99,14 @@ export class UnifiedShadow { return this.mode === "full" && !this.stats.disabled; } + get engine(): SqliteEngineName { + return this.store.engine; + } + + get engineSource(): SqliteEngineSource { + return this.store.engineSource; + } + /** Ingest + verify one committed record. Never throws. * * `rawTail` (#2960 ⑤): the live in-memory conversation tail when the diff --git a/src/web/client.ts b/src/web/client.ts index 334f505011..ca0b56ec53 100644 --- a/src/web/client.ts +++ b/src/web/client.ts @@ -537,6 +537,24 @@ export const WEB_CLIENT = `(function () { stale.classList.remove("show"); stale.innerHTML = ""; } + const sb = $("storage-degraded-banner"); + if (sb) { + const sg = d.storage; + if (sg && sg.degraded) { + sb.hidden = false; + sb.classList.add("show"); + sb.innerHTML = "" + t("sys.storage_degraded_title") + " " + escapeHtml(t("sys.storage_degraded", { reason: sg.reason || "" })) + + '
' + + '" + + '' + t("sys.report_issue") + "" + + "
"; + attachReportButtons("storage-legacy-only", sb); + } else { + sb.hidden = true; + sb.classList.remove("show"); + sb.innerHTML = ""; + } + } const pt = $("passthrough-banner"); if (d.passthrough && d.passthrough.enabled) { pt.hidden = false; @@ -1545,6 +1563,23 @@ export const WEB_CLIENT = `(function () { if (navigator.clipboard && navigator.clipboard.writeText) navigator.clipboard.writeText(text).then(done).catch(fallback); else fallback(); } + // #3040: generic report wiring shared by every warning banner — fetches the + // topic's diagnostics report once and binds #report-copy-btn (clipboard) + + // #report-issue-link (prefilled GitHub issue) inside the given container. + async function attachReportButtons(topic, host) { + const copyBtn = host.querySelector("#report-copy-btn"); + const issueLink = host.querySelector("#report-issue-link"); + busy(copyBtn, true); + try { + const d = await json("/__bili/diagnostics?topic=" + encodeURIComponent(topic)); + if (copyBtn) copyBtn.addEventListener("click", () => copyText(d.blob, copyBtn)); + if (issueLink && typeof d.url === "string") issueLink.href = d.url; + } catch (e) { + toast(friendlyMsg(e), "err"); + } finally { + busy(copyBtn, false); + } + } function refRangeOf(b) { return b.startRef ? (b.endRef && b.endRef !== b.startRef ? b.startRef + "–" + b.endRef : b.startRef) : null; } diff --git a/src/web/diagnostics.ts b/src/web/diagnostics.ts new file mode 100644 index 0000000000..72a5b7c5e0 --- /dev/null +++ b/src/web/diagnostics.ts @@ -0,0 +1,111 @@ +/** + * Generic diagnostics report builder (#3040). + * + * One reusable facility behind every web warning: assemble a ready-to-paste + * diagnostic blob (environment facts + one topic-specific section) plus a + * prefilled GitHub issue link, so any future warning can offer "copy + * diagnostics / report on GitHub" without inventing its own plumbing. The + * first consumer is the SQLite legacy-only degradation banner + * (topic `storage-legacy-only`). + * + * Contract: NEVER throws — every fs/listSessions access is guarded so a + * broken log file or an unbuilt store degrades the blob, not the endpoint. + */ + +import { readFileSync, statSync } from "node:fs"; +import os from "node:os"; +import * as path from "node:path"; +import { getLogPath } from "../logger.js"; +import { defaultLogFile } from "../paths.js"; +import { listSessions } from "../session.js"; +import { storageDiagnosticsLines } from "../storage/runtime-status.js"; +import { BUILD_COMMIT, PACKAGE_NAME, VERSION } from "../version.js"; + +const GITHUB_NEW_ISSUE_URL = "https://github.com/ranxianglei/billion-context/issues/new"; +const STORAGE_LOG_TAIL_LINES = 12; + +function humanUptime(seconds: number): string { + const h = Math.floor(seconds / 3600); + const m = Math.floor((seconds % 3600) / 60); + const s = Math.floor(seconds % 60); + if (h > 0) return `${h}h ${m}m`; + if (m > 0) return `${m}m ${s}s`; + return `${s}s`; +} + +function baseLines(): string[] { + return [ + `=== ${PACKAGE_NAME} diagnostics ===`, + `generated: ${new Date().toISOString()}`, + `bili version: ${VERSION} (commit ${BUILD_COMMIT})`, + `node: ${process.version}`, + `platform: ${process.platform} ${process.arch}`, + `os: ${os.type()} ${os.release()}`, + `uptime: ${humanUptime(process.uptime())}`, + ]; +} + +/** Last N `[storage]` lines across the rotated pair (same candidate recipe as + * sendWebLogs); empty on any fs failure. */ +function storageLogTail(): string[] { + try { + const logFile = getLogPath() ?? defaultLogFile(); + const dir = logFile ? path.dirname(logFile) + path.sep : ""; + const candidates = [dir + "bili.log.old", dir + "bili.log"]; + let lines: string[] = []; + for (const f of candidates) { + try { if (!statSync(f).isFile()) continue; } catch { continue; } + try { + lines = lines.concat(readFileSync(f, "utf8").split("\n").filter((l) => l.length > 0 && l.includes("[storage]"))); + } catch { continue; } + } + return lines.slice(-STORAGE_LOG_TAIL_LINES); + } catch { + return []; + } +} + +function safeSessionCount(): number { + try { return listSessions().length; } catch { return -1; } +} + +interface TopicContext { + sessions: number; + storageLogLines: string[]; +} + +interface TopicDef { + title: () => string; + section: (ctx: TopicContext) => string[]; +} + +const TOPICS: Record = { + "storage-legacy-only": { + title: () => `SQLite unified storage degraded to legacy-only (bili v${VERSION}, node ${process.version}, ${process.platform}-${process.arch})`, + section: (ctx) => storageDiagnosticsLines(ctx), + }, +}; + +export interface DiagnosticsReport { + blob: string; + title: string; + url: string; +} + +export function buildDiagnostics(topic?: string): DiagnosticsReport { + const t = topic?.trim().slice(0, 64) ?? ""; + const def = t ? TOPICS[t] : undefined; + const ctx: TopicContext = { + sessions: safeSessionCount(), + storageLogLines: def ? storageLogTail() : [], + }; + const lines = baseLines(); + if (t && !def) lines.push(`topic: ${t} (no topic-specific section registered)`); + if (def) lines.push(...def.section(ctx)); + const blob = lines.join("\n"); + const title = def + ? def.title() + : `bili diagnostics report (v${VERSION}, node ${process.version}, ${process.platform}-${process.arch})`; + const url = `${GITHUB_NEW_ISSUE_URL}?title=${encodeURIComponent(title)}&body=${encodeURIComponent(blob)}`; + return { blob, title, url }; +} diff --git a/src/web/i18n.ts b/src/web/i18n.ts index 143fc63137..61e5614703 100644 --- a/src/web/i18n.ts +++ b/src/web/i18n.ts @@ -109,6 +109,10 @@ export const MESSAGES: Record> = { "sys.pt_on": "Passthrough 已开启:所有请求原样转发,压缩关闭。来源:", "sys.pt_env": "ACP_PASSTHROUGH 环境变量(或 --passthrough 参数)", "sys.pt_file": "配置文件 passthrough: true", + "sys.storage_degraded_title": "SQLite 存储降级:", + "sys.storage_degraded": "未来几个版本将默认开启 SQLite 统一存储,但你的系统因 {reason} 暂不支持(已自动回退 JSON 存储,当前不受影响)。请点击下方按钮反馈,帮助我们在默认开启前覆盖你的环境。", + "sys.report_copy": "复制诊断信息", + "sys.report_issue": "在 GitHub 反馈", "conflict.on": "检测到压缩冲突", // #2102: the sentence is composed per kind family present — a ledger full of // client-native rewrites must not read as "third-party plugin" evidence. @@ -570,6 +574,10 @@ export const MESSAGES: Record> = { "sys.pt_on": "Passthrough ON: all requests forwarded as-is, compression disabled. Source:", "sys.pt_env": "ACP_PASSTHROUGH env var (or --passthrough flag)", "sys.pt_file": "config file passthrough: true", + "sys.storage_degraded_title": "SQLite storage degraded:", + "sys.storage_degraded": "Unified SQLite storage becomes the default in an upcoming release, but this system cannot run it ({reason}). You have been automatically rolled back to JSON storage — nothing is affected today. Please report this so your environment is covered before the flip.", + "sys.report_copy": "Copy diagnostics", + "sys.report_issue": "Report on GitHub", "conflict.on": "Compression conflict detected", // #2102: composed per kind family present — see the zh entry above. "conflict.found": ": traces of ", diff --git a/src/web/page.ts b/src/web/page.ts index 807ae78331..aa75a8dbb7 100644 --- a/src/web/page.ts +++ b/src/web/page.ts @@ -23,6 +23,7 @@ export function renderPage(origin: string, version: string, embed = false, theme + diff --git a/tests/web-storage-banner.test.ts b/tests/web-storage-banner.test.ts new file mode 100644 index 0000000000..8963822997 --- /dev/null +++ b/tests/web-storage-banner.test.ts @@ -0,0 +1,310 @@ +// #3040 web surface: SQLite unified storage degrades to legacy-only through +// several fail-open paths (#2825 contract): engine ladder exhausted, +// self-download blocked in cooldown, corrupt index.db guard (#2771), 3-strike +// sidecar disable. The proxy keeps running on JSON — correct — but until now +// the condition was only visible as one-time log lines, so environments that +// cannot run SQLite were never learned about before the upcoming full-mode +// default flip. These tests pin the wire contract the web banner reads: +// 1. PARITY (#2152 lesson): /__bili/status and /__bili/overview share one +// storageStatusWire() payload — byte-identical on both surfaces. +// 2. degraded=true iff a unified mode was requested AND not intentionally +// opted out (BILI_ENCRYPTION_KEY) AND the sidecar carries no data; +// explicit legacy or a healthy sidecar → false (banner stays hidden). +// 3. the generic diagnostics endpoint (/__bili/diagnostics?topic=…) serves +// a copyable blob + a prefilled GitHub issues/new URL whose body decodes +// back to the exact blob — the reusable "copy error → file issue" +// facility ("以后错误都这样"); unknown topics fall back to the base blob. +// 4. the page ships the banner element and the client references it plus +// the localized copy keys and the diagnostics endpoint. +import test from "node:test"; +import assert from "node:assert/strict"; +import http from "node:http"; +import { once } from "node:events"; +import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import path from "node:path"; +import { defaultConfig } from "acp-kernel"; +import { startServer } from "../src/server.ts"; +import type { ProxyOptions } from "../src/config.ts"; +import { SessionStore, _setStoreForTest } from "../src/persist.ts"; +import { probeBuiltinSqlite, probeHostBetterSqlite3, setPreferredSqliteEngineForTests, setSqliteEnginesUnavailableForTests } from "../src/storage/driver.ts"; +import { _resetStorageRuntimeStatusForTest, recordEngineBootstrap } from "../src/storage/runtime-status.ts"; +import { renderPage } from "../src/web/page.ts"; +import { WEB_CLIENT } from "../src/web/client.ts"; +import { VERSION } from "../src/version.ts"; +import { rmrf } from "./tmp-rm.ts"; + +process.env.BILI_PERSIST_ZSTD = "0"; + +const ENV_KEYS = ["BILI_SESSIONS_DIR", "BILI_CONFIG_FILE", "XDG_CACHE_HOME", "XDG_STATE_HOME", "BILI_STORAGE_UNIFIED", "BILI_ENCRYPTION_KEY"] as const; +type EnvSnap = Partial>; + +function saveEnv(): EnvSnap { + const snap: EnvSnap = {}; + for (const k of ENV_KEYS) snap[k] = process.env[k]; + return snap; +} + +function restoreEnv(snap: EnvSnap): void { + for (const k of ENV_KEYS) { + if (snap[k] === undefined) delete process.env[k]; + else process.env[k] = snap[k]; + } +} + +/** Point every bili path at the temp base: sessions dir (existing), an ABSENT + * config file (no file-tier knob values), cache + state roots (bootstrap + * failure marker, log tail) — nothing outside this test can leak into the + * status or the diagnostics blob. */ +function isolate(base: string): void { + mkdirSync(path.join(base, "sessions"), { recursive: true }); + process.env.BILI_SESSIONS_DIR = path.join(base, "sessions"); + process.env.BILI_CONFIG_FILE = path.join(base, "absent-config.json"); + process.env.XDG_CACHE_HOME = path.join(base, "cache"); + process.env.XDG_STATE_HOME = path.join(base, "state"); +} + +function resetSeams(): void { + setSqliteEnginesUnavailableForTests(false); + setPreferredSqliteEngineForTests(null); + _resetStorageRuntimeStatusForTest(); +} + +function close(server: http.Server): Promise { + return new Promise((resolve, reject) => server.close((error) => (error ? reject(error) : resolve()))); +} + +async function freePort(): Promise { + const server = http.createServer(); + server.listen(0, "127.0.0.1"); + await once(server, "listening"); + const port = (server.address() as { port: number }).port; + await close(server); + return port; +} + +interface StorageWire { + requested: string; + effective: string; + degraded: boolean; + intentionalOptOut: boolean; + reason: string | null; + engine: { name: string; source: string } | null; + bootstrap: string | null; + bootstrapFailure: unknown; + cooldownRemainingMs: number | null; + sidecarDisabled: boolean; +} + +interface DiagnosticsWire { + blob: string; + title: string; + url: string; +} + +async function fetchJson(port: number, p: string): Promise { + const res = await fetch(`http://127.0.0.1:${port}${p}`); + assert.equal(res.status, 200, `${p} answers 200`); + return (await res.json()) as T; +} + +function makeOpts(upstreamPort: number): ProxyOptions { + return { + port: 0, + host: "127.0.0.1", + upstream: `http://127.0.0.1:${upstreamPort}`, + routes: {}, + modelContextLimit: 400_000, + kernelConfig: defaultConfig(400_000), + compress: { injectTool: false, injectNudge: false }, + promptCache: { routing: "auto" }, + sessionHeader: "x-acp-session", + log: false, + debug: false, + passthrough: false, + autoUpdate: false, + compat: { roles: {} }, + streamErrorShape: "protocol", + passthroughSource: null, + autoRestartOnUpdate: false, + updateTag: "latest", + advisoryCheck: false, + releaseNotesCheck: false, + mitm: { enabled: false, domains: [] }, + }; +} + +test("#3040 forced none-engine: status+overview report degraded; diagnostics blob + prefilled issue link", async () => { + const snap = saveEnv(); + const base = mkdtempSync(path.join(tmpdir(), "bili-storage-banner-")); + try { + isolate(base); + resetSeams(); + delete process.env.BILI_STORAGE_UNIFIED; + delete process.env.BILI_ENCRYPTION_KEY; + setSqliteEnginesUnavailableForTests(true); + recordEngineBootstrap({ status: "failed", detail: "ECONNREFUSED registry.npmjs.org" }); + _setStoreForTest(new SessionStore({ dir: process.env.BILI_SESSIONS_DIR, enabled: true })); + const upstreamPort = await freePort(); + const proxy = await startServer(makeOpts(upstreamPort)); + await once(proxy, "listening"); + const port = (proxy.address() as { port: number }).port; + try { + const s = await fetchJson<{ storage: StorageWire }>(port, "/__bili/status"); + const o = await fetchJson<{ storage: StorageWire }>(port, "/__bili/overview"); + assert.equal(o.storage.requested, "shadow", "default requested mode is shadow"); + assert.equal(o.storage.effective, "legacy"); + assert.equal(o.storage.degraded, true); + assert.equal(o.storage.intentionalOptOut, false); + assert.ok(typeof o.storage.reason === "string" && o.storage.reason.length > 0, "degrade reason present"); + assert.match(o.storage.reason ?? "", /no SQLite engine available/); + assert.equal(o.storage.engine, null); + assert.equal(o.storage.sidecarDisabled, false); + assert.deepEqual(o.storage, s.storage, "status/overview storage parity (one shared helper)"); + + const d = await fetchJson(port, "/__bili/diagnostics?topic=storage-legacy-only"); + assert.ok(d.blob.includes(`bili version: ${VERSION}`), "blob carries the bili version"); + assert.ok(d.blob.includes(`node: ${process.version}`), "blob carries the node version"); + assert.ok(d.blob.includes(`platform: ${process.platform} ${process.arch}`), "blob carries platform/arch"); + assert.ok(d.blob.includes("os: "), "blob carries the OS line"); + assert.ok(d.blob.includes("requested mode: shadow")); + assert.ok(d.blob.includes("effective mode: legacy")); + assert.ok(d.blob.includes("degrade reason:"), "blob carries the degrade reason"); + assert.ok(d.blob.includes("engine bootstrap: failed"), "blob carries the ladder outcome"); + assert.ok(d.blob.includes("BILI_STORAGE_UNIFIED: (unset)"), "blob carries the raw knob values"); + assert.ok(d.blob.includes("sessions on disk:"), "blob carries the session count"); + assert.ok(d.title.startsWith("SQLite unified storage degraded to legacy-only"), "title names the condition"); + assert.ok(d.title.includes(`${process.platform}-${process.arch}`), "title carries the environment"); + assert.ok(d.url.startsWith("https://github.com/ranxianglei/billion-context/issues/new?title="), "url targets issues/new"); + const u = new URL(d.url); + assert.equal(u.searchParams.get("body"), d.blob, "issue body decodes back to the exact blob"); + assert.ok((u.searchParams.get("title") ?? "").includes(VERSION), "issue title encodes the same environment facts"); + + const d2 = await fetchJson(port, "/__bili/diagnostics?topic=some-future-topic"); + assert.ok(d2.blob.includes("some-future-topic (no topic-specific section registered)"), "unknown topics degrade to the base blob"); + assert.equal(new URL(d2.url).searchParams.get("body"), d2.blob, "generic facility encodes any topic's blob"); + + const html = renderPage(`http://127.0.0.1:${port}`, VERSION); + assert.ok(html.includes('id="storage-degraded-banner"'), "page carries the banner div"); + assert.ok(WEB_CLIENT.includes('"storage-degraded-banner"'), "client targets the banner element"); + assert.ok(WEB_CLIENT.includes('t("sys.storage_degraded_title")'), "client uses the localized title"); + assert.ok(WEB_CLIENT.includes('t("sys.storage_degraded"'), "client composes the localized sentence with {reason}"); + assert.ok(WEB_CLIENT.includes('t("sys.report_copy")'), "client offers the copy button"); + assert.ok(WEB_CLIENT.includes('t("sys.report_issue")'), "client offers the GitHub button"); + assert.ok(WEB_CLIENT.includes("/__bili/diagnostics?topic="), "buttons wire to the generic diagnostics endpoint"); + } finally { + await close(proxy); + } + } finally { + resetSeams(); + rmrf(base); + restoreEnv(snap); + } +}); + +test("#3040 healthy sidecar and explicit legacy: no degraded flag (banner stays hidden)", { skip: !(probeBuiltinSqlite() || probeHostBetterSqlite3()) && "no SQLite engine available on this host" }, async () => { + const snap = saveEnv(); + const base = mkdtempSync(path.join(tmpdir(), "bili-storage-banner-")); + try { + isolate(base); + resetSeams(); + delete process.env.BILI_STORAGE_UNIFIED; + delete process.env.BILI_ENCRYPTION_KEY; + _setStoreForTest(new SessionStore({ dir: process.env.BILI_SESSIONS_DIR, enabled: true })); + const upstreamPort = await freePort(); + const proxy = await startServer(makeOpts(upstreamPort)); + await once(proxy, "listening"); + const port = (proxy.address() as { port: number }).port; + try { + // healthy default shadow: sidecar opened, nothing to warn about + let o = await fetchJson<{ storage: StorageWire }>(port, "/__bili/overview"); + assert.equal(o.storage.requested, "shadow"); + assert.equal(o.storage.effective, "shadow"); + assert.equal(o.storage.degraded, false, "healthy shadow does not warn"); + assert.equal(o.storage.intentionalOptOut, false); + assert.equal(o.storage.reason, null); + assert.ok(o.storage.engine && o.storage.engine.name.length > 0 && o.storage.engine.source.length > 0, "engine reported when the sidecar is live"); + + // explicit opt-out to legacy: requested === effective by choice + resetSeams(); + process.env.BILI_STORAGE_UNIFIED = "0"; + const legacyDir = path.join(base, "sessions-legacy"); + mkdirSync(legacyDir, { recursive: true }); + _setStoreForTest(new SessionStore({ dir: legacyDir, enabled: false })); + o = await fetchJson<{ storage: StorageWire }>(port, "/__bili/overview"); + assert.equal(o.storage.requested, "legacy"); + assert.equal(o.storage.effective, "legacy"); + assert.equal(o.storage.degraded, false, "explicit legacy never warns"); + assert.equal(o.storage.engine, null); + } finally { + await close(proxy); + } + } finally { + resetSeams(); + rmrf(base); + restoreEnv(snap); + } +}); + +test("#3040 BILI_ENCRYPTION_KEY opt-out is intentional: reported, never warned", async () => { + const snap = saveEnv(); + const base = mkdtempSync(path.join(tmpdir(), "bili-storage-banner-")); + try { + isolate(base); + resetSeams(); + process.env.BILI_STORAGE_UNIFIED = "1"; + process.env.BILI_ENCRYPTION_KEY = "a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90"; + _setStoreForTest(new SessionStore({ dir: process.env.BILI_SESSIONS_DIR, enabled: true })); + const upstreamPort = await freePort(); + const proxy = await startServer(makeOpts(upstreamPort)); + await once(proxy, "listening"); + const port = (proxy.address() as { port: number }).port; + try { + const o = await fetchJson<{ storage: StorageWire }>(port, "/__bili/overview"); + assert.equal(o.storage.requested, "shadow"); + assert.equal(o.storage.effective, "legacy"); + assert.equal(o.storage.intentionalOptOut, true, "encryption block is reported as intentional"); + assert.equal(o.storage.degraded, false, "intentional opt-out must NOT raise the warning"); + assert.equal(o.storage.reason, null); + } finally { + await close(proxy); + } + } finally { + resetSeams(); + rmrf(base); + restoreEnv(snap); + } +}); + +test("#3040 corrupt index.db (guard #2771): degraded with the open-failure reason", { skip: !(probeBuiltinSqlite() || probeHostBetterSqlite3()) && "no SQLite engine available on this host" }, async () => { + const snap = saveEnv(); + const base = mkdtempSync(path.join(tmpdir(), "bili-storage-banner-")); + try { + isolate(base); + resetSeams(); + delete process.env.BILI_STORAGE_UNIFIED; + delete process.env.BILI_ENCRYPTION_KEY; + const dir = process.env.BILI_SESSIONS_DIR!; + writeFileSync(path.join(dir, "index.db"), Buffer.from("this is definitely not a sqlite database file".repeat(8))); + _setStoreForTest(new SessionStore({ dir, enabled: true })); + const upstreamPort = await freePort(); + const proxy = await startServer(makeOpts(upstreamPort)); + await once(proxy, "listening"); + const port = (proxy.address() as { port: number }).port; + try { + const o = await fetchJson<{ storage: StorageWire }>(port, "/__bili/overview"); + assert.equal(o.storage.requested, "shadow"); + assert.equal(o.storage.effective, "legacy"); + assert.equal(o.storage.degraded, true, "corrupt index.db trips the warning"); + assert.equal(o.storage.intentionalOptOut, false); + assert.match(o.storage.reason ?? "", /index database failed to open/); + assert.equal(o.storage.engine, null); + } finally { + await close(proxy); + } + } finally { + resetSeams(); + rmrf(base); + restoreEnv(snap); + } +}); From 52ff122d5a3711ff09d92fb639e42f0dc1cc98d2 Mon Sep 17 00:00:00 2001 From: ework-agent Date: Tue, 13 Oct 2026 21:00:41 +0800 Subject: [PATCH 2/5] refactor: drop duplicated file-tier knob readers in engine-bootstrap (follow-up to #3040) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- src/storage/engine-bootstrap.ts | 26 ++++---------------------- 1 file changed, 4 insertions(+), 22 deletions(-) diff --git a/src/storage/engine-bootstrap.ts b/src/storage/engine-bootstrap.ts index 865b77aa67..80afec8336 100644 --- a/src/storage/engine-bootstrap.ts +++ b/src/storage/engine-bootstrap.ts @@ -33,9 +33,9 @@ import path from "node:path"; import { gunzipSync } from "node:zlib"; import { log as loggerLog } from "../logger.js"; import { cacheDir } from "../paths.js"; -import { loadConfigFile } from "../config.js"; + import { probeBuiltinSqlite, probeHostBetterSqlite3, registerSelfDownloadedBetterSqlite3, type BetterSqlite3Ctor } from "./driver.js"; -import { resolveStorageMode, resolveSqliteAutoDownload, updateRegistryBase } from "../knobs.js"; +import { fileStorageAutoDownload, fileStorageUnified, resolveStorageMode, resolveSqliteAutoDownload, updateRegistryBase } from "../knobs.js"; import { normalizeRegistryBase } from "../update.js"; import { proxyDispatcher } from "../upstream-proxy.js"; @@ -179,24 +179,6 @@ function cacheUsable(dir: string, target: string): boolean { && existsSync(path.join(dir, "prebuilds", `${target}.node`)); } -function fileStorageUnifiedValue(): string | undefined { - try { - const section = (loadConfigFile() as { storage?: { unified?: unknown } }).storage; - return typeof section?.unified === "string" ? section.unified : undefined; - } catch { - return undefined; - } -} - -function fileSqliteAutoDownloadValue(): boolean | undefined { - try { - const v = (loadConfigFile() as { storage?: { sqliteAutoDownload?: unknown } }).storage?.sqliteAutoDownload; - return typeof v === "boolean" ? v : undefined; - } catch { - return undefined; - } -} - interface EnsureSqliteEngineOptions { /** Egress proxy resolver (same chain as updater/model traffic, #609). Absent = direct. */ resolveProxy?: (url: string) => string | undefined; @@ -213,7 +195,7 @@ export function ensureSqliteEngine(opts: EnsureSqliteEngineOptions = {}): Promis async function runBootstrap(opts: EnsureSqliteEngineOptions): Promise { const env = opts.env ?? process.env; - if (resolveStorageMode(env, fileStorageUnifiedValue()) === "legacy") { + if (resolveStorageMode(env, fileStorageUnified()) === "legacy") { return { status: "not-needed", detail: "unified storage disabled" }; } if (probeBuiltinSqlite()) { @@ -236,7 +218,7 @@ async function runBootstrap(opts: EnsureSqliteEngineOptions): Promise Date: Tue, 13 Oct 2026 21:01:47 +0800 Subject: [PATCH 3/5] test: pin HTML-escaping of the storage degrade reason in the banner (follow-up to #3040) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- tests/web-storage-banner.test.ts | 3 +++ 1 file changed, 3 insertions(+) diff --git a/tests/web-storage-banner.test.ts b/tests/web-storage-banner.test.ts index 8963822997..4649e7cc1b 100644 --- a/tests/web-storage-banner.test.ts +++ b/tests/web-storage-banner.test.ts @@ -192,6 +192,9 @@ test("#3040 forced none-engine: status+overview report degraded; diagnostics blo assert.ok(WEB_CLIENT.includes('t("sys.report_copy")'), "client offers the copy button"); assert.ok(WEB_CLIENT.includes('t("sys.report_issue")'), "client offers the GitHub button"); assert.ok(WEB_CLIENT.includes("/__bili/diagnostics?topic="), "buttons wire to the generic diagnostics endpoint"); + // the reason is error-derived text flowing into innerHTML → must be escaped + const escRe = /escapeHtml\(t\("sys\.storage_degraded", \{ reason: sg\.reason \|\| "" \}\)\)/; + assert.ok(escRe.test(WEB_CLIENT), "degrade reason is HTML-escaped before innerHTML"); } finally { await close(proxy); } From 78c063b1f56c0246e4d6fc6fb97a11197a033f4f Mon Sep 17 00:00:00 2001 From: ework-agent Date: Tue, 13 Oct 2026 21:07:58 +0800 Subject: [PATCH 4/5] fix: drop 4 INTERNAL_ONLY exports tripping the unused-exports gate MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- src/storage/runtime-status.ts | 6 +++--- src/web/diagnostics.ts | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/storage/runtime-status.ts b/src/storage/runtime-status.ts index 7b1c28a9a9..438b7df7f2 100644 --- a/src/storage/runtime-status.ts +++ b/src/storage/runtime-status.ts @@ -120,7 +120,7 @@ function cooldownState(): { marker: CooldownMarker | null; remainingMs: number | return { marker, remainingMs: marker ? Math.max(0, marker.atMs + COOLDOWN_MS - now) : null }; } -export interface StorageRuntimeStatus { +interface StorageRuntimeStatus { requested: StorageMode; effective: "legacy" | "shadow" | "full"; /** Requested a unified mode but the sidecar is not carrying data. */ @@ -138,7 +138,7 @@ export interface StorageRuntimeStatus { indexDbOpenError: string | null; } -export function getStorageRuntimeStatus(): StorageRuntimeStatus { +function getStorageRuntimeStatus(): StorageRuntimeStatus { // Fallback before the first SessionStore build: full knob resolution // (a running server always has a store, so this path is defensive). const requested = state.requested ?? resolveStorageMode(process.env, fileStorageUnified()); @@ -169,7 +169,7 @@ export function getStorageRuntimeStatus(): StorageRuntimeStatus { /** Wire payload shared by /__bili/status and /__bili/overview (#2152 parity: * one helper, two surfaces — they can never drift apart again). */ -export interface StorageStatusWire { +interface StorageStatusWire { requested: StorageMode; effective: "legacy" | "shadow" | "full"; degraded: boolean; diff --git a/src/web/diagnostics.ts b/src/web/diagnostics.ts index 72a5b7c5e0..ab5e684e9e 100644 --- a/src/web/diagnostics.ts +++ b/src/web/diagnostics.ts @@ -86,7 +86,7 @@ const TOPICS: Record = { }, }; -export interface DiagnosticsReport { +interface DiagnosticsReport { blob: string; title: string; url: string; From cdd6e834b0d7878cc23173b0b398ee07dcd46618 Mon Sep 17 00:00:00 2001 From: ework-agent Date: Tue, 13 Oct 2026 21:45:42 +0800 Subject: [PATCH 5/5] fix: release SQLite handle before temp-dir teardown in #3040 web banner 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. --- tests/web-storage-banner.test.ts | 27 ++++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/tests/web-storage-banner.test.ts b/tests/web-storage-banner.test.ts index 4649e7cc1b..40a2f55c3e 100644 --- a/tests/web-storage-banner.test.ts +++ b/tests/web-storage-banner.test.ts @@ -137,6 +137,9 @@ function makeOpts(upstreamPort: number): ProxyOptions { test("#3040 forced none-engine: status+overview report degraded; diagnostics blob + prefilled issue link", async () => { const snap = saveEnv(); const base = mkdtempSync(path.join(tmpdir(), "bili-storage-banner-")); + // Hoisted so the finally can release the sidecar's SQLite handle via + // closeQuietly() before rmrf — Windows can't delete a dir while index.db is open. + let store: SessionStore | null = null; try { isolate(base); resetSeams(); @@ -144,7 +147,8 @@ test("#3040 forced none-engine: status+overview report degraded; diagnostics blo delete process.env.BILI_ENCRYPTION_KEY; setSqliteEnginesUnavailableForTests(true); recordEngineBootstrap({ status: "failed", detail: "ECONNREFUSED registry.npmjs.org" }); - _setStoreForTest(new SessionStore({ dir: process.env.BILI_SESSIONS_DIR, enabled: true })); + store = new SessionStore({ dir: process.env.BILI_SESSIONS_DIR, enabled: true }); + _setStoreForTest(store); const upstreamPort = await freePort(); const proxy = await startServer(makeOpts(upstreamPort)); await once(proxy, "listening"); @@ -200,6 +204,7 @@ test("#3040 forced none-engine: status+overview report degraded; diagnostics blo } } finally { resetSeams(); + store?.closeQuietly(); rmrf(base); restoreEnv(snap); } @@ -208,12 +213,15 @@ test("#3040 forced none-engine: status+overview report degraded; diagnostics blo test("#3040 healthy sidecar and explicit legacy: no degraded flag (banner stays hidden)", { skip: !(probeBuiltinSqlite() || probeHostBetterSqlite3()) && "no SQLite engine available on this host" }, async () => { const snap = saveEnv(); const base = mkdtempSync(path.join(tmpdir(), "bili-storage-banner-")); + let store: SessionStore | null = null; + let legacyStore: SessionStore | null = null; try { isolate(base); resetSeams(); delete process.env.BILI_STORAGE_UNIFIED; delete process.env.BILI_ENCRYPTION_KEY; - _setStoreForTest(new SessionStore({ dir: process.env.BILI_SESSIONS_DIR, enabled: true })); + store = new SessionStore({ dir: process.env.BILI_SESSIONS_DIR, enabled: true }); + _setStoreForTest(store); const upstreamPort = await freePort(); const proxy = await startServer(makeOpts(upstreamPort)); await once(proxy, "listening"); @@ -233,7 +241,8 @@ test("#3040 healthy sidecar and explicit legacy: no degraded flag (banner stays process.env.BILI_STORAGE_UNIFIED = "0"; const legacyDir = path.join(base, "sessions-legacy"); mkdirSync(legacyDir, { recursive: true }); - _setStoreForTest(new SessionStore({ dir: legacyDir, enabled: false })); + legacyStore = new SessionStore({ dir: legacyDir, enabled: false }); + _setStoreForTest(legacyStore); o = await fetchJson<{ storage: StorageWire }>(port, "/__bili/overview"); assert.equal(o.storage.requested, "legacy"); assert.equal(o.storage.effective, "legacy"); @@ -244,6 +253,8 @@ test("#3040 healthy sidecar and explicit legacy: no degraded flag (banner stays } } finally { resetSeams(); + store?.closeQuietly(); + legacyStore?.closeQuietly(); rmrf(base); restoreEnv(snap); } @@ -252,12 +263,14 @@ test("#3040 healthy sidecar and explicit legacy: no degraded flag (banner stays test("#3040 BILI_ENCRYPTION_KEY opt-out is intentional: reported, never warned", async () => { const snap = saveEnv(); const base = mkdtempSync(path.join(tmpdir(), "bili-storage-banner-")); + let store: SessionStore | null = null; try { isolate(base); resetSeams(); process.env.BILI_STORAGE_UNIFIED = "1"; process.env.BILI_ENCRYPTION_KEY = "a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90"; - _setStoreForTest(new SessionStore({ dir: process.env.BILI_SESSIONS_DIR, enabled: true })); + store = new SessionStore({ dir: process.env.BILI_SESSIONS_DIR, enabled: true }); + _setStoreForTest(store); const upstreamPort = await freePort(); const proxy = await startServer(makeOpts(upstreamPort)); await once(proxy, "listening"); @@ -274,6 +287,7 @@ test("#3040 BILI_ENCRYPTION_KEY opt-out is intentional: reported, never warned", } } finally { resetSeams(); + store?.closeQuietly(); rmrf(base); restoreEnv(snap); } @@ -282,6 +296,7 @@ test("#3040 BILI_ENCRYPTION_KEY opt-out is intentional: reported, never warned", test("#3040 corrupt index.db (guard #2771): degraded with the open-failure reason", { skip: !(probeBuiltinSqlite() || probeHostBetterSqlite3()) && "no SQLite engine available on this host" }, async () => { const snap = saveEnv(); const base = mkdtempSync(path.join(tmpdir(), "bili-storage-banner-")); + let store: SessionStore | null = null; try { isolate(base); resetSeams(); @@ -289,7 +304,8 @@ test("#3040 corrupt index.db (guard #2771): degraded with the open-failure reaso delete process.env.BILI_ENCRYPTION_KEY; const dir = process.env.BILI_SESSIONS_DIR!; writeFileSync(path.join(dir, "index.db"), Buffer.from("this is definitely not a sqlite database file".repeat(8))); - _setStoreForTest(new SessionStore({ dir, enabled: true })); + store = new SessionStore({ dir, enabled: true }); + _setStoreForTest(store); const upstreamPort = await freePort(); const proxy = await startServer(makeOpts(upstreamPort)); await once(proxy, "listening"); @@ -307,6 +323,7 @@ test("#3040 corrupt index.db (guard #2771): degraded with the open-failure reaso } } finally { resetSeams(); + store?.closeQuietly(); rmrf(base); restoreEnv(snap); }