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..80afec8336 100644 --- a/src/storage/engine-bootstrap.ts +++ b/src/storage/engine-bootstrap.ts @@ -26,16 +26,16 @@ */ 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"; 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"; @@ -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"); @@ -165,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; @@ -199,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()) { @@ -222,7 +218,7 @@ async function runBootstrap(opts: EnsureSqliteEngineOptions): Promise 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 }; +} + +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; +} + +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). */ +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..ab5e684e9e --- /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), + }, +}; + +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..40a2f55c3e --- /dev/null +++ b/tests/web-storage-banner.test.ts @@ -0,0 +1,330 @@ +// #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-")); + // 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(); + delete process.env.BILI_STORAGE_UNIFIED; + delete process.env.BILI_ENCRYPTION_KEY; + setSqliteEnginesUnavailableForTests(true); + recordEngineBootstrap({ status: "failed", detail: "ECONNREFUSED registry.npmjs.org" }); + 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"); + 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"); + // 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); + } + } finally { + resetSeams(); + store?.closeQuietly(); + 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-")); + 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; + 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"); + 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 }); + 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"); + assert.equal(o.storage.degraded, false, "explicit legacy never warns"); + assert.equal(o.storage.engine, null); + } finally { + await close(proxy); + } + } finally { + resetSeams(); + store?.closeQuietly(); + legacyStore?.closeQuietly(); + 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-")); + let store: SessionStore | null = null; + try { + isolate(base); + resetSeams(); + process.env.BILI_STORAGE_UNIFIED = "1"; + process.env.BILI_ENCRYPTION_KEY = "a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90"; + 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"); + 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(); + store?.closeQuietly(); + 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-")); + let store: SessionStore | null = null; + 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))); + store = new SessionStore({ dir, enabled: true }); + _setStoreForTest(store); + 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(); + store?.closeQuietly(); + rmrf(base); + restoreEnv(snap); + } +});