Skip to content

fix: close dead-port race in zcode-native + upstream-alerts tests (#2548) - #2551

Merged
ranxianglei merged 1 commit into
masterfrom
2026-10-09_dead-port-race-guard
Oct 9, 2026
Merged

ranxianglei merged 1 commit into
masterfrom
2026-10-09_dead-port-race-guard

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Closes #2548

What

The CI flake from #2547's run — bootstrapZcodeNative fails closed on an unhealthy attach target — is a released-port race, not a product bug. Two test helpers hand out a listen(0)+close port and assume it stays dead; under parallel npm test another process can rebind it before the consumer acts.

Fix (per the issue's two-layer plan)

zcode-native (deadOrigin() → withUnhealthyOrigin(), 3 sites) — deterministic. The helper no longer releases the port; it keeps a live server bound for the whole test that answers 500. probeProxyHealth judges a 500 answer unhealthy (it returns true only for a 2xx/404 JSON body whose text starts with { and contains "ok"), so the "unhealthy" expectation is constructed, not assumed. The race is closed rather than narrowed — a late assertPortDead still has the residual window its own header comment admits ("a squatter can still land in the final gap"). Mirrors the existing withHealthServer idiom in the same file.

upstream-alerts (freePort(), 1 of 2 sites) — transitional guard. Its consumer asserts kind === "connect-refused", which cannot be constructed with a live server (a hung socket is connect-timeout; a 500 is a real HTTP response). So this site uses assertPortDead(port, { label }) immediately before the first dial, matching log-mask.test.ts (#1689).

Deliberate deviation from the issue checklist

The issue lists 5 unguarded sites (deadOrigin ×3, freePort ×2). This PR guards 4 and leaves tests/upstream-alerts.test.ts:399 unchanged, because verification shows that site is not actually vulnerable:

  • That test seeds alerts in-memory via recordUpstreamAlert(...) and only polls /__bili/overview.
  • sendOverview (src/server/admin.ts) reads fs/in-memory state only (sessions, alert table, advisory, in-flight, blind-tunnel stats) — it never connects to the configured upstream. The VM harness never clicks the upstream-test button either.
  • So the freed port there is decorative and is never dialed. Adding assertPortDead would introduce a new flake: if a squatter takes the port, the guard throws even though the test does not care whether the port is dead.

Guarding a port the test never consumes would create the very flake class this PR removes.

Behavior change / config surface / cache

  • Production behavior: none — test-only change; no src/, kernel/, wire protocol, config schema, or persistence touched.
  • Config surface: none.
  • Cache / retry / cursor / dedup keys: none.

Verification

Rebased onto current master (4b5666406). On the rebased head:

  • npm run typecheck clean (rebuilds kernel/ + pi-subagents/).
  • Targeted node --import tsx --test tests/zcode-native.test.ts tests/upstream-alerts.test.ts: 42 pass / 0 fail. These two files are the only ones changed; the full suite is left to CI.

)

zcode-native's deadOrigin() released its listen(0)+close port and assumed it stayed
dead; under parallel 'npm test' another process could rebind it inside the 300ms
health window, so probeProxyHealth saw a live answer and the expected refusal
flipped to an active attach (the #2547 CI flake). Replace it with a live server
bound for the whole test that answers 500 - probeProxyHealth judges a 500 answer
unhealthy - so the unhealthy expectation is constructed, not assumed: the race is
closed rather than narrowed.

upstream-alerts' freePort() feeds a connect-refused assertion, which cannot be
constructed with a live server (hang = connect-timeout, 500 = a real response);
guard its real consumer with assertPortDead right before the first dial, matching
log-mask (#1689). The banner site never dials the port (/__bili/overview reads
fs/in-memory state only), so it is left unchanged - adding a guard there would
introduce a new flake.

Closes #2548
@github-actions

github-actions Bot commented Oct 9, 2026

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-09_dead-port-race-guard (555442c)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.2731-pr.2551.11eabf2

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-pr2551.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 #2551(分支 2026-10-09_dead-port-race-guard,head 555442c46)。基线核对:head 正好是 master 4b5666406 + 1 提交(git rev-list --count pr..master = 0,GitHub API 的 "behind" 状态是陈旧数据)。

查重:按机制关键词(released-port race / deadOrigin / freePort / #1689 follow-up)检索 open+closed issue——无重复项;#2548 是该机制家族(#1689 后续)的唯一定向 issue,单 issue → 单 PR,loop guard 合规。

① 原 issue 方向关:#2548 的诊断成立。因果链从代码复核过:deadOrigin() 做 listen(0)+close 后假设释放端口保持死亡;并行 npm test 下其他进程在健康窗口内重绑该端口,probeProxyHealth 接受任何 live 应答 → "死亡"目标答成 healthy。#2547 CI 那一格红是表面现象,根因是"释放后假设死亡"这个 producer。PR 修在 producer 侧(zcode 侧不再释放端口、期望改为构造),不是症状层拦截;唯一无法构造的位点(connect-refused 语义)用过渡守护对齐 log-mask(#1689)既有做法。方向正确,方案打到核心。

结构化八问:

  1. 是什么问题:两个测试 helper 把 listen(0)+close 释放掉的临时端口当作永久死亡,并行测试负载下别的进程可重绑它,把"预期拒绝/unhealthy"翻成"live 应答"——间歇性 CI 红,且未来真实回归可能被当成"又是端口 flake"放行。
  2. 什么原因导致的:helper 释放端口后假设其保持死亡;竞态窗口 = 释放→消费之间的间隙(flaky CI: freed-port tests race on port reuse (log-mask #255 tunnel test got HTTP 200 instead of 502) #1689 已命名)。非产品 bug。
  3. 影响范围与严重程度:仅 CI 间歇性红(单事件低严重度、会复发);零生产影响。
  4. 怎么修复的:两层,按 issue 计划执行——zcode 3 处改 withUnhealthyOrigin(整测试期持有答 500 的 live server;已核 probeProxyHealth 对 500 在 src/zcode/native.ts:59 res.status >= 500 → false,期望被构造而非假设,竞态彻底关闭);upstream-alerts 的 connect-refused 位点无法用 live server 构造(hang=connect-timeout、500=真实 HTTP 应答),故首次拨号前紧贴 assertPortDead。有意偏离一处成立::399 banner 测试查证后确不脆弱——它只对 chatgpt.example.com 内存播种告警并轮询 /__bili/overview,sendOverview(src/server/admin.ts:588-621)纯 fs/内存态,且整个 admin.ts 无任何出站连接(grep 无 fetch/http.request/net.connect);那个释放端口是装饰性的、从未被拨号,加守护反而引入新 flake。
  5. 是否有回归问题:无。逐点清点两文件既有行为:zcode 三个断言语义不变(probe→false / bootstrap rejects /not healthy/ / drift→"repointed-self");upstream-alerts transport-failure 仍验证 connect-refused、banner 测试完全未动。高危模式逐项过:无语义漂移;无 fail-fast→吞错(方向相反——静默错果变带 flaky CI: freed-port tests race on port reuse (log-mask #255 tunnel test got HTTP 200 instead of 502) #1689 标签的响亮失败);无阈值/时序/输出格式变化。diff 只碰 tests/ 两文件,零 src//kernel//wire/config/persistence。
  6. 是否破坏缓存:不涉及(纯测试)。
  7. 是否改了设计方向:不涉及(测试正确性收紧:假设→构造)。
  8. 是否引入了新的配置:不涉及。

验证证据(均在 rebase 后的 head 上本地执行):

  • npm run typecheck 干净(kernel + pi-subagents 经 pre-hook 重建)。
  • 定向 node --import tsx --test tests/zcode-native.test.ts tests/upstream-alerts.test.ts:42/42 pass,与 PR 描述一致。
  • 补充定向压测:后台跑激进 listen(0)+close 端口抢占器,连跑 3 轮 zcode-native 套件——3×34 pass / 0 fail。新 helper 全程不释放端口,squatter 无机可乘,证实竞态是结构性关闭而非收窄。
  • CI:21/25 绿(含 kernel-guard / version-guard / lane-guard / unused-exports / build-artifact 及全部 e2e lane);余 4 个为全量 npm test 矩阵格(in_progress)——恰是本修复要验证的并行负载通道,落地后全绿即可合。
  • 代码级核对:assertPortDead(port, { label }) 签名与 tests/port-race.ts:23 一致;withUnhealthyOrigin 与同文件 withHealthServer 逐行同构(仅应答不同);closeAllConnections() 需 Node ≥18.2,CI 矩阵为 22/24;PR 分支无 deadOrigin 残留引用(grep 0 命中)。

diff 整洁度:2 文件 +37/-14,每行都服务于本 issue,注释均引 #2548/#1689 且与代码事实相符;无无关改动、无空行/重排噪音。

判定:可合并——纯测试确定性修复,零生产行为变更,issue 两层计划完整落地,唯一偏离有代码证据支撑,本地定向验证(含抢占压测)全部通过。等人工合并:#2551

@ranxianglei
ranxianglei merged commit 47dd1b1 into master Oct 9, 2026
25 checks passed
@github-actions

github-actions Bot commented Oct 9, 2026

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.195-master.47dd1b1 (rolling master tag).

npm install -g billion-context@0.0.195-master.47dd1b1  # 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

Development

Successfully merging this pull request may close these issues.

test: unguarded expect-dead port helpers race under parallel npm test (zcode-native deadOrigin x3, upstream-alerts freePort x2) — #1689 follow-up

1 participant