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

package/lib/relay/route-observer.js

@@ -0,0 +1,122 @@
+/**
+ * 运行时路由观测：读取 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 const MAX_PREFIX_LENGTH = 64;
+/** 单实例上报条数上限。 */
+export const MAX_PREFIXES_PER_INSTANCE = 32;
+/** 把任意值描述成「类型(条数)」形式的短串，用于诊断日志。 */
+function describeTable(value) {
+    if (value instanceof Map)
+        return 'Map(' + value.size + ')';
+    if (Array.isArray(value))
+        return 'Array(' + value.length + ')';
+    if (value === undefined)
+        return 'undefined';
+    if (value === null)
+        return 'null';
+    return typeof value;
+}
+/**
+ * 校验单条前缀。
+ *
+ * 拒绝规则（任何一条命中即拒）：
+ *   - 不以 '/' 开头或不以 '/' 结尾（前缀必须是目录形式，避免 /ab 误匹配 /abc）
+ *   - 含 '..'（路径穿越）、':'（协议）、'*'（通配）
+ *   - 长度超过 MAX_PREFIX_LENGTH
+ *   - 含空白或控制字符
+ */
+export function validatePrefix(raw) {
+    if (typeof raw !== 'string')
+        return { ok: false, reason: 'not a string' };
+    const value = raw;
+    if (value.length === 0)
+        return { ok: false, reason: 'empty' };
+    if (value.length > MAX_PREFIX_LENGTH)
+        return { ok: false, reason: 'too long (>' + MAX_PREFIX_LENGTH + ')' };
+    if (!value.startsWith('/'))
+        return { ok: false, reason: 'must start with /' };
+    if (!value.endsWith('/'))
+        return { ok: false, reason: 'must end with /' };
+    if (value.includes('..'))
+        return { ok: false, reason: 'contains ..' };
+    if (value.includes(':'))
+        return { ok: false, reason: 'contains :' };
+    if (value.includes('*'))
+        return { ok: false, reason: 'contains *' };
+    if (/[\s\u0000-\u001f]/.test(value))
+        return { ok: false, reason: 'contains whitespace/control chars' };
+    return { ok: true, value };
+}
+/**
+ * 从一条完整路径推出它的前缀。
+ *
+ * 规则：取第一段（/dsh-market/status → /dsh-market/）。
+ * 对根级路径（/favicon.svg）返回 undefined —— 根级资源不构成可放行前缀。
+ */
+export function prefixOf(pathname) {
+    if (!pathname.startsWith('/'))
+        return undefined;
+    const rest = pathname.slice(1);
+    const slash = rest.indexOf('/');
+    if (slash <= 0)
+        return undefined;
+    return '/' + rest.slice(0, slash) + '/';
+}
+/**
+ * 读取 webServer 已注册路由，归并成前缀集合。
+ *
+ * @param webServer DSH 的 webServer 服务实例（可以是 undefined，表示该 profile 没有 web 面）
+ */
+export function collectRegisteredPrefixes(webServer) {
+    const rejected = [];
+    if (!webServer || typeof webServer !== 'object') {
+        return {
+            accepted: [],
+            rejected,
+            observed: 0,
+            diagnostic: 'webServer=' + (webServer === undefined ? 'undefined' : String(webServer)),
+        };
+    }
+    const tables = webServer;
+    const diagnostic = 'webServer=present, exact=' + describeTable(tables.exact) +
+        ', prefixes=' + describeTable(tables.prefixes) +
+        ', upgrades=' + describeTable(tables.upgrades);
+    const paths = [];
+    for (const table of [tables.exact, tables.prefixes, tables.upgrades]) {
+        if (!(table instanceof Map))
+            continue;
+        for (const key of table.keys())
+            if (typeof key === 'string')
+                paths.push(key);
+    }
+    const prefixes = new Set();
+    for (const pathname of paths) {
+        const prefix = prefixOf(pathname);
+        if (prefix === undefined)
+            continue;
+        const verdict = validatePrefix(prefix);
+        if (!verdict.ok) {
+            rejected.push({ value: prefix, reason: verdict.reason });
+            continue;
+        }
+        prefixes.add(verdict.value);
+    }
+    const accepted = Array.from(prefixes).slice(0, MAX_PREFIXES_PER_INSTANCE);
+    if (prefixes.size > MAX_PREFIXES_PER_INSTANCE) {
+        rejected.push({ value: '(overflow)', reason: 'more than ' + MAX_PREFIXES_PER_INSTANCE + ' prefixes; truncated' });
+    }
+    return { accepted, rejected, observed: paths.length, diagnostic };
+}
+//# sourceMappingURL=route-observer.js.map

package/lib/relay/route-observer.js.map

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

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

@@ -0,0 +1,28 @@
+import type { WsOpenFrame } from '@ntdgy/dsh-remote-proto';
+/** 单条上游 WS 的最大缓冲，超过即认为消费端不可救，主动关闭。 */
+export declare const UPSTREAM_HARD_LIMIT: number;
+export interface WsSink {
+    /** 回 ws-open-ack。 */
+    ack(id: string, ok: boolean, error?: string): void;
+    /** 回一条上游数据帧。 */
+    data(id: string, opcode: number, payload: Uint8Array): void;
+    /** 回 ws-close。 */
+    close(id: string, code: number, reason: string, from: 'browser' | 'upstream' | 'gateway'): void;
+}
+export declare class WsForwarder {
+    private readonly upstreams;
+    private readonly origin;
+    private readonly sink;
+    constructor(origin: () => string | undefined, sink: WsSink);
+    /** 发起上游 upgrade。任何失败都必须 ack(false)，绝不让网关干等。 */
+    open(frame: WsOpenFrame): void;
+    /** 网关→上游 的数据。 */
+    toUpstream(id: string, opcode: number, payload: Uint8Array): void;
+    /** 流量控制：暂停/恢复从上游读取，避免慢消费者把内存撑爆。 */
+    setFlow(id: string, action: 'pause' | 'resume'): void;
+    /** 网关要求关闭。 */
+    closeUpstream(id: string, code: number, reason: string): void;
+    /** 连接整体断开：清掉所有上游，不留半开。 */
+    closeAll(): void;
+    get size(): number;
+}

package/lib/relay/ws-forward.js

@@ -0,0 +1,138 @@
+/**
+ * WS 升级转发执行器（ADR-005，T34）：把网关转来的升级请求打到本机 DSH。
+ *
+ * 与 HTTP 转发同一条出站连接（C7），只是这里要维持一条长连接并双向搬帧。
+ * Host 必须原样保留（理由同 T33：DSH 的 cookie 绑它）。
+ */
+import WebSocket from 'ws';
+import { encodeWsDataFrame, WS_OPCODE_BINARY, WS_OPCODE_TEXT } from '@ntdgy/dsh-remote-proto';
+/** 单条上游 WS 的最大缓冲，超过即认为消费端不可救，主动关闭。 */
+export const UPSTREAM_HARD_LIMIT = 32 * 1024 * 1024;
+export class WsForwarder {
+    upstreams = new Map();
+    origin;
+    sink;
+    constructor(origin, sink) {
+        this.origin = origin;
+        this.sink = sink;
+    }
+    /** 发起上游 upgrade。任何失败都必须 ack(false)，绝不让网关干等。 */
+    open(frame) {
+        const base = this.origin();
+        if (!base) {
+            this.sink.ack(frame.id, false, 'DSH webServer origin unavailable');
+            return;
+        }
+        let url;
+        try {
+            url = new URL(frame.path, base);
+        }
+        catch {
+            this.sink.ack(frame.id, false, 'invalid path');
+            return;
+        }
+        if (url.origin !== new URL(base).origin) {
+            this.sink.ack(frame.id, false, 'path escapes upstream origin');
+            return;
+        }
+        const headers = { ...frame.headers };
+        // Host 保留网关透传来的值（cookie 绑它）；缺失才回落 loopback。
+        if (!headers['host'])
+            headers['host'] = url.host;
+        const wsUrl = (url.protocol === 'https:' ? 'wss:' : 'ws:') + '//' + url.host + url.pathname + url.search;
+        const socket = new WebSocket(wsUrl, { headers });
+        const entry = { socket, paused: false };
+        this.upstreams.set(frame.id, entry);
+        let settled = false;
+        const fail = (reason) => {
+            if (settled)
+                return;
+            settled = true;
+            this.upstreams.delete(frame.id);
+            try {
+                socket.terminate();
+            }
+            catch { /* gone */ }
+            this.sink.ack(frame.id, false, reason);
+        };
+        socket.on('unexpected-response', (_req, res) => {
+            // 上游明确拒绝升级（如 401/403）：把它作为 ack 失败原因回传。
+            fail('upstream rejected upgrade: HTTP ' + res.statusCode);
+        });
+        socket.on('error', (err) => fail(err.message));
+        socket.on('open', () => {
+            if (settled)
+                return;
+            settled = true;
+            this.sink.ack(frame.id, true);
+        });
+        socket.on('message', (data, isBinary) => {
+            const payload = Buffer.isBuffer(data) ? data : Buffer.from(data);
+            // 二进制安全：opcode 由 isBinary 还原，payload 原样搬运。
+            const opcode = isBinary ? WS_OPCODE_BINARY : WS_OPCODE_TEXT;
+            this.sink.data(frame.id, opcode, new Uint8Array(payload.buffer, payload.byteOffset, payload.byteLength));
+            if (socket.bufferedAmount > UPSTREAM_HARD_LIMIT) {
+                this.closeUpstream(frame.id, 1011, 'upstream backpressure');
+            }
+        });
+        socket.on('close', (code, reason) => {
+            if (this.upstreams.delete(frame.id)) {
+                this.sink.close(frame.id, code, reason.toString() || 'upstream closed', 'upstream');
+            }
+        });
+    }
+    /** 网关→上游 的数据。 */
+    toUpstream(id, opcode, payload) {
+        const entry = this.upstreams.get(id);
+        if (!entry)
+            return;
+        const s = entry.socket;
+        if (s.readyState !== WebSocket.OPEN)
+            return;
+        if (opcode === WS_OPCODE_TEXT)
+            s.send(Buffer.from(payload).toString('utf8'), { binary: false });
+        else
+            s.send(Buffer.from(payload), { binary: true });
+    }
+    /** 流量控制：暂停/恢复从上游读取，避免慢消费者把内存撑爆。 */
+    setFlow(id, action) {
+        const entry = this.upstreams.get(id);
+        if (!entry)
+            return;
+        if (action === 'pause' && !entry.paused) {
+            entry.paused = true;
+            entry.socket.pause();
+            return;
+        }
+        if (action === 'resume' && entry.paused) {
+            entry.paused = false;
+            entry.socket.resume();
+        }
+    }
+    /** 网关要求关闭。 */
+    closeUpstream(id, code, reason) {
+        const entry = this.upstreams.get(id);
+        if (!entry)
+            return;
+        this.upstreams.delete(id);
+        // 1005/1006/1015 是「读到的」哨兵值，不允许写进 close 帧，ws 会抛错带崩进程。
+        const safe = code === 1005 || code === 1006 || code === 1015 || !Number.isInteger(code) ? 1000
+            : (code >= 1000 && code <= 4999 ? code : 1000);
+        try {
+            entry.socket.close(safe, reason.slice(0, 120));
+        }
+        catch { /* gone */ }
+        const t = setTimeout(() => { try {
+            entry.socket.terminate();
+        }
+        catch { /* gone */ } }, 5000);
+        t.unref?.();
+    }
+    /** 连接整体断开：清掉所有上游，不留半开。 */
+    closeAll() {
+        for (const id of Array.from(this.upstreams.keys()))
+            this.closeUpstream(id, 1011, 'gateway disconnected');
+    }
+    get size() { return this.upstreams.size; }
+}
+//# sourceMappingURL=ws-forward.js.map

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

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

package/lib/types/client/StatusPanel.d.ts

@@ -0,0 +1,36 @@
+/**
+ * bridge-plugin 只读状态面板的视图。
+ *
+ * 全部颜色取自 DSH 的 design token（--dsw-*），**没有任何硬编码十六进制** ——
+ * DSH 支持深浅主题切换，写死的颜色在另一套主题下会不可读。
+ *
+ * 纯只读：没有任何按钮会写状态。
+ */
+import type { StatusOutcome } from './types.ts';
+/** 一行展示项。 */
+export interface StatusRow {
+    label: string;
+    value: string;
+    /** 异常项用警示色，便于一眼看出问题。 */
+    bad?: boolean;
+}
+/**
+ * 把一次读取结果转成展示行。
+ *
+ * 读取失败时**只显示错误**，不显示上一次的快照 ——
+ * 否则「relay 已断但面板还显示旧的正常数据」会被误读成一切正常。
+ */
+export declare function rowsOf(outcome: StatusOutcome): StatusRow[];
+/**
+ * 面板组件。
+ *
+ * 颜色全部走 token：
+ *   标题 / 值     → --dsw-alias-label-primary
+ *   标签列       → --dsw-alias-label-secondary
+ *   异常值       → --dsw-alias-state-error-primary
+ *   面板底色     → --dsw-specific-sidebar-fill（与侧边栏同底，避免突兀色块）
+ *   分隔线       → --dsw-alias-border-l3
+ */
+export declare function StatusPanel(props: {
+    outcome: StatusOutcome;
+}): React.ReactElement;

package/lib/types/client/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * bridge-plugin 只读状态面板（浏览器侧）。
+ *
+ * 样式全部取自 DSH 的 design token 与原生 CSS（--dsw-*），不硬编码颜色 ——
+ * DSH 支持深浅主题切换，写死的十六进制在另一套主题下会不可读。
+ *
+ * 入口对齐原生 sidebar 的 .panelRow（插件 / 自动化任务 那一列），逐项照抄数值：
+ *   box-sizing:border-box; border-radius:var(--dsw-radius-md); min-height:36px;
+ *   gap:8px; margin:0 2px; padding:7px 8px; line-height:22px; font:inherit; border:none;
+ *   悬停 background:var(--dsw-alias-interactive-bg-hover)。
+ *
+ * 宽度：原生 .panelRow **没有** width 声明 —— 它是 .panelList（column flex）的子项，
+ * 默认 stretch 所以撑满。这里用同样的办法：外层 column flex + align-items:stretch，
+ * 不写死 100%（写死会在将来加内边距时错位）。
+ *
+ * 图标：原生用 size:16（IconPanelLeftOutlineRegular 等，实测其 size 参数为 16），
+ * viewBox 24、stroke-width 1.5 —— 与 DS 图标集一致。
+ *
+ * 纯只读：不调用任何写接口。数据来自本插件注册的 GET /bridge-plugin/status。
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+import { type StatusRow } from './StatusPanel.tsx';
+import type { StatusOutcome } from './types.ts';
+export declare const inject: string[];
+export declare function readStatus(): Promise<StatusOutcome>;
+export declare function apply(ctx: ClientContext): void;
+export type { StatusRow };

package/lib/types/client/types.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 面板状态的数据结构（与 Host 侧 buildStatusPayload 一一对应）。
+ *
+ * 单独一行类型文件：Host 与浏览器两侧共享同一形状，避免各写一份漂移。
+ */
+export interface BridgeStatus {
+    connection: {
+        registered: boolean;
+        connected: boolean;
+        connectedAt: number | null;
+        reconnects: number;
+    };
+    identity: {
+        instanceId: string;
+        relayUrl: string;
+    };
+    heartbeat: {
+        intervalMs: number | null;
+    };
+    authFailures: number;
+    droppedFrames: number;
+    httpPrefixes: {
+        reported: string[];
+        observed: number;
+    };
+    lastClose: {
+        reason: string | null;
+        at: number | null;
+    };
+    sessionControllerReady: boolean;
+    sampledAt: number;
+}
+/** 一次读取的结果。失败也是一等公民：面板要能显示原因。 */
+export type StatusOutcome = {
+    kind: 'ok';
+    status: BridgeStatus;
+} | {
+    kind: 'error';
+    message: string;
+};

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "@ntdgy/dsh-remote-bridge-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "DSH host-side plugin: outbound registration and narrow RPC server",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json && tsc -p tsconfig.client-types.json && tsdown",
+    "prepack": "node scripts/prepack.mjs",
+    "test": "node --experimental-strip-types --test src/**/*.test.ts"
+  },
+  "dsh": {
+    "engines": {
+      "dsh": "^0.2.1-rc.2"
+    },
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-renderer",
+        "@deepseek-ai/dsh-client-ui-sidebar"
+      ],
+      "platform": "web"
+    }
+  },
+  "dependencies": {
+    "@ntdgy/dsh-remote-proto": "^0.1.0",
+    "@deepseek-ai/schemastery": "^3.18.5",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.5",
+    "@types/node": "^22.19.0",
+    "@types/ws": "^8.5.13"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh": "^0.2.1-rc.2",
+    "react": "^18.2.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "comment": "由宿主 DSH 提供 React 运行时；本包不打包它，否则会装出第二份 React 实例"
+    }
+  },
+  "engines": {
+    "node": ">=20.11.0",
+    "dsh": "^0.2.1-rc.2"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.