Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -222,6 +222,7 @@ Commit convention: `feat:` / `fix:` / `refactor:` / `test:` / `docs:` / `release

### 7.3 Correctness Guardrails

- **Availability over performance (可用性永远大于性能 — owner rule, 2026-10-14, #3128).** When a defect makes a capability UNAVAILABLE, restoring availability outranks every other consideration — performance, memory footprint, elegance. Do not block or defer an availability fix on performance grounds: ship the availability fix and track the performance cost as SEPARATE work (it may already be in flight). Canonical case #3128: raising the hardcoded 100 MiB HTTP request-body cap to a 5 GiB default so multi-gigabyte single requests are accepted instead of reset is an AVAILABILITY decision; the in-RAM buffering cost of large single bodies is a distinct performance concern owned by separate streaming/spill work, not a reason to hold the cap.
- **Root cause, not symptom (疏, not 堵 — first principle for every fix).** A fix removes the mechanism that PRODUCES the defect; it never merely hides the defect's visible trace at whatever layer is cheapest to intercept. Before writing any fix, name the producer of the offending bytes/behavior and fix it at the source or decision point — never by rewriting or filtering payload in transit to make the symptom invisible. Litmus test: "if the same root cause surfaced in a different shape tomorrow, would this fix still hold?" If not, it is a mask, and a mask is a latent bug. Canonical failure: #933 (model-echoed render tags leaking into a TUI) was "fixed" by stripping tool-call arguments mid-stream; the mask itself became #1039's silent data corruption once users legitimately wrote tag-shaped payloads through write/edit/bash. When the true root cause is out of scope (another repo, a product decision), fix the in-scope part, leave a documented boundary note pointing at the real home of the fix, and do NOT compensate in the wrong layer (#1039's echo-noise belongs on the injection side — host renderTags policy — not on the wire).
- **Never silently clobber or drop user config.** Any read-modify-write on user config needs a parse-state guard; reject malformed input loudly (HTTP 400/409) instead of merging into defaults or dropping fields. Whitelists must be complete (#155: a missing key silently erased custom compress prompts).
- **Sane defaults & fallbacks.** Fallback values must be reasonable (never a too-small value that thrashes); a static/fallback source must always lose to a fresher authoritative source when both are cheaply available (#282: window fallback 200K/min 100K, not 64K; the bundled registry snapshot must not outrank the live registry).
Expand Down
6 changes: 6 additions & 0 deletions CONFIGURATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -153,6 +153,9 @@ This index is generated from `website/config-reference/*.yaml` — edit the seed
| `network.proxyKeepAliveMaxMs` | number | 55000 (0 = one-shot connections) | BILI_PROXY_KEEPALIVE_MAX_MS | Max lifetime of a connection through an outbound egress proxy before forcing reconnection (avoids stale NAT mappings). |
| `network.postResponseLingerMs` | number | 5000 | BILI_POST_RESPONSE_LINGER_MS | Graceful-close budget for proxy-initiated closes after the response completed: the socket is held waiting for the peer's FIN/TLS close_notify and destroyed at the deadline (reason=linger-backstop). |
| `network.allowPrivateHttpProviders` | boolean | false | BILI_ALLOW_PRIVATE_HTTP_PROVIDERS | Opt-in (#2984): admit plain-HTTP providers on private networks (RFC1918, 127/8, link-local, ULA, *.local/.lan/.internal) into the agent-registry intake and summary-endpoint guards. Off by default — plaintext stays loopback-only; public IPs/domains and CGNAT (100.64/10) stay refused regardless. 1/true enables. |
| `network.receiveBodyBytes` | number | 5368709120 | BILI_RECEIVE_BODY_BYTES | Max inbound wire bytes read into memory per request before a 413 at the receive stage. Raised from a hardcoded 100 MiB to 5 GiB (#3128 owner decision) so multi-gigabyte single requests are accepted instead of the socket being reset. Also the threshold above which a decoded request consumes one of two shared large-decode admission slots. WebSocket lanes keep the fixed 100 MiB surface. |
| `network.decodedBodyBytes` | number | 10737418240 | BILI_DECODED_BODY_BYTES | Max DECODED bytes after content-encoding expansion (gzip/deflate/br/zstd), checked incrementally during decode (decode-stage 413). Default is 2x the receive budget, mirroring the legacy decode=2x-wire relationship; guards against decompression bombs. |
| `network.outboundBodyBytes` | number | 5368709120 | BILI_OUTBOUND_BODY_BYTES | Max rebuilt request bytes forwarded upstream (forward-stage 413), counted as UTF-8 bytes of the final body string. Checked before the fetch so an over-budget rebuild never reaches the upstream watchdog allocation. |
| `persist` | object | {} (all defaults) | — | Session persistence to disk under the XDG state dir. |
| `persist.enabled` | boolean | true | BILI_PERSIST | Master switch for writing session records to disk (0/false turns it off). |
| `persist.zstd` | boolean | false | BILI_PERSIST_ZSTD | Zstd-compress persisted session files (1/true enables). |
Expand Down Expand Up @@ -1642,6 +1645,7 @@ File keys resolve only when the matching env var is unset. Defaults in parenthes
| `BILI_CLIENT_ERROR_BACKSTOP_MS` | `network.clientErrorBackstopMs` | 30000 |
| `BILI_CODEARTS_REF` | `resign` | {} (armed; built-in scheme sdk-hmac-sha256) |
| `BILI_CODEX_COMPACT` | `codexCompact` | "intercept" |
| `BILI_DECODED_BODY_BYTES` | `network.decodedBodyBytes` | 10737418240 |
| `BILI_DECOMPRESS_TMP_CAP` | `decompressTmpCap` | 50 |
| `BILI_DUMP_4XX` | `diagnostics.dump4xx` | false |
| `BILI_DUMP_4XX_MAX_BYTES` | `diagnostics.dump4xxMaxBytes` | 2097152 (floor 1024) |
Expand All @@ -1666,6 +1670,7 @@ File keys resolve only when the matching env var is unset. Defaults in parenthes
| `BILI_NATIVE_ATTACH_POLICY` | `native.attachPolicy` | own-lane |
| `BILI_NON_HTTP_PROVIDERS` | `compactionOptIn` | false |
| `BILI_NO_CACHE_CONTROL` | `compat.noCacheControl` | false |
| `BILI_OUTBOUND_BODY_BYTES` | `network.outboundBodyBytes` | 5368709120 |
| `BILI_PERSIST` | `persist.enabled` | true |
| `BILI_PERSIST_DEBOUNCE_MS` | `persist.debounceMs` | 500 |
| `BILI_PERSIST_EPERM_ALERT_REPEAT_MS` | `persist.epermAlertRepeatMs` | 0 (no repeats) |
Expand All @@ -1678,6 +1683,7 @@ File keys resolve only when the matching env var is unset. Defaults in parenthes
| `BILI_PREFLIGHT_HOLD_MS` | `network.preflightHoldMs` | 30000 |
| `BILI_PROXY_KEEPALIVE_MAX_MS` | `network.proxyKeepAliveMaxMs` | 55000 (0 = one-shot connections) |
| `BILI_PUBLIC_SNAPSHOT_CAP_BYTES` | `plugin.snapshotCapBytes` | 104857600 (0 disables snapshots) |
| `BILI_RECEIVE_BODY_BYTES` | `network.receiveBodyBytes` | 5368709120 |
| `BILI_RELEASE_NOTES_CHECK` | `releaseNotesCheck` | true |
| `BILI_RELEASE_NOTES_URL` | `releaseNotesUrl` | unset (built-in feed) |
| `BILI_REPLAY_RETRY_BASE_MS` | `network.replayRetryBaseMs` | 1500 (0 disables the delay) |
Expand Down
6 changes: 6 additions & 0 deletions CONFIGURATION.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -153,6 +153,9 @@
| `network.proxyKeepAliveMaxMs` | number | 55000 (0 = one-shot connections) | BILI_PROXY_KEEPALIVE_MAX_MS | 经出站代理的连接最大存活时长,到期强制重建(规避陈旧 NAT 映射)。 |
| `network.postResponseLingerMs` | number | 5000 | BILI_POST_RESPONSE_LINGER_MS | 代理主动发起的响应后关闭的优雅关闭预算:socket 挂起等待对端 FIN/TLS close_notify,到点销毁(reason=linger-backstop)。 |
| `network.allowPrivateHttpProviders` | boolean | false | BILI_ALLOW_PRIVATE_HTTP_PROVIDERS | 可选开关(#2984):允许私网(RFC1918、127/8、link-local、ULA、*.local/.lan/.internal)明文 HTTP provider 进入 agent-registry 接收与摘要端点守卫。默认关——明文仅回环受信;公网 IP/域名与 CGNAT(100.64/10)无论如何都拒。1/true 启用。 |
| `network.receiveBodyBytes` | number | 5368709120 | BILI_RECEIVE_BODY_BYTES | 单请求读入内存的入站 wire 字节上限,超限在 receive 阶段返回 413。由硬编码 100 MiB 提升到 5 GiB(#3128 owner 决定),使多 GB 单请求被接受而非断连。同时也是解码请求占用两个共享大解码准入槽位的阈值。WebSocket lane 保持固定 100 MiB 表面。 |
| `network.decodedBodyBytes` | number | 10737418240 | BILI_DECODED_BODY_BYTES | content-encoding 解压(gzip/deflate/br/zstd)后的解码字节上限,解码过程中增量检查(decode 阶段 413)。默认为接收预算的 2 倍,沿用旧的 decode=2×wire 关系;用于防解压炸弹。 |
| `network.outboundBodyBytes` | number | 5368709120 | BILI_OUTBOUND_BODY_BYTES | 转发到上游的重建请求字节上限(forward 阶段 413),按最终 body 字符串的 UTF-8 字节计。在 fetch 之前检查,超预算的重建不会触发上游看门狗分配。 |
| `persist` | object | {} (all defaults) | — | 会话落盘持久化(XDG state 目录之下)。 |
| `persist.enabled` | boolean | true | BILI_PERSIST | 会话记录落盘总开关(0/false 关闭)。 |
| `persist.zstd` | boolean | false | BILI_PERSIST_ZSTD | zstd 压缩持久化会话文件(1/true 启用)。 |
Expand Down Expand Up @@ -1641,6 +1644,7 @@ ACP 原生 agent(当前为 `pi` 扩展)会在每个进程内向代理上报
| `BILI_CLIENT_ERROR_BACKSTOP_MS` | `network.clientErrorBackstopMs` | 30000 |
| `BILI_CODEARTS_REF` | `resign` | {} (armed; built-in scheme sdk-hmac-sha256) |
| `BILI_CODEX_COMPACT` | `codexCompact` | "intercept" |
| `BILI_DECODED_BODY_BYTES` | `network.decodedBodyBytes` | 10737418240 |
| `BILI_DECOMPRESS_TMP_CAP` | `decompressTmpCap` | 50 |
| `BILI_DUMP_4XX` | `diagnostics.dump4xx` | false |
| `BILI_DUMP_4XX_MAX_BYTES` | `diagnostics.dump4xxMaxBytes` | 2097152 (floor 1024) |
Expand All @@ -1665,6 +1669,7 @@ ACP 原生 agent(当前为 `pi` 扩展)会在每个进程内向代理上报
| `BILI_NATIVE_ATTACH_POLICY` | `native.attachPolicy` | own-lane |
| `BILI_NON_HTTP_PROVIDERS` | `compactionOptIn` | false |
| `BILI_NO_CACHE_CONTROL` | `compat.noCacheControl` | false |
| `BILI_OUTBOUND_BODY_BYTES` | `network.outboundBodyBytes` | 5368709120 |
| `BILI_PERSIST` | `persist.enabled` | true |
| `BILI_PERSIST_DEBOUNCE_MS` | `persist.debounceMs` | 500 |
| `BILI_PERSIST_EPERM_ALERT_REPEAT_MS` | `persist.epermAlertRepeatMs` | 0 (no repeats) |
Expand All @@ -1677,6 +1682,7 @@ ACP 原生 agent(当前为 `pi` 扩展)会在每个进程内向代理上报
| `BILI_PREFLIGHT_HOLD_MS` | `network.preflightHoldMs` | 30000 |
| `BILI_PROXY_KEEPALIVE_MAX_MS` | `network.proxyKeepAliveMaxMs` | 55000 (0 = one-shot connections) |
| `BILI_PUBLIC_SNAPSHOT_CAP_BYTES` | `plugin.snapshotCapBytes` | 104857600 (0 disables snapshots) |
| `BILI_RECEIVE_BODY_BYTES` | `network.receiveBodyBytes` | 5368709120 |
| `BILI_RELEASE_NOTES_CHECK` | `releaseNotesCheck` | true |
| `BILI_RELEASE_NOTES_URL` | `releaseNotesUrl` | unset (built-in feed) |
| `BILI_REPLAY_RETRY_BASE_MS` | `network.replayRetryBaseMs` | 1500 (0 disables the delay) |
Expand Down
8 changes: 8 additions & 0 deletions src/config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1829,6 +1829,14 @@ type FileConfig = {
* guards. Default false: plaintext stays loopback-only. Public IPs/domains and
* CGNAT (100.64/10) remain refused regardless. Env BILI_ALLOW_PRIVATE_HTTP_PROVIDERS wins. */
allowPrivateHttpProviders?: boolean;
/** Per-request inbound wire byte budget (#3128; was hardcoded 100 MiB, now default 5 GiB).
* Env BILI_RECEIVE_BODY_BYTES wins. Also the threshold above which a decoded request
* consumes one of two shared large-decode admission slots. WebSocket lanes keep 100 MiB. */
receiveBodyBytes?: number;
/** Per-request DECODED byte budget after content-encoding expansion (#3128; default 10 GiB = 2x receive). Env BILI_DECODED_BODY_BYTES wins. */
decodedBodyBytes?: number;
/** Per-request rebuilt-outbound byte budget forwarded upstream (#3128; default 5 GiB). Env BILI_OUTBOUND_BODY_BYTES wins. */
outboundBodyBytes?: number;
};
/** Session persistence knobs (#2030) — was BILI_PERSIST_* env-only. */
persist?: {
Expand Down
30 changes: 30 additions & 0 deletions src/knobs.ts
Original file line number Diff line number Diff line change
Expand Up @@ -170,6 +170,36 @@ export function mitmHandshakeTimeoutMs(): number {
return Number.isFinite(v) && v > 0 ? Math.floor(v) : MITM_HANDSHAKE_TIMEOUT_MS_DEFAULT;
}

// --- request-body byte budgets (#3128) ---

const DEFAULT_LIMITS_RECEIVE_BYTES = 5 * 1024 * 1024 * 1024;
const DEFAULT_LIMITS_DECODED_BYTES = 10 * 1024 * 1024 * 1024;
const DEFAULT_LIMITS_OUTBOUND_BYTES = 5 * 1024 * 1024 * 1024;

/** BILI_RECEIVE_BODY_BYTES > network.receiveBodyBytes > 5 GiB. Max inbound wire bytes
* read into memory per request. #3128: these were hardcoded 100 MiB constants; the
* HTTP path now resolves them here with a 5 GiB default so multi-gigabyte single
* requests are accepted instead of reset. They bound SINGLE-REQUEST in-RAM buffering
* (~2x peak while a body is read+decoded); cross-turn history lives in SQLite and is
* unaffected. The WebSocket lanes keep the fixed 100 MiB surface (MAX_REQUEST_BYTES). */
export function limitsReceiveBytes(): number {
const v = tInt("BILI_RECEIVE_BODY_BYTES", loadConfigFile().network?.receiveBodyBytes);
return Number.isFinite(v) && v > 0 ? Math.floor(v) : DEFAULT_LIMITS_RECEIVE_BYTES;
}

/** BILI_DECODED_BODY_BYTES > network.decodedBodyBytes > 10 GiB. Max DECODED bytes after
* content-encoding expansion (2x the receive default, mirroring the legacy decode cap). */
export function limitsDecodedBytes(): number {
const v = tInt("BILI_DECODED_BODY_BYTES", loadConfigFile().network?.decodedBodyBytes);
return Number.isFinite(v) && v > 0 ? Math.floor(v) : DEFAULT_LIMITS_DECODED_BYTES;
}

/** BILI_OUTBOUND_BODY_BYTES > network.outboundBodyBytes > 5 GiB. Max rebuilt bytes forwarded upstream. */
export function limitsOutboundBytes(): number {
const v = tInt("BILI_OUTBOUND_BODY_BYTES", loadConfigFile().network?.outboundBodyBytes);
return Number.isFinite(v) && v > 0 ? Math.floor(v) : DEFAULT_LIMITS_OUTBOUND_BYTES;
}

// --- session persistence (was BILI_PERSIST_* env-only) ---

function filePersist() {
Expand Down
10 changes: 6 additions & 4 deletions src/request-body-budget.ts
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
import { limitsOutboundBytes, limitsReceiveBytes } from "./knobs.js";

export const MAX_REQUEST_BYTES = 100 * 1024 * 1024;
export const MAX_DECODED_REQUEST_BYTES = 2 * MAX_REQUEST_BYTES;
const MAX_LARGE_DECODED_REQUESTS = 2;
Expand All @@ -10,11 +12,11 @@ export class DecodedRequestBusyError extends Error {
}
}

/** 只限制超过旧上限的解压请求;普通请求不占超大正文名额。 */
/** 只限制超过配置的接收预算(limitsReceiveBytes)的解压请求;普通请求不占超大正文名额。 */
export class DecodedRequestAdmission {
private admitted = false;
observe(bytes: number): void {
if (bytes <= MAX_REQUEST_BYTES || this.admitted) return;
if (bytes <= limitsReceiveBytes() || this.admitted) return;
if (largeDecodedRequests >= MAX_LARGE_DECODED_REQUESTS) throw new DecodedRequestBusyError();
largeDecodedRequests++;
this.admitted = true;
Expand All @@ -28,12 +30,12 @@ export class DecodedRequestAdmission {

export class OutboundBodyTooLargeError extends Error {
constructor(public readonly bytes: number) {
super(`rebuilt request exceeds ${MAX_REQUEST_BYTES} bytes (${bytes} bytes); reduce historical images or content before retrying`);
super(`rebuilt request exceeds ${limitsOutboundBytes()} bytes (${bytes} bytes); reduce historical images or content before retrying`);
this.name = "OutboundBodyTooLargeError";
}
}

export function checkOutboundBody(body: unknown): void {
const bytes = typeof body === "string" ? Buffer.byteLength(body) : Buffer.isBuffer(body) ? body.byteLength : 0;
if (bytes > MAX_REQUEST_BYTES) throw new OutboundBodyTooLargeError(bytes);
if (bytes > limitsOutboundBytes()) throw new OutboundBodyTooLargeError(bytes);
}
15 changes: 8 additions & 7 deletions src/server.ts
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ import { resetProxyCache } from "./upstream-proxy.js";
import { FALLBACK_EFFECTIVE_WINDOW_FLOOR, findRoute, findRouteKey, lookupContextLimit, resolveConfiguredContextLimit, resolveConfiguredOutputLimit, resolveCompressProtocol, resolveResignSettings } from "./config.js";
import { contextFromRegistry, loadRegistry, peekRegistryContext, peekRegistryOutputLimit, peekRegistryPriceProfile } from "./registry.js";
import { codexAlignedWindow } from "./codex-models.js";
import { fetchWithTimeout, MAX_REQUEST_BYTES, upstreamTimeoutMs } from "./fetch-util.js";
import { fetchWithTimeout, upstreamTimeoutMs } from "./fetch-util.js";
import { getUpstreamConnectionStatus, resolveProxy, resolveProxyDecision, proxyDispatcher, type UpstreamProxyDecision } from "./upstream-proxy.js";
import type { SkippedProxyInfo } from "./upstream-fail.js";
import { getUpstreamAlerts } from "./upstream-alerts.js";
Expand Down Expand Up @@ -134,6 +134,7 @@ import {
forceTextProtocol as knobForceTextProtocol,
keepAliveTimeoutMs as knobKeepAliveTimeoutMs,
keepResponseId as knobKeepResponseId,
limitsReceiveBytes as knobLimitsReceiveBytes,
noCompressPrompt as knobNoCompressPrompt,
noInjectTool as knobNoInjectTool,
postResponseLingerMs as knobPostResponseLingerMs,
Expand Down Expand Up @@ -3521,10 +3522,10 @@ export function logRequestCost(log: (level: string, msg: string) => void, sessio
log("info", `[${sessionId}] request: ${msgs ?? "?"} msgs, inbound=${formatBytes(inboundBytes)}${outboundField}, local=${ms}ms${view}`);
}

/** Thrown by readBody when the request body exceeds MAX_REQUEST_BYTES.
* handle() catches this and attempts a 413 response; readBody also destroys
* the request socket so a client that keeps streaming a pathological body
* cannot hold the connection open. */
/** Thrown by readBody when the request body exceeds the configured receive-body
* budget (limitsReceiveBytes). handle() catches this and attempts a 413 response;
* readBody also destroys the request socket so a client that keeps streaming a
* pathological body cannot hold the connection open. */
export class BodyTooLargeError extends Error {
constructor(public readonly limit: number) {
super(`request body exceeds ${limit} bytes`);
Expand All @@ -3540,10 +3541,10 @@ export function readBody(req: http.IncomingMessage): Promise<Buffer> {
req.on("data", (c: Buffer) => {
if (aborted) return;
size += c.length;
if (size > MAX_REQUEST_BYTES) {
if (size > knobLimitsReceiveBytes()) {
aborted = true;
req.destroy();
reject(new BodyTooLargeError(MAX_REQUEST_BYTES));
reject(new BodyTooLargeError(knobLimitsReceiveBytes()));
return;
}
chunks.push(c);
Expand Down
Loading
Loading