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 CONFIGURATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -821,6 +821,7 @@ Environment variables take precedence over the config file. They are useful for
| `BILI_KEEP_ALIVE_TIMEOUT_MS` | Keep-alive timeout (ms) for client-facing sockets (default `5000`, matching Node's implicit default; #1452). Idle client connections are reaped with a clean FIN by Node's built-in reaper; this makes the previously implicit value explicit and configurable, and the reap is classified as `reason=idle-timeout` in the connection lifecycle ledger (debug log). Non-numeric or non-positive values fall back to `5000`. |
| `BILI_EXPOSURE_LOG_INTERVAL_MS` | Interval (ms) for the periodic long-lived-exposure telemetry line `[exposure] uptime=… liveConns=… tcpHandles=… handles=… sessions=… blindTunnels=… inFlight=…` (default `3600000` = hourly; #1452). `0` disables. Exists so socket-handle leaks and zombie connections surface in long-running logs instead of post-mortem forensics. |
| `BILI_CLIENT_ERROR_BACKSTOP_MS` | Terminal backstop (ms) for the clientError drain path (#1529, follow-up to #1452 item 1): after the 300ms drain bail has `end()`ed a connection whose peer never sends FIN, the socket would otherwise sit half-open on our side indefinitely — the keep-alive reaper keys off completed responses and Node enables no SO_KEEPALIVE by default. After this much post-bail silence the proxy destroys the socket instead, classified as `reason=clienterror-backstop` in the connection lifecycle ledger with its own warn marker. Safe against the #1452 RST signature: the socket has been `resume()`-drained for the whole window, so the destroy carries no unread residual bytes. Default `30000`; `0` restores the hold-until-peer-death status quo. Non-numeric or negative values fall back to `30000`. |
| `BILI_POST_RESPONSE_LINGER_MS` | Graceful-close budget (ms) after a completed response (#1982): when the proxy initiates closing a client connection right after the last response (e.g. `Connection: close`), it holds the socket open for up to this budget waiting for the peer's close signal — a TCP FIN or TLS close_notify, which can only arrive after our final byte was received+ACKed — then closes cleanly; if no signal arrives within the budget the socket is destroyed anyway and classified as `reason=linger-backstop` (warn line). This removes the abortive destroy that could race unACKed bytes into an RST on the client side (nginx `lingering_time` parity). Default `5000`; non-numeric or non-positive values fall back to `5000`. Error-driven closes, pre-handshake teardown, the clientError drain (#1529), and the idle reaper are intentionally unaffected. |
| `ACP_SESSION_HEADER` | Conversation-id header name (default `x-acp-session`). |
| `ACP_REASONING_KEEP` | Responses API only: set `none` to drop all reasoning items. Default routes reasoning through the compression pipeline so it is hidden automatically once its turn is summarized (prevents the unbounded accumulation that broke Codex's prompt-cache prefix). |
| `ACP_RENDER_NONE` | Set to `1` to stop injecting per-message render tags (the `` `<acp>` `` markers carrying `mNNNNN` refs) into outgoing request history — applies to every wire format (OpenAI chat, Anthropic, Responses) and compact rebuilds (#933). Default is `text-only`: the model reads these refs to cite messages in `compress` calls, so only disable them once you've confirmed your workflow doesn't need ref-based compression (e.g. tag echoes leaking into client-visible output). Previously this variable was honored only on the Responses path and compact; #933 extended it to all paths. |
Expand Down
1 change: 1 addition & 0 deletions CONFIGURATION.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -818,6 +818,7 @@
| `BILI_KEEP_ALIVE_TIMEOUT_MS` | 客户端侧套接字的 keep-alive 超时(毫秒,默认 `5000`,与 Node 隐式默认一致;#1452)。空闲客户端连接由 Node 内建回收器以干净 FIN 回收;此开关把原先隐式的值显式化并可配置,回收在连接生命周期台账(debug 日志)中分类为 `reason=idle-timeout`。非数字或非正值回退到 `5000`。 |
| `BILI_EXPOSURE_LOG_INTERVAL_MS` | 长驻暴露遥测行 `[exposure] uptime=… liveConns=… tcpHandles=… handles=… sessions=… blindTunnels=… inFlight=…` 的周期(毫秒,默认 `3600000` 即每小时;#1452)。`0` 关闭。目的是让套接字句柄泄漏与僵尸连接在长期运行日志中现形,而不是靠事后取证。 |
| `BILI_CLIENT_ERROR_BACKSTOP_MS` | clientError 排空路径的终局兜底(毫秒)(#1529,#1452 第 1 项后续):排空 bail(300ms)对连接调用 `end()` 后,若对端始终不发 FIN,该套接字否则会在我方无限期半开滞留——keep-alive 回收器以已完成响应为键,且 Node 默认不开 SO_KEEPALIVE。bail 后静默超过此值时,代理改为销毁该套接字,在连接生命周期台账中分类为 `reason=clienterror-backstop` 并带独立的 warn 标记。对 #1452 的 RST 签名安全:整个窗口内套接字一直处于 `resume()` 排空状态,销毁时不携带未读残留字节。默认 `30000`;`0` 恢复「持有直到对端死亡」的旧行为。非数字或负值回退到 `30000`。 |
| `BILI_POST_RESPONSE_LINGER_MS` | 响应完成后的优雅关闭预算(毫秒)(#1982):代理在最后一个响应结束后主动关闭客户端连接(如 `Connection: close`)时,最多为此预算时长持有该套接字,等待对端的关闭信号——TCP FIN 或 TLS close_notify(它只能在我方最后字节被接收并 ACK 之后到达)——然后干净地关闭;预算内无信号则照常销毁套接字,分类为 `reason=linger-backstop`(warn 行)。此举消除了可能在客户端侧把未 ACK 字节竞态成 RST 的激进销毁(与 nginx `lingering_time` 对齐)。默认 `5000`;非数字或非正值回退到 `5000`。错误驱动的关闭、握手前拆除、clientError 排空(#1529)与空闲回收器均刻意不受影响。 |
| `ACP_SESSION_HEADER` | 会话 id 请求头名称(默认 `x-acp-session`)。 |
| `ACP_REASONING_KEEP` | 仅 Responses API:设 `none` 丢弃全部 reasoning 项。默认让 reasoning 走压缩管道,其轮次被摘要后自动隐藏(避免无限累积破坏 Codex 的 prompt-cache 前缀)。 |
| `ACP_RENDER_NONE` | 设为 `1` 停止向出站请求历史注入逐消息渲染标签(承载 `mNNNNN` ref 的 `` `` `` 标记)——适用于所有线格式(OpenAI chat、Anthropic、Responses)及 compact 重建(#933)。默认 `text-only`:模型靠这些 ref 在 `compress` 调用中引用消息,只有确认自己的工作流不需要基于 ref 的压缩(例如标签回声泄漏到客户端可见输出)后才应禁用。此前该变量仅在 Responses 路径与 compact 上生效;#933 扩展到了所有路径。 |
Expand Down
4 changes: 4 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -375,6 +375,10 @@ By default the proxy binds `127.0.0.1` and only accepts loopback connections. To

All logs tee to `~/.local/state/billion-context/bili.log` by default (XDG state dir) and still print to stderr. Override with `"logFile"` in config or `ACP_LOG_FILE` (`off` disables the file). Auto-rotates at 10 MB (`bili.log.old`). Per-request cache-hit stats log as `[acp-usage] round N input=X cached=Y (cache hit Z%)` so you can measure prefix-cache health directly from the log.

### Connection lifecycle tuning (#1982)

Client-facing connections close gracefully after the final response: when the proxy initiates the close (`Connection: close`), it waits up to `BILI_POST_RESPONSE_LINGER_MS` (default `5000`) for the client's close signal before releasing the socket, so pooled clients see a clean EOF instead of a possible RST from racing bytes. Related knobs: `BILI_KEEP_ALIVE_TIMEOUT_MS` (idle-reap budget, default `5000`) and `BILI_CLIENT_ERROR_BACKSTOP_MS` (terminal backstop for the error-drain path, default `30000`) — full semantics in [CONFIGURATION.md](CONFIGURATION.md#environment-variables).

### Self-update

The proxy checks npm on startup and every 3 minutes; a newer version is installed in place and a notice is logged — **restart `bili` to pick it up**, unless you enable opt-in self-restart (`--auto-restart-on-update` flag, env `ACP_AUTO_RESTART_ON_UPDATE=1`, or `"autoRestartOnUpdate": true` in config — default OFF): with zero in-flight requests it verifies the new install, stops accepting connections, drains, spawns a replacement on the same port, and exits once it accepts connections (clients reconnect automatically; session state survives on disk). Safety gates: zero in-flight through the drain window, an install sanity check before re-exec, and a 10-minute cooldown marker so a flapping version can never loop-restart; any failure resumes the original listener and falls back to the plain reminder.
Expand Down
4 changes: 4 additions & 0 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -295,6 +295,10 @@ bili --no-auto-update # 本次启动禁用自动更新

所有日志**默认同时写入文件**:`~/.local/state/billion-context/bili.log`(XDG state 目录),同时仍打印到 stderr。覆盖用配置的 `"logFile"` 或 `ACP_LOG_FILE`(`off` 关闭文件)。超过 10 MB 自动轮转(`bili.log.old`)。每个请求的缓存命中统计以 `[acp-usage] round N input=X cached=Y (cache hit Z%)` 打印,可直接从日志衡量前缀缓存健康度。

### 连接生命周期调优(#1982)

客户端侧连接在最终响应结束后优雅关闭:代理主动发起关闭(`Connection: close`)时,最多等待 `BILI_POST_RESPONSE_LINGER_MS`(默认 `5000`)毫秒的对端关闭信号才释放套接字,池化客户端因此看到的是干净的 EOF,而非字节竞态可能产生的 RST。相关旋钮:`BILI_KEEP_ALIVE_TIMEOUT_MS`(空闲回收预算,默认 `5000`)与 `BILI_CLIENT_ERROR_BACKSTOP_MS`(错误排空路径终局兜底,默认 `30000`)——完整语义见 [CONFIGURATION.zh-CN.md](CONFIGURATION.zh-CN.md)。

### 自动更新

代理启动时和每 3 分钟检查 npm 是否有新版本。发现新版本就原位安装并打印通知 —— **重启 `bili` 才能生效**,除非启用可选自重启(`--auto-restart-on-update` 参数 / `ACP_AUTO_RESTART_ON_UPDATE=1` 环境变量 / 配置 `"autoRestartOnUpdate": true`,默认关闭):零在途请求时校验新安装、停止接收连接、排空、在同一端口拉起替代进程并在其开始接受连接后退出(客户端自动重连;会话状态在磁盘上保留)。安全门:排空窗口全程零在途、re-exec 前安装完整性检查、10 分钟冷却标记防止版本抖动循环重启;任何失败恢复原监听器并回落到普通提醒。运行进程落后于磁盘安装("stale")时,Web UI 显示横幅,`GET /__bili/status` 返回 `{version, diskVersion, stale, autoRestartOnUpdate, advisory, inFlight}` 供脚本使用(`advisory` 为生效中的严重缺陷公告或 `null`,见下节)。永久禁用:配置(`"autoUpdate": false`)或环境变量(`ACP_AUTO_UPDATE=0`)。
Expand Down
13 changes: 11 additions & 2 deletions src/mitm.ts
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,12 @@ export const DEFAULT_MITM_DOMAINS = [
* host the CONNECT tunnel targeted. */
export const MITM_UPSTREAM_KEY = "__biliMitmUpstream";

/** Socket marker: the raw TCP socket backing a MITM TLS leg. The connection
* ledger (#1982) pairs the two records so the raw leg's close — which Node's
* TLSWrap.close() structurally turns into destroy() even on fully graceful
* TLS closes — can be classified with knowledge of how its TLS leg closed. */
export const MITM_RAW_SOCKET_KEY = "__biliMitmRawSocket";

// A client that rejects our MITM cert (root CA not trusted) can flood the log
// with hundreds of identical handshake failures. Warn once, with the fix.
let warnedCertRejected = false;
Expand Down Expand Up @@ -272,8 +278,11 @@ function doMitm(
}
// Mark the socket so resolveUpstream() can recover the real origin. handle()
// sees the decrypted request as a plain POST /api/anthropic/v1/messages —
// with this marker it routes to https://<host> instead of the default.
(tlsSocket as unknown as Record<string, unknown>)[MITM_UPSTREAM_KEY] = `https://${host}`;
// with this marker it routes to https://<host>[:port] instead of the default.
// The port must be preserved: dropping it silently misroutes every
// non-443 CONNECT to :443 (connect-refused for local gateways).
(tlsSocket as unknown as Record<string, unknown>)[MITM_UPSTREAM_KEY] = `https://${host}${port === 443 ? "" : `:${port}`}`;
(tlsSocket as unknown as Record<string, unknown>)[MITM_RAW_SOCKET_KEY] = clientSocket;
// A TLS handshake error (client rejects our cert, abrupt disconnect,
// reset) emits "error" on the TLSSocket. Without a listener Node treats
// it as an uncaught exception and crashes the whole proxy. Destroy the
Expand Down
Loading
Loading