@leaf233/dsh-llm-rate-limiter 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.2.1] - 2026-09-25
+
+### Fixed
+- **Live status panel stopped working on DSH 0.1.5-rc.3** — the channel silently failed to mount and the panel sat on "○ 重试中" forever. Root cause is upstream: DSH 0.1.5-rc.3 changed `@deepseek-ai/dsh-client-connection`'s own `inject` from `["webServer", "credentials"]` to `["credentials"]`, while `HostConnectionService.register()` still dereferences `owner.webServer`. Cordis rebinds a cross-fiber service's `ctx` to the *reader's* fiber, so `connection.rpc.handle()` threw `cannot get property "webServer" without inject` — which the plugin's own try/catch swallowed.
+- The plugin now falls back to a **self-registered `kind: "prefix"` route** on its own fiber (which can see `webServer`) and reuses `connection.requestRejection()` for the 403/401 fence. Both carriers speak the identical wire protocol, so **`lib/client.js` is unchanged**.
+
+### Added
+- `createChannelRoute({ channel, handler, reject })` and `endpointFromPath()` in `lib/status-rpc.js` — a Connection-RPC-compatible webserver prefix route, mirroring the framework's `rpcFetchHandler` request-shape decisions (404 / 415 / 413 / 400 / `gateway/bad-request` / 500 / 200)
+- `test-status-route.mjs` (73 assertions) in four layers: route grammar, request-shape decisions, a simulated 0.1.5 regression (proves both the fallback *and* the preference for `rpc.handle` when it works), and the real 0.1.5 package (auto-skips when DSH is absent)
+- `tools/verify-live-route.mjs` (19 assertions) — boots the real `dsh-host-webserver` on a real socket plus the real `dsh-client-connection`, then issues real HTTP requests; exits 2 (skipped) without a DSH install
+- `pnpm run verify:live` script
+
+### Changed
+- `dsh.compatibility.dshReleases` now declares `0.1.5-rc.3` as compatible alongside `0.1.2-rc.1`
+- The status channel's mount log now names the active carrier (`connection.rpc` vs `self-registered route`), and a failed path-1 registration is reported as a warning instead of being swallowed
+- If `connection.requestRejection()` is unavailable or throws, the plugin **refuses to mount** rather than publishing an unauthenticated route
+
+### Notes
+- Path 1 (`connection.rpc.handle`) is still preferred: it keeps route ownership, request validation, and withdrawal with the framework. The fallback exists only for hosts where path 1 is broken.
+- When DSH fixes the upstream `inject` mismatch, path 1 succeeds again and the fallback goes unused — no plugin change required.
+- Verified on: DSH `0.1.5-rc.3` (client-connection 0.1.5-rc.3, host-webserver 0.1.5-rc.3), Cordis 4.0.2, Node 24.21.0. Test totals: 19 + 61 + 70 + 77 + 73 = **300 assertions**, plus 31 in `tools/verify-install.mjs` and 19 in `tools/verify-live-route.mjs`. Producer: **deepseek-v4.1-flash**.
+
 ## [0.2.0] - 2026-09-13
 
 ### Added

package/COMPATIBILITY.md

@@ -1,8 +1,73 @@
 # dsh-llm-rate-limiter — DSH 版本兼容性检测报告
 
-> 检测日期: 2026-07-28  
-> 本地 DSH 版本: **0.1.2-rc.1**  
-> 测试方式: 源码分析（npm registry 在沙箱中被拦截，无法查询其他版本）
+> 初检日期: 2026-07-28 · 复检日期: **2026-09-25**  
+> 已验证 DSH 版本: **0.1.2-rc.1**、**0.1.5-rc.3**  
+> 测试方式: 源码分析 + 可执行回归测试（`test-status-route.mjs`、`tools/verify-live-route.mjs` 走真实 socket）
+
+---
+
+## 〇、0.1.5-rc.3 回归与修复（2026-09-25 复检）
+
+### 现象
+升级到 DSH **0.1.5-rc.3** 后，状态面板永久停在「○ 重试中」，实时数据不再刷新；限速本身与设置页配置完全正常。
+
+### 根因（已用真实包 + 真实 Cordis 复现，非推断）
+DSH 0.1.5-rc.3 把 **`@deepseek-ai/dsh-client-connection` 这个框架插件自身**的 `inject` 从
+`["webServer", "credentials"]` 改成了 `["credentials"]`（lib/index.js:736），
+但其 `HostConnectionService.register()` 仍然直接解引用 `owner.webServer`：
+
+```js
+// dsh-client-connection/lib/index.js:618
+return owner.effect(() => owner.webServer.register(route), `... rpc channel`);
+```
+
+而 `connection.rpc` 的 getter 取 `const owner = this.ctx`，Cordis 的 `createTraceable`
+会把跨 fiber 读取的 service 的 `ctx` 重绑定到**读取者**的 fiber
+（实测 `owner.fiber === consumer.fiber` 为 true）。因此 `owner.webServer` 的解析从读取者的
+inject 出发 —— 读取者只 inject 了 `["connection"]`，于是抛：
+
+```
+cannot get property "webServer" without inject
+```
+
+该异常发生在插件 `ctx.inject(["connection"], ...)` 回调内，被插件自己的 try/catch 吞掉，
+只留一条 `logger.warn`，于是通道**静默未注册**。
+
+### 线上证据
+| 探测 | 修复前 | 含义 |
+|---|---|---|
+| `GET /api/xxx` | 401 | `/api` 路由存在，仅认证被拒 |
+| `GET /llm-rate-limiter/snapshot` | **404** | 该前缀**无路由**（走 SPA fallback） |
+| `POST /llm-rate-limiter/snapshot` | **405** | 同上 |
+
+而 `dsh --profile web --dump-config` 中插件条目仍存在 → 插件确实被加载，只是通道注册失败。
+
+### 交叉验证（隔离变量）
+| 实验 | 结果 |
+|---|---|
+| 0.1.2 代码 + fiber `[webServer,credentials]` | ✅ 注册成功 |
+| 0.1.2 代码 + fiber `[credentials]` | ❌ 失败 |
+| 0.1.5 代码 + fiber `[webServer,credentials]` | ✅ 注册成功 |
+| 0.1.5 代码 + fiber `[credentials]`（真实形态） | ❌ 失败 |
+
+→ 差异**只由 inject 列表决定**，与两版 `register` 代码差异无关。另实测：仅给**消费者**外层 fiber 加
+`webServer`（或嵌套 `ctx.inject(["connection","webServer"])`）**均无效** —— 因为 `owner` 绑定的是
+connection service 自身那条 fiber。
+
+### 修复（v0.2.1，方案 E）
+保留路径 1 为首选，新增路径 2 兜底，两者**同一套 wire 协议**，浏览器端零改动：
+
+| 路径 | 触发条件 | 做法 |
+|---|---|---|
+| 1（首选） | `connection.rpc.handle()` 正常 | 框架持有路由、请求校验与 fiber 级撤销 |
+| 2（兜底） | 路径 1 抛错 | 插件在**自己的 fiber**（能看到 `webServer`）注册 `kind:"prefix"` 路由，并复用 `connection.requestRejection()` 保留 403/401 栅栏 |
+
+- 若 `connection.requestRejection()` 缺失或抛错，插件**拒绝挂载**，绝不发布未鉴权路由
+- 上游修复该 inject 不一致后，路径 1 会自动重新生效，无需再改插件
+
+### 回归测试
+- `test-status-route.mjs`（73 断言）四层：路由语法、请求形态判定、**模拟 0.1.5 回归**（同时验证「兜底生效」与「路径 1 可用时优先」）、真实 0.1.5 包（无 DSH 时自动跳过）
+- `tools/verify-live-route.mjs`（19 断言）：真实 `dsh-host-webserver` 真 socket + 真实 `dsh-client-connection`，发真实 HTTP 请求；无 DSH 时退出码 2（跳过）
 
 ---
 
@@ -34,7 +99,8 @@
 
 | # | API | 所属包 | 本地存在 | 稳定性评估 |
 |---|-----|--------|----------|------------|
-| 1 | `ctx.inject(["connection"], cb)` + `conn.rpc.handle(channel, handler)` | dsh-client-connection | ✅ `HostConnectionService.register`（lib/index.js 572-589） | **公开通用 API**；注册包在 `owner.effect` 中，卸载自动撤通道。通道名须匹配 `/^\/[A-Za-z0-9._~-]+$/` 且非 `/api` |
+| 1 | `ctx.inject(["connection"], cb)` + `conn.rpc.handle(channel, handler)` | dsh-client-connection | ⚠️ 0.1.2 可用 / **0.1.5 抛错** | 首选路径。0.1.5-rc.3 起因该包自身 `inject` 缺 `webServer` 而抛 `cannot get property "webServer" without inject`，故 v0.2.1 增加路径 2 兜底 |
+| 1b | `conn.requestRejection(req)` + `ctx.inject(["webServer"], cb)` + `webServer.register({kind:"prefix",...})` | dsh-client-connection + dsh-host-webserver | ✅ 0.1.2 / 0.1.5 | **v0.2.1 兜底路径**。复用框架的 403/401 栅栏，自行注册前缀路由；wire 协议与路径 1 逐字一致 |
 | 2 | handler 签名 `(endpoint, payload, signal) => envelope` | dsh-client-connection | ✅ `rpcFetchHandler`（605-631） | 框架强制 POST + `application/json`（否则 404/415），并自动套 `requestRejection`（Host/Origin 不信→403，未认证→401） |
 | 3 | envelope `{ok:true,value}` / `{ok:false,error:{code,message,details}}` | dsh-client-connection | ✅ 与 `clientRequestSchema` / `errorResponse` 一致 | 契约字面量，dsh-context 逐字复制同一范式 |
 | 4 | 客户端 `ctx.get("connection")?.rpc.call(channel, endpoint, payload, signal)` | dsh-client-connection | ✅ `createWebConnectionRpc.call`（client.js 4606-4628） | 传输失败 reject；返回 `result`（即 envelope）。经 `rpcCallOf` 反射读取，服务缺席/敌意时降级为 `undefined` |
@@ -143,8 +209,13 @@
    - [ ] `settings.register` 返回值结构是否变化
    - [ ] `settingsScope.set/mutate` 接口是否变化
    - [ ] `settings.plugin.item` slot 是否仍可注入
-   - [ ] **状态通道（v0.2.0）**：`connection.rpc.handle` 仍为公开 API 且通道名规则未变
-   - [ ] **状态通道（v0.2.0）**：`snapshot` / `reset` 端点往返成功（面板显示"● 实时"而非"状态通道不可用"）
-   - [ ] **状态通道（v0.2.0）**：折叠卡片后 DevTools Network 无 `/llm-rate-limiter/snapshot` 轮询
-   - [ ] **状态通道（v0.2.0）**：无 connection 服务的组合下，卡片配置区仍可用且面板显示降级文案
+   - [ ] **状态通道**：`connection.rpc.handle` 是否仍抛 `webServer` 相关错误（0.1.5-rc.3 会）
+   - [ ] **状态通道**：`connection.requestRejection` 仍为公开 API（兜底路径的鉴权依赖它）
+   - [ ] **状态通道**：`webServer.register({kind:"prefix"})` 仍接受前缀路由
+   - [ ] **状态通道**：`snapshot` / `reset` 端点往返成功（面板显示"● 实时"而非"重试中"）
+   - [ ] **状态通道**：折叠卡片后 DevTools Network 无 `/llm-rate-limiter/snapshot` 轮询
+   - [ ] **状态通道**：无 connection 服务的组合下，卡片配置区仍可用且面板显示降级文案
+   - [ ] **状态通道**：直接 `POST /llm-rate-limiter/snapshot` 应返回 401（路由存在且被栅栏保护），而非 404/405（路由缺失）
+
+   > 上述清单已由 `test-status-route.mjs` + `tools/verify-live-route.mjs` 自动覆盖，升级 DSH 后先跑 `pnpm test && pnpm run verify:live`。
 4. **如果 cordis 升级到 5.0+**：整个 `apply(ctx)` 接口、`ctx.effect()`、`ctx.on()` 签名可能重写，需要全面适配

package/README.md

@@ -4,7 +4,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![DSH 0.1.x](https://img.shields.io/badge/DSH-0.1.x-brightgreen.svg)](COMPATIBILITY.md)
 [![Cordis 4.x](https://img.shields.io/badge/Cordis-%3E%3D4.0.2-brightgreen.svg)](package.json)
-[![Tests](https://img.shields.io/badge/tests-19%2F19%20passing-brightgreen.svg)](test-strategies.mjs)
+[![Tests](https://img.shields.io/badge/tests-300%20passing-brightgreen.svg)](test-status-route.mjs)
 
 Per-model LLM call rate limiter for [DeepSeek Harness](https://github.com/deepseek-ai/dsh) with queue/reject support and interactive GUI configuration.
 
@@ -39,7 +39,8 @@ Expanding the card shows a live panel at the top of its body:
 
 | Aspect | Behaviour |
 |--------|-----------|
-| Data channel | Framework `connection.rpc` channel `/llm-rate-limiter` — authenticated (401/403 fence), POST+JSON, auto-cleaned with the plugin fiber |
+| Data channel | Channel `/llm-rate-limiter` — authenticated (401/403 fence), POST+JSON, auto-cleaned with the plugin fiber |
+| Carrier | Prefers the framework's `connection.rpc.handle()`; falls back to a self-registered prefix route that reuses `connection.requestRejection()` when the framework path is broken (see below) |
 | Cadence | 1 s polling while the card is expanded; backs off 2 s → 4 s → 8 s after failures |
 | Collapsed card | The panel unmounts, so **no polling runs at all** |
 | Endpoints | `snapshot` (live counters) and `reset` (zero the statistics) |
@@ -49,6 +50,30 @@ Expanding the card shows a live panel at the top of its body:
 
 > 🧠 **From Hindsight memory (dsh-context-host-client)** — the channel idiom is dsh-context's: `ctx.inject(["connection"])` → `conn.rpc.handle(channel, handler)`, with the browser side resolving `ctx.get("connection")?.rpc.call` defensively so a missing service degrades instead of throwing.
 
+### Carrier fallback (DSH 0.1.5-rc.3)
+
+DSH 0.1.5-rc.3 changed `@deepseek-ai/dsh-client-connection`'s own `inject` from
+`["webServer", "credentials"]` to `["credentials"]`, but its
+`HostConnectionService.register()` still dereferences `owner.webServer`.
+Cordis rebinds a cross-fiber service's `ctx` to the *reader's* fiber, so
+`connection.rpc.handle()` throws:
+
+```
+cannot get property "webServer" without inject
+```
+
+The plugin now detects that and mounts the same channel itself:
+
+| Path | When | How |
+|------|------|-----|
+| 1 (preferred) | `connection.rpc.handle()` works | The framework owns the route, request validation, and fiber-scoped withdrawal |
+| 2 (fallback) | Path 1 throws | The plugin registers a `kind: "prefix"` route on its own fiber (which *can* see `webServer`) and reuses `connection.requestRejection()` for the 403/401 fence |
+
+Both carriers speak the identical wire protocol, so **the browser half is
+unchanged** — the panel cannot tell which one is live. If
+`connection.requestRejection()` is unavailable, the plugin refuses to mount
+rather than publishing an unauthenticated route.
+
 
 ---
 
@@ -189,8 +214,18 @@ cd dsh-llm-rate-limiter
 # Install deps
 pnpm install
 
-# Run tests (19 tests)
-node test-strategies.mjs
+# Run the full suite (300 assertions across 5 files)
+pnpm test
+
+# Individual suites
+node test-strategies.mjs       # 19 — rate-limit algorithms
+node test-status-rpc.mjs       # 61 — channel handler + counters
+node test-client-bundle.mjs    # 70 — real client bundle on a miniature React runtime
+node test-host-integration.mjs # 77 — real apply() wiring
+node test-status-route.mjs     # 73 — self-registered route + the 0.1.5 regression
+
+# Live HTTP proof against a real DSH install (real socket, real webserver)
+pnpm run verify:live           # 19 — exits 2 (skipped) when DSH is absent
 
 # Run E2E rate-limit test
 node test-3rpm.mjs
@@ -207,7 +242,8 @@ The plugin uses a live symlink when installed via `link:` — edits to `lib/` ta
 
 | DSH Version | Status | Notes |
 |-------------|--------|-------|
-| 0.1.x (RC) | ✅ Tested | Verified against 0.1.2-rc.1, cordis 4.0.2 |
+| 0.1.2-rc.1 | ✅ Tested | Original target; `connection.rpc` carrier |
+| 0.1.5-rc.3 | ✅ Tested | Requires the carrier fallback (see above); verified over real HTTP |
 | 0.2.x | ⚠️ Untested | May need API adjustments |
 | Cordis 5+ | ⚠️ Untested | Major version change likely requires rewrite |
 

package/lib/index.js

@@ -21,7 +21,7 @@
 import { TokenBucketStrategy } from "./strategies/token-bucket.js";
 import { SlidingWindowStrategy } from "./strategies/sliding-window.js";
 import { RateLimiterConfig } from "./types/config.js";
-import { CHANNEL, createStatusChannel } from "./status-rpc.js";
+import { CHANNEL, createChannelRoute, createStatusChannel } from "./status-rpc.js";
 
 const name = "llm-rate-limiter";
 const SETTINGS_NS = "llm-rate-limiter";
@@ -184,28 +184,90 @@ function apply(ctx) {
     }, "rate-limiter: settings scope teardown");
   });
 
-  // ── Status RPC channel (dynamic inject) ────────────────────
+  // ── Status channel (dynamic inject) ────────────────────────
   // Same defensive shape as the settings wiring: on a host without a
   // connection service the callback never runs and the plugin stays silent.
-  // The registration is owned by this fiber, so unloading withdraws it.
+  // Either path below registers inside an effect owned by this fiber, so
+  // unloading the plugin withdraws the channel automatically.
+  //
+  // Two mounting paths exist, and both speak the same wire protocol, so the
+  // browser half never needs to know which one is live:
+  //
+  //   1. connection.rpc.handle(channel, handler) — the framework's generic
+  //      channel registry (preferred: the framework owns the route, the
+  //      request validation, and the withdrawal).
+  //
+  //   2. a self-registered prefix route reusing connection.requestRejection()
+  //      — the fallback for hosts where path 1 is broken. DSH 0.1.5-rc.3
+  //      changed dsh-client-connection's own `inject` from
+  //      ["webServer", "credentials"] to ["credentials"] while its
+  //      HostConnectionService.register() still dereferences
+  //      `owner.webServer`, and Cordis rebinds a cross-fiber service's `ctx`
+  //      to the *reader's* fiber — so rpc.handle() throws
+  //      'cannot get property "webServer" without inject'. Registering the
+  //      route on our own fiber (which injects webServer below) avoids that
+  //      while still using the framework's own 403/401 fence.
   ctx.inject(["connection"], (scopedCtx) => {
     const connection = scopedCtx.get("connection");
+    const channel = createStatusChannel({ buildSnapshot, resetTotals });
+
+    // ── Path 1: the framework's generic channel registry ──
     const handle = typeof connection?.rpc?.handle === "function"
       ? connection.rpc.handle.bind(connection.rpc)
       : undefined;
-    if (handle === undefined) return; // older host: degrade silently
 
+    if (handle !== undefined) {
+      try {
+        scopedCtx.effect(() => {
+          const unregister = handle(CHANNEL, channel);
+          return () => { unregister(); };
+        }, "rate-limiter: status rpc channel");
+        logger?.info("rate limiter status channel mounted via connection.rpc (%s)", CHANNEL);
+        return;
+      } catch (err) {
+        logger?.warn(
+          "connection.rpc channel registration failed (%s); falling back to a self-registered route",
+          err instanceof Error ? err.message : String(err),
+        );
+      }
+    }
+
+    // ── Path 2: self-registered route (needs webServer on THIS fiber) ──
+    // The fence is mandatory: without connection.requestRejection() we would
+    // be publishing an unauthenticated route, so we refuse to mount at all.
+    // Probing once here turns a broken fence into a mount-time refusal instead
+    // of a per-request surprise.
     try {
-      scopedCtx.effect(() => {
-        const unregister = handle(CHANNEL, createStatusChannel({ buildSnapshot, resetTotals }));
-        return () => { unregister(); };
-      }, "rate-limiter: status rpc channel");
+      if (typeof connection?.requestRejection !== "function") {
+        logger?.warn("connection.requestRejection unavailable; status channel not mounted");
+        return;
+      }
+      connection.requestRejection({ headers: {} });
     } catch (err) {
-      logger?.warn("status channel registration failed: %s", err instanceof Error ? err.message : String(err));
+      logger?.warn(
+        "connection.requestRejection unusable (%s); refusing to mount an unfenced status route",
+        err instanceof Error ? err.message : String(err),
+      );
       return;
     }
 
-    logger?.info("rate limiter status channel mounted (%s)", CHANNEL);
+    scopedCtx.inject(["webServer"], (webCtx) => {
+      const webServer = webCtx.get("webServer");
+      if (typeof webServer?.register !== "function") return; // no web carrier: degrade silently
+
+      try {
+        webCtx.effect(() => webServer.register(createChannelRoute({
+          channel: CHANNEL,
+          handler: channel,
+          reject: (req) => connection.requestRejection(req),
+        })), "rate-limiter: status route (self-registered)");
+      } catch (err) {
+        logger?.warn("status channel registration failed: %s", err instanceof Error ? err.message : String(err));
+        return;
+      }
+
+      logger?.info("rate limiter status channel mounted via self-registered route (%s)", CHANNEL);
+    });
   });
 
   // ── LLM stream interceptor ─────────────────────────────────

package/lib/status-rpc.js

@@ -2,15 +2,27 @@
  * dsh-llm-rate-limiter — status RPC channel (Host half).
  *
  * Exposes live rate-limiter statistics to the browser over the framework's
- * generic Connection RPC channel — the same idiom dsh-context uses for its
- * detail channel. The framework supplies POST+JSON transport, the Host/Origin
- * fence (403) and browser authentication (401); this module only answers
- * endpoints and shapes envelopes.
+ * generic Connection RPC channel. The framework supplies POST+JSON transport,
+ * the Host/Origin fence (403) and browser authentication (401); this module
+ * only answers endpoints and shapes envelopes.
  *
- * Registration is owned by the calling fiber (`register()` wraps
- * `owner.webServer.register` in `owner.effect`), so unloading the plugin
- * withdraws the channel automatically — there is no connection bookkeeping
- * here.
+ * Two mounting paths exist, and both speak the *same* wire protocol so the
+ * browser half never needs to know which one is active:
+ *
+ *  1. `connection.rpc.handle(channel, handler)` — the framework's own generic
+ *     channel registry. Preferred: the framework owns the route, the request
+ *     validation, and the fiber-scoped withdrawal.
+ *
+ *  2. `createChannelRoute({ channel, handler, reject })` — a self-registered
+ *     prefix route for hosts where path 1 is broken. DSH 0.1.5-rc.3 changed
+ *     `@deepseek-ai/dsh-client-connection`'s own `inject` from
+ *     `["webServer", "credentials"]` to `["credentials"]` while
+ *     `HostConnectionService.register()` still dereferences
+ *     `owner.webServer`, so `rpc.handle` throws
+ *     `cannot get property "webServer" without inject`. This route is
+ *     registered on our own fiber (which *can* see `webServer`) and reuses the
+ *     connection service's public `requestRejection()` fence, so the 403/401
+ *     policy is still the framework's.
  *
  * Envelope contract (mirrors the Connection wire schema):
  *   success: { ok: true,  value: <JSON-safe> }
@@ -25,6 +37,27 @@
  */
 const CHANNEL = "/llm-rate-limiter";
 
+/**
+ * Endpoint grammar for one path segment, copied verbatim from the framework's
+ * `ENDPOINT_SEGMENT_PATTERN` in dsh-client-connection. Keeping it identical is
+ * what makes the self-registered route accept and reject exactly the same URLs
+ * as `rpc.handle` would.
+ */
+const ENDPOINT_SEGMENT_PATTERN = /^[A-Za-z0-9_$.-]+$/;
+
+/**
+ * Buffered-body cap for the self-registered route. Both endpoints are called
+ * with an empty payload, so this is a defensive memory bound rather than a
+ * real limit (the framework uses its own, much larger, carrier cap).
+ */
+const MAX_REQUEST_BODY_BYTES = 1024 * 1024;
+
+/**
+ * Correlation id echoed when the request envelope cannot be parsed at all —
+ * the same literal the framework uses (`INVALID_REQUEST_RPC_ID`).
+ */
+const INVALID_REQUEST_RPC_ID = "invalid-request";
+
 /**
  * Build a failure envelope. Field-for-field the same shape the Connection
  * host accepts, so callers can rely on `ok` discrimination alone.
@@ -64,4 +97,189 @@ function createStatusChannel({ buildSnapshot, resetTotals }) {
   };
 }
 
-export { CHANNEL, createStatusChannel, failure, success };
+/* ── self-registered route (the DSH 0.1.5-rc.3 fallback) ───────────────── */
+
+/** Narrow an unknown JSON value to a plain object. */
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Extract the endpoint from a channel-relative pathname, mirroring the
+ * framework's `endpointFromPath`: a single `channel/<endpoint>` segment whose
+ * segments all satisfy {@link ENDPOINT_SEGMENT_PATTERN}.
+ *
+ * @param {string} channel - the channel prefix (e.g. `/llm-rate-limiter`).
+ * @param {string} pathname - request pathname.
+ * @returns {string | undefined} the endpoint, or undefined when the URL is not
+ *   a well-formed member of this channel.
+ */
+function endpointFromPath(channel, pathname) {
+  if (!pathname.startsWith(`${channel}/`)) return undefined;
+  const endpoint = pathname.slice(channel.length + 1);
+  const segments = endpoint.split("/");
+  if (segments.some((segment) => segment === "" || segment === "." || segment === ".." || !ENDPOINT_SEGMENT_PATTERN.test(segment))) return undefined;
+  return endpoint;
+}
+
+/**
+ * Read and decode the request body, refusing anything above `limit` bytes so a
+ * hostile caller cannot make the host buffer without bound.
+ *
+ * @param {import("node:http").IncomingMessage} req - node request stream.
+ * @param {number} limit - maximum accepted byte count.
+ * @returns {Promise<string>} the decoded UTF-8 body.
+ * @throws {Error & { code: "TOO_LARGE" }} when the body exceeds `limit`.
+ */
+async function readBody(req, limit) {
+  const chunks = [];
+  let received = 0;
+  for await (const chunk of req) {
+    const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+    received += buffer.byteLength;
+    if (received > limit) {
+      const error = new Error("request body too large");
+      error.code = "TOO_LARGE";
+      throw error;
+    }
+    chunks.push(buffer);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+/**
+ * Write one `server-response` envelope as JSON — byte-for-byte the shape
+ * `Response.json(...)` produces on the framework's own route.
+ *
+ * @param {import("node:http").ServerResponse} res - response to own.
+ * @param {string} rpcId - correlation id to echo.
+ * @param {object} result - the `{ ok, value }` / `{ ok, error }` envelope.
+ */
+function sendEnvelope(res, rpcId, result) {
+  res.writeHead(200, { "content-type": "application/json" });
+  res.end(JSON.stringify({ type: "server-response", rpcId, result }));
+}
+
+/**
+ * Build a webserver prefix route that speaks the Connection RPC wire protocol.
+ *
+ * This is the fallback carrier for {@link createStatusChannel} on hosts where
+ * `connection.rpc.handle` throws. Every request-shape decision mirrors the
+ * framework's `rpcFetchHandler` so the browser half is byte-compatible with the
+ * preferred path:
+ *
+ * | condition | response |
+ * |---|---|
+ * | fence/auth rejected by `reject` | `403` (or `401`) + `forbidden`/`unauthorized` |
+ * | non-POST, or URL outside the channel | `404 not found` |
+ * | `content-type` not `application/json` | `415` |
+ * | body over {@link MAX_REQUEST_BODY_BYTES} | `413` |
+ * | body not JSON | `400 body is not JSON` |
+ * | envelope not a `client-request` | `gateway/bad-request` envelope |
+ * | `method` ≠ endpoint | `gateway/bad-request` envelope |
+ * | handler threw | `500 handler failure: ...` |
+ * | otherwise | `200` + `server-response` envelope |
+ *
+ * @param {object} deps
+ * @param {string} deps.channel - channel prefix to own (e.g. `/llm-rate-limiter`).
+ * @param {(endpoint: string, payload: unknown, signal?: AbortSignal) => Promise<object>} deps.handler - endpoint dispatcher.
+ * @param {(req: import("node:http").IncomingMessage) => number | undefined} deps.reject - the framework's `connection.requestRejection` fence; returns an HTTP status to refuse with, or undefined to allow.
+ * @returns {{ kind: "prefix", path: string, handler: (req: import("node:http").IncomingMessage, res: import("node:http").ServerResponse) => Promise<void> }}
+ */
+function createChannelRoute({ channel, handler, reject }) {
+  return {
+    kind: "prefix",
+    path: channel,
+    handler: async (req, res) => {
+      // 1. The framework's own fence: Host/Origin trust (403) then browser
+      //    authentication (401). Reusing it keeps the security policy identical.
+      const rejection = reject(req);
+      if (rejection !== undefined) {
+        res.writeHead(rejection);
+        res.end(rejection === 401 ? "unauthorized" : "forbidden");
+        return;
+      }
+
+      // 2. POST-only, and only inside this channel (framework: 404 otherwise).
+      const url = new URL(req.url ?? "/", "http://dsh.internal");
+      const endpoint = endpointFromPath(channel, url.pathname);
+      if (req.method !== "POST" || endpoint === undefined) {
+        res.writeHead(404);
+        res.end("not found");
+        return;
+      }
+
+      // 3. JSON only (framework: 415).
+      const mediaType = String(req.headers["content-type"] ?? "").split(";", 1)[0].trim().toLowerCase();
+      if (mediaType !== "application/json") {
+        res.writeHead(415);
+        res.end("content type must be application/json");
+        return;
+      }
+
+      // 4. Buffer the body under a defensive cap, then parse it.
+      let raw;
+      try {
+        raw = await readBody(req, MAX_REQUEST_BODY_BYTES);
+      } catch (error) {
+        if (error?.code === "TOO_LARGE") {
+          res.writeHead(413, { connection: "close" });
+          res.end();
+          req.destroy?.();
+          return;
+        }
+        throw error;
+      }
+      let body;
+      try {
+        body = JSON.parse(raw);
+      } catch {
+        res.writeHead(400);
+        res.end("body is not JSON");
+        return;
+      }
+
+      // 5. Validate the client-request envelope; echo the correlation id
+      //    whenever it is a string, exactly like the framework does.
+      const rpcId = typeof body?.rpcId === "string" ? body.rpcId : INVALID_REQUEST_RPC_ID;
+      if (!isRecord(body) || body.type !== "client-request" || typeof body.rpcId !== "string" || typeof body.method !== "string") {
+        sendEnvelope(res, rpcId, failure("gateway/bad-request", "invalid client-request message", { issues: [] }));
+        return;
+      }
+      if (body.method !== endpoint) {
+        sendEnvelope(res, rpcId, failure(
+          "gateway/bad-request",
+          `method ${JSON.stringify(body.method)} does not match endpoint ${JSON.stringify(endpoint)}`,
+          { issues: [] },
+        ));
+        return;
+      }
+
+      // 6. Dispatch. Tie the signal to the response lifetime, as the framework's
+      //    http bridge does, so a dropped client can cancel the work.
+      const abort = new AbortController();
+      res.on?.("close", () => {
+        if (!res.writableEnded) abort.abort();
+      });
+      let result;
+      try {
+        result = await handler(endpoint, body.payload, abort.signal);
+      } catch (error) {
+        res.writeHead(500);
+        res.end(`handler failure: ${String(error)}`);
+        return;
+      }
+      sendEnvelope(res, rpcId, result);
+    },
+  };
+}
+
+export {
+  CHANNEL,
+  MAX_REQUEST_BODY_BYTES,
+  createChannelRoute,
+  createStatusChannel,
+  endpointFromPath,
+  failure,
+  success,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leaf233/dsh-llm-rate-limiter",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Per-model LLM call rate limiter for DeepSeek Harness with queue support and a live status panel",
   "type": "module",
   "main": "lib/index.js",
@@ -21,13 +21,15 @@
     },
     "compatibility": {
       "dshReleases": {
-        "0.1.2-rc.1": "compatible"
+        "0.1.2-rc.1": "compatible",
+        "0.1.5-rc.3": "compatible"
       }
     }
   },
   "scripts": {
     "build": "echo 'no build needed'",
-    "test": "node test-strategies.mjs"
+    "test": "node test-strategies.mjs && node test-status-rpc.mjs && node test-client-bundle.mjs && node test-host-integration.mjs && node test-status-route.mjs",
+    "verify:live": "node tools/verify-live-route.mjs"
   },
   "repository": {
     "type": "git",