dsh-boost 0.1.4 → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.en.md +60 -18
- package/README.md +53 -17
- package/dist/http/fence.js +119 -0
- package/dist/http/fence.js.map +1 -0
- package/dist/http/mount.js +71 -0
- package/dist/http/mount.js.map +1 -0
- package/dist/http/state.js +216 -0
- package/dist/http/state.js.map +1 -0
- package/dist/index.js +36 -4
- package/dist/index.js.map +1 -1
- package/dist/scope/doc.js +8 -0
- package/dist/scope/doc.js.map +1 -1
- package/dist/scope/store.js +5 -4
- package/dist/scope/store.js.map +1 -1
- package/dist/shared/api-prefix.js +9 -0
- package/dist/shared/api-prefix.js.map +1 -0
- package/dist/shared/api-types.js +10 -0
- package/dist/shared/api-types.js.map +1 -0
- package/dist/tools/boost.js +11 -3
- package/dist/tools/boost.js.map +1 -1
- package/lib/client.js +929 -0
- package/locale/en.json +96 -2
- package/locale/zh.json +96 -2
- package/package.json +21 -7
package/README.en.md
CHANGED
|
@@ -85,32 +85,52 @@ denominator statistic that a later version must add.
|
|
|
85
85
|
directory:
|
|
86
86
|
|
|
87
87
|
```bash
|
|
88
|
-
# install from the registry: npmjs has latest = 0.
|
|
88
|
+
# install from the registry: npmjs has latest = 0.2.0 (this repository's
|
|
89
89
|
# .npmrc and lockfile are pinned to npmjs too — see below)
|
|
90
|
-
dsh plugin --profile <name> add dsh-boost@^0.
|
|
90
|
+
dsh plugin --profile <name> add dsh-boost@^0.2.0 --registry=https://registry.npmjs.org/
|
|
91
91
|
|
|
92
92
|
# or from a local checkout (build first; dist/ is not committed)
|
|
93
93
|
npm run build
|
|
94
94
|
dsh plugin --profile <name> add /absolute/path/to/dsh-boost
|
|
95
95
|
```
|
|
96
96
|
|
|
97
|
-
For the web profile: `dsh plugin --profile web add dsh-boost@^0.
|
|
97
|
+
For the web profile: `dsh plugin --profile web add dsh-boost@^0.2.0 --registry=https://registry.npmjs.org/`.
|
|
98
98
|
`dsh plugin` forwards the operation to pnpm, so pnpm must be on `PATH`.
|
|
99
99
|
|
|
100
|
-
>
|
|
101
|
-
> `
|
|
102
|
-
> current `latest` on both), `0.1.2`, `0.1.1`, `0.1.0`, and `0.0.0-stage`, the placeholder npm
|
|
100
|
+
> **`^0.2.0` is the current safe pin.** `registry.npmjs.org` has `latest` at `0.2.0`, with
|
|
101
|
+
> `0.1.4`, `0.1.3`, `0.1.2`, `0.1.1`, `0.1.0` behind it, plus `0.0.0-stage`, the placeholder npm
|
|
103
102
|
> creates on a package's first publish — **do not install `0.0.0-stage`**; it is not a usable
|
|
104
|
-
> build. 0.
|
|
105
|
-
>
|
|
106
|
-
>
|
|
107
|
-
>
|
|
108
|
-
>
|
|
109
|
-
>
|
|
110
|
-
>
|
|
111
|
-
>
|
|
112
|
-
>
|
|
113
|
-
|
|
103
|
+
> build. `0.2.0` adds the settings page (`dsh.client`, the `./client` export, the
|
|
104
|
+
> `/dsh-boost/api` routes, and a `lib/client.js` shipped in the tarball) and Chinese/English
|
|
105
|
+
> localisation; `0.1.4` and earlier **have no settings page**, and `^0.1.4` does not resolve to
|
|
106
|
+
> `0.2.0` (`^` does not cross a major version), so upgrading from `0.1.x` means writing
|
|
107
|
+
> `@^0.2.0` explicitly. This repository's `.npmrc` and lockfile are pinned to npmjs, but **your
|
|
108
|
+
> machine's global npm config** may still point at a mirror that has not synced `0.2.0`: that is
|
|
109
|
+
> local configuration, not this repository's state. Pass `--registry=https://registry.npmjs.org/`
|
|
110
|
+
> explicitly when the registry matters; against a lagging mirror `@^0.2.0` fails to resolve until
|
|
111
|
+
> it catches up.
|
|
112
|
+
|
|
113
|
+
## Settings page
|
|
114
|
+
|
|
115
|
+
Once installed and enabled in a profile, the host's settings panel gains a **"Token efficiency"**
|
|
116
|
+
section (「Token 效率」 in Chinese). It does three things:
|
|
117
|
+
|
|
118
|
+
- **Shows state**: every degradation code with what to do about it, the substitution saving as a
|
|
119
|
+
lower and upper bound, projection gross and net, retrieval count, receipt counts, the fixed
|
|
120
|
+
per-request overhead, and the **effective** configuration (read-only — editing it means editing
|
|
121
|
+
the profile's `cordis.patch.yml`).
|
|
122
|
+
- **Edits scope**: `mode` (all workspaces or selected ones), `workspaceIds`, `shadow`,
|
|
123
|
+
`projection`. It writes `<dshHome>/boost/scope.json` through the **same** CAS as the `boost`
|
|
124
|
+
tool's `scope-set`, so neither overwrites the other; if someone else got there first the page
|
|
125
|
+
reports `ERR_SCOPE_REVISION_CONFLICT` and keeps your draft, leaving the decision to you.
|
|
126
|
+
- **Warns about the two dangerous switches**: projection going to `on` shows the spill
|
|
127
|
+
precondition; turning shadow mode off shows the `content[].thinking` 400 to watch for. Both
|
|
128
|
+
give a rollback and both are **advisory, never gates** — whether this route is an
|
|
129
|
+
Anthropic-compatible thinking mode cannot be determined on this machine, and a gate would only
|
|
130
|
+
create the illusion of having checked.
|
|
131
|
+
|
|
132
|
+
When the page cannot reach its data (no `webServer`, a reverse proxy that drops `Host`) it shows a
|
|
133
|
+
stable code instead of an empty table; `curl <host>/dsh-boost/api/state` returns the same JSON.
|
|
114
134
|
|
|
115
135
|
The package is ESM (`"type": "module"`) and the `.` entry of `exports` also maps `require` /
|
|
116
136
|
`default`: on Node >= 24.9, `require('dsh-boost')` loads the very same code as `import`. Nothing
|
|
@@ -150,7 +170,10 @@ the clean default (`ENOENT` carries no degradation code, `src/scope/store.ts`);
|
|
|
150
170
|
with the host capabilities in place, `degraded` is simply an empty array. On the `status` read
|
|
151
171
|
path,
|
|
152
172
|
`ERR_SCOPE_READ_FAILED` means the file **exists but cannot be read** (permissions, I/O, a
|
|
153
|
-
directory in its place, …) — not a normal first run; fix it first.
|
|
173
|
+
directory in its place, …) — not a normal first run; fix it first. A failed *write* is a different
|
|
174
|
+
code, `ERR_SCOPE_WRITE_FAILED` (disk full, directory permissions): the page then asks you to retry
|
|
175
|
+
unchanged rather than re-read, because the baseline is still valid and a re-read would throw away
|
|
176
|
+
your draft. The first successful `scope-set` creates the file.
|
|
154
177
|
|
|
155
178
|
Then list the workspace to expose:
|
|
156
179
|
|
|
@@ -546,12 +569,31 @@ to load. `llm` is soft (only the selector uses it); when absent the selector fal
|
|
|
546
569
|
| (spill backend present but failing) | — | Every `saveText` is rejected: the receipt records `projection-skipped:spill-failed` and `status.degraded` reports **`ERR_HOST_SPILL_FAILING`**. This is a **third** state — neither "no backend" nor "no footer renderer" — and telling an operator to restore the spill package would send them after a package that is installed and failing |
|
|
547
570
|
| `@deepseek-ai/dsh-token-meter/estimate` | soft (dynamic import) | Fixed overhead cannot be measured, so `fixedOverheadTokens` is `'unknown'`; `status.degraded` reports `ERR_HOST_NO_ESTIMATOR` |
|
|
548
571
|
| `win32` platform | runtime `isPosixOnly()` check | Substitution is refused, projection still works; `status.degraded` reports `ERR_HOST_PLATFORM_UNSUPPORTED` |
|
|
572
|
+
| `locale` | soft (`ctx.get('locale')`) | The settings page **follows the host language** (Chinese and English, the nav label included); without this service it falls back to Chinese with one `console.warn`, and the page still works; projection, substitution and the `boost` tool are unaffected |
|
|
573
|
+
| `webServer` | soft (dynamic `ctx.inject(['webServer'], …)`) | **The settings page has no data**: the route is not mounted and the page shows `ERR_CLIENT_NETWORK` with a pointer to the host log. Projection, substitution and the `boost` tool are **unaffected** — this is the only dependency whose absence costs only the page. Once mounted, the trusted `Host` list comes from `webStartup.trustedHosts` (loopback-only when unreadable), so a reverse proxy that drops `Host` is stopped by `ERR_HTTP_FORBIDDEN` |
|
|
549
574
|
| Host version line | startup check of the `@deepseek-ai/dsh-app-boot` version | A version **outside the `engines.dsh` range** (`>=0.2.2-rc.4 <0.2.3-0`) logs `ERR_HOST_VERSION_MISMATCH` and loads anyway — advisory only, not a `status.degraded` code. A version inside the range but not the verified `0.2.2-rc.4` (such as `rc.5` / `0.2.2`) logs an info line, no code; an undeterminable version or an unparseable range also logs info only |
|
|
550
575
|
| Receipt shard readability | `boost status` full scan (not a dependency) | When at least one receipt shard cannot be read (EACCES, a directory named `x.jsonl`, …), `status.degraded` carries `ERR_RECEIPTS_UNREADABLE`; `status` stays a **total over the healthy shards** — they are still counted — so the figures may be incomplete. Check permissions and stray entries in `<dshHome>/boost/receipts/`, fix, and re-run `status`, comparing counts |
|
|
551
576
|
| Receipt shard count | `boost status` full scan (not a dependency) | When more than 256 shards exist, `status` counts only the first 256 by encoded name and `status.degraded` carries `ERR_RECEIPTS_TRUNCATED`; every count is therefore a **lower bound**. Shards are never pruned automatically; archive or move old session shards and re-run `status` |
|
|
552
577
|
| Prompt assembly waterfall | outgoing-request probe (not a dependency) | When the host's `complete: true` prompt section replaces the assembled system prompt after the waterfall and the protocol section never reaches the request, `status.degraded` carries `ERR_HOST_COMPLETE_SECTION`; substitution and projection fail closed for the affected requests (the plugin stays inert although the workspace is visible). Find the complete section overriding the waterfall (usually another plugin's) and remove it, or accept the inaction on those requests |
|
|
553
578
|
|
|
554
579
|
`ERR_HOST_NO_STEP_WHEN` no longer exists: step-level `when` has been part of
|
|
580
|
+
The settings page's data route has codes of its own, and they are **not** members of
|
|
581
|
+
`status.degraded` — every failure returns one in a JSON body, and the page decides what to say from it:
|
|
582
|
+
|
|
583
|
+
| Code | Where | Meaning |
|
|
584
|
+
|---|---|---|
|
|
585
|
+
| `ERR_HTTP_FORBIDDEN` | route body (403) | Same-origin fence refused: `Host` is neither loopback nor in `webStartup.trustedHosts`, or `sec-fetch-site: cross-site`, or `Origin` and `Host` name different authorities, or `Origin` does not parse |
|
|
586
|
+
| `ERR_HTTP_METHOD` | route body (405) | A write reached `/state`, or something other than `GET`/`HEAD`/`POST` reached `/scope` |
|
|
587
|
+
| `ERR_HTTP_BODY` | route body (400) | The write body is not valid JSON, or exceeds 64 KiB |
|
|
588
|
+
| `ERR_HTTP_NOT_FOUND` | route body (404) | The prefix matched but the sub-path is unknown: page and server are different versions |
|
|
589
|
+
| `ERR_HTTP_INTERNAL` | route body (500) | A host service getter threw while reading `status`/`scope`; none of the four blocks is returned |
|
|
590
|
+
| `ERR_HTTP_WORKSPACES_UNAVAILABLE` | route body (`workspaces.available === false`) | No registry, or `list()` threw: the page disables saving and says the list could not be read rather than rendering an empty one |
|
|
591
|
+
| `ERR_CLIENT_NETWORK` | page only (never on the wire) | The page could not reach the route: it may not be mounted |
|
|
592
|
+
| `ERR_CLIENT_SHAPE` | page only | The route returned a body this page cannot read: version mismatch |
|
|
593
|
+
|
|
594
|
+
`ERR_BOOST_HTTP_MOUNT_FAILED` goes to the log only: mounting the route threw (`ctx.inject` missing or
|
|
595
|
+
refused), so the page has no data source. It is not `ERR_BOOST_PARTIAL_MOUNT` — that one is about hooks.
|
|
596
|
+
|
|
555
597
|
`ToolRegistrationOptions` since the oldest host line this package declares, so the plugin no
|
|
556
598
|
longer probes it and registers unconditionally.
|
|
557
599
|
|
|
@@ -657,7 +699,7 @@ The source and docs live in the repository at
|
|
|
657
699
|
| [Design](docs/superpowers/specs/2026-11-18-dsh-token-efficiency-design.md) | Goals, evidence, architecture, contracts, measurement, risks, release shape |
|
|
658
700
|
| [Host contracts appendix](docs/superpowers/plans/2026-11-18-host-contracts.md) | Interface reference copied line by line from the host sources |
|
|
659
701
|
| [Three-tier delegation research](docs/research/2026-11-18-three-tier-delegation.md) | 25 primary sources on caching, routing thresholds, compression, and verification |
|
|
660
|
-
| [Release acceptance](docs/RELEASE.md) | The one-command `npm run verify:package` acceptance, the zero-peerDependencies state and install spec, the degradation-code matrix, the 20-task regression procedure (manual; the task set, runner, and locator-retrieval integrity check all remain undelivered), and the shadow week and stats recompute |
|
|
702
|
+
| [Release acceptance](docs/RELEASE.md) | The one-command `npm run verify:package` acceptance, the two release-gate invariants (no static host import in `dist/`; the client artifact resolves host modules only through `require` and must carry the loader envelope), the zero-peerDependencies state and install spec, the degradation-code matrix, the 20-task regression procedure (manual; the task set, runner, and locator-retrieval integrity check all remain undelivered), and the shadow week and stats recompute |
|
|
661
703
|
|
|
662
704
|
## License
|
|
663
705
|
|
package/README.md
CHANGED
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
## 它解决什么
|
|
10
10
|
|
|
11
11
|
DSH 每次模型请求都会回放全部历史。本机 300 个最长会话的实测聚合(`npm run --silent stats`——不带
|
|
12
|
-
`--silent` 时 npm 会把 `> dsh-boost@0.
|
|
12
|
+
`--silent` 时 npm 会把 `> dsh-boost@0.2.0 stats` 横幅打进 stdout,机器解析请用 `--silent` 或直接
|
|
13
13
|
`node scripts/session-stats.mjs`;快照时刻 `2026-11-19T03:13:21Z`):54,141 步、54,088 个请求,合计 10,575,904,022 raw token。按步均值
|
|
14
14
|
195,340 token,按请求均值 195,531、中位 187,681;97.01% 的输入是缓存读。工具回执是体积主体
|
|
15
15
|
(bash 61.75%、read 22.13%、ssh 10.01%),而下一步真正会用到的部分通常远小于回执本身。
|
|
@@ -64,29 +64,45 @@ v1 的**事前估算**区间是 **3.5%(下界)– 10.0%(理想上界)**
|
|
|
64
64
|
`dsh plugin` 要求指定 profile,剩下的参数原样转发给该 profile 目录里的 pnpm:
|
|
65
65
|
|
|
66
66
|
```bash
|
|
67
|
-
# 从 registry 安装:npmjs 上的 latest 是 0.
|
|
67
|
+
# 从 registry 安装:npmjs 上的 latest 是 0.2.0(本仓库 .npmrc 与 lockfile
|
|
68
68
|
# 也已钉在 npmjs,见下)
|
|
69
|
-
dsh plugin --profile <name> add dsh-boost@^0.
|
|
69
|
+
dsh plugin --profile <name> add dsh-boost@^0.2.0 --registry=https://registry.npmjs.org/
|
|
70
70
|
|
|
71
71
|
# 或从本地 checkout 安装(先构建;dist/ 不入库)
|
|
72
72
|
npm run build
|
|
73
73
|
dsh plugin --profile <name> add /absolute/path/to/dsh-boost
|
|
74
74
|
```
|
|
75
75
|
|
|
76
|
-
例如 web profile:`dsh plugin --profile web add dsh-boost@^0.
|
|
76
|
+
例如 web profile:`dsh plugin --profile web add dsh-boost@^0.2.0 --registry=https://registry.npmjs.org/`。
|
|
77
77
|
`dsh plugin` 把操作转发给 pnpm,所以 pnpm 必须在 PATH 上。
|
|
78
78
|
|
|
79
|
-
>
|
|
80
|
-
> `
|
|
81
|
-
> `0.
|
|
82
|
-
> `
|
|
83
|
-
>
|
|
84
|
-
>
|
|
85
|
-
>
|
|
86
|
-
>
|
|
87
|
-
>
|
|
88
|
-
|
|
89
|
-
|
|
79
|
+
> **`^0.2.0` 是当前的安全钉法。** `registry.npmjs.org` 上 `latest` 是 `0.2.0`,历史版本依次是
|
|
80
|
+
> `0.1.4`、`0.1.3`、`0.1.2`、`0.1.1`、`0.1.0`,以及首次发布时 npm 自动创建的占位版本
|
|
81
|
+
> `0.0.0-stage`——**不要安装 `0.0.0-stage`**,它不是可用构建。`0.2.0` 新增了设置页
|
|
82
|
+
> (`dsh.client` 与 `./client` 出口、`/dsh-boost/api` 路由、随包发布的 `lib/client.js`)与中英
|
|
83
|
+
> 双语;`0.1.4` 及更早**没有设置页**,`^0.1.4` 也不会解析到 `0.2.0`(`^` 不跨大版本),所以从
|
|
84
|
+
> `0.1.x` 升上来要显式写 `@^0.2.0`。本仓库已把 `.npmrc` 与 lockfile 钉在 npmjs,但**你机器上
|
|
85
|
+
> 的全局 npm 配置**可能仍指向一个尚未同步 `0.2.0` 的镜像:那是本机配置,不是本仓库的状态。
|
|
86
|
+
> 在意 registry 时显式传 `--registry=https://registry.npmjs.org/`;镜像滞后时 `@^0.2.0` 会在
|
|
87
|
+
> 同步前解析失败。
|
|
88
|
+
|
|
89
|
+
## 设置页
|
|
90
|
+
|
|
91
|
+
装好并在 profile 里启用之后,宿主设置面板里会多出一节 **「Token 效率」**(英文界面是
|
|
92
|
+
“Token efficiency”)。它做三件事:
|
|
93
|
+
|
|
94
|
+
- **看状态**:降级码及每个码该怎么办、替换节省的上下界、投影毛额与净额、取回次数、各类收据
|
|
95
|
+
计数、常驻开销,以及当前**生效**配置(只读——改配置要编辑 profile 的 `cordis.patch.yml`)。
|
|
96
|
+
- **改作用域**:`mode`(全部工作区 / 仅选中的工作区)、`workspaceIds`、`shadow`、`projection`
|
|
97
|
+
四个字段。写的是 `<dshHome>/boost/scope.json`,与 `boost` 工具的 `scope-set` 走**同一个**
|
|
98
|
+
CAS,所以两边改都不会互相覆盖;别人先改了,页面会给出 `ERR_SCOPE_REVISION_CONFLICT` 并保留
|
|
99
|
+
你的草稿,由你决定要不要按磁盘上的文档重来。
|
|
100
|
+
- **提示危险开关**:投影切到 `on` 时提示 spill 前置条件;关掉影子模式时提示盯一次含
|
|
101
|
+
`content[].thinking` 的 400。两处都给回滚办法,都**只提示不做硬门**——当前路由是不是
|
|
102
|
+
Anthropic 兼容的 thinking 模式在这台机器上查不出来,硬门只会给出“已检查过”的错觉。
|
|
103
|
+
|
|
104
|
+
页面读不到数据(宿主没有 `webServer`、反向代理没透传 `Host`)时会显示稳定码而不是空白表格;
|
|
105
|
+
`curl <host>/dsh-boost/api/state` 能看到同一份 JSON。
|
|
90
106
|
|
|
91
107
|
包是 ESM(`"type": "module"`),`exports` 的 `.` 条目同时映射 `require` / `default`:Node ≥ 24.9
|
|
92
108
|
下 `require('dsh-boost')` 与 `import` 加载同一份代码,装好的包里**不做任何构建**(`files` 只带
|
|
@@ -120,7 +136,8 @@ bundle,patch 的 `insert` 行落在 profile root 上。**装完必须重启 DS
|
|
|
120
136
|
缺失而出现 `ERR_SCOPE_READ_FAILED`:缺失是干净的默认值(`ENOENT` 不带降级码,
|
|
121
137
|
`src/scope/store.ts`);全新根目录且宿主能力齐全时,`degraded` 就是空数组。在 `status` 的
|
|
122
138
|
读取路径上,`ERR_SCOPE_READ_FAILED` 只表示文件**存在但读不出来**(权限、I/O、路径是目录
|
|
123
|
-
|
|
139
|
+
等)——那不是正常的首次状态,要先修掉。写不进去是另一个码 `ERR_SCOPE_WRITE_FAILED`(磁盘满、
|
|
140
|
+
目录权限),页面拿到它会让你原样重试而不是重读——基线还在,重读会丢掉草稿。
|
|
124
141
|
第一次成功的 `scope-set` 会创建这个文件。
|
|
125
142
|
|
|
126
143
|
然后列出要暴露的工作区:
|
|
@@ -456,12 +473,31 @@ horizon 重放,并计入 `projection_horizon_reestimated`;`projection_horizo
|
|
|
456
473
|
| `@deepseek-ai/dsh-spill-policy/notice` | 软(动态 import) | spill 后端在,但页脚渲染器 `formatSpillNotice` 加载不到/不存在:apply 模式无法拼页脚,逐条跳过(收据 `projection-skipped:no-footer`;页脚渲染时抛错则记 `projection-skipped:footer-failed`),`status.degraded` 带 `ERR_HOST_NO_SPILL_NOTICE`。这与「没有 spill 后端」的 `ERR_HOST_NO_SPILL` 是两件事 |
|
|
457
474
|
| (spill 后端存在但写失败) | — | 每次 `saveText` 被拒:收据 `projection-skipped:spill-failed`,`status.degraded` 带 **`ERR_HOST_SPILL_FAILING`**。这是**第三种**状态,既不是「没有后端」也不是「没有页脚渲染器」——让操作者去「恢复 spill 包」会把一个已装好却报错的包当成没装 |
|
|
458
475
|
| `@deepseek-ai/dsh-token-meter/estimate` | 软(动态 import) | 固定开销无法测量,`fixedOverheadTokens` 为 `'unknown'`;`status.degraded` 带 `ERR_HOST_NO_ESTIMATOR` |
|
|
476
|
+
| `locale` | 软(`ctx.get('locale')`) | 设置页**跟随宿主语言**(中英双语,导航项标签一起换);缺这个服务时回落中文并 `console.warn` 说明一次,页面照常可用;投影、替换与 `boost` 工具不受影响 |
|
|
477
|
+
| `webServer` | 软(动态注入 `ctx.inject(['webServer'], …)`) | **设置页读不到数据**:路由没挂上,页面显示 `ERR_CLIENT_NETWORK` 并提示去看宿主日志。投影、替换与 `boost` 工具**完全不受影响**——这是唯一一个缺失只影响页面的依赖。挂上之后 `Host` 的受信名单来自 `webStartup.trustedHosts`(读不到就只信 loopback),所以反向代理没透传 `Host` 时页面会被 `ERR_HTTP_FORBIDDEN` 挡住 |
|
|
459
478
|
| `win32` 平台 | 运行时检查 `isPosixOnly()` | 拒绝替换,投影照常;`status.degraded` 带 `ERR_HOST_PLATFORM_UNSUPPORTED` |
|
|
460
479
|
| 宿主版本线 | 启动时读 `@deepseek-ai/dsh-app-boot` 的版本 | 版本**落在 `engines.dsh` 区间外**(`>=0.2.2-rc.4 <0.2.3-0`)时日志警告 `ERR_HOST_VERSION_MISMATCH`,插件照常加载(advisory,不是 `status.degraded` 码);区间内但不是验证过的 `0.2.2-rc.4`(如 `rc.5` / `0.2.2`)只记 info、不发码;版本读不到或区间无法解析时也只记 info |
|
|
461
480
|
| 收据分片可读性 | `boost status` 全量扫描(非依赖) | 至少一个收据分片读不出来(EACCES、名为 `x.jsonl` 的目录等)时 `status.degraded` 带 `ERR_RECEIPTS_UNREADABLE`;`status` 仍是**全量聚合**——健康分片照常计数——所以数字可能不完整。查 `<dshHome>/boost/receipts/` 的权限与异常条目,修复后重跑并对比计数 |
|
|
462
481
|
| 收据分片数量 | `boost status` 全量扫描(非依赖) | 分片超过 256 个时 `status` 只统计按编码名排序的前 256 个,`status.degraded` 带 `ERR_RECEIPTS_TRUNCATED`,所有计数因此是**下界**;分片永不自动删除,可归档/移走旧会话分片后重跑 `status` |
|
|
463
482
|
| 提示段装配瀑布 | 出站请求探测(非依赖) | 宿主的 `complete: true` 提示段在装配瀑布之后替换了整个系统提示、协议段没有到达请求时,`status.degraded` 带 `ERR_HOST_COMPLETE_SECTION`;受影响请求上替换与投影 fail-closed(工作区明明可见插件却不动作)。找出宿主里覆盖瀑布的 complete 段(通常属于另一个插件)并移除,或接受这些请求上不动作 |
|
|
464
483
|
|
|
484
|
+
设置页的数据路由有自己的码,它们**不是** `status.degraded` 的成员——每次失败都以 JSON 体返回一个码,
|
|
485
|
+
页面据码决定说什么:
|
|
486
|
+
|
|
487
|
+
| 码 | 出现位置 | 含义 |
|
|
488
|
+
|---|---|---|
|
|
489
|
+
| `ERR_HTTP_FORBIDDEN` | 路由响应体(403) | 同源栅栏拒绝:`Host` 既非 loopback 也不在 `webStartup.trustedHosts` 里,或 `sec-fetch-site: cross-site`,或 `Origin` 与 `Host` 不同 authority,或 `Origin` 解析不了 |
|
|
490
|
+
| `ERR_HTTP_METHOD` | 路由响应体(405) | 对 `/state` 发了写,或对 `/scope` 发了 `GET`/`HEAD`/`POST` 以外的方法 |
|
|
491
|
+
| `ERR_HTTP_BODY` | 路由响应体(400) | 写请求的体不是合法 JSON,或超过 64 KiB |
|
|
492
|
+
| `ERR_HTTP_NOT_FOUND` | 路由响应体(404) | 前缀匹配上了但子路径不认识:页面与服务端版本不一致 |
|
|
493
|
+
| `ERR_HTTP_INTERNAL` | 路由响应体(500) | 读 `status`/`scope` 时宿主服务的 getter 抛错;四块内容一个都不返回 |
|
|
494
|
+
| `ERR_HTTP_WORKSPACES_UNAVAILABLE` | 路由响应体(`workspaces.available === false`) | 没有注册表,或 `list()` 抛错:页面禁用保存并说明「读不到」,不渲染空列表 |
|
|
495
|
+
| `ERR_CLIENT_NETWORK` | 页面(不经网络) | 页面读不到路由:可能没挂上 |
|
|
496
|
+
| `ERR_CLIENT_SHAPE` | 页面(不经网络) | 路由返回的体本页读不懂:版本不匹配 |
|
|
497
|
+
|
|
498
|
+
`ERR_BOOST_HTTP_MOUNT_FAILED` 只进日志:路由挂载本身抛了(`ctx.inject` 不可用或被拒绝),
|
|
499
|
+
页面因此没有数据源。它与 `ERR_BOOST_PARTIAL_MOUNT` 是两件事——后者说的是钩子。
|
|
500
|
+
|
|
465
501
|
`ERR_HOST_NO_STEP_WHEN` 已不存在:步骤级 `when` 从本包声明的最老宿主线起就在
|
|
466
502
|
`ToolRegistrationOptions` 里,插件不再探测、无条件注册。
|
|
467
503
|
|
|
@@ -543,7 +579,7 @@ spill,报它只会制造噪音);但**收据通道**不看当前模式—
|
|
|
543
579
|
| [设计稿](docs/superpowers/specs/2026-11-18-dsh-token-efficiency-design.md) | 目标、证据、架构、契约、度量、风险、发布形态 |
|
|
544
580
|
| [宿主契约附录](docs/superpowers/plans/2026-11-18-host-contracts.md) | 逐条抄自宿主源码的接口准绳 |
|
|
545
581
|
| [三层委派研究](docs/research/2026-11-18-three-tier-delegation.md) | 缓存、路由阈值、压缩、校验的 25 条一手来源 |
|
|
546
|
-
| [发布验收](docs/RELEASE.md) | `npm run verify:package`
|
|
582
|
+
| [发布验收](docs/RELEASE.md) | `npm run verify:package` 一条命令验收、两条发布门不变式(服务端 `dist/` 零静态宿主 import;客户端产物只经 `require` 解析宿主模块且必须带加载器信封)、零 peerDependencies 现状与安装规格、降级码矩阵、20 任务回退流程(人工;任务集、runner 与取回完整性检查均未交付)、影子周与统计复算 |
|
|
547
583
|
|
|
548
584
|
## 许可证
|
|
549
585
|
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The browser-trust fence for the plugin's own HTTP surface.
|
|
3
|
+
*
|
|
4
|
+
* WHY THIS EXISTS: `webServer.register` does no authentication and claims no
|
|
5
|
+
* path namespace. Any page the operator's browser loads from any origin can
|
|
6
|
+
* POST to this server, and the host's SPA is not the only client that can. The
|
|
7
|
+
* read route returns the full scope document, so "only the settings page talks
|
|
8
|
+
* to it" has to be enforced here or nowhere.
|
|
9
|
+
*
|
|
10
|
+
* Two confused-deputy paths are closed:
|
|
11
|
+
*
|
|
12
|
+
* - **DNS rebinding** — an attacker-controlled name resolving to this server,
|
|
13
|
+
* so the browser's own request looks same-origin. `Host` is the one header
|
|
14
|
+
* rebinding cannot forge, so it is judged first and unconditionally.
|
|
15
|
+
* - **Cross-site requests** — a malicious page firing a request at this
|
|
16
|
+
* server. An attached `Origin` that disagrees with `Host` is rejected, and
|
|
17
|
+
* `sec-fetch-site: cross-site` rejects before that comparison is reached.
|
|
18
|
+
*
|
|
19
|
+
* AN ABSENT `Origin` IS NOT AN ATTACK. Over plain HTTP a browser attaches
|
|
20
|
+
* neither `Origin` nor Fetch Metadata to a same-origin GET — the settings
|
|
21
|
+
* page's own reads carry no `Origin` at all. Requiring one would 403 the page
|
|
22
|
+
* that owns this surface while stopping nothing (a cross-site read is `no-cors`
|
|
23
|
+
* and cannot read the body; a `cors` read sends `Origin` and is rejected).
|
|
24
|
+
* Writes are the opposite case: a browser DOES send `Origin` on POST, so a
|
|
25
|
+
* write route requires it (`requireOrigin`).
|
|
26
|
+
*/
|
|
27
|
+
/** The first value of a header, ignoring the array form Node allows. */
|
|
28
|
+
function header(headers, name) {
|
|
29
|
+
const value = headers[name];
|
|
30
|
+
if (typeof value === 'string')
|
|
31
|
+
return value;
|
|
32
|
+
if (Array.isArray(value)) {
|
|
33
|
+
const first = value[0];
|
|
34
|
+
return typeof first === 'string' ? first : undefined;
|
|
35
|
+
}
|
|
36
|
+
return undefined;
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* Canonical authority of a `Host` header or a `trustedHosts` entry.
|
|
40
|
+
*
|
|
41
|
+
* Returns `undefined` for anything a URL cannot express, which is how a
|
|
42
|
+
* malformed `Host` becomes a rejection rather than a comparison that happens
|
|
43
|
+
* to pass.
|
|
44
|
+
*/
|
|
45
|
+
export function parseAuthority(value) {
|
|
46
|
+
if (typeof value !== 'string' || value.length === 0)
|
|
47
|
+
return undefined;
|
|
48
|
+
try {
|
|
49
|
+
const url = new URL(`http://${value}`);
|
|
50
|
+
if (url.hostname === '')
|
|
51
|
+
return undefined;
|
|
52
|
+
return { hostname: url.hostname, host: url.host, bare: url.port === '' };
|
|
53
|
+
}
|
|
54
|
+
catch {
|
|
55
|
+
return undefined;
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
/**
|
|
59
|
+
* Whether a hostname names the local machine.
|
|
60
|
+
*
|
|
61
|
+
* The input is the WHATWG serialisation, which KEEPS the brackets on an IPv6
|
|
62
|
+
* literal: `new URL('http://[::1]:23023').hostname` is `'[::1]'`.
|
|
63
|
+
*/
|
|
64
|
+
export function isLoopbackHostname(hostname) {
|
|
65
|
+
if (hostname === 'localhost' || hostname === '::1' || hostname === '[::1]')
|
|
66
|
+
return true;
|
|
67
|
+
const bare = hostname.startsWith('[') && hostname.endsWith(']') ? hostname.slice(1, -1) : hostname;
|
|
68
|
+
if (bare === '::1')
|
|
69
|
+
return true;
|
|
70
|
+
// 127.0.0.0/8. A deployment may bind 127.0.0.53 and a browser may name it.
|
|
71
|
+
return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(bare);
|
|
72
|
+
}
|
|
73
|
+
/**
|
|
74
|
+
* Whether the request authority is a deployment-declared trusted host.
|
|
75
|
+
*
|
|
76
|
+
* A port-less entry matches the hostname on any port — the shape the CLI
|
|
77
|
+
* derives for IP-literal LAN serving, where the bound port may be OS-assigned.
|
|
78
|
+
* An entry with an explicit port matches that exact authority.
|
|
79
|
+
*/
|
|
80
|
+
export function isTrustedAuthority(authority, trustedHosts) {
|
|
81
|
+
for (const entry of trustedHosts) {
|
|
82
|
+
const parsed = parseAuthority(entry);
|
|
83
|
+
if (parsed === undefined)
|
|
84
|
+
continue;
|
|
85
|
+
if (parsed.bare ? parsed.hostname === authority.hostname : parsed.host === authority.host) {
|
|
86
|
+
return true;
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
return false;
|
|
90
|
+
}
|
|
91
|
+
/**
|
|
92
|
+
* The fence. Returns `true` only when the request may be served.
|
|
93
|
+
*
|
|
94
|
+
* Branches run in this order, and the order is the design: `Host` first
|
|
95
|
+
* because rebinding forges everything else, then Fetch Metadata, then
|
|
96
|
+
* `Origin` — so a request that fails an earlier branch never reaches a later
|
|
97
|
+
* comparison that a malformed value could accidentally satisfy.
|
|
98
|
+
*/
|
|
99
|
+
export function isTrustedWebRequest(request, options = {}) {
|
|
100
|
+
const host = header(request.headers, 'host');
|
|
101
|
+
const authority = parseAuthority(host);
|
|
102
|
+
if (authority === undefined)
|
|
103
|
+
return false;
|
|
104
|
+
if (!isLoopbackHostname(authority.hostname) && !isTrustedAuthority(authority, options.trustedHosts ?? [])) {
|
|
105
|
+
return false;
|
|
106
|
+
}
|
|
107
|
+
if (header(request.headers, 'sec-fetch-site') === 'cross-site')
|
|
108
|
+
return false;
|
|
109
|
+
const origin = header(request.headers, 'origin');
|
|
110
|
+
if (origin === undefined)
|
|
111
|
+
return options.requireOrigin !== true;
|
|
112
|
+
try {
|
|
113
|
+
return new URL(origin).host === authority.host;
|
|
114
|
+
}
|
|
115
|
+
catch {
|
|
116
|
+
return false;
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
//# sourceMappingURL=fence.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"fence.js","sourceRoot":"","sources":["../../src/http/fence.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The browser-trust fence for the plugin's own HTTP surface.\n *\n * WHY THIS EXISTS: `webServer.register` does no authentication and claims no\n * path namespace. Any page the operator's browser loads from any origin can\n * POST to this server, and the host's SPA is not the only client that can. The\n * read route returns the full scope document, so \"only the settings page talks\n * to it\" has to be enforced here or nowhere.\n *\n * Two confused-deputy paths are closed:\n *\n * - **DNS rebinding** — an attacker-controlled name resolving to this server,\n * so the browser's own request looks same-origin. `Host` is the one header\n * rebinding cannot forge, so it is judged first and unconditionally.\n * - **Cross-site requests** — a malicious page firing a request at this\n * server. An attached `Origin` that disagrees with `Host` is rejected, and\n * `sec-fetch-site: cross-site` rejects before that comparison is reached.\n *\n * AN ABSENT `Origin` IS NOT AN ATTACK. Over plain HTTP a browser attaches\n * neither `Origin` nor Fetch Metadata to a same-origin GET — the settings\n * page's own reads carry no `Origin` at all. Requiring one would 403 the page\n * that owns this surface while stopping nothing (a cross-site read is `no-cors`\n * and cannot read the body; a `cors` read sends `Origin` and is rejected).\n * Writes are the opposite case: a browser DOES send `Origin` on POST, so a\n * write route requires it (`requireOrigin`).\n */\n\n/** A parsed `Host` header or `trustedHosts` entry. */\nexport interface Authority {\n /** WHATWG hostname; an IPv6 literal keeps its brackets. */\n hostname: string\n /** Hostname and port, as `URL.host` serialises them. */\n host: string\n /** Whether the value carried no explicit port. */\n bare: boolean\n}\n\n/** What the fence needs from a request: header access, nothing else. */\nexport interface HeaderCarrier {\n headers: Record<string, string | string[] | undefined>\n}\n\n/** The fence's inputs. */\nexport interface FenceOptions {\n /** Authorities the deployment declared (`webStartup.trustedHosts`). */\n trustedHosts?: readonly string[]\n /**\n * Whether an absent `Origin` is refused.\n *\n * False for reads (the page's own GETs carry none); true for writes (a\n * browser always sends one on POST, so its absence means a non-browser\n * client, which this surface does not serve).\n */\n requireOrigin?: boolean\n}\n\n/** The first value of a header, ignoring the array form Node allows. */\nfunction header(headers: HeaderCarrier['headers'], name: string): string | undefined {\n const value = headers[name]\n if (typeof value === 'string') return value\n if (Array.isArray(value)) {\n const first = value[0]\n return typeof first === 'string' ? first : undefined\n }\n return undefined\n}\n\n/**\n * Canonical authority of a `Host` header or a `trustedHosts` entry.\n *\n * Returns `undefined` for anything a URL cannot express, which is how a\n * malformed `Host` becomes a rejection rather than a comparison that happens\n * to pass.\n */\nexport function parseAuthority(value: unknown): Authority | undefined {\n if (typeof value !== 'string' || value.length === 0) return undefined\n try {\n const url = new URL(`http://${value}`)\n if (url.hostname === '') return undefined\n return { hostname: url.hostname, host: url.host, bare: url.port === '' }\n } catch {\n return undefined\n }\n}\n\n/**\n * Whether a hostname names the local machine.\n *\n * The input is the WHATWG serialisation, which KEEPS the brackets on an IPv6\n * literal: `new URL('http://[::1]:23023').hostname` is `'[::1]'`.\n */\nexport function isLoopbackHostname(hostname: string): boolean {\n if (hostname === 'localhost' || hostname === '::1' || hostname === '[::1]') return true\n const bare = hostname.startsWith('[') && hostname.endsWith(']') ? hostname.slice(1, -1) : hostname\n if (bare === '::1') return true\n // 127.0.0.0/8. A deployment may bind 127.0.0.53 and a browser may name it.\n return /^127\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}$/.test(bare)\n}\n\n/**\n * Whether the request authority is a deployment-declared trusted host.\n *\n * A port-less entry matches the hostname on any port — the shape the CLI\n * derives for IP-literal LAN serving, where the bound port may be OS-assigned.\n * An entry with an explicit port matches that exact authority.\n */\nexport function isTrustedAuthority(authority: Authority, trustedHosts: readonly string[]): boolean {\n for (const entry of trustedHosts) {\n const parsed = parseAuthority(entry)\n if (parsed === undefined) continue\n if (parsed.bare ? parsed.hostname === authority.hostname : parsed.host === authority.host) {\n return true\n }\n }\n return false\n}\n\n/**\n * The fence. Returns `true` only when the request may be served.\n *\n * Branches run in this order, and the order is the design: `Host` first\n * because rebinding forges everything else, then Fetch Metadata, then\n * `Origin` — so a request that fails an earlier branch never reaches a later\n * comparison that a malformed value could accidentally satisfy.\n */\nexport function isTrustedWebRequest(request: HeaderCarrier, options: FenceOptions = {}): boolean {\n const host = header(request.headers, 'host')\n const authority = parseAuthority(host)\n if (authority === undefined) return false\n if (!isLoopbackHostname(authority.hostname) && !isTrustedAuthority(authority, options.trustedHosts ?? [])) {\n return false\n }\n if (header(request.headers, 'sec-fetch-site') === 'cross-site') return false\n const origin = header(request.headers, 'origin')\n if (origin === undefined) return options.requireOrigin !== true\n try {\n return new URL(origin).host === authority.host\n } catch {\n return false\n }\n}\n"]}
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Mounts the plugin's HTTP surface onto the host's web server.
|
|
3
|
+
*
|
|
4
|
+
* The mount is a CHILD FIBER, not a load-time probe: `webServer` is provided by
|
|
5
|
+
* the web composition and may become active after this plugin does, so
|
|
6
|
+
* `ctx.inject(['webServer'], …)` runs the callback when (and if) the service
|
|
7
|
+
* exists and unloads the routes when it goes away. A load-time `ctx.get` would
|
|
8
|
+
* see `undefined` in a headless deployment and never mount, which is correct,
|
|
9
|
+
* but it would also never mount in a web deployment whose siblings start in a
|
|
10
|
+
* different order — the silent-disable trap this repo has hit before.
|
|
11
|
+
*
|
|
12
|
+
* `ctx.inject` is an AND gate over its list, so `webServer` is the only key:
|
|
13
|
+
* every other service this surface reads (`webStartup` for the trusted hosts)
|
|
14
|
+
* goes through the un-gated `ctx.get`, because a strict proxy throws on any
|
|
15
|
+
* name outside the injection list.
|
|
16
|
+
*/
|
|
17
|
+
import { HTTP_API_PREFIX } from '../shared/api-prefix.js';
|
|
18
|
+
import { ERR_BOOST_HTTP_MOUNT_FAILED } from '../tools/boost.js';
|
|
19
|
+
import { createStateHandler } from './state.js';
|
|
20
|
+
/** Where the deployment declared its trusted hosts, across host generations. */
|
|
21
|
+
function resolveTrustedHosts(ctx) {
|
|
22
|
+
for (const service of ['webStartup', 'webRuntime']) {
|
|
23
|
+
try {
|
|
24
|
+
const value = ctx.get?.(service)?.trustedHosts;
|
|
25
|
+
if (Array.isArray(value))
|
|
26
|
+
return value.filter((entry) => typeof entry === 'string');
|
|
27
|
+
}
|
|
28
|
+
catch {
|
|
29
|
+
// A service that throws on read is not a reason to skip the fence: an
|
|
30
|
+
// empty list falls back to loopback-only, which is stricter, not looser.
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
return [];
|
|
34
|
+
}
|
|
35
|
+
/**
|
|
36
|
+
* Registers the route and returns its disposer.
|
|
37
|
+
*
|
|
38
|
+
* A host without dynamic injection gets a warning and no surface — the plugin's
|
|
39
|
+
* other behaviour is untouched, which is the whole point of the mount being
|
|
40
|
+
* optional.
|
|
41
|
+
*/
|
|
42
|
+
export function registerHttpApi(ctx, deps, warn) {
|
|
43
|
+
if (typeof ctx.inject !== 'function') {
|
|
44
|
+
warn(`${ERR_BOOST_HTTP_MOUNT_FAILED}: no dynamic injection (\`ctx.inject\` is missing); ` +
|
|
45
|
+
'settings page has no data route');
|
|
46
|
+
return () => { };
|
|
47
|
+
}
|
|
48
|
+
let dispose;
|
|
49
|
+
try {
|
|
50
|
+
ctx.inject(['webServer'], (context) => {
|
|
51
|
+
const webServer = context.webServer;
|
|
52
|
+
if (webServer === undefined) {
|
|
53
|
+
warn(`${ERR_BOOST_HTTP_MOUNT_FAILED}: webServer resolved to undefined; settings page has no data route`);
|
|
54
|
+
return;
|
|
55
|
+
}
|
|
56
|
+
const handler = createStateHandler(deps, { trustedHosts: () => resolveTrustedHosts(ctx) });
|
|
57
|
+
dispose = webServer.register({ kind: 'prefix', path: HTTP_API_PREFIX, handler });
|
|
58
|
+
});
|
|
59
|
+
}
|
|
60
|
+
catch (error) {
|
|
61
|
+
// The mount must never cost the plugin: a composition without a web server
|
|
62
|
+
// is the normal headless case, not a fault.
|
|
63
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
64
|
+
warn(`${ERR_BOOST_HTTP_MOUNT_FAILED}: ${message}`);
|
|
65
|
+
}
|
|
66
|
+
return () => {
|
|
67
|
+
dispose?.();
|
|
68
|
+
dispose = undefined;
|
|
69
|
+
};
|
|
70
|
+
}
|
|
71
|
+
//# sourceMappingURL=mount.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"mount.js","sourceRoot":"","sources":["../../src/http/mount.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AACzD,OAAO,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAA;AAC/D,OAAO,EAAE,kBAAkB,EAAkB,MAAM,YAAY,CAAA;AAa/D,gFAAgF;AAChF,SAAS,mBAAmB,CAAC,GAAoB;IAC/C,KAAK,MAAM,OAAO,IAAI,CAAC,YAAY,EAAE,YAAY,CAAC,EAAE,CAAC;QACnD,IAAI,CAAC;YACH,MAAM,KAAK,GAAI,GAAG,CAAC,GAAG,EAAE,CAAC,OAAO,CAA4C,EAAE,YAAY,CAAA;YAC1F,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;gBAAE,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,KAAK,EAAmB,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAA;QACtG,CAAC;QAAC,MAAM,CAAC;YACP,sEAAsE;YACtE,yEAAyE;QAC3E,CAAC;IACH,CAAC;IACD,OAAO,EAAE,CAAA;AACX,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAC7B,GAAoB,EACpB,IAAe,EACf,IAA+B;IAE/B,IAAI,OAAO,GAAG,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;QACrC,IAAI,CACF,GAAG,2BAA2B,sDAAsD;YAClF,iCAAiC,CACpC,CAAA;QACD,OAAO,GAAG,EAAE,GAAE,CAAC,CAAA;IACjB,CAAC;IACD,IAAI,OAAiC,CAAA;IACrC,IAAI,CAAC;QACH,GAAG,CAAC,MAAM,CAAC,CAAC,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE;YACpC,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAA;YACnC,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;gBAC5B,IAAI,CAAC,GAAG,2BAA2B,oEAAoE,CAAC,CAAA;gBACxG,OAAM;YACR,CAAC;YACD,MAAM,OAAO,GAAG,kBAAkB,CAAC,IAAI,EAAE,EAAE,YAAY,EAAE,GAAG,EAAE,CAAC,mBAAmB,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;YAC1F,OAAO,GAAG,SAAS,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,CAAC,CAAA;QAClF,CAAC,CAAC,CAAA;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,2EAA2E;QAC3E,4CAA4C;QAC5C,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QACtE,IAAI,CAAC,GAAG,2BAA2B,KAAK,OAAO,EAAE,CAAC,CAAA;IACpD,CAAC;IACD,OAAO,GAAG,EAAE;QACV,OAAO,EAAE,EAAE,CAAA;QACX,OAAO,GAAG,SAAS,CAAA;IACrB,CAAC,CAAA;AACH,CAAC","sourcesContent":["/**\n * Mounts the plugin's HTTP surface onto the host's web server.\n *\n * The mount is a CHILD FIBER, not a load-time probe: `webServer` is provided by\n * the web composition and may become active after this plugin does, so\n * `ctx.inject(['webServer'], …)` runs the callback when (and if) the service\n * exists and unloads the routes when it goes away. A load-time `ctx.get` would\n * see `undefined` in a headless deployment and never mount, which is correct,\n * but it would also never mount in a web deployment whose siblings start in a\n * different order — the silent-disable trap this repo has hit before.\n *\n * `ctx.inject` is an AND gate over its list, so `webServer` is the only key:\n * every other service this surface reads (`webStartup` for the trusted hosts)\n * goes through the un-gated `ctx.get`, because a strict proxy throws on any\n * name outside the injection list.\n */\nimport { HTTP_API_PREFIX } from '../shared/api-prefix.js'\nimport { ERR_BOOST_HTTP_MOUNT_FAILED } from '../tools/boost.js'\nimport { createStateHandler, type StateDeps } from './state.js'\n\n/** The one service this plugin needs from the host's web composition. */\ninterface WebServerLike {\n register(route: { kind: 'exact' | 'prefix'; path: string; handler: unknown }): () => void\n}\n\n/** The slice of the plugin context this module uses. */\nexport interface HttpContextLike {\n inject?: (names: string[], callback: (context: { webServer?: WebServerLike }) => void) => unknown\n get?: (name: string) => unknown\n}\n\n/** Where the deployment declared its trusted hosts, across host generations. */\nfunction resolveTrustedHosts(ctx: HttpContextLike): readonly string[] {\n for (const service of ['webStartup', 'webRuntime']) {\n try {\n const value = (ctx.get?.(service) as { trustedHosts?: unknown } | undefined)?.trustedHosts\n if (Array.isArray(value)) return value.filter((entry): entry is string => typeof entry === 'string')\n } catch {\n // A service that throws on read is not a reason to skip the fence: an\n // empty list falls back to loopback-only, which is stricter, not looser.\n }\n }\n return []\n}\n\n/**\n * Registers the route and returns its disposer.\n *\n * A host without dynamic injection gets a warning and no surface — the plugin's\n * other behaviour is untouched, which is the whole point of the mount being\n * optional.\n */\nexport function registerHttpApi(\n ctx: HttpContextLike,\n deps: StateDeps,\n warn: (message: string) => void,\n): () => void {\n if (typeof ctx.inject !== 'function') {\n warn(\n `${ERR_BOOST_HTTP_MOUNT_FAILED}: no dynamic injection (\\`ctx.inject\\` is missing); ` +\n 'settings page has no data route',\n )\n return () => {}\n }\n let dispose: (() => void) | undefined\n try {\n ctx.inject(['webServer'], (context) => {\n const webServer = context.webServer\n if (webServer === undefined) {\n warn(`${ERR_BOOST_HTTP_MOUNT_FAILED}: webServer resolved to undefined; settings page has no data route`)\n return\n }\n const handler = createStateHandler(deps, { trustedHosts: () => resolveTrustedHosts(ctx) })\n dispose = webServer.register({ kind: 'prefix', path: HTTP_API_PREFIX, handler })\n })\n } catch (error) {\n // The mount must never cost the plugin: a composition without a web server\n // is the normal headless case, not a fault.\n const message = error instanceof Error ? error.message : String(error)\n warn(`${ERR_BOOST_HTTP_MOUNT_FAILED}: ${message}`)\n }\n return () => {\n dispose?.()\n dispose = undefined\n }\n}\n"]}
|