Skip to content

refactor(server): extract forward() relay zone into src/server/relay module (#1440 P2 cut 4) - #2429

Merged
ranxianglei merged 2 commits into
masterfrom
2026-10-08_server-relay-extract
Oct 9, 2026
Merged

ranxianglei merged 2 commits into
masterfrom
2026-10-08_server-relay-extract

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

What

#1440 P2 cut 4 (final cut of the four-cut plan): extract the upstream relay zone — export async function forward(...) (1388 lines) and its private recovery companion async function resolveFakeCompletion(...) (60 lines, the #371 fake-completion retry loop) — from src/server.ts into src/server/relay.ts. Pure move: zero behavior change. Monolith 4465 → 2938 lines (−1527); the monolith is under 3k for the first time since the god-file audit.

src/server/relay.ts                  NEW 1561 lines — header comment + import block + zones verbatim
src/server.ts                        −1552/+26 — zones removed; 3 export keywords added;
                                      ONE re-export line; dead import specifiers pruned (tsc-driven)
tests/side-lane-invariants.test.ts   +test (H) — see lane-guard section
reference/architecture.md            +1 module-map row

What co-moves (and what stays)

The zone closes over two module-private helpers whose ONLY runtime callers live inside forward() — they travel as privates (no exports added):

resolveFakeCompletion stays PRIVATE in relay.ts — only forward calls it. prepareCountTokens (the count-tokens dispatcher at the zone boundary) stays in the monolith.

New cross-file surface (exports added in src/server.ts)

Exactly what tsc --noEmit demands for the moved bodies, nothing more (unused-exports gate verifies each is consumed):

group symbols why
fns with both in-zone and out-of-zone callers registerRequestAbort, buildForwardTarget, outboundPayloadBreakdown called from the moved zone AND remaining monolith code — keyword-only export adds
re-export (call-site freeze) export { forward } from "./server/relay.js"; forward's only caller is src/server/handle.ts (cut 3), which keeps importing it from "../server.js" with zero edits; future consumers likewise untouched
type-only type Prepared (already exported) imported via import type in relay.ts — no runtime cycle contribution

relay.ts carries its own import block (~115 specifiers, direct from their own modules, e.g. effectiveAbsorbBlock from ./prepare-responses.js). The server.ts ↔ relay.ts runtime edge is the same cycle class already production-proven by cuts 1–3 (admin.ts, handle.ts, the prepare-* modules): every binding consumed across the edge is a hoisted function declaration or an already-initialized const, no TDZ exposure.

Verification

  • Byte identity: element-wise multiset proof over git diff -U0 — 1506 removed lines matched byte-identical among the 1587 added; every remaining delta sanctioned and enumerated: (a) 3 export keyword adds, (b) 1 re-export line, (c) the 55-line relay.ts import header, (d) 43 removed / 22 rewritten import lines in server.ts (specifiers whose only uses lived in the zone — tsc-driven), (e) blank-line normalization: 0 needed, (f) R3 leading-export removal: 0 (forward stays exported). Comments traveled byte-for-byte.
  • npx tsc --noEmit clean · npm run build (tsup) clean · npm run check:unused-exports clean (relay.ts staged; 2 pre-existing waivers)
  • Local suites (run on the exact push commit): wire-contract family 66/0 · fake-completion + issue473-plugin-fake-completion + e2e-relay-5xx-selfheal + issue2078-outbound-estimate + issue1195-overflow-refold + wire-overhead + issue2117-context-estimate-provenance + ccr-plugin = 74/0 · issue2421-dump-body-buffer + issue2347-dump-sse-plugin-lane + one-call-payload + wire-contract-golden + side-lane-invariants + fork-side-request-lane + side-lane-truth-table + side-request-isolation = 53/0 · e2e-responses-chat-relay + issue2218-relay-affinity-signal = 13/0 — 206 pass / 0 fail
  • Lane-guard literal precheck green (see below).

Why this PR touches tests/side-lane-invariants.test.ts (lane-guard)

Four moved lines read prepared.sidePassthrough (plus one prose "side requests") — the CI lane-guard greps the diff for those substrings and requires a genuine change to one of the four waived lane suites. Test (H) does exactly what the guard wants, honestly: it asserts src/server/relay.ts neither imports side-request.js nor names any engine symbol (resolveSideLane|demoteGate|SideLaneDecision|demotedSide|sideRequestLike|SIDE_REQUEST_MAX_TOKENS|isSideRequest|stripLeakedBiliTools|hasLeakedBiliToolsOnly|restoreOutputBudget|sideRequestGuard). The .sidePassthrough field reads are deliberately ALLOWED — the relay consumes an already-made lane DECISION carried on the Prepared it receives; that is data flow, not coupling, and the test comment says so.

Sequence

Fourth (and final) extraction of the #1440 P2 four-cut plan, on top of merged cuts 1–3 (#2284, #2368, #2424). Remaining approved scope after this: P3 items — runLaunch's ~29 copied client branches and the plugin-install XInstall/XRemove/XStatus registry (each its own PR).

@github-actions

github-actions Bot commented Oct 8, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-08_server-relay-extract (aeed520)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.2657-pr.2429.612d2fb

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-pr2429.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] 🏷 收到。这是 #1440 P2 cut 4 的已实现 PR(分支 2026-10-08_server-relay-extract,单提交叠在当前 master 上;src/server.ts 2938 行、新增 src/server/relay.ts 1561 行,与 spec 完全一致;github-actions 已在 floor 2 构建出包)。

按 [PR] 识别规则我不重做,改为做核验/审查:

  1. 字节一致性——纯移动「零行为变更」是核心声明,逐段比对 moved zone 在旧 server.ts vs 新 relay.ts 是否逐字节一致(只允许 spec 列出的受控 delta);
  2. npx tsc --noEmit / npm run build / npm run check:unused-exports;
  3. 定向测试套件(side-lane-invariants 新测试 H、fake-completion、wire-contract 家族、e2e-relay、outbound-estimate);
  4. CI 状态与高危域(relay 是请求主链路)逐点核查。

完成后按结构化八问给结论。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 核验完成 — 可合(mergeable)。 这是 #1440 P2 cut 4 的已实现 PR,我按 [PR] 规则做审查/核验而非重做,未改动任何代码。分支 2026-10-08_server-relay-extract(单提交 87519a1,叠在当前 master c2dc81b 上)已实现且 github-actions 已构建。

结构化八问

  1. 是什么问题:重构——把上游 relay 区(forward() 1388 行 + resolveFakeCompletion() 60 行)从 4465 行的 god-file src/server.ts 抽到 src/server/relay.ts。纯移动、零行为变更,是 audit: 全仓冗余审计与重构计划——server.ts 解体、客户端矩阵去重、死代码、AGENTS.md 模块图腐化 #1440 P2 四刀计划的最后一刀。
  2. 什么原因导致的:非缺陷,是可维护性驱动。god-file 审计 audit: 全仓冗余审计与重构计划——server.ts 解体、客户端矩阵去重、死代码、AGENTS.md 模块图腐化 #1440 发现 server.ts 达 4465 行;relay 区是最大内聚单元、跨模块耦合最多故最后切。切完单体降到 2938 行——自审计以来首次破 3k。
  3. 影响范围与严重程度:触及请求主链路(forward 是每个模型请求的 relay 路径),若出错影响面=全量请求。但因是逐字节纯移动且全绿验证,实际无行为变更 → 严重度为无。正因高危我才做了严格字节级证明(见下)。
  4. 怎么修复的:纯文本重定位。四个函数逐字节原样搬入 relay.ts(自带 import 块);只加 tsc 要求的 export(3 个 keyword-only:registerRequestAbort/buildForwardTarget/outboundPayloadBreakdown);用一行 re-export export { forward } from "./server/relay.js" 冻结调用点——handle.ts(唯一调用方)零改动;server.ts 剪掉死 import specifier;新增 lane-invariant 测试 (H) 诚实满足 CI lane-guard。
  5. 是否有回归问题:未发现。 逐项审过的既有行为及结论:
  6. 是否破坏缓存:否。 未改 prefix-cache / retry / cursor / dedup-key 任何逻辑。
  7. 是否改了设计方向:否。 延续 audit: 全仓冗余审计与重构计划——server.ts 解体、客户端矩阵去重、死代码、AGENTS.md 模块图腐化 #1440 P2 既有抽取模式(cut 1–3 已合:admin.ts / prepare-* / handle.ts),给 src/server/ 家族加一个模块;re-export 冻结刻意保留现有 import 图,消费方零感知。
  8. 是否引入新配置:否。 零 env/config/CLI flag/默认值变化;version 未动(仍 0.1.188 = master,version-guard 绿)。

证据(本地独立复现,非只看 PR 描述)

  • 字节一致性(核心声明):用 TypeScript 编译器 API 取精确节点区间比对 master src/server.ts vs branch src/server/relay.ts —— 四个函数 code-range 全部逐字节一致:inferWireProtocol(7L)·armFailureShrink(12L)·forward(1388L)·resolveFakeCompletion(60L),行数与 spec 完全吻合。(注:我第一版手写括号匹配器因模板串 ${}/正则处理有 bug 给出假阳性,已换 TS API 复核。)
  • diff 面:server.ts net −1552/+26(与 spec 数字精确一致);26 个新增 = 22 条剪枝后的 import 重写(同源模块、仅删 zone 内唯一使用的 specifier)+ 1 re-export 行 + 3 keyword export。无其他改动。
  • 门禁:npx tsc --noEmit 干净 · npm run build(tsup) 干净 · npm run check:unused-exports 干净(仅 side-request.ts 2 条既有 waiver)。
  • 定向测试:16 个文件 125 pass / 0 fail(side-lane-invariants 含新测试 H、fake-completion×2、e2e-relay-5xx-selfheal、issue2078-outbound-estimate、issue1195-overflow-refold、e2e-responses-chat-relay、issue2218-relay-affinity-signal、wire-contract 家族、wire-overhead、ccr-plugin、issue2117、one-call-payload、dump-body-buffer、dump-sse-plugin-lane)。
  • cross-edge:relay.ts:56 从 ../server.js 消费的符号恰为文档所列;forward 全仓唯一调用方 handle.ts 经 re-export 保持不变。
  • CI:28 个 check-run 全部 completed/success,含 lane-guard ✅、unused-exports ✅、version-guard ✅、kernel-guard ✅、pi-subagents-guard ✅、ubuntu+windows 全量 test ✅、各 e2e lane ✅。

判定

纯移动、零行为变更、无回归、diff 干净最小化、CI 全绿、本地独立复现一致。建议合并(合并动作留给人工)。我未做任何代码改动,也未新立 issue(未发现新问题)。

@ranxianglei
ranxianglei force-pushed the 2026-10-08_server-relay-extract branch from 87519a1 to 1f3b145 Compare October 9, 2026 01:15
@ranxianglei
ranxianglei merged commit 7d5ed5b into master Oct 9, 2026
28 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.169-master.7d5ed5b (rolling master tag).

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

1 participant