Skip to content

fix: preflight transport resilience + shipped-payload baseline anchor (#1987) - #1989

Merged
ranxianglei merged 2 commits into
masterfrom
2026-10-03_preflight-transport-resilience
Oct 3, 2026
Merged

ranxianglei merged 2 commits into
masterfrom
2026-10-03_preflight-transport-resilience

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Closes #1987

What this changes

One mechanism family — the preflight compression pipeline's failure handling and meter anchoring — four sub-defects:

B1 — In-loop retry parity for summary calls (src/preflight.ts)
TRANSIENT_SUMMARY_CODES missed ENOTFOUND, UND_ERR_CONNECT_TIMEOUT, ECONNABORTED — classes the main model-request path retries via isFailFastUpstreamKind (#1263/#1453). A summary call died faster than the request it protects. Sets now align; TLS trust failures stay OUT of both paths on purpose (a bad CA does not self-heal inside the backoff window).

B2 — Transport-class preflight failures are client-retryable (src/preflight.ts catch → PreflightFailure.retryable)
Any transport death whose code fell outside the narrow transient set (cert errors, gzip corruption, unknown) produced retryable=false → the client treated the turn as terminally failed and every later turn hit the same 502 (the session block reported in #1987). A transport-class death carries NO upstream verdict about the content — the call simply did not complete — so it is now always marked retryable: true. Aborts (client gone) keep their field omitted as before.

B3 — TLS trust codes classify as tls, not unknown (src/upstream-fail.ts)
DEPTH_ZERO_*, UNABLE_TO_VERIFY_LEAF_SIGNATURE, SELF_SIGNED_CERT_IN_CHAIN, UNABLE_TO_GET_ISSUER_CERT_LOCALLY now map to kind tls (was unknown). Pure classification change: tls is already non-fail-fast on the main path, so no retry-behavior change — logs/status/hints become correct.

B4 — CA remediation hint in the client-facing error (src/preflight.ts)
When the surfaced code is a certificate-trust code, the fail-fast error detail names the remedy: NODE_EXTRA_CA_CERTS=/path/to/ca.pem or node --use-system-ca. No new config surface: both mechanisms are already honored today (undici's default root store applies through bili's custom dispatcher).

A — Baseline anchored to what actually ships (src/server.ts + src/preflight.ts)
The post-compression meter anchor used the kernel's no-emergency-truncate view, which keeps tool outputs that prepare() trims near the window edge — hence "~42619 tokens saved (2309870 → 2818817)" (post > pre) and every later meter inflated until a real usage report landed. The anchor now sits on the rebuilt normal-config payload (text + wire overhead; images still excluded per the #857 never-persist-the-image-floor rule). The log line moved after the rebuild so it prints two values from the same channel.

D — Chunking waste when assembled summaries exceed maxSummaryLength: rides open PR #1818 (commit c180330, truncate-to-cap rescue). Same file region; deliberately not duplicated here.

C — Inconsistent window denominators (750000 vs 872000): by design, no code change. Effective window = native − min(maxOutput, 0.25×native); maxOutput resolves per request from wire field → runtime-info → launcher env → configured value → registry. For deepseek-v4.1-flash (registry: 1M context / 384k output): registry fallback ⇒ 1M − 250k = 750000; a request carrying maxOutput=128000 (e.g. host-configured limit) ⇒ 1M − 128k = 872000. Different sessions/integrations hit different tiers.

Behavior changes (old → new)

  • preflight_compress_failed 502 on transport-class failures: retryable false → true (every non-aborted transport death: cert/DNS/timeout/gzip/unknown). Hosts may now treat these as transient instead of terminal.
  • Summary-call in-loop retry set widened: ENOTFOUND / UND_ERR_CONNECT_TIMEOUT / ECONNABORTED now get up to replayMaxAttempts() attempts (default 3, existing knob BILI_REPLAY_RETRY_MAX; backoff 1.5s/3s). Wall-clock cost stays bounded per attempt.
  • Post-compression log value + persisted baseline: derived from the rebuilt/shipped payload instead of the untruncated kernel view — can be LOWER than before near the window edge (intended: it matches what actually ships).
  • Log line suffix "; rebuilding payload" removed (the rebuild now happens before the line).
  • DEPTH_ZERO_* etc. now log/report kind=tls with a CA hint instead of kind=unknown.

Config surface

None added. NODE_EXTRA_CA_CERTS / --use-system-ca already work today; BILI_REPLAY_RETRY_MAX / BILI_REPLAY_RETRY_BASE_MS are existing knobs referenced here.

Modes

Preflight runs identically in plugin mode and proxy mode; this PR touches neither wire shape nor message rebuild — only failure classification, retry sets, meter anchoring, and log placement.

Tests

  • tests/upstream-fail.test.ts: 5 new trust-code classification cases (+ wrapped cause-chain case).
  • tests/preflight-transport-recovery.test.ts: gzip/unknown-error cases now pin retryable === true; new tests for connect-timeout/DNS in-loop retry parity and for TLS trust failures (no in-loop retry, but client-retryable with the CA hint in the detail).
  • tests/issue1987-preflight-baseline-anchor.test.ts (new e2e): reproduces the user regime — 300k-token raw payload vs a stale 240k usage baseline at a 10k window; preflight exhausts its budget leaving the untruncated view at ~219k while the rebuilt payload is ~48k; pins that the persisted baseline stays at netted-meter scale (< 190k) instead of rising to the untruncated view (old code would record 218977 > bound). Deterministic across runs.

Sync with master (#1933 k-hat estimate calibration + others). Conflict in
preflightCompressIfNeeded resolved by union: keep the #1987 shipped-payload
baseline anchor + moved log, keep the #1933 calibrated fit judgment on the
same rebuilt-text value.
@github-actions

github-actions Bot commented Oct 3, 2026

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-03_preflight-transport-resilience (f286ec1)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.2005-pr.1989.023b05e

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-pr1989.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] 🏷

PR #1989 review 结论(fix #1987:preflight 传输韧性 + shipped-payload 基线锚定)

① 是什么问题:企业 TLS 拦截环境下,preflight 的 summary 调用死于证书信任错误 → 502 retryable=false → 客户端把该 turn 当终态失败,此后每个 turn 都撞同一个 502,会话永久卡死;同时压缩后 meter 基线锚在 kernel 未截断视图上(用户日志 "~42619 tokens saved (2309870 → 2818817)"、post > pre),之后所有 meter 虚高直到真实 usage 报告落地。

② 什么原因导致的:同一机制家族(preflight 失败处理 + meter 锚定)四个子缺陷——B1 summary 调用的瞬时错误集合比主请求路径窄(缺 ENOTFOUND / UND_ERR_CONNECT_TIMEOUT / ECONNABORTED,#1263/#1453 主路径都重试它们);B2 窄集合之外的任何传输层死亡都被标 retryable=false,但传输死亡不携带任何关于内容的上游裁决(调用根本没完成),"终态"判定没有依据;B3 TLS 信任码被分类成 unknown 而非 tls(纯分类错误);A 基线锚用了 kernel 的 no-emergency-truncate 视图,而实际发出的是 prepare() 在窗口边缘截断后的 payload。C 项(750000 vs 872000 分母不一致)按设计成立(effective window = native − min(maxOutput, 25%·native),不同 maxOutput 解析层级命中不同值),不改码;D 项(maxSummaryLength 超长的 chunking 浪费)由 #1818 承载,此处刻意不重复。

③ 怎么修复的:B1 把 summary 调用重试集合与主路径对齐(TLS 信任错误两条路径都刻意排除——坏 CA 不会在 backoff 窗口内自愈);B2 一切非 abort 的传输死亡统一标 retryable=true(abort 保持字段省略),语义诚实:"调用未完成"而非"内容不行";B3 信任码归入 tls;B4 对证书信任码在 client-facing 错误里给出 NODE_EXTRA_CA_CERTS=/path/to/ca.pem 或 node --use-system-ca 补救提示(无新配置面,两个机制今天就生效);A 把锚点从 preflight 尾部移到 server.ts rebuild 处,锚在实际发出的 payload(text + wire overhead,图片仍按 #857 排除),日志行移到 rebuild 之后,两个数值出自同一通道。

④ 回归审查(触碰路径既有行为逐项清点):

⑤ 是否破坏缓存:不影响前缀缓存/重试策略/去重键。仅 meter 基线的来源变化(kernel 视图 → 实际发出 payload),持久化的 lastInputTokens 在窗口边缘附近可比之前更低(有意:与实际发出一致);不触碰 head system message 字节稳定性,前缀缓存不受影响。

⑥ 是否改了设计方向:没有转向。失败分类/重试集/meter 锚定/日志位置都在既有机制家族内;"锚在实际发出的东西上"与 #1933 "gate/exit/fit 同一尺度判断 payload" 的方向一致且分工明确(fits 用校准尺度,锚用 raw 地板)。

⑦ 是否引入新配置:无。NODE_EXTRA_CA_CERTS / --use-system-ca 今天就生效;BILI_REPLAY_RETRY_MAX / BILI_REPLAY_RETRY_BASE_MS 是既有旋钮。

测试有效性:三个测试文件都有牙——gzip/unknown 钉 retryable===true(原为 undefined)、abort 钉字段省略、connect-timeout/DNS 钉 attempts===3 用满预算、TLS 信任钉 attempts===1 + 前两个码有 CA 提示/EPROTO 无提示 + secret 不回显;新 e2e(issue1987)复刻用户 regime(300k raw vs stale 240k usage @ 10k window):旧代码会把基线写到未截断视图 ~219k > 190k 上界并把 source 翻成 estimate,测试断言 <190k && source==="usage",确定性(port 0、hermetic mock upstream;场景内 k̂ 学不出来——需 ≥2 个一致样本而场景最多 1 个——故 facet A 独立于 #1933 被钉住)。

合并判定:代码通过审查;唯一阻塞(stale-base 与 #1933 的内容冲突)已修复并推送(f286ec1,GitHub mergeable=True)。CI:e2e/build-artifact/version-guard/各 lane e2e 已绿,test 矩阵(ubuntu/windows × 22/24)+ registry e2e 运行中——结果出来我补报。CI 全绿即可合并。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷

CI 补报:f286ec16 上 15/15 checks 全绿——test 矩阵(ubuntu/windows × Node 22/24)、e2e、build-artifact、version-guard、hermetic registry e2e(ubuntu+windows)、real-image billing e2e、各真实 lane e2e(pi/codex/dsh/opencode)、codex MCP overlay。GitHub:mergeable=True,mergeable_state=clean。

最终判定:可合并。 合并动作按惯例留给人工:#1989

@ranxianglei
ranxianglei merged commit 33d58e5 into master Oct 3, 2026
15 checks passed
@ranxianglei
ranxianglei deleted the 2026-10-03_preflight-transport-resilience branch October 15, 2026 05:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

preflight: one failed summarization call fails the whole turn with a non-retryable 502 and blocks the session

1 participant