Skip to content

feat(#2809): name the skipped env/system proxy in default-direct failure diagnostics - #2860

Merged
ranxianglei merged 1 commit into
masterfrom
2026-10-12_skipped-proxy-hint
Oct 12, 2026
Merged

ranxianglei merged 1 commit into
masterfrom
2026-10-12_skipped-proxy-hint

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Closes #2809

What

Unset upstreamProxyMode defaults 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-timeout et al.), no channel named the skipped proxy: bili.log said hint=TCP handshake never completed — upstream/proxy unreachable or blackholed, the 502 detail repeated 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:

hint=TCP handshake never completed — upstream/proxy unreachable or blackholed; a bounded transparent replay may be attempted (BILI_REPLAY_RETRY_MAX); available proxy http://***:***@127.0.0.1:7890 (HTTPS_PROXY) 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

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

  • resolveProxyDecision peeks the auto-detect chain (NO_PROXY → env tier → Windows bypass → system proxy, extracted verbatim into autoDetectProxy) inside the default-direct short-circuit and attaches the would-be proxy to the decision as skippedProxy. Egress stays direct byte-for-byte — the peek is diagnostic-only and never feeds routing.
  • New internal flag ProxyFallbackOptions.defaultDirect (= rawProxyMode === undefined && !biliProxy in loadOptions) distinguishes unset mode from explicit "direct" — the same distinction bili codex 报错 MCP client for codex_apps failed to start #1012 made for aux egress (src/config.ts). Explicit direct never nags.
  • The note renders through one shared helper hintWithSkippedProxy(kind, skipped) into formatUpstreamError's hint= part: bili.log line, 502 detail, connection-status snapshot error, loop re-request log — so the channels cannot drift apart.
  • Alert table gains structured fields skippedProxy/skippedSource (redacted); the banner appends the localized note after the static per-kind hint.
  • Gating: ① fail-fast kinds only (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.
  • redactProxyUrl moved from upstream-proxy.ts to upstream-fail.ts (shared bottom layer) so every renderer uses one masking implementation; credentials never reach any surface.

Behavior change disclosure (old → new)

Surface Old New
bili.log / 502 detail / status snapshot / loop re-request log hint=<static per-kind text> when gated above: <static text>; available proxy <redacted> (<source>) was skipped …
#1682 web banner static i18n hint per kind static hint + localized skipped-proxy sentence (zh/en) when fields present
UpstreamAlert JSON payload {kind, host, hint, firstSeen, lastSeen, count} additive optional skippedProxy/skippedSource
Egress behavior default = direct unchanged (#346/#357 intact; proxyUrl, 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. defaultDirect is an internal derived flag on ProxyFallbackOptions computed 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)

  • Explicit-direct short-circuit returns the exact legacy object {source:"direct"} (byte-identical, deepEqual-pinned).
  • Auto/manual/provider/no-proxy/windows-bypass flows: tail extracted verbatim, order and side effects (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 against UPSTREAM_FAIL_HINTS[kind]).
  • Alert dedup key (kind, host), MAX_ALERTS eviction, clearUpstreamAlertsForHost on success: untouched.
  • Retry/replay logic (fetch-util), session/persist, compression pipeline, wire injection: untouched. Both compression modes unaffected (this lives below the compression layer).
  • i18n: catalog parity + literal-reference lint green (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 injected systemProxy, 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), and loadOptions end-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 error field of the 502 (not detail) is dsh-side; the improved text does reach the 502 detail, bili.log, and the banner regardless.

…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
@github-actions

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-12_skipped-proxy-hint (c750c3e)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.3174-pr.2860.a4d5dfc

This exact version is immutable and reproducible. The rolling pr tag tracks the newest test build across all PRs.

Option B — Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr2860.tgz
npm install -g package

Install instructions are refreshed on each push.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 收到,开始 review PR #2860(skipped-proxy hint)。初步状态:

  • 分支 2026-10-12_skipped-proxy-hint(c750c3e)已拉取,12 个文件 +366/-38。
  • CI:30 个 check run,25 个 completed/success;剩余 5 个 in_progress(4× test 矩阵 ubuntu/windows × node 22/24、hermetic registry e2e ×2)。
  • 基线检查:master 在 PR 建立后只前进了 fix: allow bugfix-release/* carve-out branches in ci.yml version-guard #2859(ci.yml version-guard + release.md,与本 PR 无文件交集),无冲突风险。

正在逐文件核对代码与描述一致性,稍后按八问体例给完整结论。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 PR #2860 review 完成,逐项作答(结构化八问):

1. 是什么问题:upstreamProxyMode 未设置(默认直连是有意设计,#346/#357)且机器上实际存在可用 env/system 代理时,直连 fail-fast 失败(connect-timeout 等)的所有诊断面(bili.log hint / 502 detail / #1682 alert banner)都不提"有个能用的代理被跳过了"——用户只能自己猜到该切 auto。是诊断盲区,不是 egress bug。

2. 什么原因导致的:resolveProxyDecision 的 default-direct 短路在 auto-detect chain 之前就返回,decision 对象只携带 egress 信息(proxy/source)、没有"本会选到什么"的诊断载体;下游各渲染面因此只有静态 per-kind hint 可用。根因在决策点缺通道,不是某个渲染层缺字段。

3. 影响范围与严重程度:影响"配了 env/system 代理但模式留 unset + 直连被黑洞/拒连"的用户(即 #2809 场景);程度 = 体验/诊断缺陷,对既有行为零影响(egress 不变)。

4. 怎么修复的:修在源头(decision point)而非显示层——default-direct 短路内对共享 auto-detect tail(NO_PROXY→env tier→Windows bypass→system proxy,原样抽成 autoDetectProxy)做一次性只读 peek,结果挂到 decision 的新字段 skippedProxy(diagnostic-only,无任何路由消费者)。unset vs explicit-direct 用内部 flag defaultDirect(=rawProxyMode === undefined && !biliProxy,与 #1012 aux 区分同语义系);显式 direct 永不 nag。所有显示面共享一个 hintWithSkippedProxy helper + 一个 redactProxyUrl(原样搬到 upstream-fail.ts 共享底层),渠道不会漂移;web banner 用新 i18n key alert.note.skipped_proxy(zh+en parity)从结构化字段渲染本地化措辞(#1024 纪律)。三重门控:仅 fail-fast kind / 仅 unset mode / auto chain 对该 host 确实解出代理(用户自己的 NO_PROXY/ProxyOverride 排除被尊重 → 不点名)。

5. 是否有回归问题:未发现。逐项审过的既有行为:

  • egress 行为:ZCode 会话消息丢失:接入 bili MITM 后,旧会话打开无消息、新会话切换后丢失 #346/fix: default upstream proxy to direct; add gost-style -F forward flag (#346) #357 的 IP-bound-OAuth 设计 intact——default-direct 的 decision.proxy 保持 undefined、source 保持 "direct",peek 从不喂路由(代码通读 + 测试钉死 d.proxy === undefined)✅
  • explicit-direct 字节级身份:deepEqual({source:"direct"}) 被新 suite 与 routing fixture 双钉 ✅
  • auto/manual/provider/no-proxy/windows-bypass 流:tail 原样抽取,shape 不变(2 个 fixture 因新增 defaultDirect 字段更新,测试内注明)✅
  • legacy hint 字节级身份:无 skipped 信息时输出精确以 UPSTREAM_FAIL_HINTS[kind] 结尾(assertion 作回归守卫)✅
  • alert 表:dedup key (kind,host)、MAX_ALERTS 淘汰、成功即清全部未动;新字段 additive optional,无 skipped 时无 stray fields(有断言)✅
  • loop re-request log / admin probe / 502 detail:均只透传新可选参数;handle.ts/dispatch 管道未改(error 字符串走既有 catch)✅
  • peek 成本:非 win32 no-op;win32 registry 读取 5s 缓存 + 3s timeout + try/catch——与既有 auto mode 成本画像相同,无新 per-request 开销 ✅
  • i18n:zh/en catalog parity + literal-reference lint 绿(CI docs-sync/lane-guard 已过)✅
  • 一个边界判为可接受:alert 活跃期间若中途切换模式,旧 skipped 字段会滞留到下次成功清 alert(自愈、cosmetic;alert 语义本就是 live-traffic 证据窗口),不值得为此改 dedup 语义或立项。

6. 是否破坏缓存:不涉及——prefix cache/session persist/增量游标/去重键均未动(alert dedup key 不变)。

7. 是否改了设计方向:没有。纯增量诊断通道;架构/边界/数据流不变(诊断信息挂在既有 decision 对象上,经既有失败面渲染)。

8. 是否引入新配置:没有。无新 config 字段/env var/CLI flag;defaultDirect 是内部派生 flag,点名的三个 opt-in(config auto/env var/provider lane)均已存在且有文档。

验证证据:

  • 12 文件 diff 逐行读(vs 描述核对):gating、masking、字节级身份、aux inertness 全部属实;UPSTREAM_FAIL_HINTS 直接引用只剩 helper 内部一处,无漂移渠道。
  • 本地定向验证:tests/skipped-proxy-hint.test.ts + tests/upstream-proxy-routing.test.ts = 25/25 pass @ c750c3e(全量回归按纪律交给 CI)。
  • CI @ c750c3e:27/30 completed/success(含 kernel-guard、config-surface-guard、build-artifact、theorem、real-image billing e2e、codex/dsh/pi/opencode real-client lanes、hermetic registry e2e ×2),0 failure;余 3 个 test 矩阵 job(ubuntu/windows 的 node22 + windows24)仍在跑,出结果我再确认一次。
  • 基线:master 自 PR 建立后仅前进 fix: allow bugfix-release/* carve-out branches in ci.yml version-guard #2859(ci.yml version-guard + release.md,与本 PR 零文件交集),无需 rebase。
  • diff 整洁度:每一行都服务于本 PR 目的(诊断路径 src + 恰好 2 个测试文件),无无关改动。

判定:代码与行为均达标,可合(待最后 3 个 CI 矩阵 job 收尾确认,目前零失败)。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 CI 收尾确认:最后 3 个 test 矩阵 job(ubuntu/windows × node22、windows24)已全部完成——30/30 check runs success,零失败 @ c750c3e。上一条 review 结论不变:可合。

@ranxianglei
ranxianglei merged commit f5631ed into master Oct 12, 2026
30 checks passed
@github-actions

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.314-master.f5631ed (rolling master tag).

npm install -g billion-context@0.0.314-master.f5631ed  # this exact build
npm install -g billion-context@master  # always the newest merged build

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

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

Labels

None yet

Projects

None yet

1 participant