Repository navigation
feat(#2809): name the skipped env/system proxy in default-direct failure diagnostics - #2860
Conversation
…ure diagnostics 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
📦 Built Package ArtifactBranch: Option A — Install this exact build (recommended)npm install -g billion-context@0.0.3174-pr.2860.a4d5dfcThis exact version is immutable and reproducible. The rolling Option B — Download artifact
tar xzf billion-context-pr2860.tgz
npm install -g packageInstall instructions are refreshed on each push. |
[bot] 🏷 收到,开始 review PR #2860(skipped-proxy hint)。初步状态:
正在逐文件核对代码与描述一致性,稍后按八问体例给完整结论。 |
[bot] 🏷 PR #2860 review 完成,逐项作答(结构化八问): 1. 是什么问题: 2. 什么原因导致的: 3. 影响范围与严重程度:影响"配了 env/system 代理但模式留 unset + 直连被黑洞/拒连"的用户(即 #2809 场景);程度 = 体验/诊断缺陷,对既有行为零影响(egress 不变)。 4. 怎么修复的:修在源头(decision point)而非显示层——default-direct 短路内对共享 auto-detect tail(NO_PROXY→env tier→Windows bypass→system proxy,原样抽成 5. 是否有回归问题:未发现。逐项审过的既有行为:
6. 是否破坏缓存:不涉及——prefix cache/session persist/增量游标/去重键均未动(alert dedup key 不变)。 7. 是否改了设计方向:没有。纯增量诊断通道;架构/边界/数据流不变(诊断信息挂在既有 decision 对象上,经既有失败面渲染)。 8. 是否引入新配置:没有。无新 config 字段/env var/CLI flag; 验证证据:
判定:代码与行为均达标,可合(待最后 3 个 CI 矩阵 job 收尾确认,目前零失败)。 |
📦 Merged Build PublishedThis merge to master was published as npm install -g billion-context@0.0.314-master.f5631ed # this exact build
npm install -g billion-context@master # always the newest merged build
|
Closes #2809
What
Unset
upstreamProxyModedefaults to direct by design (#346/#357: silent env-proxy use changes egress IP → 401 on IP-bound OAuth endpoints). But when an env/Windows-system proxy IS available and the direct attempt dies fail-fast (connect-timeoutet al.), no channel named the skipped proxy: bili.log saidhint=TCP handshake never completed — upstream/proxy unreachable or blackholed, the 502detailrepeated it, and the #1682 alert banner showed the same static text. The user had to dig out their own registry/env to discover the machine's own proxy could reach the host fine.Now, in exactly that scenario, every failure surface names the skipped proxy plus the three opt-in paths:
The web banner gets the equivalent as a localized sentence (new i18n key
alert.note.skipped_proxy, zh+en), rendered from structured alert fields rather than the server-side English string — the client's i18n catalog stays the single source of truth for banner wording (#1024 discipline).How
resolveProxyDecisionpeeks the auto-detect chain (NO_PROXY → env tier → Windows bypass → system proxy, extracted verbatim intoautoDetectProxy) inside the default-direct short-circuit and attaches the would-be proxy to the decision asskippedProxy. Egress stays direct byte-for-byte — the peek is diagnostic-only and never feeds routing.ProxyFallbackOptions.defaultDirect(=rawProxyMode === undefined && !biliProxyinloadOptions) distinguishes unset mode from explicit"direct"— the same distinction bili codex 报错 MCP client forcodex_appsfailed to start #1012 made for aux egress (src/config.ts). Explicit direct never nags.hintWithSkippedProxy(kind, skipped)intoformatUpstreamError'shint=part: bili.log line, 502detail, connection-status snapshot error, loop re-request log — so the channels cannot drift apart.skippedProxy/skippedSource(redacted); the banner appends the localized note after the static per-kind hint.isFailFastUpstreamKind) — a post-connect failure may have run on a working path where "skipped proxy" would mislead; ② unset mode only; ③ only when the auto chain actually resolves a proxy for THIS host — if the user's own NO_PROXY/ProxyOverride excludes the host, direct was their intent and nothing is named.redactProxyUrlmoved fromupstream-proxy.tstoupstream-fail.ts(shared bottom layer) so every renderer uses one masking implementation; credentials never reach any surface.Behavior change disclosure (old → new)
hint=<static per-kind text><static text>; available proxy <redacted> (<source>) was skipped …UpstreamAlertJSON payload{kind, host, hint, firstSeen, lastSeen, count}skippedProxy/skippedSourceproxyUrl, dispatcher, retry policy all untouched)WHY: closes the diagnosis dead-end from #2809 without touching the intentional default. No behavior drift beyond additive diagnostic text.
Config surface
No new config file field, no new
BILI_*env var, no CLI flag.defaultDirectis an internal derived flag onProxyFallbackOptionscomputed from existing inputs (BILI_UPSTREAM_PROXY_MODE/upstreamProxyMode/BILI_UPSTREAM_PROXY); the opt-ins it names (upstreamProxyMode: "auto",BILI_UPSTREAM_PROXY_MODE=auto, per-provider"proxy"lane) all already exist and are already documented.Regression review (existing behaviors walked)
directshort-circuit returns the exact legacy object{source:"direct"}(byte-identical, deepEqual-pinned).warnUnsupportedScheme) unchanged; decision shapes unchanged (existing routing suite green, two shape fixtures updated for the new fields — noted in-test).formatUpstreamError/recordUpstreamConnection/recordUpstreamAlert: new params optional; without them output is byte-identical (regression-guarded by assertion againstUPSTREAM_FAIL_HINTS[kind]).(kind, host), MAX_ALERTS eviction,clearUpstreamAlertsForHoston success: untouched.fetch-util), session/persist, compression pipeline, wire injection: untouched. Both compression modes unaffected (this lives below the compression layer).tests/web-i18n.test.ts).Tests
New hermetic suite
tests/skipped-proxy-hint.test.ts(10 tests): decision-level gating (env tier, windows-system tier via injectedsystemProxy, NO_PROXY/bypass exclusion, explicit-direct silence, auto-mode shape stability, empty-env byte-identical shape), hint helper (masking, fail-fast-only gate, legacy byte-equality), alert table (structured fields, dedup refresh, no-stray-fields case), andloadOptionsend-to-end for the exact #2809 scenario incl. aux-path inertness. Local: typecheck + build + the 21 suites touching the changed seams (264 tests) all green; full regression delegated to CI.Note: dsh desktop rendering only the
errorfield of the 502 (notdetail) is dsh-side; the improved text does reach the 502detail, bili.log, and the banner regardless.