From c750c3e303072f386320cdb14b32f6e711bc0684 Mon Sep 17 00:00:00 2001 From: ework-agent Date: Mon, 12 Oct 2026 11:37:29 +0800 Subject: [PATCH] feat(#2809): name the skipped env/system proxy in default-direct failure diagnostics MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Unset upstreamProxyMode defaults to direct by design (#346/#357), but when an env/Windows-system proxy IS available and the direct attempt dies fail-fast (connect-timeout et al.), no channel named the skipped proxy: bili.log, the 502 detail and the #1682 alert banner all said only "unreachable/blackholed". resolveProxyDecision now peeks the auto-detect chain (NO_PROXY -> env -> Windows bypass -> system proxy) inside the default-direct short-circuit and attaches the would-be proxy to the decision as diagnostic-only info (skippedProxy); egress stays direct byte-for-byte. The note renders into formatUpstreamError's hint part (log + 502 detail + status snapshot + loop re-request log) and into the alert table as structured fields (skippedProxy / skippedSource) so the web banner can render a localized sentence through the i18n catalog instead of the server-side English string. Gates: fail-fast kinds only (post-connect failures may have run on a working path), UNSET mode only (explicit "direct" never nags — rawProxyMode === undefined, same distinction #1012 made for aux egress), and only when the auto chain actually resolves a proxy for THIS host (user's own NO_PROXY / ProxyOverride exclusion means direct was their intent). Credentials masked via the shared redactProxyUrl (moved to upstream-fail so all renderers share one implementation). Closes #2809 --- src/config.ts | 8 + src/loop/core.ts | 8 +- src/server.ts | 7 +- src/server/admin.ts | 8 +- src/server/relay.ts | 10 +- src/upstream-alerts.ts | 20 ++- src/upstream-fail.ts | 46 ++++++ src/upstream-proxy.ts | 49 +++--- src/web/client.ts | 9 +- src/web/i18n.ts | 2 + tests/skipped-proxy-hint.test.ts | 227 +++++++++++++++++++++++++++ tests/upstream-proxy-routing.test.ts | 10 +- 12 files changed, 366 insertions(+), 38 deletions(-) create mode 100644 tests/skipped-proxy-hint.test.ts diff --git a/src/config.ts b/src/config.ts index fb57d08fbc..7612c45131 100644 --- a/src/config.ts +++ b/src/config.ts @@ -1320,6 +1320,10 @@ export function loadOptions(env: NodeJS.ProcessEnv = process.env): ProxyOptions // is set so that proxy still wins (globalProxy is non-empty, so the short-circuit // is skipped regardless). const explicitDirect = proxyMode === "direct" && !biliProxy; + // #2809: unset mode resolves to direct too, but means "no preference" — + // this flag (unlike explicitDirect) never gates egress; it only lets + // failure diagnostics name the proxy the auto chain would have picked. + const defaultDirect = rawProxyMode === undefined && !biliProxy; const proxy = biliProxy ?? (proxyMode === "direct" ? "" : proxyMode === "manual" ? webProxy ?? configProxy : configProxy); const proxySource: ProxyOptions["proxySource"] = biliProxy ? "bili-env" @@ -1342,6 +1346,7 @@ export function loadOptions(env: NodeJS.ProcessEnv = process.env): ProxyOptions biliPort: port, globalSource: proxySource, explicitDirect, + defaultDirect, }; // #1012: the launcher forwards the user's pre-strip proxy vars under // BILI_INHERITED_* (the child's own env tier is intentionally empty — @@ -1360,6 +1365,9 @@ export function loadOptions(env: NodeJS.ProcessEnv = process.env): ProxyOptions // aux tier for every default-config user. Only an EXPLICIT "direct" // mode (upstreamProxyMode / BILI_UPSTREAM_PROXY_MODE) opts aux egress // out of the inherited tier; unset means "no preference". + // defaultDirect inherits via the spread above: whenever it is true, + // this explicitDirect is false, so the model-path short-circuit (and + // the #2809 diagnostic peek inside it) can never fire for aux. explicitDirect: rawProxyMode === "direct" && !biliProxy, ...(httpProxy ? {} : inheritedHttpProxy ? { httpProxy: inheritedHttpProxy } : {}), ...(httpsProxy ? {} : inheritedHttpsProxy ? { httpsProxy: inheritedHttpsProxy } : {}), diff --git a/src/loop/core.ts b/src/loop/core.ts index 12ea26bbfc..6ccc567226 100644 --- a/src/loop/core.ts +++ b/src/loop/core.ts @@ -28,7 +28,7 @@ import { applyConfiguredCompression } from "../external-summary-compress.js"; import { executeSearchContextTarget, resolveDecompress } from "../decompress-shared.js"; import { toolFail, type ProxyToolResult } from "../proxy-tool-result.js"; import { fetchWithRetry, UpstreamHttpError } from "../fetch-util.js"; -import { classifyUpstreamFailure, type UpstreamFailureKind } from "../upstream-fail.js"; +import { classifyUpstreamFailure, type SkippedProxyInfo, type UpstreamFailureKind } from "../upstream-fail.js"; import { formatUpstreamError, proxyDispatcher } from "../upstream-proxy.js"; import { warnCacheCollapse } from "../cache-warn.js"; import { dumpRejectedBody } from "../error-dump.js"; @@ -172,6 +172,10 @@ export interface LoopCtx { session: Session; log: (msg: string) => void; proxyUrl?: string; + /** #2809: diagnostic-only — the proxy the auto chain would have picked + * while default-direct mode ran this session's upstream directly. Names + * itself in re-request transport-failure logs like the outer forward does. */ + skippedProxy?: SkippedProxyInfo; /** #1536: origin (scheme://host) of the LLM endpoint this loop forwards to * — part of the cache-invalidation target identity (rotating relays busts * the prefix even for the same model+wire). Distinct from proxyUrl, which @@ -1396,7 +1400,7 @@ export async function* runCompressLoop( : absorbed ? "context work committed; " : ""; const msg = `${note}the follow-up request to the model failed (${TRANSPORT_FAILURE_LABELS[kind]}) before any response — your context is intact, resend your last message to continue`; ctx.log(`[acp-loop] round ${round}: re-request transport failure (${kind}); ending turn in-band instead of throwing (#1453)`); - loggerLog("error", `[acp-loop] re-request transport failure after ${round} round(s): ${formatUpstreamError(e, requestOptions.url, ctx.proxyUrl)}`); + loggerLog("error", `[acp-loop] re-request transport failure after ${round} round(s): ${formatUpstreamError(e, requestOptions.url, ctx.proxyUrl, ctx.skippedProxy)}`); yield adapter.emitError(msg); return; } diff --git a/src/server.ts b/src/server.ts index 9c56cd5a24..37b7873129 100644 --- a/src/server.ts +++ b/src/server.ts @@ -17,6 +17,7 @@ import { contextFromRegistry, loadRegistry, peekRegistryContext, peekRegistryOut import { codexAlignedWindow } from "./codex-models.js"; import { fetchWithTimeout, MAX_REQUEST_BYTES, upstreamTimeoutMs } from "./fetch-util.js"; import { getUpstreamConnectionStatus, resolveProxy, resolveProxyDecision, proxyDispatcher, type UpstreamProxyDecision } from "./upstream-proxy.js"; +import type { SkippedProxyInfo } from "./upstream-fail.js"; import { getUpstreamAlerts } from "./upstream-alerts.js"; import { hostIdForLog, maskHostPortForLog, setMaskHostsEnabled, maskUrlForLog, maskUrlsInText } from "./log-mask.js"; // Protocol codecs + the historical-image strip primitive live in the kernel now @@ -1829,6 +1830,10 @@ type ForwardTarget = { upstreamUrl: string; headers: Record; proxyUrl: string | undefined; + /** #2809: diagnostic-only — the proxy the auto chain would have picked + * while default-direct mode ran this request directly. Rendered into + * failure surfaces (log/502/alert/loop re-request), never used for egress. */ + skippedProxy?: SkippedProxyInfo; }; // Log each unique (host, proxy, source) upstream-proxy decision once so the @@ -1941,7 +1946,7 @@ export function buildForwardTarget( } const decision = resolveProxyDecision(opts.routes, opts.proxy, route?.rewrittenUrl ?? upstreamUrl, opts.proxyFallback); logUpstreamProxyDecision(opts, upstreamUrl, decision); - return { upstreamUrl, headers, proxyUrl: decision.proxy }; + return { upstreamUrl, headers, proxyUrl: decision.proxy, skippedProxy: decision.skippedProxy }; } // #2228: model-decided nudge timing — the side-channel decision call. It diff --git a/src/server/admin.ts b/src/server/admin.ts index 5dc099a08a..b6371cb242 100644 --- a/src/server/admin.ts +++ b/src/server/admin.ts @@ -256,7 +256,9 @@ export async function handleAdminRoute(req: http.IncomingMessage, res: http.Serv if (req.method === "POST" && req.url === "/__bili/upstream/test") { const target = opts.upstream; const targetUrl = new URL(target).origin; - const proxyUrl = resolveProxyDecision(opts.routes, opts.proxy, target, opts.proxyFallback).proxy; + // Keep the whole decision: #2809's skippedProxy diagnostic rides on it. + const decision = resolveProxyDecision(opts.routes, opts.proxy, target, opts.proxyFallback); + const proxyUrl = decision.proxy; try { const result = await fetchWithTimeout(targetUrl, { method: "HEAD", @@ -273,9 +275,9 @@ export async function handleAdminRoute(req: http.IncomingMessage, res: http.Serv } catch (error) { // #1682: probe failures deliberately do NOT feed the alert table — // they are user-initiated diagnostics, not live-traffic evidence. - recordUpstreamConnection(targetUrl, proxyUrl, error); + recordUpstreamConnection(targetUrl, proxyUrl, error, decision.skippedProxy); res.writeHead(502, { "content-type": "application/json" }); - res.end(JSON.stringify({ error: formatUpstreamError(error, targetUrl, proxyUrl) })); + res.end(JSON.stringify({ error: formatUpstreamError(error, targetUrl, proxyUrl, decision.skippedProxy) })); } return; } diff --git a/src/server/relay.ts b/src/server/relay.ts index 50ca1da563..1836c62c41 100644 --- a/src/server/relay.ts +++ b/src/server/relay.ts @@ -148,7 +148,7 @@ export async function forward( // #1757 resolved drop list, shared with wireTransform below (re-sent // compress-retry bodies must carry the same drops as the initial forward). let compatDropPaths: string[] = []; - const { upstreamUrl, headers, proxyUrl } = buildForwardTarget(req, opts, route, affinity, prepared !== null ? instanceId : undefined); + const { upstreamUrl, headers, proxyUrl, skippedProxy } = buildForwardTarget(req, opts, route, affinity, prepared !== null ? instanceId : undefined); // #1884 re-sign arm: the native lane tunneled this request with the // signing credential (x-bili-resign markers — stripped in // buildForwardTarget, they must never reach the upstream). Every egress @@ -501,15 +501,15 @@ export async function forward( // #1682: any resolved response proves the host is reachable again. clearUpstreamAlertsForHost(upstreamUrl); } catch (error) { - recordUpstreamConnection(upstreamUrl, proxyUrl, error); - recordUpstreamAlert(upstreamUrl, error, proxyUrl !== undefined); + recordUpstreamConnection(upstreamUrl, proxyUrl, error, skippedProxy); + recordUpstreamAlert(upstreamUrl, error, proxyUrl !== undefined, skippedProxy); // #604: a network-level failure (socket reset, timeout abort) also never // reports usage — arm the emergency shrink like the 5xx branch below. if (prepared && req.method !== "GET" && req.method !== "HEAD") armFailureShrink(prepared, log, "network failure", outboundPayloadBreakdown(prepared, opts, route, req.url ?? "").armEstimate); // [#1343] no response means the attached full text never reached the model — // drop-and-log it (a corrective note surfaces on the next qualifying request). if (prepared && prepared.attachedRetrievals && prepared.attachedRetrievals.length > 0) dropRetrievals(prepared.session, prepared.attachedRetrievals.map((i) => i.ref), "upstream network failure"); - throw new Error(`upstream request failed: ${formatUpstreamError(error, upstreamUrl, proxyUrl)}`, { cause: error }); + throw new Error(`upstream request failed: ${formatUpstreamError(error, upstreamUrl, proxyUrl, skippedProxy)}`, { cause: error }); } // #552 learn-on-failure: a converting upstream that rejects a role (codex // ≥0.153 sends "developer"; vLLM/SGLang-style backends answer 400 @@ -1394,7 +1394,7 @@ export async function forward( const loopBillingUpstream = route?.rewrittenUrl ?? (/^https?:\/\//i.test(req.url ?? "") ? req.url ?? undefined : opts.upstream); const loop = runCompressLoop( responseBody, - { core, config, messages: prepared.processedMessages.length > 0 ? prepared.processedMessages : prepared.originalMessages, compressMessages: prepared.originalMessages, session: prepared.session, log: ctx.log, proxyUrl, upstreamOrigin: targetOrigin, protocol: prepared.protocol, textProtocol, debug: opts.debug, refreshFolded, visibilityMarkers, dumpSse: loopDumpDir ? (name, stream) => dumpStreamToFile(stream, loopDumpDir, name) : undefined, imageLearn: { host: upstreamHost(loopBillingUpstream), fp: `${imageBillingFor(opts, loopBillingUpstream)}:${imageTokenCapFor(opts, loopBillingUpstream)}` } }, + { core, config, messages: prepared.processedMessages.length > 0 ? prepared.processedMessages : prepared.originalMessages, compressMessages: prepared.originalMessages, session: prepared.session, log: ctx.log, proxyUrl, skippedProxy, upstreamOrigin: targetOrigin, protocol: prepared.protocol, textProtocol, debug: opts.debug, refreshFolded, visibilityMarkers, dumpSse: loopDumpDir ? (name, stream) => dumpStreamToFile(stream, loopDumpDir, name) : undefined, imageLearn: { host: upstreamHost(loopBillingUpstream), fp: `${imageBillingFor(opts, loopBillingUpstream)}:${imageTokenCapFor(opts, loopBillingUpstream)}` } }, parsedReq, { url: upstreamUrl, headers: reqHeaders, wireTransform, resign: applyResign }, adapter, diff --git a/src/upstream-alerts.ts b/src/upstream-alerts.ts index f641cf0e8d..8c4b863f73 100644 --- a/src/upstream-alerts.ts +++ b/src/upstream-alerts.ts @@ -11,7 +11,7 @@ * The web UI renders whatever is here as a global banner via the existing * /__bili/overview poll; nothing else consumes this table. */ -import { classifyUpstreamFailure, UPSTREAM_FAIL_HINTS, type UpstreamFailureKind } from "./upstream-fail.js"; +import { classifyUpstreamFailure, hintWithSkippedProxy, redactedSkippedProxy, type SkippedProxyInfo, type UpstreamFailureKind } from "./upstream-fail.js"; export interface UpstreamAlert { kind: UpstreamFailureKind; @@ -22,6 +22,12 @@ export interface UpstreamAlert { firstSeen: number; lastSeen: number; count: number; + /** #2809: set when the failing path ran default-direct while a proxy was + * available. The banner renders a LOCALIZED note from these structured + * fields (the client's i18n catalog owns the wording; `hint` above is + * the full English string for JSON consumers). Redacted. */ + skippedProxy?: string; + skippedSource?: string; } /** v1 scope (#1682): only "fundamentally cannot connect" transport failures. @@ -55,18 +61,22 @@ function keyFor(kind: UpstreamFailureKind, host: string): string { } /** Record one failed model request. Dedup key (kind, host): repeats refresh - * lastSeen/count only. Non-alert kinds are ignored entirely. */ -export function recordUpstreamAlert(url: string, error: unknown, viaProxy: boolean): void { + * lastSeen/count only. Non-alert kinds are ignored entirely. `skipped` (#2809) + * rides along so the banner can name the proxy default-direct mode skipped. */ +export function recordUpstreamAlert(url: string, error: unknown, viaProxy: boolean, skipped?: SkippedProxyInfo): void { const kind = classifyUpstreamFailure(error, { viaProxy }); if (!ALERT_KINDS.has(kind)) return; const host = hostOf(url); const now = Date.now(); const key = keyFor(kind, host); + const skippedFields = skipped ? { skippedProxy: redactedSkippedProxy(skipped), skippedSource: skipped.source } : {}; + const hint = hintWithSkippedProxy(kind, skipped); const existing = alerts.get(key); if (existing) { existing.lastSeen = now; existing.count += 1; - existing.hint = UPSTREAM_FAIL_HINTS[kind]; + existing.hint = hint; + Object.assign(existing, skippedFields); return; } if (alerts.size >= MAX_ALERTS) { @@ -80,7 +90,7 @@ export function recordUpstreamAlert(url: string, error: unknown, viaProxy: boole } if (oldestKey !== undefined) alerts.delete(oldestKey); } - alerts.set(key, { kind, host, hint: UPSTREAM_FAIL_HINTS[kind], firstSeen: now, lastSeen: now, count: 1 }); + alerts.set(key, { kind, host, hint, firstSeen: now, lastSeen: now, count: 1, ...skippedFields }); } /** Any resolved response to this host proves the path works again — clear ALL diff --git a/src/upstream-fail.ts b/src/upstream-fail.ts index 7cc947e036..32c60165d0 100644 --- a/src/upstream-fail.ts +++ b/src/upstream-fail.ts @@ -108,3 +108,49 @@ export const UPSTREAM_FAIL_HINTS: Record = { tls: "TLS/certificate failure at CONNECT or upstream handshake — CA/proxy MITM config", unknown: "unclassified transport failure — report with full error chain", }; + +/** Mask proxy credentials for display surfaces (log lines, 502 detail, the + * #2809 skipped-proxy note, alert payloads). Lives HERE instead of + * upstream-proxy so every renderer below that layer can share one + * implementation without a new import edge. */ +export function redactProxyUrl(value: string | undefined): string | undefined { + if (!value) return undefined; + try { + const url = new URL(value); + if (url.username || url.password) { + url.username = "***"; + url.password = "***"; + } + return url.href; + } catch { + return "(invalid proxy URL)"; + } +} + +/** #2809: an AVAILABLE proxy that default-direct mode skipped for this host — + * the value the auto-detect chain would have resolved. Raw on purpose: each + * display channel redacts per its own needs (see redactedSkippedProxy). */ +export type SkippedProxyInfo = { + proxy: string; + /** Tier that offered it: an env var name ("HTTPS_PROXY") or "windows-system". */ + source: string; +}; + +/** Display form of a skipped proxy: credentials masked, the normalization + * trailing slash stripped so the note reads like a human wrote it. */ +export function redactedSkippedProxy(skipped: SkippedProxyInfo): string { + return (redactProxyUrl(skipped.proxy) ?? "").replace(/\/$/, ""); +} + +/** #2809 dead-end: a fail-fast failure under UNSET proxy mode reads + * "unreachable/blackholed" while the machine's own env/system proxy could + * reach the host fine — and no channel ever named that proxy. This appends + * the conditional suffix naming it plus the opt-in paths. Only fail-fast + * kinds qualify: a post-connect failure may have run on a working path, + * where "skipped proxy" would mislead. Diagnostic text only — egress + * decisions never read it. */ +export function hintWithSkippedProxy(kind: UpstreamFailureKind, skipped: SkippedProxyInfo | undefined): string { + const base = UPSTREAM_FAIL_HINTS[kind]; + if (!skipped || !isFailFastUpstreamKind(kind)) return base; + return `${base}; available proxy ${redactedSkippedProxy(skipped)} (${skipped.source}) was skipped because upstreamProxyMode is unset (direct is the default by design, #346/#357) — follow it with "upstreamProxyMode": "auto" or BILI_UPSTREAM_PROXY_MODE=auto, or give this provider a "proxy" lane`; +} diff --git a/src/upstream-proxy.ts b/src/upstream-proxy.ts index 308b87ee5c..05eeccad61 100644 --- a/src/upstream-proxy.ts +++ b/src/upstream-proxy.ts @@ -6,7 +6,7 @@ import type { ProviderRoutes } from "./config.js"; import { log as loggerLog } from "./logger.js"; import { maskHostInText, maskUrlForLog } from "./log-mask.js"; import { upstreamTimeoutMs } from "./fetch-util.js"; -import { classifyUpstreamFailure, UPSTREAM_FAIL_HINTS } from "./upstream-fail.js"; +import { classifyUpstreamFailure, hintWithSkippedProxy, redactProxyUrl, type SkippedProxyInfo } from "./upstream-fail.js"; import { proxyKeepAliveMaxMs as knobProxyKeepAliveMaxMs } from "./knobs.js"; type ParsedHttpProxy = { @@ -29,12 +29,21 @@ export type ProxyFallbackOptions = { * unset mode also parses as "direct" but means "no preference" — in that * case an empty globalProxy must fall through to env proxy discovery. */ explicitDirect?: boolean; + /** #2809: true only when NO proxy mode was set anywhere (unset → defaults + * to direct). Unlike explicitDirect (which gates the SHORT-CIRCUIT), this + * only arms the diagnostic peek: a fail-fast failure may name the proxy + * the auto chain would have picked. Egress stays direct either way. */ + defaultDirect?: boolean; }; export type UpstreamProxyDecision = { proxy?: string; source: string; autoConfigUrl?: string; + /** #2809: set when the decision is default-direct while the auto chain + * WOULD have picked a proxy for this host. Diagnostic-only — never read + * by egress decisions, only by failure renderers (log/502/alert). */ + skippedProxy?: SkippedProxyInfo; }; type WindowsSystemProxy = { @@ -80,20 +89,6 @@ function proxyAuthorization(url: URL): string | undefined { return `Basic ${Buffer.from(`${username}:${password}`).toString("base64")}`; } -function redactProxyUrl(value: string | undefined): string | undefined { - if (!value) return undefined; - try { - const url = new URL(value); - if (url.username || url.password) { - url.username = "***"; - url.password = "***"; - } - return url.href; - } catch { - return "(invalid proxy URL)"; - } -} - export function parseHttpProxy(proxy?: string, biliPort?: number): ParsedHttpProxy | undefined { if (!proxy || typeof proxy !== "string" || !proxy.trim()) return undefined; const candidate = /^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(proxy.trim()) ? proxy.trim() : `http://${proxy.trim()}`; @@ -289,9 +284,23 @@ export function resolveProxyDecision( return { proxy: parsed.url, source: "provider" }; } } - if (globalProxy === "" && fallback.explicitDirect) return { source: "direct" }; + if (globalProxy === "" && fallback.explicitDirect) { + // #2809: unset mode defaults to direct like explicit "direct", but means + // "no preference". Peek at what the auto chain WOULD have picked so + // failure diagnostics can name the skipped proxy. Egress stays direct + // either way — only the diagnostic payload changes (#346/#357 intact). + if (!fallback.defaultDirect) return { source: "direct" }; + const peek = autoDetectProxy(target, fallback); + return peek.proxy ? { source: "direct", skippedProxy: { proxy: peek.proxy, source: peek.source } } : { source: "direct" }; + } const explicit = parseHttpProxy(globalProxy, fallback.biliPort)?.url; if (explicit) return { proxy: explicit, source: fallback.globalSource ?? "global" }; + return autoDetectProxy(target, fallback); +} + +/** Auto-detect tail shared by the normal flow and the #2809 default-direct + * peek: NO_PROXY → env tier → Windows bypass → Windows system proxy → direct. */ +function autoDetectProxy(target: URL | undefined, fallback: ProxyFallbackOptions): UpstreamProxyDecision { if (target && matchesNoProxy(target, fallback.noProxy)) return { source: "no-proxy" }; const environmentCandidates: Array<[string, string | undefined]> = target?.protocol === "http:" ? [["HTTP_PROXY", fallback.httpProxy], ["ALL_PROXY", fallback.allProxy]] @@ -511,7 +520,7 @@ function errorChain(error: unknown): Array> { return chain; } -export function formatUpstreamError(error: unknown, url: string, proxyUrl?: string): string { +export function formatUpstreamError(error: unknown, url: string, proxyUrl?: string, skipped?: SkippedProxyInfo): string { const chain = errorChain(error); const kind = classifyUpstreamFailure(error, { viaProxy: proxyUrl !== undefined }); const fields = ["code", "errno", "syscall", "address", "port"]; @@ -534,16 +543,16 @@ export function formatUpstreamError(error: unknown, url: string, proxyUrl?: stri if (messages.length > 0) parts.push(`message=${messages.join(" <- ")}`); parts.push(`url=${maskUrlForLog(url)}`); parts.push(`proxy=${redactProxyUrl(proxyUrl) ?? "direct"}`); - parts.push(`hint=${UPSTREAM_FAIL_HINTS[kind]}`); + parts.push(`hint=${hintWithSkippedProxy(kind, skipped)}`); return parts.join(" "); } -export function recordUpstreamConnection(url: string, proxyUrl: string | undefined, error?: unknown): void { +export function recordUpstreamConnection(url: string, proxyUrl: string | undefined, error?: unknown, skipped?: SkippedProxyInfo): void { lastConnection = { url, proxy: redactProxyUrl(proxyUrl), connected: error === undefined, - ...(error === undefined ? {} : { error: formatUpstreamError(error, url, proxyUrl) }), + ...(error === undefined ? {} : { error: formatUpstreamError(error, url, proxyUrl, skipped) }), checkedAt: new Date().toISOString(), }; } diff --git a/src/web/client.ts b/src/web/client.ts index a25f92dac2..ec64496d00 100644 --- a/src/web/client.ts +++ b/src/web/client.ts @@ -635,7 +635,14 @@ export const WEB_CLIENT = `(function () { const row = document.createElement("div"); row.className = "alert-row"; const msg = document.createElement("span"); - msg.textContent = t("alert.item", { host: a.host, kind: a.kind, count: a.count, first: fmtDT(a.firstSeen), hint: alertHint(a.kind) }); + // #2809: the server-side note names the proxy default-direct mode + // skipped. Rendered from the STRUCTURED fields (skippedProxy / + // skippedSource) through the catalog — the per-kind hint above is + // static and can't carry dynamic values; a.hint (full English + // string) stays for JSON consumers only. + const baseHint = alertHint(a.kind); + const skippedNote = a.skippedProxy ? " " + t("alert.note.skipped_proxy", { proxy: a.skippedProxy, source: a.skippedSource || "" }) : ""; + msg.textContent = t("alert.item", { host: a.host, kind: a.kind, count: a.count, first: fmtDT(a.firstSeen), hint: baseHint + skippedNote }); const btn = document.createElement("button"); btn.className = "btn sm alert-dismiss"; btn.textContent = t("alert.dismiss"); diff --git a/src/web/i18n.ts b/src/web/i18n.ts index 6b823204f6..0d22fa6584 100644 --- a/src/web/i18n.ts +++ b/src/web/i18n.ts @@ -149,6 +149,7 @@ export const MESSAGES: Record> = { "advisory.hint": "。若未自动完成,请手动执行:", "alert.title": "上游连接异常", "alert.item": "无法连接 {host}({kind} ×{count},首次 {first})— {hint}", + "alert.note.skipped_proxy": "可用的代理 {proxy}({source})被跳过——未设置 upstreamProxyMode(默认直连是有意设计,#346/#357);设置 \"upstreamProxyMode\": \"auto\" 或 BILI_UPSTREAM_PROXY_MODE=auto,或为该 provider 配置 \"proxy\" 即可启用", "alert.dismiss": "知道了", "alert.hint.connect_timeout": "TCP 握手未完成——上游/代理不可达或被黑洞(丢包);可能已按 BILI_REPLAY_RETRY_MAX 做有界透明重放", "alert.hint.connect_refused": "TCP 被拒绝(配置了代理则指代理,否则指上游)——端点未启动或端口错误", @@ -582,6 +583,7 @@ export const MESSAGES: Record> = { "advisory.hint": ". If it did not complete automatically, run manually:", "alert.title": "Upstream connection problems", "alert.item": "Cannot reach {host} ({kind} ×{count}, since {first}) — {hint}", + "alert.note.skipped_proxy": "available proxy {proxy} ({source}) was skipped — upstreamProxyMode is unset (direct is the default by design, #346/#357); set \"upstreamProxyMode\": \"auto\" or BILI_UPSTREAM_PROXY_MODE=auto, or give this provider a \"proxy\" lane to enable it", "alert.dismiss": "Got it", "alert.hint.connect_timeout": "TCP handshake never completed — upstream/proxy unreachable or blackholed; a bounded transparent replay may be attempted (BILI_REPLAY_RETRY_MAX)", "alert.hint.connect_refused": "TCP refused (proxy when configured, else upstream) — endpoint down or wrong port", diff --git a/tests/skipped-proxy-hint.test.ts b/tests/skipped-proxy-hint.test.ts new file mode 100644 index 0000000000..2ef26bfbcc --- /dev/null +++ b/tests/skipped-proxy-hint.test.ts @@ -0,0 +1,227 @@ +import assert from "node:assert/strict"; +import { test } from "node:test"; +import fs from "node:fs"; +import os from "node:os"; +import path from "node:path"; + +import { loadOptions } from "../src/config.ts"; +import { formatUpstreamError, resolveProxyDecision } from "../src/upstream-proxy.ts"; +import { UPSTREAM_FAIL_HINTS, hintWithSkippedProxy, redactedSkippedProxy } from "../src/upstream-fail.ts"; +import { _resetUpstreamAlertsForTest, getUpstreamAlerts, recordUpstreamAlert } from "../src/upstream-alerts.ts"; + +// Hermetic state isolation for loadOptions (same pattern as the #1012 suite). +function withSandboxEnv(mutate: (env: NodeJS.ProcessEnv) => void, run: () => void): void { + const prev = { ...process.env }; + const home = fs.mkdtempSync(path.join(os.tmpdir(), "bili-2809-home-")); + process.env.HOME = home; + process.env.XDG_CONFIG_HOME = path.join(home, ".config"); + process.env.XDG_CACHE_HOME = path.join(home, ".cache"); + process.env.XDG_STATE_HOME = path.join(home, ".local", "state"); + fs.mkdirSync(process.env.XDG_CONFIG_HOME, { recursive: true }); + try { + mutate(process.env); + run(); + } finally { + process.env = prev; + } +} + +function netError(code: string, message: string): Error { + const err = new Error(message); + (err as Error & { code?: string }).code = code; + return err; +} + +const TARGET = "https://relay.example.com/v1/chat/completions"; +const ENV_PROXY = "http://user:pass@127.0.0.1:7890"; +const SYS_PROXY = "http://127.0.0.1:7897"; + +test("resolveProxyDecision: unset mode (defaultDirect) names the skipped env proxy", () => { + const d = resolveProxyDecision({}, "", TARGET, { + biliPort: 42422, + explicitDirect: true, + defaultDirect: true, + httpsProxy: ENV_PROXY, + systemProxy: { enabled: false }, + }); + // egress decision is STILL direct — only the diagnostic payload changed + assert.equal(d.source, "direct"); + assert.equal(d.proxy, undefined); + assert.deepEqual(d.skippedProxy, { proxy: "http://user:pass@127.0.0.1:7890/", source: "HTTPS_PROXY" }); +}); + +test("resolveProxyDecision: unset mode names the skipped Windows system proxy", () => { + const d = resolveProxyDecision({}, "", TARGET, { + biliPort: 42422, + explicitDirect: true, + defaultDirect: true, + systemProxy: { enabled: true, https: SYS_PROXY, bypass: "localhost;127.*;" }, + }); + assert.equal(d.source, "direct"); + assert.deepEqual(d.skippedProxy, { proxy: `${SYS_PROXY}/`, source: "windows-system" }); +}); + +test("resolveProxyDecision: NO_PROXY / ProxyOverride exclusion means no skipped note (user intent)", () => { + // The decision itself stays the short-circuit's "direct" (egress + log + // line unchanged vs before #2809); the PEEK just finds no proxy worth + // naming when the user's own exclusion lists cover the host. + // user's own NO_PROXY excludes the host → direct IS their preference + const d1 = resolveProxyDecision({}, "", TARGET, { + biliPort: 42422, + explicitDirect: true, + defaultDirect: true, + httpsProxy: ENV_PROXY, + noProxy: "relay.example.com", + systemProxy: { enabled: false }, + }); + assert.equal(d1.source, "direct"); + assert.equal(d1.skippedProxy, undefined); + + // Clash-style windows bypass list excludes loopback targets + const d2 = resolveProxyDecision({}, "", "https://127.0.0.1:8443/v1/messages", { + biliPort: 42422, + explicitDirect: true, + defaultDirect: true, + systemProxy: { enabled: true, https: SYS_PROXY, bypass: "localhost;127.*;" }, + }); + assert.equal(d2.source, "direct"); + assert.equal(d2.skippedProxy, undefined); +}); + +test("resolveProxyDecision: EXPLICIT direct mode never nags (#2809 Q3)", () => { + const d = resolveProxyDecision({}, "", TARGET, { + biliPort: 42422, + explicitDirect: true, + defaultDirect: false, + httpsProxy: ENV_PROXY, + systemProxy: { enabled: false }, + }); + assert.deepEqual(d, { source: "direct" }); +}); + +test("resolveProxyDecision: auto mode and empty-env defaults keep today's exact shape", () => { + // auto mode: the tail runs for real, no diagnostic field at all + const auto = resolveProxyDecision({}, undefined, TARGET, { + biliPort: 42422, + httpsProxy: ENV_PROXY, + systemProxy: { enabled: false }, + }); + assert.deepEqual(auto, { proxy: "http://user:pass@127.0.0.1:7890/", source: "HTTPS_PROXY" }); + + // nothing available anywhere → plain direct, byte-identical to before + const bare = resolveProxyDecision({}, "", TARGET, { + biliPort: 42422, + explicitDirect: true, + defaultDirect: true, + systemProxy: { enabled: false }, + }); + assert.deepEqual(bare, { source: "direct" }); +}); + +test("hintWithSkippedProxy: fail-fast kinds gain the suffix, others never do", () => { + const skipped = { proxy: ENV_PROXY, source: "HTTPS_PROXY" }; + const annotated = hintWithSkippedProxy("connect-timeout", skipped); + assert.ok(annotated.startsWith(UPSTREAM_FAIL_HINTS["connect-timeout"])); + assert.match(annotated, /available proxy http:\/\/\*\*\*:\*\*\*@127\.0\.0\.1:7890 \(HTTPS_PROXY\)/); + assert.match(annotated, /"upstreamProxyMode": "auto"/); + assert.match(annotated, /BILI_UPSTREAM_PROXY_MODE=auto/); + assert.ok(!annotated.includes("user:pass"), "credentials stay masked in the hint"); + + // no info → byte-identical legacy hint (regression guard) + assert.equal(hintWithSkippedProxy("connect-timeout", undefined), UPSTREAM_FAIL_HINTS["connect-timeout"]); + // post-connect failure may have run on a working path → no misleading note + assert.equal(hintWithSkippedProxy("upstream-timeout", skipped), UPSTREAM_FAIL_HINTS["upstream-timeout"]); + assert.equal(hintWithSkippedProxy("unknown", skipped), UPSTREAM_FAIL_HINTS["unknown"]); +}); + +test("redactedSkippedProxy: masks credentials and drops the normalization slash", () => { + assert.equal(redactedSkippedProxy({ proxy: "http://user:pass@127.0.0.1:7890/", source: "x" }), "http://***:***@127.0.0.1:7890"); + assert.equal(redactedSkippedProxy({ proxy: "http://127.0.0.1:7890/", source: "x" }), "http://127.0.0.1:7890"); +}); + +test("formatUpstreamError: skipped note lands in the hint part, masking intact", () => { + const err = netError("UND_ERR_CONNECT_TIMEOUT", "connect ETIMEDOUT 10.0.0.5:8443"); + const url = "http://10.0.0.5:8443/v1/messages"; + + const plain = formatUpstreamError(err, url); + assert.ok(plain.endsWith(`hint=${UPSTREAM_FAIL_HINTS["connect-timeout"]}`), "no-skipped output is byte-identical to before"); + + const noted = formatUpstreamError(err, url, undefined, { proxy: ENV_PROXY, source: "HTTPS_PROXY" }); + assert.match(noted, /^kind=connect-timeout /); + assert.match(noted, /proxy=direct/); + assert.ok(noted.includes("http://***:***@127.0.0.1:7890"), "skipped proxy named, masked"); + assert.ok(!noted.includes("user:pass"), "credentials never reach the log line"); + assert.ok(!noted.includes("10.0.0.5") || noted.includes("(masked)"), "upstream host masking unchanged"); +}); + +test("recordUpstreamAlert: structured skipped fields ride along for the localized banner", () => { + _resetUpstreamAlertsForTest(); + const err = netError("UND_ERR_CONNECT_TIMEOUT", "connect timed out"); + recordUpstreamAlert(TARGET, err, false, { proxy: ENV_PROXY, source: "HTTPS_PROXY" }); + let [a] = getUpstreamAlerts(); + assert.ok(a, "alert recorded"); + assert.equal(a.kind, "connect-timeout"); + assert.equal(a.skippedProxy, "http://***:***@127.0.0.1:7890"); + assert.equal(a.skippedSource, "HTTPS_PROXY"); + assert.ok(a.hint.startsWith(UPSTREAM_FAIL_HINTS["connect-timeout"])); + assert.match(a.hint, /available proxy http:\/\/\*\*\*:\*\*\*@127\.0\.0\.1:7890/); + + // repeat refreshes count AND keeps the diagnostic (same decision per host) + recordUpstreamAlert(TARGET, err, false, { proxy: ENV_PROXY, source: "HTTPS_PROXY" }); + [a] = getUpstreamAlerts(); + assert.equal(a.count, 2); + assert.equal(a.skippedProxy, "http://***:***@127.0.0.1:7890"); + + // a failure WITHOUT skipped info keeps the legacy shape (no stray fields) + _resetUpstreamAlertsForTest(); + recordUpstreamAlert(TARGET, netError("ECONNREFUSED", "connect ECONNREFUSED"), false); + [a] = getUpstreamAlerts(); + assert.equal(a.skippedProxy, undefined); + assert.equal(a.skippedSource, undefined); + assert.equal(a.hint, UPSTREAM_FAIL_HINTS["connect-refused"]); +}); + +test("loadOptions: defaultDirect tracks UNSET mode only (model path)", () => { + // unset mode + available env proxy → the full #2809 scenario end-to-end + withSandboxEnv(() => {}, () => { + const opts = loadOptions({ ACP_PORT: "42422", HTTPS_PROXY: ENV_PROXY }); + assert.equal(opts.proxyFallback?.explicitDirect, true); + assert.equal(opts.proxyFallback?.defaultDirect, true); + const d = resolveProxyDecision({}, opts.proxy, TARGET, opts.proxyFallback!); + assert.equal(d.source, "direct"); + assert.equal(d.skippedProxy?.source, "HTTPS_PROXY"); + // aux fallback inherits defaultDirect but its explicitDirect=false, so + // the short-circuit (and thus the peek) can never fire for aux egress + const aux = resolveProxyDecision({}, opts.proxy, TARGET, opts.auxProxyFallback!); + assert.equal(aux.skippedProxy, undefined); + }); + + // EXPLICIT "direct" mode → no nag even with an available proxy + withSandboxEnv(() => {}, () => { + const opts = loadOptions({ ACP_PORT: "42422", BILI_UPSTREAM_PROXY_MODE: "direct", HTTPS_PROXY: ENV_PROXY }); + assert.equal(opts.proxyFallback?.defaultDirect, false); + const d = resolveProxyDecision({}, opts.proxy, TARGET, opts.proxyFallback!); + assert.deepEqual(d, { source: "direct" }); + }); + + // explicit proxy set (mode still unset) → defaultDirect false, nothing skipped + withSandboxEnv(() => {}, () => { + const opts = loadOptions({ ACP_PORT: "42422", BILI_UPSTREAM_PROXY: "http://explicit:3128", HTTPS_PROXY: ENV_PROXY }); + assert.equal(opts.proxyFallback?.defaultDirect, false); + const d = resolveProxyDecision({}, opts.proxy, TARGET, opts.proxyFallback!); + assert.equal(d.source, "bili-env"); + assert.equal(d.skippedProxy, undefined); + }); + + // unset mode but NO proxy anywhere → plain direct, no diagnostic field + withSandboxEnv((env) => { + delete env.HTTPS_PROXY; + delete env.HTTP_PROXY; + delete env.ALL_PROXY; + }, () => { + const opts = loadOptions({ ACP_PORT: "42422" }); + assert.equal(opts.proxyFallback?.defaultDirect, true); + const d = resolveProxyDecision({}, opts.proxy, TARGET, { ...opts.proxyFallback!, systemProxy: { enabled: false } }); + assert.deepEqual(d, { source: "direct" }); + }); +}); diff --git a/tests/upstream-proxy-routing.test.ts b/tests/upstream-proxy-routing.test.ts index 958fd57a02..923a9fad1f 100644 --- a/tests/upstream-proxy-routing.test.ts +++ b/tests/upstream-proxy-routing.test.ts @@ -253,6 +253,8 @@ test("loadOptions keeps BILI_UPSTREAM_PROXY above config/environment fallback", }); assert.equal(opts.proxy, "https://explicit.example:9443"); assert.equal(opts.proxySource, "bili-env"); + // #2809: proxyFallback gained defaultDirect (false here — an explicit + // BILI_UPSTREAM_PROXY is set, so the unset-mode diagnostic peek is off). assert.deepEqual(opts.proxyFallback, { httpsProxy: "http://fallback.example:8080", allProxy: "http://all.example:8080", @@ -260,6 +262,7 @@ test("loadOptions keeps BILI_UPSTREAM_PROXY above config/environment fallback", biliPort: 9100, globalSource: "bili-env", explicitDirect: false, + defaultDirect: false, }); }); @@ -277,8 +280,13 @@ test("default (unset mode) is direct, not env auto-detect (#346)", () => { assert.equal(opts.proxy, ""); assert.equal(opts.proxySource, "direct"); assert.equal(opts.proxyFallback!.explicitDirect, true); + // #346 egress pin stands (source stays "direct"); #2809 adds the + // diagnostic-only skippedProxy naming the env proxy that was skipped. const decision = resolveProxyDecision(opts.routes, opts.proxy, "https://api.example.com/v1", opts.proxyFallback); - assert.deepEqual(decision, { source: "direct" }); + assert.deepEqual(decision, { + source: "direct", + skippedProxy: { proxy: "http://fallback.example:8080/", source: "HTTPS_PROXY" }, + }); } finally { if (prevConfig === undefined) delete process.env.BILI_CONFIG_FILE; else process.env.BILI_CONFIG_FILE = prevConfig;