@ntdgy/dsh-remote-bridge-plugin 0.0.0-stage → 0.1.0

package/lib/relay/follow.js

@@ -0,0 +1,307 @@
+/**
+ * 单条帧流的时间预算。
+ *
+ * 空闲超时（收到上一条帧之后多久没有新帧）与生存上限（一个订阅最长活多久）
+ * 是两件事，必须分开：前者防僵尸订阅，后者防会话长期被一个订阅钉住。
+ * 取值都远大于一次正常 turn 的时长，误杀风险留给 frame-end 的 reason 体现。
+ */
+export const FOLLOW_IDLE_TIMEOUT_MS = 30 * 60_000;
+export const FOLLOW_MAX_LIFETIME_MS = 2 * 60 * 60_000;
+/** cursor 缓存上限与 TTL（D4：避免无限增长）。 */
+export const CURSOR_CACHE_MAX_ENTRIES = 512;
+export const CURSOR_CACHE_TTL_MS = 10 * 60_000;
+/**
+ * 订阅注册表。
+ *
+ * 一个实例持有一个 registry；transport 在连接断开时调 `abortAll()`，
+ * 插件卸载时同理——这样"连接断开即 abort"是结构性保证，不靠调用方记得。
+ */
+export class FollowRegistry {
+    source;
+    cursors = new CursorCache();
+    active = new Map();
+    onFrame;
+    /**
+     * @param source - DSH sessionController（或同形状的替身，便于单测）。
+     * @param onFrame - 帧出口。返回值被忽略；出口自身决定这条帧投给哪个浏览器连接。
+     */
+    constructor(source, onFrame) {
+        this.source = source;
+        this.onFrame = onFrame;
+    }
+    get size() {
+        return this.active.size;
+    }
+    /**
+     * 订阅一个会话。
+     *
+     * @param target - 会话 id 与派生出的 subscriptionId。
+     * @param onEnd - 流终止时回调一次（正常结束、被 abort、出错都走这里）。
+     * @returns 句柄；调用方必须保存它以便退订，
+     *   同时应当在连接关闭时调用 `abortAll()`。
+     */
+    subscribe(target, onEnd) {
+        const { sessionId, subscriptionId } = target;
+        // 同一 subscriptionId 重复订阅直接拒绝：订阅号唯一性由 ADR-004 保证，
+        // 允许覆盖会让旧订阅的 abort 落在新订阅上。
+        if (this.active.has(subscriptionId)) {
+            throw new Error(`subscription already active: ${subscriptionId}`);
+        }
+        const controller = new AbortController();
+        const lifetime = AbortSignal.timeout(FOLLOW_MAX_LIFETIME_MS);
+        const stop = this.combine(controller.signal, lifetime);
+        let closed = false;
+        let seq = 0;
+        const finish = (reason, message) => {
+            if (closed)
+                return;
+            closed = true;
+            this.active.delete(subscriptionId);
+            onEnd({
+                kind: 'frame-end',
+                subscriptionId,
+                reason,
+                ...(message === undefined
+                    ? {}
+                    : { error: { code: mapFollowErrorCode(reason), message } }),
+            });
+        };
+        const subscription = {
+            subscriptionId,
+            controller,
+            get closed() {
+                return closed;
+            },
+            end(reason) {
+                if (closed)
+                    return;
+                // 先 abort DSH 侧，让 for await 立刻退出；finish 在 pump 的 finally 里只会跑一次。
+                controller.abort();
+                finish(reason);
+            },
+        };
+        this.active.set(subscriptionId, subscription);
+        void this.pump(sessionId, subscriptionId, stop, (frame) => {
+            seq += 1;
+            this.onFrame({ kind: 'frame', subscriptionId, seq, frame });
+        }).then(() => finish('completed'), (error) => {
+            // abort 是正常退订路径，不该被记成 error。
+            if (stop.aborted) {
+                finish('aborted');
+                return;
+            }
+            finish('error', error instanceof Error ? error.message : String(error));
+        });
+        return subscription;
+    }
+    /**
+     * 终止单个订阅（网关 sub-control / 同号重入）。
+     *
+     * 走的是与 `end()` 完全相同的路径：controller.abort() 让 DSH 侧 follower 立刻拆除，
+     * 再由幂等的 finish 发一次 frame-end。因此无论从哪条入口终止，
+     * frame-end 都只发一次，注册表也不会残留条目。
+     *
+     * @param subscriptionId - 订阅号；由网关视角给出，与其发起 follow 的 req.id 一致。
+     * @param reason - 终止原因，写进 frame-end。
+     * @returns true 表示确实终止了一条活跃订阅；未知 id 静默返回 false，不抛也不告警——
+     *   网关与插件对订阅的可见性存在天然时差（刚结束 / 已超时），把它当错误会刷屏。
+     */
+    abortSubscription(subscriptionId, reason = 'aborted') {
+        const subscription = this.active.get(subscriptionId);
+        if (subscription === undefined)
+            return false;
+        subscription.end(reason);
+        return true;
+    }
+    /** 插件卸载 / 连接断开：终止全部订阅，签名与 ADR-004 的三条纪律一一对应。 */
+    abortAll(reason = 'aborted') {
+        // 遍历快照：end() 会从 this.active 里删除当前项，直接迭代 Map 会漏项。
+        for (const subscriptionId of [...this.active.keys()]) {
+            this.abortSubscription(subscriptionId, reason);
+        }
+    }
+    /**
+     * session.history 的 throughSeq 缺省解析（D4）。
+     *
+     * 只跑一趟"取首帧就退订"的短路 follow，不会长期持有会话；
+     * @param signal - 调用方期限（通常是一条 RPC 的超时信号）。
+     */
+    async resolveCursor(sessionId, signal) {
+        const cached = this.cursors.get(sessionId);
+        if (cached !== undefined)
+            return cached;
+        // 显式用 AbortController 而不是 AbortSignal.timeout：前者能主动 abort，
+        // 这样"拿到首帧立刻退订"是真实的资源回收，而不是等超时自然结束。
+        const controller = new AbortController();
+        const stop = signal === undefined ? controller.signal : AbortSignal.any([controller.signal, signal]);
+        const lifetime = setTimeout(() => controller.abort(), Math.min(FOLLOW_IDLE_TIMEOUT_MS, FOLLOW_MAX_LIFETIME_MS));
+        try {
+            for await (const frame of this.followStream({ address: { kind: 'session', sessionId } }, stop)) {
+                if (frame.type !== 'snapshot')
+                    continue;
+                // 只取首帧 cursor：这是"短暂 follow"，不是订阅。
+                this.cursors.set(sessionId, frame.cursor);
+                return frame.cursor;
+            }
+            return undefined;
+        }
+        finally {
+            clearTimeout(lifetime);
+            // 只 abort 我们自己的控制器；调用方信号不归我们关。
+            controller.abort();
+        }
+    }
+    /**
+     * 唯一的 `source.follow` 取用点。
+     *
+     * T16：`this.source.follow(...)` 在本文件出现过三处，任何一处拿到 undefined
+     * 都会炸成 "Cannot read properties of undefined (reading 'follow')" ——
+     * 这个信息里没有任何关于「谁给我一个坏 source」的线索，是本次排查卡住的直接原因。
+     *
+     * T18 教训（**守卫比缺陷更严格**）：这一版最初的守卫写成 `!'follow' in source`。
+     * 而 source 可能是装配层传入的惰性代理——只实现 `get` 的 Proxy，
+     * `'follow' in proxy` 走默认 [[Has]] 落在空 target 上，恒为 false，
+     * 于是**健康服务**被判成装配错误，history 100% 不可用：守卫自己成了新的单点障碍。
+     *
+     * 规则（写在这里供后来者沿用）：
+     *   1. 守卫必须比它守护的缺陷更**宽松**——宁可漏过交给下游，也不要误杀正常路径；
+     *   2. 检查方式必须与被检查对象的**形态**匹配——对代理/惰性对象用 `typeof x.prop`
+     *      取真实属性值，不要用 `in` / `hasOwnProperty`（两者都受 [[Has]] 与自有属性限制）。
+     *
+     * `typeof` 会真实触发一次 get，因此对惰性 source 既能拿到函数，也不会误判。
+     */
+    followStream(request, signal) {
+        const source = this.source;
+        if (source === null || typeof source !== 'object') {
+            throw new Error('remote-bridge: FollowRegistry.source is not an object — assembly bug, ' +
+                `received ${source === null ? 'null' : typeof source}. This is the plugin wiring, not DSH data.`);
+        }
+        // 用 typeof 取真实值：对惰性代理（只实现 get）同样可靠。
+        const follow = source.follow;
+        if (typeof follow !== 'function') {
+            throw new Error(`remote-bridge: FollowRegistry.source.follow is not a function (got ${typeof follow}) — assembly bug.`);
+        }
+        return follow.call(source, request, signal);
+    }
+    /** 已解析的 cursor 直接记下，避免 history 再开一次 follow。 */
+    rememberCursor(sessionId, cursor) {
+        this.cursors.set(sessionId, cursor);
+    }
+    /**
+     * 一次"取首帧 cursor 就退订"的短暂 follow。
+     *
+     * 这是 D4 给 history 用的入口，语义与 {@link resolveCursor} 相同，
+     * 区别只在返回值形态：history 需要把"DSH 侧失败"与"没有快照帧"分开报错，
+     * 因此这里把两种结果区分开，而不是把失败折叠成 undefined。
+     *
+     * @returns `{ cursor }` 取到切口；`{ missing: true }` 流结束但没给 snapshot 帧。
+     *   失败（会话不存在等）直接抛出，由调用方映射成 RPC 错误码——不静默吞掉。
+     */
+    async peekCursor(sessionId, signal) {
+        const cached = this.cursors.get(sessionId);
+        if (cached !== undefined)
+            return { cursor: cached };
+        const controller = new AbortController();
+        const stop = signal === undefined ? controller.signal : AbortSignal.any([controller.signal, signal]);
+        const lifetime = setTimeout(() => controller.abort(), FOLLOW_MAX_LIFETIME_MS);
+        try {
+            for await (const frame of this.followStream({ address: { kind: 'session', sessionId } }, stop)) {
+                if (frame.type !== 'snapshot')
+                    continue;
+                this.cursors.set(sessionId, frame.cursor);
+                return { cursor: frame.cursor };
+            }
+            return { missing: true };
+        }
+        finally {
+            clearTimeout(lifetime);
+            controller.abort();
+        }
+    }
+    /**
+     * 泵帧。
+     *
+     * 生命周期保证：
+     *   - for await 只在 stop 未 abort 时推进；
+     *   - 空闲计时器每次 yield 重置，超时直接 end('aborted')，不看错误形态；
+     *   - 无论正常结束还是抛错，finally 一定 abort，DSH 侧的 follower 因此被拆除。
+     */
+    async pump(sessionId, subscriptionId, stop, emit) {
+        let idle;
+        const resetIdle = () => {
+            if (idle)
+                clearTimeout(idle);
+            idle = setTimeout(() => {
+                const subscription = this.active.get(subscriptionId);
+                subscription?.end('aborted');
+            }, FOLLOW_IDLE_TIMEOUT_MS);
+        };
+        try {
+            resetIdle();
+            const stream = this.followStream({ address: { kind: 'session', sessionId }, assistantStream: true }, stop);
+            for await (const frame of stream) {
+                if (stop.aborted)
+                    break;
+                resetIdle();
+                // snapshot 的 cursor 是 history 的唯一合法切口（D4），先入缓存再外发。
+                if (frame.type === 'snapshot' && Number.isSafeInteger(frame.cursor)) {
+                    this.cursors.set(sessionId, frame.cursor);
+                }
+                emit(frame);
+            }
+        }
+        finally {
+            if (idle)
+                clearTimeout(idle);
+            this.active.get(subscriptionId)?.controller.abort();
+        }
+    }
+    combine(...signals) {
+        return AbortSignal.any([...signals]);
+    }
+}
+/**
+ * cursor 缓存。
+ *
+ * 有界是硬要求（D4）：条目数上限 + TTL，双约束都命中即淘汰，
+ * 免得长跑进程里每个开过的会话都留一条记录。
+ */
+class CursorCache {
+    entries = new Map();
+    get(sessionId) {
+        const entry = this.entries.get(sessionId);
+        if (entry === undefined)
+            return undefined;
+        if (Date.now() - entry.at > CURSOR_CACHE_TTL_MS) {
+            this.entries.delete(sessionId);
+            return undefined;
+        }
+        // 命中即续期：正在用的会话不应被淘汰。
+        entry.at = Date.now();
+        return entry.cursor;
+    }
+    set(sessionId, cursor) {
+        this.entries.delete(sessionId);
+        this.entries.set(sessionId, { cursor, at: Date.now() });
+        this.evict();
+    }
+    evict() {
+        const now = Date.now();
+        for (const [key, entry] of this.entries) {
+            if (now - entry.at <= CURSOR_CACHE_TTL_MS)
+                break;
+            this.entries.delete(key);
+        }
+        while (this.entries.size > CURSOR_CACHE_MAX_ENTRIES) {
+            const oldest = this.entries.keys().next();
+            if (oldest.done === true)
+                break;
+            this.entries.delete(oldest.value);
+        }
+    }
+}
+/** 帧流错误码 -> proto 错误码。DSH 侧失败一律不给前端伪装成成功。 */
+function mapFollowErrorCode(reason) {
+    return reason === 'error' ? 'internal' : 'timeout';
+}
+//# sourceMappingURL=follow.js.map

package/lib/relay/follow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"follow.js","sourceRoot":"","sources":["../../src/relay/follow.ts"],"names":[],"mappings":"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"}

package/lib/relay/http-forward.d.ts

@@ -0,0 +1,30 @@
+import { type HttpRequestFrame, type HttpResponseErrorFrame, type HttpResponseFrame } from '@ntdgy/dsh-remote-proto';
+/** 单次上游请求超时。 */
+export declare const UPSTREAM_TIMEOUT_MS = 55000;
+export interface UpstreamResult {
+    frame: HttpResponseFrame | HttpResponseErrorFrame;
+    /** 成功时的原始 body；失败时缺省。 */
+    body?: Uint8Array;
+}
+/**
+ * 把被 latin1 误解码的 UTF-8 头值还原回 Unicode。
+ *
+ * 背景：Node 的 `res.headers` 按 latin1 解码 header 字节。上游若发
+ * 合法的 UTF-8（如中文文件名），到这里会变成一串 0x80-0xFF 的字符。
+ * 网关侧看到"全是 latin1"就原样放行 —— 文件名最终是乱码。
+ *
+ * 还原策略（保守，宁可不动也不要搞坏）：
+ *   · 没有 0x80-0xFF 的字符 → 原样返回（纯 ASCII，不可能有问题）
+ *   · 有 → 试 latin1→utf8；能解出合法 UTF-8 且不含 U+FFFD 才采用
+ *   · 任何一步失败 → 原样返回（保持 Node 给出的值，至少有确定性）
+ *
+ * 为什么可以这样判：latin1 解码会把每个字节变成同码点字符，
+ * 而 UTF-8 的续字节落在 0x80-0xBF —— 两者组合能唯一还原。
+ */
+export declare function recoverUtf8Header(value: string): string;
+/**
+ * 把一个转发请求执行到本机 DSH，返回可直接回传的帧。
+ *
+ * @param origin DSH 监听的真实 origin，如 http://127.0.0.1:3080
+ */
+export declare function forwardToUpstream(origin: string, frame: HttpRequestFrame, body?: Uint8Array): Promise<UpstreamResult>;

package/lib/relay/http-forward.js

@@ -0,0 +1,183 @@
+/**
+ * HTTP 转发执行器（ADR-005）：把网关转来的请求打给本机 DSH。
+ *
+ * 为什么是「反向请求本机 loopback」而不是「直接喂给 webServer」：
+ * dsh-host-webserver 只暴露 register/registerUpgrade/registerFallback/getOrigin，
+ * 真正的 dispatch（handle）是私有的，插件调不到；fallback 席位已被 SPA dist server 占着，
+ * 再注册会 throw。因此用 getOrigin() 拿到 http://127.0.0.1:<port> 再请求一次。
+ * 代价是一次同机 loopback 往返，可忽略；DSH 侧零新增监听，C1/C7 均不破坏。
+ *
+ * ⚠️ 必须用 http.request 而不是 fetch：fetch 会**静默丢弃** headers.Host（T32 踩过），
+ * 而 DSH 的 cookie 绑定它看到的 Host，Host 传不对就认证失败。
+ */
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { HTTP_BODY_MAX_BYTES, isForwardableHeader, } from '@ntdgy/dsh-remote-proto';
+/** 单次上游请求超时。 */
+export const UPSTREAM_TIMEOUT_MS = 55_000;
+/**
+ * 把被 latin1 误解码的 UTF-8 头值还原回 Unicode。
+ *
+ * 背景：Node 的 `res.headers` 按 latin1 解码 header 字节。上游若发
+ * 合法的 UTF-8（如中文文件名），到这里会变成一串 0x80-0xFF 的字符。
+ * 网关侧看到"全是 latin1"就原样放行 —— 文件名最终是乱码。
+ *
+ * 还原策略（保守，宁可不动也不要搞坏）：
+ *   · 没有 0x80-0xFF 的字符 → 原样返回（纯 ASCII，不可能有问题）
+ *   · 有 → 试 latin1→utf8；能解出合法 UTF-8 且不含 U+FFFD 才采用
+ *   · 任何一步失败 → 原样返回（保持 Node 给出的值，至少有确定性）
+ *
+ * 为什么可以这样判：latin1 解码会把每个字节变成同码点字符，
+ * 而 UTF-8 的续字节落在 0x80-0xBF —— 两者组合能唯一还原。
+ */
+export function recoverUtf8Header(value) {
+    let hasHighByte = false;
+    for (let i = 0; i < value.length; i += 1) {
+        const code = value.charCodeAt(i);
+        if (code > 0x7f) {
+            hasHighByte = true;
+            break;
+        }
+    }
+    if (!hasHighByte)
+        return value;
+    try {
+        const recovered = Buffer.from(value, 'latin1').toString('utf8');
+        // 还原失败时 Node 会插入 U+FFFD；出现它就说明原串不是 UTF-8 字节。
+        if (recovered.includes('\uFFFD'))
+            return value;
+        return recovered;
+    }
+    catch {
+        return value;
+    }
+}
+function errorResult(id, code, message) {
+    return { frame: { kind: 'http-response-error', id, code, message } };
+}
+/**
+ * 把一个转发请求执行到本机 DSH，返回可直接回传的帧。
+ *
+ * @param origin DSH 监听的真实 origin，如 http://127.0.0.1:3080
+ */
+export function forwardToUpstream(origin, frame, body) {
+    return new Promise((resolve) => {
+        let url;
+        try {
+            url = new URL(frame.path, origin);
+        }
+        catch {
+            resolve(errorResult(frame.id, 'internal', 'invalid path'));
+            return;
+        }
+        // 只允许打本机 origin：路径里带绝对 URL 时必须仍落在 origin 内（防 SSRF）。
+        if (url.origin !== new URL(origin).origin) {
+            resolve(errorResult(frame.id, 'internal', 'path escapes upstream origin'));
+            return;
+        }
+        const headers = {};
+        for (const [name, value] of Object.entries(frame.headers ?? {})) {
+            // content-length 由实际 body 重算（网关已按真实字节设置，这里再兜一次）。
+            if (!isForwardableHeader(name) && name.toLowerCase() !== 'content-length')
+                continue;
+            headers[name] = value;
+        }
+        if (frame.bodyLength > 0)
+            headers['content-length'] = String(frame.bodyLength);
+        // ── Host：原样保留浏览器/网关发来的值，不改成 loopback ────────────────
+        //
+        // DSH 的 cookie 绑它看到的 Host（client-connection 的 requestAudience）。
+        // 若这里改写成 127.0.0.1:<port>，DSH 会签发 authority=127.0.0.1 的 cookie，
+        // 浏览器拿不到也用不上——实测现象就是「能拿到 303 + set-cookie，但后续全 401」。
+        //
+        // 因此走 T32 裁决的方案 A：透传浏览器 Host，并在 DSH 侧用
+        // dsh web --trusted-host <公网域名> 把它登记进 trustedHosts。
+        // 两者缺一：缺 Host 透传 → cookie 绑错 authority；缺 trustedHosts → /api 全 403。
+        if (!headers['host'])
+            headers['host'] = url.host;
+        headers['accept-encoding'] = 'identity';
+        const isHttps = url.protocol === 'https:';
+        const doRequest = isHttps ? httpsRequest : httpRequest;
+        const req = doRequest({
+            protocol: url.protocol,
+            hostname: url.hostname,
+            port: url.port || (isHttps ? 443 : 80),
+            path: url.pathname + url.search,
+            method: frame.method,
+            headers,
+        }, (res) => {
+            const chunks = [];
+            let total = 0;
+            let aborted = false;
+            res.on('data', (chunk) => {
+                if (aborted)
+                    return;
+                total += chunk.length;
+                if (total > HTTP_BODY_MAX_BYTES) {
+                    // 超限立即断开上游，不继续读，避免把内存撑爆。
+                    aborted = true;
+                    res.destroy();
+                    resolve(errorResult(frame.id, 'body_too_large', 'response exceeds ' + HTTP_BODY_MAX_BYTES + ' bytes'));
+                    return;
+                }
+                chunks.push(chunk);
+            });
+            res.on('end', () => {
+                if (aborted)
+                    return;
+                const body = Buffer.concat(chunks.map((c) => Buffer.from(c.buffer, c.byteOffset, c.byteLength)), total);
+                const outHeaders = {};
+                for (const [name, value] of Object.entries(res.headers)) {
+                    if (value === undefined)
+                        continue;
+                    if (!isForwardableHeader(name))
+                        continue;
+                    // set-cookie 不能用 ', ' 合并：cookie 的 Expires 属性本身含逗号
+                    // （"Expires=Fri, 04 Dec 2026 ..."），拼起来就再也切不开了。
+                    // 用换行分隔是 Node 对多值头的通用约定，接收方按行拆即可。
+                    //
+                    // ⚠️ 头值还要做一次 UTF-8 还原（安全审查的 P2-2）：
+                    // Node 的 res.headers 把 header 按 **latin1** 解码，上游发
+                    // UTF-8 的 "报告.txt" 到这里会变成 "报告.txt" ——
+                    // 每个字符都 ≤ 0xFF，网关侧会当成"合法 latin1"直接透传，
+                    // 于是 RFC 5987 转换永不触发，浏览器下载的文件名是乱码。
+                    //
+                    // 判据：字符串里出现 0x80-0xFF 的连续段、且按 latin1→utf8
+                    // 还原后能解出合法 UTF-8 多字节序列，就认为原本是 UTF-8。
+                    const raw = Array.isArray(value) ? value.join('\n') : value;
+                    outHeaders[name] = recoverUtf8Header(raw);
+                }
+                resolve({
+                    frame: { kind: 'http-response', id: frame.id, status: res.statusCode ?? 502, headers: outHeaders, bodyLength: body.length },
+                    body,
+                });
+            });
+            res.on('error', (err) => {
+                if (aborted)
+                    return;
+                aborted = true;
+                resolve(errorResult(frame.id, 'upstream_unreachable', err.message));
+            });
+        });
+        req.setTimeout(UPSTREAM_TIMEOUT_MS, () => {
+            req.destroy();
+            resolve(errorResult(frame.id, 'upstream_timeout', 'upstream did not respond in time'));
+        });
+        req.on('error', (err) => {
+            resolve(errorResult(frame.id, 'upstream_unreachable', err.message));
+        });
+        // 请求体：POST 的 /api/<endpoint> 靠它传参。body 由二进制帧送达，
+        // 调用方在 frame.bodyLength > 0 时把字节附在 body 参数里。
+        if (frame.bodyLength > 0) {
+            if (!body || body.byteLength !== frame.bodyLength) {
+                req.destroy();
+                resolve(errorResult(frame.id, 'internal', 'request body missing or truncated'));
+                return;
+            }
+            req.end(Buffer.from(body.buffer, body.byteOffset, body.byteLength));
+            return;
+        }
+        req.end();
+    });
+}
+//# sourceMappingURL=http-forward.js.map

package/lib/relay/http-forward.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-forward.js","sourceRoot":"","sources":["../../src/relay/http-forward.ts"],"names":[],"mappings":"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"}

package/lib/relay/route-observer.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 运行时路由观测：读取 DSH webServer 上**已注册**的 HTTP 路径，归并成前缀后上报网关。
+ *
+ * 为什么观测而不是推断：包名与路由常常不一致（dshmarket 的路由是 /dsh-market/，
+ * 不是 /dshmarket/）。推断猜错了与猜对了在日志上无法区分，运维没法判断该不该信 ——
+ * 而观测到的是**真实存在**的路由，可审计。
+ *
+ * 技术依据（dsh-host-webserver 0.2.1-rc.2，lib/index.js:267-269）：
+ *   exact = new Map(); prefixes = new Map(); upgrades = new Map();
+ * 三者都是**类字段初始化的普通 Map**（非 #private），运行时可直接遍历。
+ * register()（:326-333）就是往 exact/prefixes 里 set。
+ *
+ * 时机：hello 发生在运行时、晚于所有插件注册，取到的正是完整快照。
+ */
+/** 单条前缀长度上限。 */
+export declare const MAX_PREFIX_LENGTH = 64;
+/** 单实例上报条数上限。 */
+export declare const MAX_PREFIXES_PER_INSTANCE = 32;
+export interface PrefixReport {
+    /** 通过校验、可上报的前缀。 */
+    accepted: string[];
+    /** 被拒绝的原始值及原因（用于本地日志）。 */
+    rejected: Array<{
+        value: string;
+        reason: string;
+    }>;
+    /** 观测到的原始路由条数，便于判断「一条都没看到」是不是异常。 */
+    observed: number;
+    /**
+     * 诊断信息：webServer 是否存在、三张表的实际类型与条数。
+     *
+     * 只在 observed === 0 时有意义 —— 那时的关键问题是「为什么一条都没读到」，
+     * 而这只有 webServer / 字段类型 / 条数能回答。只打「未观测到路由」等于没给线索
+     * （T37 部署后就是因此要回去翻代码才定位到 inject 缺 webServer）。
+     */
+    diagnostic: string;
+}
+/**
+ * 校验单条前缀。
+ *
+ * 拒绝规则（任何一条命中即拒）：
+ *   - 不以 '/' 开头或不以 '/' 结尾（前缀必须是目录形式，避免 /ab 误匹配 /abc）
+ *   - 含 '..'（路径穿越）、':'（协议）、'*'（通配）
+ *   - 长度超过 MAX_PREFIX_LENGTH
+ *   - 含空白或控制字符
+ */
+export declare function validatePrefix(raw: unknown): {
+    ok: true;
+    value: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * 从一条完整路径推出它的前缀。
+ *
+ * 规则：取第一段（/dsh-market/status → /dsh-market/）。
+ * 对根级路径（/favicon.svg）返回 undefined —— 根级资源不构成可放行前缀。
+ */
+export declare function prefixOf(pathname: string): string | undefined;
+/**
+ * 读取 webServer 已注册路由，归并成前缀集合。
+ *
+ * @param webServer DSH 的 webServer 服务实例（可以是 undefined，表示该 profile 没有 web 面）
+ */
+export declare function collectRegisteredPrefixes(webServer: unknown): PrefixReport;