Skip to content

fix: fail fast on dead upstreams — round-level circuit breaker + acp_status visibility (#3148) - #3154

Merged
ranxianglei merged 3 commits into
masterfrom
2026-10-14_upstream-circuit-breaker
Oct 15, 2026
Merged

ranxianglei merged 3 commits into
masterfrom
2026-10-14_upstream-circuit-breaker

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Closes #3148

(ai: vllm-qwen/qwen3.8-27b)

修什么

#3148 证实:上游在会话中途不可用时,bili 没有「轮级记忆」——dsh 每重试一轮,bili 都完整烧一遍请求内重试阶梯(~4.5s)再全量冷发一次上下文;20 连击 ≈4.8MiB 全部发往已证明死掉的端点。compress 路径早有 3 连败熔断,上游路径没有;紧急收缩、输出钳制、最后一次上游失败三种状态也只存在于 bili.log,acp_status 看不到。

两处改动(机制层,无新配置项):

1. 上游熔断(src/upstream-alerts.ts + src/server/relay.ts)

2. 失败状态可见性(src/acp-status.ts + session.ts + cache-ledger.ts + budget.ts + prepare-{openai,responses,google}.ts)

  • acp_status 新增三段,仅在非平凡时渲染:UPSTREAM CIRCUIT OPEN(host、连续失败数、起始时间、最后失败详情、下次探针时间);EMERGENCY SHRINK ARMED(估计值 + arm 时间;marker 在 arm 时写入、下一次真实 usage report 清除);OUTPUT BUDGET CLAMP(最近一次钳制事件 raw→capped/window/input + sticky planning floor dsh压缩与bili压缩冲突 #2490)。
  • 纯展示层:不触碰任何 wire 决策。

行为变更(旧 → 新)

项 旧 新 原因
对已证明死亡端点的请求(≥3 次连续 pre-response 失败后) 每次烧完 3-attempt 重试阶梯(~4.5s)+ 全量冷发,502 upstream request failed: … fail-fast,502 detail 以 upstream circuit open: <host>: N consecutive pre-response failures … next probe <ISO> — stop resending full context 开头 停止放大故障,给宿主可行动信息
acp_status 输出 无上游失败相关内容 熔断打开 / shrink armed / clamp floor 存在时各增一行 用户报告的可见性缺口
session.stats 持久化格式 — 新增 3 个可选字段 emergencyShrinkAt / emergencyShrinkEstimate / lastOutputClamp(additive,旧文件不受影响) 可见性状态需跨重启存活

不变:请求内重试阶梯(network.replayRetryMax/BaseMs)、5xx passthrough、所有状态码、#2490 sticky floor 语义、nudge 策略。

config surface

未新增。熔断阈值(3)与冷却(60s)为内部常量,镜像 compress-loop breaker 先例(同样无配置项)。如需可配置化,建议 owner 后续拍板形态(如挂 network.* 下),本 PR 不擅自建形状。

测试

  • 新增 tests/issue3148-upstream-circuit.test.ts(8 例):开/关/中途重置/半开单飞/不计入种类/host 隔离;精确复现 reporter 的 65536→1360 clamp 数学 + hook 不改变 wire 决策;acp_status dirty/clean fixture;usage report 清 marker。全绿。
  • 相邻套件全绿:acp-status、upstream-alerts、issue2490-ledger-floor-doomed-probe、issue2122-clamp-calibration、issue2096-clamp-headroom-window、issue2558-clamp-image、deferred-tool-budget、cache-ledger、issue1547-nonstream-cache-ledger(共 86 例本地定向)。
  • typecheck clean、build green。全量以 CI 为准。

相关但不在本 PR 范围(见 issue 回复)

…status visibility (#3148)

A mid-session upstream outage was amplified per round: every host-driven retry burned the full in-request ladder (~4.5s) plus a full cold resend of the context, with no round-level memory that the endpoint was already proven dead. The compress path had a 3-strike breaker; the upstream path had none.

- upstream-alerts.ts: per-host circuit — 3 consecutive FINAL pre-response transport failures (connect-refused/connect-timeout/dns/proxy-reset/upstream-reset; timeouts+aborts+5xx deliberately excluded) open it; any resolved response closes it; half-open admits exactly one probe after a 60s cooldown, a failed probe re-arms.

- relay.ts forward(): while open, requests fail fast BEFORE any fetch with the last failure kind/detail/time and the next-probe ETA in the error (surfaces as the existing 502 detail — no status-code change); the fast-fail round still arms emergency shrink and drops attached retrievals like a network failure.

- acp_status: new sections rendered only when non-trivial — UPSTREAM CIRCUIT OPEN, EMERGENCY SHRINK ARMED (marker now recorded at arm time and cleared by the next real usage report), OUTPUT BUDGET CLAMP (last clamp event + sticky #2490 planning floor). Display-only; no wire decision changes.

No new config/env/CLI surface; breaker constants are internal (knob-ization owner-gated). Regression tests: tests/issue3148-upstream-circuit.test.ts (8 cases incl. the reporter's exact 65536->1360 clamp math).
@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-14_upstream-circuit-breaker (eea8248)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.3603-pr.3154.10b0376

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-pr3154.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

(ai: vllm-qwen/qwen3.8-27b)

收到,开始独立审核 PR #3154:拉分支核对代码、对照原 issue #3148 验证方向、过回归面与测试有效性、查 CI。结论按结构化八问回复。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

独立审核进行中,先报两个已当场修掉并推入 PR 分支的发现(eb90660f5 之上追加 2 个独立标注 commit,head 现为 eea8248eb):

1. CI 红:unused-exports 门禁失败。 根因:本 PR 新增的 UpstreamCircuitFailure / UpstreamCircuit 两个 interface 只在本文件内被引用(门禁判 INTERNAL_ONLY)。修法:去掉 export(消费方经 getOpenUpstreamCircuits() 返回值推断使用,不受影响)。本地门禁复跑通过。此前 test / static-gates 两个 job 显示 skipped,是被这个门禁红按 #2637 fail-fast 分层挡掉的连带结果——修复后全量测试矩阵已在跑。

2. 熔断器自身的状态机缺陷(代码审出,非既有行为回归)。 半开探针以「不计入」种类的失败结束时(超时 / 客户端中止 / unknown——即不在 ALERT_KINDS 里的),recordUpstreamCircuitFailure 提前 return,不释放单飞槽位(probeInFlight 卡死为 true)→ 该 host 从此永久 fail-fast:即使端点完全恢复,进程重启前也不会再发探针。可达场景:熔断打开后 host「半恢复」(接受 TCP 但响应挂起 → headers timeout),或 dsh 在探针在途时取消请求(AbortError)。修法:open 状态下任何种类的最终失败都释放槽位并重置冷却(不计入的结果既不证明活也不证明死,但槽位必须归还,冷却照旧防再次放大);补了回归测试并做了证伪验证(旧代码上该测试失败、新代码通过)。

本地定向验证:unused-exports 门禁绿、tests/issue3148-upstream-circuit.test.ts 9/9 过(含新例)、typecheck clean。全量以 CI 为准,全绿后按结构化八问给最终结论。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

独立审核完成(未照抄 #3148 侧结论,diff 逐文件重读、行为逐项清点)。审核中发现两处问题已当场修掉并推入分支(a346e8807 门禁修复、eea8248eb 状态机修复+回归测试),新 head eea8248eb CI 43/43 全绿(含此前被门禁红挡掉的 test/static-gates 全量矩阵),PR mergeable。按八问给结论:

1. 是什么问题:上游端点在会话中途不可用时,bili 没有轮级记忆——宿主每重试一轮,bili 都完整烧一遍请求内重试阶梯(~4.5s)再全量冷发一次上下文到已证明死掉的端点(#3148 现场:20 连击 ≈4.8MiB);同时熔断外的三种失败状态(紧急收缩 armed、输出钳制、上游失败)只存在于 bili.log,宿主/模型看不到「为什么这轮失败」。

2. 什么原因导致的:compress 路径早有 3 连败熔断,上游路径从未有过对等的轮级状态(每请求无状态是既有设计);可见性状态写在 warn 日志行里、没有落到 session.stats,acp_status 自然读不到。

3. 影响范围与严重程度:所有「上游中途失联 + 宿主会重试」的会话(dsh 模式最典型)。修前属体验/带宽放大问题而非正确性缺陷:不丢数据,但每轮多付 ~4.5s 延迟 + 完整 payload 重发,且用户无从判断端点是否真的死了。可见性缺口为诊断便利级别。

4. 怎么修复的:机制层两件事——① 按 host 的上游熔断:连续 3 次最终 pre-response 传输失败(口径与 #1682 ALERT_KINDS 完全一致,含 tls;不含超时/客户端中止/5xx)打开,打开期间 fetch 之前 fail-fast,错误走既有 502 detail 通道(状态码不变),带最后一次失败的 kind/detail/时间 + 下次探针时间;60s 冷却后半开单飞探针,任何已解析响应(含 5xx)立即关闭。② 纯展示层可见性:acp_status 三个条件段(UPSTREAM CIRCUIT OPEN / EMERGENCY SHRINK ARMED / OUTPUT BUDGET CLAMP),数据来自 session.stats 新增可选字段(armFailureShrink 写入 shrink marker、下一次真实 usage report 清除;clamp 经可选 hook 在既有日志行之后记录)——不触碰任何 wire 决策。
审核追加的两处修复(行为变更披露):a) 本 PR 初版让 unused-exports 门禁红(两个仅内部引用的 interface 被 export),连带 test/static-gates 被 fail-fast 分层跳过——去 export 修复;b) 半开探针以「不计入」种类失败时(超时/客户端中止/unknown),原实现提前 return 不释放单飞槽位,该 host 会永久 fail-fast 直到进程重启(可达场景:host 半恢复接受 TCP 但响应挂起、或 dsh 在探针在途时取消请求)——改为 open 状态下任何种类的最终失败都释放槽位并重置冷却。旧值→新值:探针不计入失败后「永久锁死」→「归还槽位+60s 后再探」;回归测试已证伪验证(旧代码失败/新代码通过)。

5. 是否有回归问题:审了 diff 触碰路径的全部既有行为,结论均为保持——正常失败路径错误串字节不变(failureDetail 同一 formatUpstreamError 结果);成功路径不变(+1 幂等关闭调用);armFailureShrink 抬升逻辑与 markDirty 不变(+2 附加字段);settleUsageReport 既有写入不变(+2 附加删除);clamp 数学不变(测试钉住 reporter 精确数字 65536→1360,hook 前后一致,健康场景零调用);acp_status 无状态时完全静默(clean fixture 钉住);持久化字段全部可选附加(旧文件不受影响);5xx passthrough、nudge 策略、#2490 sticky floor 语义、重试阶梯常量均未动。高危模式逐项过:无吞错(fail-fast 仍 throw 仍 502,detail 更明确)、无阈值/时序漂移、输出格式变化仅限披露的新增展示行与新失败路径的前缀 upstream circuit open:。一个有意的小语义点:熔断打开期间对该 host 的 GET/旁路流量也 fail-fast(host 已被证明不可达,一致语义);客户端取消探针会把下次探针推迟至多一个冷却期(防放大的代价,可接受)。范围核查:claim 2 饿死链(floor sticky × input 永不收缩)确属 #3071 症状族、由在途 PR 覆盖,本 PR 正确地只加可见性不动钳制下限;claim 4 的 nudge idle 比例是 kernel decideNudge 的设计行为,不在本 PR 范围——均同意。

6. 是否破坏缓存:不涉及。前缀缓存/ledger/重放游标零改动;fail-fast 时的 dropRetrievals 与既有网络失败路径同一语义(附件全文没到过模型就丢弃并留痕)。

7. 是否改了设计方向:没有转向。是对既有告警/熔断家族(#1682 告警表 + compress-loop 熔断先例)的同构扩展;刻意不建配置面(阈值 3 / 冷却 60s 为内部常量,镜像 compress-loop breaker 同样无配置项的先例),PR 里已注明如需可配置化建议挂 network.* 下由 owner 拍板——同意这个处理。小瑕疵一处不拦:PR 正文列举计入种类时漏写了 tls(代码实际与 ALERT_KINDS 完全一致,含 tls,描述少列了一个词)。

8. 是否引入了新的配置:无。无新 env/config/默认值。

判定:可合并。 head eea8248eb,CI 43/43 success(含全量 test 矩阵),mergeable=True。合并动作按惯例留给 owner。

@ranxianglei
ranxianglei merged commit bf92293 into master Oct 15, 2026
43 checks passed
@github-actions

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.433-master.bf92293 (rolling master tag).

npm install -g billion-context@0.0.433-master.bf92293  # 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.

@ranxianglei
ranxianglei deleted the 2026-10-14_upstream-circuit-breaker branch October 15, 2026 05:33
ranxianglei pushed a commit that referenced this pull request Oct 15, 2026
…ssed by #3101's re-pin)

#3154 (merged 2026-10-15 09:35) pinned the #3148 clamp event at capped=1360. #3101 (merged 2026-10-15 20:30) introduced the owner-signed #3071 floor floor_out=min(4096, window-input) and re-pinned the pre-existing #2122/#2558 pins, but its re-pin commit predates #3154, so the newer #3148 pin stayed stale and every CI test shard touching this file has been red since. Both asserts (event.capped and rebuilt.max_tokens) come from the same floored value in clampOutgoingOutput; headroom 51228 >= 4096 so the floored value is 4096. The tooth still bites: the scenario still clamps 65536 far below the requested budget.
@github-actions github-actions Bot mentioned this pull request Oct 17, 2026
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