Repository navigation
[PR] feat: opt-in transparent WebSocket passthrough (#1467) - #1472
ranxianglei wants to merge 4 commits into
Conversation
📦 Built Package ArtifactBranch: Option A — Install this exact build (recommended)npm install -g billion-context@0.0.1725-pr.1472.cf8becaThis exact version is immutable and reproducible. The rolling Option B — Download artifact
tar xzf billion-context-pr1472.tgz
npm install -g packageInstall instructions are refreshed on each push. |
[bot] 🏷 Reviewing now — interim status:
Full conclusion shortly. |
…1472 review) checkTunnelDestination computed the default port as https?443:80, so a portless wss:// destination (newly routable via the ws passthrough of #1467) was admitted as port 80 while handleWsUpgrade connects on 443: BILI_TUNNEL_ALLOWED_HOSTS host:443 entries never matched WS destinations and the self layer mis-evaluated when the proxy listens on 443. Treat wss like https for the default port; pin both consequences in the scheme-default test.
a89724c to
c29ae05
Compare
[bot] 🏷 Review complete — mergeable. PR #1472 (head now ① Original issue direction (#1467): sound. Root cause correctly identified (unconditional 426 at ② Regression inventory (touched paths → verdict):
③ Code review (main gate): ④ Test validity: the 9 new tests have teeth — replayed-head assertions on the fake-upstream side (path, Host rewrite, no proxy-host leak, custom-header verbatim), bidirectional byte proof via echo (S-PUSH/C-PING), 401 verbatim propagation, self/link-local 403s, 426-preserved-when-enabled, blind-tunnel survival without opt-in, plus unit matrices for both pure functions. All ports via ⑤ Diff cleanliness: every line serves the PR purpose; no unrelated churn, no whitespace noise. Rebased onto current master (only overlap was disjoint hunks in CONFIGURATION.md). Behavior-change flags (old → new, why):
Verification: original head One-line summary: 修复了 WS 透传准入中 portless |
[bot] 🏷 Final status: CI fully green (13/13) on head 中文摘要:WS 透传 PR 已 rebase 到最新 master、修复了 wss 默认端口准入缺陷并补齐 config-surface 说明,本地与 CI 全量验证通过(13/13 绿),可以合并。 |
…upstream (#1472) Node's upgrade event hands over any bytes the client pipelined after its handshake request as the third argument; the listener discarded them, so a pipelining client's early frames were silently dropped. Accept the buffer, write it to the upstream right after the rebuilt handshake head (compliant clients send none, so the default path is unchanged).
…1472 review) checkTunnelDestination computed the default port as https?443:80, so a portless wss:// destination (newly routable via the ws passthrough of #1467) was admitted as port 80 while handleWsUpgrade connects on 443: BILI_TUNNEL_ALLOWED_HOSTS host:443 entries never matched WS destinations and the self layer mis-evaluated when the proxy listens on 443. Treat wss like https for the default port; pin both consequences in the scheme-default test.
…upstream (#1472) Node's upgrade event hands over any bytes the client pipelined after its handshake request as the third argument; the listener discarded them, so a pipelining client's early frames were silently dropped. Accept the buffer, write it to the upstream right after the rebuilt handshake head (compliant clients send none, so the default path is unchanged).
4328f95 to
92746f4
Compare
|
Two changes pushed on top (head
Local gates: |
When ws.passthrough is enabled (config "ws": {"passthrough": true} or
BILI_WS_PASSTHROUGH=1, env wins), WS upgrades addressed to the proxy are
replayed at the real upstream and piped as opaque byte streams on 101.
Frames are never parsed, so these sessions get NO compression (loud boot
warning + web-UI banner). Supported forms: /bili/wss(s):// embedded,
absolute-form ws(s)://, and MITM-terminated connections (post-TLS
handshake forwarded). Direct destinations pass the #409 admission checks;
blind tunnels already carry WS bytes opaquely (pinned by test). Non-101
upstream answers are forwarded verbatim; connect/handshake failures answer
502.
Behavior change: default config is unchanged — every upgrade still answers
the byte-exact 426 fast-fallback Codex relies on (#2), pinned by the
untouched tests/ws-upgrade.test.ts. The new 101 path only exists when
explicitly opted in.
Phase 2 (protocol-aware WS compression) is deliberately not implemented.
Preflight: typecheck clean, full suite 2880 pass / 0 fail, build OK.
…1472 review) checkTunnelDestination computed the default port as https?443:80, so a portless wss:// destination (newly routable via the ws passthrough of #1467) was admitted as port 80 while handleWsUpgrade connects on 443: BILI_TUNNEL_ALLOWED_HOSTS host:443 entries never matched WS destinations and the self layer mis-evaluated when the proxy listens on 443. Treat wss like https for the default port; pin both consequences in the scheme-default test.
…upstream (#1472) Node's upgrade event hands over any bytes the client pipelined after its handshake request as the third argument; the listener discarded them, so a pipelining client's early frames were silently dropped. Accept the buffer, write it to the upstream right after the rebuilt handshake head (compliant clients send none, so the default path is unchanged).
92746f4 to
1cabbaf
Compare
[bot] 🏷 收到,已逐条核验你推的两个 commit,并做了一轮收尾 rebase。结论:两个 commit 都没问题;分支已 rebase 到当前 master 并全绿,CI 跑绿后即可合并。 ① ② rebase + 丢弃旧 UI web edits — 接受你的取舍。 #1426 重写后那四个旧 UI 编辑(banner/i18n key)确实没有落点,boot warn + 启动 banner 行 + CONFIGURATION.md 披露保留是合理的最小面。注意:PR body 里 "Web UI" 一条和 Config Surface 里的 ③ 本轮我做的收尾:rebase 到当前 master( 本地 gates(新 head CI 正在新 head 上跑,跑绿我会回帖确认。合并操作留给你(规则禁止 agent merge):#1472 中文摘要:核验了你推的两个 commit(pipelined-bytes 修复正确、web edit 取舍合理),发现 master 已被 #1519 推进后把分支 rebase 到当前 master(唯一冲突按并集解决),全量测试 3011 过 0 挂,PR 描述已同步修正,可以合并。 |
[bot] 🏷 CI 已在新 head 本 PR 至此就绪,无阻塞项。合并留给你:https://github.com/ranchxianglei/billion-context/pull/1472 (更正链接:#1472) 中文摘要:新 head 上 CI 13/13 全绿,PR 全部审查项闭环(两个 follow-up commit 核验通过、rebase 到当前 master、描述已修正),可以合并。 |
[bot] 🏷 更正上一条里的笔误(多了一个拼错的链接):PR 链接以这个为准 — https://github.com/ranchxianglei/billion-context/pull/1472 …抱歉,正确地址是 #1472 |
…assthrough upgrade line
…ses becomes the first codec - src/ws-bridge.ts: protocol-independent shell (admission, upgrade, labeled logging, exactly-once shutdown teardown) driven by a codec table - src/responses-ws.ts: Responses-specific handling becomes responsesCodec (WsBridgeCodec/WsBridgeSession contract) - src/server.ts: single wiring site installWebSocketBridge(server, dispatch, log, [responsesCodec]); unclaimed upgrades keep the existing 426 - tests/ws-bridge.test.ts: drives the shell with a synthetic second codec to pin the codec-table abstraction - docs: architecture section covering the shell/codec split; new protocols are a codec file plus one table entry; unknown protocols stay on #1472
…ses becomes the first codec - src/ws-bridge.ts: protocol-independent shell (admission, upgrade, labeled logging, exactly-once shutdown teardown) driven by a codec table - src/responses-ws.ts: Responses-specific handling becomes responsesCodec (WsBridgeCodec/WsBridgeSession contract) - src/server.ts: single wiring site installWebSocketBridge(server, dispatch, log, [responsesCodec]); unclaimed upgrades keep the existing 426 - tests/ws-bridge.test.ts: drives the shell with a synthetic second codec to pin the codec-table abstraction - docs: architecture section covering the shell/codec split; new protocols are a codec file plus one table entry; unknown protocols stay on #1472
…ses becomes the first codec - src/ws-bridge.ts: protocol-independent shell (admission, upgrade, labeled logging, exactly-once shutdown teardown) driven by a codec table - src/responses-ws.ts: Responses-specific handling becomes responsesCodec (WsBridgeCodec/WsBridgeSession contract) - src/server.ts: single wiring site installWebSocketBridge(server, dispatch, log, [responsesCodec]); unclaimed upgrades keep the existing 426 - tests/ws-bridge.test.ts: drives the shell with a synthetic second codec to pin the codec-table abstraction - docs: architecture section covering the shell/codec split; new protocols are a codec file plus one table entry; unknown protocols stay on #1472
…ses becomes the first codec - src/ws-bridge.ts: protocol-independent shell (admission, upgrade, labeled logging, exactly-once shutdown teardown) driven by a codec table - src/responses-ws.ts: Responses-specific handling becomes responsesCodec (WsBridgeCodec/WsBridgeSession contract) - src/server.ts: single wiring site installWebSocketBridge(server, dispatch, log, [responsesCodec]); unclaimed upgrades keep the existing 426 - tests/ws-bridge.test.ts: drives the shell with a synthetic second codec to pin the codec-table abstraction - docs: architecture section covering the shell/codec split; new protocols are a codec file plus one table entry; unknown protocols stay on #1472
|
(ai: zhipuai-lb/glm-5.3) 陈旧票清理(第三批动作①):目标 issue #1467 已关。为避免重复劳动关闭本 PR;如判断有误请直接 reopen 并留言。 |
What
Phase 1 of #1467: an opt-in transparent WebSocket relay. When enabled, a WS upgrade addressed to the proxy is replayed at the real upstream and, on
101, both sides are piped as opaque byte streams — frames are never parsed, so these sessions get NO compression (loud boot warning). This unblocks WS-only upstreams (e.g. OpenAI Realtime API) that cannot use the HTTP/SSE compression pipeline.Behavior change (flagged per deliverables): old = unconditional
426 Upgrade Requiredfor every upgrade; new = still426by default,101only when explicitly opted in. The default path is byte-for-byte unchanged — the Codex fast-fallback contract (#2) is pinned by the untouchedtests/ws-upgrade.test.ts(both plain and MITM-decrypted TLS), which passes as-is.Design
"ws": { "passthrough": true }besidemitm; envBILI_WS_PASSTHROUGH=1/0wins over the file; default OFF (same resolution pattern as other server flags).src/ws-passthrough.tsholds all new logic (resolveWsDestination,buildUpgradeHead,handleWsUpgrade) so it is unit-testable without network;src/server.tsonly routes the existingupgradelistener to it when opted in./bili/wss(s)://…embedded, absolute-formws(s)://…, and MITM-terminated connections (the post-TLS handshake is forwarded instead of hitting the plain-HTTP handler — one listener covers both becausedoMitmfeeds decrypted sockets back into the same server). Unroutable upgrades (plain origin-form) still get 426./bili/tunnel (self/link-local/private-from-remote denied with 403); MITM-terminated connections skip re-admission (already gated at CONNECT time).resolveProxy+connectThroughProxy(model-path semantics);wsswraps the connected socket in TLS.Hostrewritten to the destination authority. Bytes pipelined behind the handshake request (Node'supgradethird argumenthead) are forwarded to the upstream right after the rebuilt head — nothing silently dropped.101upstream answers (e.g.401) are forwarded verbatim; connect/handshake failures answer502. No masking.### ws+ env-var table row), README zh/en in sync.Tests (all ports via
listen(0))New
tests/ws-passthrough.test.ts(10 tests): 101 + bidirectional frame round-trip with header-fidelity assertions (Host rewrite, custom-header pass-through); absolute-form relay; non-101 (401) verbatim propagation; self-target 403; link-local 403; unroutable origin-form still 426 when enabled; blind-tunnel WS survival (no opt-in needed — opaque CONNECT pipe); pipelined-bytes survival (single write of handshake + early frame, asserts the echo round-trips); unit matrix forresolveWsDestination(incl. MITM marker socket) andbuildUpgradeHead.Phase 2
Protocol-aware WS compression is deliberately NOT implemented (design-first follow-up per the issue).
Pre-flight (on this head
1cabbaf4)npm run typecheck— cleannpm test— 3011 pass / 0 fail / 12 skipped (pre-existing gates)npm run build— success, dist import annotations OKCloses #1467
Config Surface (required per AGENTS.md §Configuration Surface Discipline)
What is added:
ws.passthrough(boolean, defaultfalse) — new optionalFileConfig.wssection besidemitm.BILI_WS_PASSTHROUGH(1/0); wins over the file; resolution follows the repo-wide(env ?? fileDerived) !== "0"convention shared byBILI_LOG_MASK_HOSTS,BILI_SUBAGENT_SPLIT,BILI_FORK_ADOPTION.Why the existing surface cannot express it: no existing key controls WebSocket upgrade handling — before this change every upgrade unconditionally answered 426 (#2 Codex fast-fallback contract). The existing
passthrough/ACP_PASSTHROUGHflag bypasses the compression pipeline for HTTP sessions; it says nothing about transport mode, and enabling it does not make WS upgrades routable. Theproviderstable routes which upstream serves an HTTP model path — WS destinations are not necessarily LLM providers with model paths, and the relay is verbatim (no provider semantics apply). A dedicated boolean is the minimal expression.Mechanisms considered:
passthrough— rejected: different mechanism (compression bypass vs transport relay); conflating them would open WS egress for users who only wanted compression off, silently changing the security surface of an existing flag.providerstable — rejected: WS destinations are not necessarily providers; admission ([SECURITY] /bili/<绝对URL> 零配置隧道无目标准入:可回环访问自家管理面、触达 link-local 元数据;0.0.0.0 部署下 LAN 可经 PUT 劫持全部流量凭据(架空自述的 loopback-only 防线) #409) is a global concern independent of routing.maskHosts/subagentSplit) vs nestedwssection — nested chosen because the issue author proposed exactly this shape in feat: support wss:// (WebSocket) traffic — opt-in transparent passthrough now, protocol-aware compression later #1467 and it leaves room for future WS-specific keys (Phase 2) without another top-level addition.Compat/migration: purely additive, default OFF. Existing configs parse identically (new fields optional). Every upgrade request under default settings behaves byte-for-byte as before (pinned by the untouched
tests/ws-upgrade.test.ts, plain + MITM-decrypted TLS). Nothing to migrate.Sign-off provenance: shape proposed by the owner in #1467 (issue opened by @ranxianglei specifying the exact form and the
BILI_MITMenv pattern), satisfying rule 3 (explicit owner sign-off before implementation). This section was added during review because §Configuration Surface Discipline landed on master via #1471 while this PR was in flight.Review addendum (agent self-review, 2026-09-27)
fix(tunnel): admit portless wss destinations on scheme-default 443:checkTunnelDestination(src/tunnel-guard.ts) computed the default port ashttps ? 443 : 80, so a portlesswss://hostdestination — newly routable by this PR — was admitted as port 80 whilehandleWsUpgradeconnects on 443. Consequences fixed:BILI_TUNNEL_ALLOWED_HOSTSentries ofhost:443never matched WS destinations, and the self-targeting layer mis-evaluated when bili itself listens on 443. Pinned intests/tunnel-guard.test.ts(scheme-default test now covers wss self-layer + allowlist match).92746f4e) verified: (a)fix(ws)pipelined-bytes forwarding — correct fix at source (Node hands post-handshake bytes to theupgradelistener ashead; they were discarded before relay), pinned by a new test; (b) rebase onto v0.1.163 dropping the old-UI web edits — accepted (owner-scoped deferral; see Web UI bullet above).86e0b684, which includes feat: inherit refs/blocks/lineage across resume forks (#1486) #1519 / Claude 上 resume 导致消息错乱 #1486 resume-ref-inheritance — master advanced past this PR's base while it was in flight, and feat: inherit refs/blocks/lineage across resume forks (#1486) #1519 rewrote regions ofsrc/server.ts). Single textual conflict (adjacent env-table rows in CONFIGURATION.md) resolved by union. Final diff vs master is exactly the 9 intended files;src/server.tsdiff contains zero deletions of master code. Full gates re-run green on the new head (typecheck clean; 3011 pass / 0 fail / 12 skipped; build OK incl. dist import annotations).