Skip to content

refactor(server): extract proxy request pipeline handle() into src/server/handle.ts (#1440 P2 cut 3) - #2424

Merged
ranxianglei merged 2 commits into
masterfrom
2026-10-08_server-handle-extract
Oct 8, 2026
Merged

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

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

What

#1440 P2 cut 3: extract the proxy request pipeline async function handle(...) (1991 lines incl. comments at merge base) from src/server.ts into src/server/handle.ts. Pure move: zero behavior change. Monolith 6436 → 4446 lines (−1990). This is the largest single extraction of the four-cut plan (handle() was ~40% of the file).

src/server/handle.ts   NEW  2052 lines — header comment + imports + handle() verbatim
src/server.ts          −1990/+25 — zone removed; `import { handle } from "./server/handle.js";`
                       beside the ./server/admin.js sibling import (cut-1 style)
tests/side-lane-invariants.test.ts  +test (G) — see lane-guard section
reference/architecture.md           +1 module-map row

Why the new file's imports look the way they do

handle() closed over 120+ module-scope identifiers in server.ts. After the move it carries its own import block: path-rewired copies of the groups it actually uses (./x.js → ../x.js), plus a value/type import line from "../server.js" for the 14 symbols listed below. The two-way runtime edge (server.ts ↔ server/handle.ts) is the same cycle class already production-proven by cut 2's prepare-* modules and by server.ts ↔ admin.ts: every binding consumed across the edge is a hoisted function declaration or an already-initialized const, no TDZ exposure. Cut 4 will re-home forward (below) into relay.ts, at which point this edge shrinks naturally.

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

14 symbols total — exactly what tsc demands for the moved body, nothing more (unused-exports gate verifies each is consumed):

group symbols
fns still home-here forward, preflightCompressIfNeeded, isPreflightFailFast, logRequestCost, googlePathKind, resignSettingsFor, scrubAnthropicPck, scrubCompatDrop, forwardUpstreamUrl, googleModelFromPath
shared singletons (exported BY REFERENCE — one canonical instance keeps its identity; verified no re-binding anywhere) headroomFallbackLogged, headroomEffectiveLogged, nonConversationRelayWarned, NON_CONVERSATION_RELAY_WARN_CAP

forward is cut 4's territory (it goes to relay.ts together with resolveFakeCompletion); exporting it now is the minimal unblock rather than widening this PR.

Verification

  • Byte identity: element-wise multiset proof over git diff -U0 — deleted zone (1991 lines incl. junction blank) vs the new file's body matches exactly modulo the single sanctioned export prefix; added side = 1 import line + 14 export-prefixed def-lines only. Comments traveled byte-for-byte.
  • tsc --noEmit: clean. tsup build: clean (pipeline verified inside dist/index.js; repo has no per-module dist files by existing convention). check:unused-exports: clean (3 pre-existing waivers).
  • Tests (local): 113 pass / 0 fail across 4 lane suites (incl. new (G)), wire-contract, count-tokens, one-call-payload, plugin-nudge-injection, fix-920-bypass-drop, prompt-pack-tool-prompts, e2e-responses-offhead-system, e2e-image-billing, plus upstream-affected path suites claude-fork-lineage / issue1333-derived-inheritance / affinity / tier-window-cap. CI is authoritative.

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

handle() drives the side-lane engine mid-pipeline for real — demoteGate(), stripLeakedBiliTools(), isSideRequest(), resolveSideLane() call sites live in the moved zone. Moving them out of src/server.ts fires the lane-guard grep by design, so the guard requires a genuine side-lane suite update alongside. Added test (G) pins the boundary of the extracted module: handle.ts must (a) reference none of the engine's internal identifiers (all 11 verified absent: SIDE_REQUEST_MAX_TOKENS, SideLaneDecision, …) and (b) import from side-request.js ONLY the public entry points {hasLeakedBiliToolsOnly, isSideRequest, resolveSideLane, demoteGate, stripLeakedBiliTools, restoreOutputBudget, sideRequestGuard} — the allowlist includes restoreOutputBudget/sideRequestGuard because their call sites already lived inside handle() before this move (moved, not newly coupled). The test deliberately does NOT extend (F)'s doesNotMatch list to handle.ts: unlike cut 2's prepare/inject modules, the pipeline legitimately consumes the lane API.

Rebase note

Rebased onto master after upstream merges (#2409 claude-fork-lineage restructured the parent-link block INSIDE handle(), among others); the zone was re-extracted verbatim from the fresh base including those edits, and the affected suites were run green above.

@github-actions

github-actions Bot commented Oct 8, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-08_server-handle-extract (0c4c5da)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.2627-pr.2424.c3ddac2

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-pr2424.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 #2424 review 结论:纯移动已字节级验证成立,CI 全绿,无回归 — 可合。

结构化八问

1. 是什么问题:不是缺陷,是计划内重构(#1440 P2 cut 3):把 ~2000 行的请求管线主函数 handle() 从 src/server.ts 单体中移出到 src/server/handle.ts,延续 cut 1(admin.ts)/ cut 2(协议模块)的拆分序列。

2. 什么原因导致的:src/server.ts 长到 6436 行,hot-file contention 是二轮回炉的头号成因(§7.5);缩小单体以降低并发 PR 的冲突面。

3. 影响范围与严重程度:纯结构性变更,声称零行为变化。若做错了会波及每一条代理请求——但下述验证未发现任何行为差异。

4. 怎么修复的:字节级相同搬移(非重写)+ 最小接口化。具体:

  • 字节级同一性(已证明,非目测):master src/server.ts 第 1295..3285 行(1991 行,恰为 handle() 全函数体)与新 src/server/handle.ts 第 63..2053 行逐字节相等(唯一差别是声明行的 export 前缀)。用多集合 diff 复核:除 hunk 上下文 6 行外无任何缺失或多余。
  • server.ts 全部新增 = 恰好 15 行:1 个 import { handle } from "./server/handle.js" + 14 个定义行加 export(10 函数 + 4 单例:headroomFallbackLogged/headroomEffectiveLogged/nonConversationRelayWarned/NON_CONVERSATION_RELAY_WARN_CAP)。删除区之外零改动。
  • 跨边接口:handle.ts 从 ../server.js 引入 25 值 + type Prepared,其中 14 为本 PR 新导出、11 为既有导出——与 PR 描述一致。
  • ESM 循环(server.js ↔ handle.js)安全:新文件第 63 行之后的全部内容都在 handle() 体内,顶层代码不触碰对侧绑定,TDZ 不可能触发;反向边导入的是 hoisted 函数声明。4 个单例在 handle.ts 内无遮蔽重声明(grep 证实)。
  • 测试 (G):对 handle.ts 断言 11 个 side-lane 引擎内部标识符缺席 + side-request.js 导入名 ∈ 7 符号白名单 + 非空转断言;风格与既有 (A)–(F) 一致。(F) 刻意不扩展到 handle.ts 的理由已在注释写明(pipeline 合法位于 lane 引擎之上)。
  • reference/architecture.md +1 行,位置与措辞正确。

5. 是否有回归问题:无。逐项核查结果:

6. 是否破坏缓存:不涉及——prefix cache / persist / 游标逻辑完全未触碰(字节级同一性覆盖此点)。

7. 是否改了设计方向:无转向——沿用 #1440 P2 既定提取模式(拆模块 + 最小导出面 + 边界测试)。一处合理演化:pipeline 模块天然消费 side-lane 公共 API,故 (G) 用白名单而非禁导入,且注释说明了与 (F) 的关系。

8. 是否引入了新的配置:不涉及——无 config/env/CLI 变化。

判定

可合。 head CI 已全绿;分支虽落后 master 11 个提交但已验证干净自动合并(#2401/#2421 与其触碰路径无交集),GitHub 合并时可直接处理。按 §7.4,refactor 类归人工合并,请 owner 直接 merge:#2424

小问题检查:未发现需要顺手修的项(测试 (G) 的导入正则只匹配单行 import,若未来有人把该 import 折成多行,sawImport 断言会响亮失败而非静默放行——可接受的失败形态,不值得单独 commit)。

@ranxianglei
ranxianglei merged commit d189be5 into master Oct 8, 2026
28 checks passed
@github-actions

github-actions Bot commented Oct 8, 2026

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.157-master.d189be5 (rolling master tag).

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