rdsh-gateway 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -24,6 +24,8 @@ export { loginPageHtml } from "./login-page.ts";
 export { installService, uninstallService, serviceStatus, systemdUnit, launchdPlist, SERVICE_NAME, JOIN_SERVICE_NAME, HOST_SERVICE_NAME, HUB_SERVICE_NAME } from "./service.ts";
 export type { ServiceSpec } from "./service.ts";
 export declare const NAME = "rdsh-gateway";
-export { join, registerJoin, detectInsecure, selfRevoke } from "./join.ts";
-export type { JoinOptions, RegisterOutcome } from "./join.ts";
+export { join, startJoin, registerJoin, detectInsecure, selfRevoke } from "./join.ts";
+export type { JoinOptions, RegisterOutcome, JoinState, JoinHooks, StartJoinOptions, JoinHandle } from "./join.ts";
 export { readPersistedToken, clearPersistedToken } from "./token-store.ts";
+export { acquireJoinLock, releaseJoinLock, readJoinLock, JOIN_LOCK_PATH } from "./lock.ts";
+export type { JoinLock, JoinLockRole } from "./lock.ts";

package/dist/index.js

@@ -16,6 +16,7 @@ export { loadTls } from "./tls.js";
 export { loginPageHtml } from "./login-page.js";
 export { installService, uninstallService, serviceStatus, systemdUnit, launchdPlist, SERVICE_NAME, JOIN_SERVICE_NAME, HOST_SERVICE_NAME, HUB_SERVICE_NAME } from "./service.js";
 export const NAME = "rdsh-gateway";
-export { join, registerJoin, detectInsecure, selfRevoke } from "./join.js";
+export { join, startJoin, registerJoin, detectInsecure, selfRevoke } from "./join.js";
 export { readPersistedToken, clearPersistedToken } from "./token-store.js";
+export { acquireJoinLock, releaseJoinLock, readJoinLock, JOIN_LOCK_PATH } from "./lock.js";
 //# sourceMappingURL=index.js.map

package/dist/join.d.ts

@@ -1,3 +1,5 @@
+import type { ProxyTarget } from "./proxy.ts";
+import type { JoinLockRole } from "./lock.ts";
 export interface JoinOptions {
     hubUrl: string;
     /** join token（用户级，register 换 host token） */
@@ -15,10 +17,44 @@ export interface RegisterOutcome {
     token: string;
     insecure: boolean;
 }
+/** 隧道状态机（onState 事件值）。 */
+export type JoinState = "connecting" | "connected" | "reconnecting" | "rejected" | "stopped";
+/** join 核心事件钩子（插件面板实时状态 + 日志预留）。 */
+export interface JoinHooks {
+    onState?(state: JoinState, detail?: {
+        message?: string;
+        delayMs?: number;
+    }): void;
+    onLog?(level: "info" | "warn" | "error", message: string): void;
+}
+/** no-spawn、外部 target 的 join 隧道启动参数（CLI 与插件共用）。 */
+export interface StartJoinOptions {
+    hubUrl: string;
+    /** 已解析的 host token（registerJoin 结果） */
+    token: string;
+    insecure: boolean;
+    /** 转发目标（no-spawn：外部 dsh 的 loopback 地址） */
+    target: ProxyTarget;
+    /** pid 锁 role：cli / plugin */
+    role: JoinLockRole;
+    /** 锁文件路径（缺省 ~/.rdsh/join.lock；测试可注入临时路径） */
+    lockPath?: string;
+    hooks?: JoinHooks;
+}
+/** 可停止的 join 隧道句柄。 */
+export interface JoinHandle {
+    stop(): Promise<void>;
+}
 /** 探测 hub 是否需 insecure：以严格校验握手一次；证书错误 → true（需 insecure）。 */
 export declare function detectInsecure(hubUrl: string): Promise<boolean>;
 /** 调用 hub self-revoke 注销本机（host 持自己的 host token）。`rdsh host leave` 使用。 */
 export declare function selfRevoke(hubUrl: string, token: string, insecure: boolean): Promise<void>;
 /** 解析 host token（--token 注册 > 持久化复用）+ 自动检测证书；供 CLI 配置命令与 join() 复用。 */
 export declare function registerJoin(opts: JoinOptions): Promise<RegisterOutcome>;
+/**
+ * 启动 join 隧道（no-spawn）：转发到外部 `opts.target`，不 spawn dsh、不 process.exit。
+ * 获取 pid 锁（opts.role）；返回 `JoinHandle`，`stop()` 干净停止（关 WS/清 heartbeat/释放锁）。
+ */
+export declare function startJoin(opts: StartJoinOptions): JoinHandle;
+/** `rdsh host serve`（join 模式）的 CLI 封装：spawn dsh + 信号退出 + startJoin(role:cli)。 */
 export declare function join(opts: JoinOptions): Promise<void>;

package/dist/join.js

@@ -5,6 +5,9 @@
  * → 帧循环（OPEN http/ws → 本地 dsh 转发 → 响应帧回传）→ 断线指数退避重连。
  *
  * 安全：只出站（不监听任何入站端口）；hub 认证在层 1，gateway 侧只认隧道内来源。
+ *
+ * 06-dsh-plugin 重构（D13 钩子落地）：`join()`（CLI 形态，spawn dsh + 信号退出）
+ * 拆出 `startJoin()`（no-spawn、外部 target、可停止、onState/onLog）——插件复用。
  */
 import { request as httpRequest } from "node:http";
 import { request as httpsRequest } from "node:https";
@@ -13,6 +16,7 @@ import { FrameParser, FRAME_TYPE, encodeFrame, jsonPayload, parseJsonPayload } f
 import { findDsh, spawnDsh } from "./spawn-dsh.js";
 import { rewriteHeadersForDsh } from "./proxy.js";
 import { clearPersistedToken, persistToken, readPersistedToken } from "./token-store.js";
+import { acquireJoinLock, releaseJoinLock } from "./lock.js";
 /** 判断错误是否为 TLS 证书类错误（自签/过期/域名不匹配）。 */
 function isCertError(err) {
     const code = err?.code ?? "";
@@ -111,19 +115,23 @@ async function register(hubUrl, joinToken, name, insecure) {
     }
     return { hostId: b.hostId, hostToken: b.hostToken };
 }
-export async function join(opts) {
+/**
+ * 启动 join 隧道（no-spawn）：转发到外部 `opts.target`，不 spawn dsh、不 process.exit。
+ * 获取 pid 锁（opts.role）；返回 `JoinHandle`，`stop()` 干净停止（关 WS/清 heartbeat/释放锁）。
+ */
+export function startJoin(opts) {
     const hubWsBase = opts.hubUrl.replace(/^https/, "wss").replace(/^http/, "ws");
-    const foundDsh = findDsh(opts.dshPath);
-    if (foundDsh === null) {
-        throw new Error("cannot find 'dsh' in PATH. Install DeepSeek Harness first, or pass --dsh <path>.");
+    const hooks = opts.hooks ?? {};
+    const log = (level, message) => {
+        hooks.onLog?.(level, message);
+    };
+    const setState = (state, detail) => {
+        hooks.onState?.(state, detail);
+    };
+    const lock = acquireJoinLock(opts.role, opts.lockPath);
+    if (!lock.ok) {
+        throw new Error(`join lock held by ${lock.heldBy.role} (pid ${lock.heldBy.pid}); stop it first`);
     }
-    const dsh = await spawnDsh(foundDsh);
-    const target = { host: "127.0.0.1", port: dsh.port };
-    // 解析 host token（含证书自动检测 + 持久化）；进程重启后复用，避免重复配对。
-    const { token: initialToken, insecure } = await registerJoin(opts);
-    let token = initialToken;
-    console.log(`rdsh join: dsh web on 127.0.0.1:${dsh.port}`);
-    console.log(`rdsh join: connecting to ${opts.hubUrl}...`);
     const parser = new FrameParser();
     /** http 流：streamId → 本地请求（写请求体 / 结束）。 */
     const httpStreams = new Map();
@@ -132,23 +140,7 @@ export async function join(opts) {
     let shuttingDown = false;
     let reconnectDelay = RECONNECT_BASE_MS;
     let heartbeat;
-    const shutdown = async (signal, code = 0) => {
-        if (shuttingDown)
-            return;
-        shuttingDown = true;
-        if (signal !== "")
-            console.log(`\nrdsh: received ${signal}, shutting down...`);
-        if (heartbeat !== undefined)
-            clearInterval(heartbeat);
-        await dsh.stop();
-        process.exit(code);
-    };
-    process.on("SIGINT", () => void shutdown("SIGINT"));
-    process.on("SIGTERM", () => void shutdown("SIGTERM"));
-    process.on("SIGHUP", () => void shutdown("SIGHUP"));
-    // 常驻：进程靠信号退出（shutdown 里 process.exit）；防止函数返回后
-    // CLI 的 main().then(exit) 误退出服务进程
-    const keepAlive = new Promise(() => { });
+    let currentClient;
     function handleFrame(frame, client) {
         switch (frame.type) {
             case FRAME_TYPE.PING: {
@@ -237,11 +229,11 @@ export async function join(opts) {
         const streamId = frame.streamId;
         // http 转发：本地 dsh（loopback http）
         const up = httpRequest({
-            host: target.host,
-            port: target.port,
+            host: opts.target.host,
+            port: opts.target.port,
             path,
             method,
-            headers: rewriteHeadersForDsh(headers, target),
+            headers: rewriteHeadersForDsh(headers, opts.target),
         }, (upRes) => {
             client.send(encodeFrame(FRAME_TYPE.OPEN, streamId, jsonPayload({
                 kind: "http",
@@ -277,8 +269,8 @@ export async function join(opts) {
     }
     function openWsStream(frame, client, path, headers) {
         const streamId = frame.streamId;
-        const upstream = new WebSocket(`ws://${target.host}:${target.port}${path}`, {
-            headers: rewriteHeadersForDsh(headers, target),
+        const upstream = new WebSocket(`ws://${opts.target.host}:${opts.target.port}${path}`, {
+            headers: rewriteHeadersForDsh(headers, opts.target),
         });
         const queue = [];
         wsStreams.set(streamId, { upstream, queue });
@@ -306,11 +298,38 @@ export async function join(opts) {
         upstream.on("close", cleanup);
         upstream.on("error", cleanup);
     }
+    /** 清空本地 http/ws 流 + heartbeat（断线/停止时）。 */
+    function cleanupStreams() {
+        if (heartbeat !== undefined) {
+            clearInterval(heartbeat);
+            heartbeat = undefined;
+        }
+        for (const s of httpStreams.values()) {
+            try {
+                s.up.destroy();
+            }
+            catch {
+                /* 已断 */
+            }
+        }
+        httpStreams.clear();
+        for (const s of wsStreams.values()) {
+            try {
+                s.upstream.terminate();
+            }
+            catch {
+                /* 已断 */
+            }
+        }
+        wsStreams.clear();
+    }
     function connect() {
         if (shuttingDown)
             return;
-        const url = `${hubWsBase}/tunnel?token=${encodeURIComponent(token)}`;
-        const client = new WebSocket(url, { rejectUnauthorized: !insecure });
+        const url = `${hubWsBase}/tunnel?token=${encodeURIComponent(opts.token)}`;
+        const client = new WebSocket(url, { rejectUnauthorized: !opts.insecure });
+        currentClient = client;
+        setState("connecting", { message: `connecting to ${opts.hubUrl}` });
         // 401/403 = token 被拒（吊销/不存在）。监听此事件后 ws 不再自动 abort，
         // 需手动 terminate → 触发 close → 决定「重配对」还是「普通重连」。
         let tokenRejected = false;
@@ -326,7 +345,8 @@ export async function join(opts) {
         });
         client.on("open", () => {
             reconnectDelay = RECONNECT_BASE_MS;
-            console.log("rdsh join: tunnel established (heartbeat 30s)");
+            setState("connected");
+            log("info", "tunnel established (heartbeat 30s)");
             if (heartbeat !== undefined)
                 clearInterval(heartbeat);
             heartbeat = setInterval(() => {
@@ -355,39 +375,22 @@ export async function join(opts) {
                 handleFrame(frame, client);
         });
         client.on("close", () => {
-            if (heartbeat !== undefined) {
-                clearInterval(heartbeat);
-                heartbeat = undefined;
-            }
-            for (const s of httpStreams.values()) {
-                try {
-                    s.up.destroy();
-                }
-                catch {
-                    /* 已断 */
-                }
-            }
-            httpStreams.clear();
-            for (const s of wsStreams.values()) {
-                try {
-                    s.upstream.terminate();
-                }
-                catch {
-                    /* 已断 */
-                }
-            }
-            wsStreams.clear();
+            cleanupStreams();
             if (shuttingDown)
                 return;
             if (tokenRejected) {
-                // token 被拒（吊销/删除）= 永久失败，无法自动恢复（已移除配对码重配）
-                // → 删旧 session + fail-fast，让 systemd/脚本拿到非零退出码与明确报错。
+                // token 被拒（吊销/删除）= 永久失败，无法自动恢复
+                // → 删旧 session + 释放锁 + 停（fail-fast），不重连。
                 clearPersistedToken(opts.hubUrl);
-                console.error("rdsh join: host token rejected by hub (revoked or removed); re-run `rdsh host join <hub>` with a new join token.");
-                void shutdown("", 1);
+                const msg = "host token rejected by hub (revoked or removed); re-join with a new join token";
+                log("error", msg);
+                setState("rejected", { message: msg });
+                shuttingDown = true;
+                releaseJoinLock(opts.lockPath);
                 return;
             }
-            console.log(`rdsh join: tunnel lost — reconnecting in ${Math.round(reconnectDelay / 1000)}s...`);
+            setState("reconnecting", { delayMs: reconnectDelay });
+            log("info", `tunnel lost — reconnecting in ${Math.round(reconnectDelay / 1000)}s...`);
             setTimeout(connect, reconnectDelay + Math.random() * 500);
             reconnectDelay = Math.min(reconnectDelay * 2, RECONNECT_MAX_MS);
         });
@@ -401,7 +404,71 @@ export async function join(opts) {
         });
     }
     connect();
-    await keepAlive;
+    return {
+        async stop() {
+            if (shuttingDown)
+                return;
+            shuttingDown = true;
+            cleanupStreams();
+            if (currentClient !== undefined) {
+                try {
+                    currentClient.terminate();
+                }
+                catch {
+                    /* 已关闭 */
+                }
+            }
+            releaseJoinLock(opts.lockPath);
+            setState("stopped");
+        },
+    };
+}
+/** `rdsh host serve`（join 模式）的 CLI 封装：spawn dsh + 信号退出 + startJoin(role:cli)。 */
+export async function join(opts) {
+    const foundDsh = findDsh(opts.dshPath);
+    if (foundDsh === null) {
+        throw new Error("cannot find 'dsh' in PATH. Install DeepSeek Harness first, or pass --dsh <path>.");
+    }
+    const dsh = await spawnDsh(foundDsh);
+    const target = { host: "127.0.0.1", port: dsh.port };
+    // 解析 host token（含证书自动检测 + 持久化）；进程重启后复用，避免重复配对。
+    const { token, insecure } = await registerJoin(opts);
+    console.log(`rdsh join: dsh web on 127.0.0.1:${dsh.port}`);
+    console.log(`rdsh join: connecting to ${opts.hubUrl}...`);
+    const handle = startJoin({
+        hubUrl: opts.hubUrl,
+        token,
+        insecure,
+        target,
+        role: "cli",
+        hooks: {
+            onLog: (level, message) => {
+                (level === "error" ? console.error : console.log)(`rdsh join: ${message}`);
+            },
+            onState: (state, detail) => {
+                if (state === "rejected") {
+                    console.error(`rdsh join: ${detail?.message ?? "rejected"}`);
+                }
+            },
+        },
+    });
+    let shuttingDown = false;
+    const shutdown = async (signal, code = 0) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        if (signal !== "")
+            console.log(`\nrdsh: received ${signal}, shutting down...`);
+        await handle.stop();
+        await dsh.stop();
+        process.exit(code);
+    };
+    process.on("SIGINT", () => void shutdown("SIGINT"));
+    process.on("SIGTERM", () => void shutdown("SIGTERM"));
+    process.on("SIGHUP", () => void shutdown("SIGHUP"));
+    // 常驻：进程靠信号退出（shutdown 里 process.exit）；防止函数返回后
+    // CLI 的 main().then(exit) 误退出服务进程
+    await new Promise(() => { });
 }
 function normalizeRespHeaders(headers) {
     const out = {};

package/dist/lock.d.ts

@@ -0,0 +1,24 @@
+export declare const JOIN_LOCK_PATH: string;
+export type JoinLockRole = "cli" | "plugin";
+export interface JoinLock {
+    pid: number;
+    role: JoinLockRole;
+}
+/**
+ * 读锁。不存在/损坏/过短 → null；pid 已死（stale）→ 清除文件并返回 null。
+ * 供面板「外部托管」态判定（role=cli）与 acquire 前检测复用。
+ */
+export declare function readJoinLock(path?: string): JoinLock | null;
+export type AcquireResult = {
+    ok: true;
+} | {
+    ok: false;
+    heldBy: JoinLock;
+};
+/**
+ * 获取锁：写入 `{pid: process.pid, role}`（目录 0700、文件 0600）。
+ * 已有**他人**（不同 pid）持有的活锁 → 拒绝（防同机双隧道）。
+ */
+export declare function acquireJoinLock(role: JoinLockRole, path?: string): AcquireResult;
+/** 释放锁：仅当锁是自己 pid 持有才删（不误删他人锁）。 */
+export declare function releaseJoinLock(path?: string): void;

package/dist/lock.js

@@ -0,0 +1,73 @@
+/**
+ * lock.ts — join pid 锁：CLI 与插件共享「单身份铁律」（同机单隧道，D5 档2）。
+ *
+ * 锁文件 `~/.rdsh/join.lock`（0600）记 `{pid, role}`；stale（pid 已死）自动视为无锁并清除。
+ * role = "cli"（rdsh CLI / systemd 服务持有）| "plugin"（dsh 插件持有）——面板据此显示「外部托管」。
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+const RDSH_DIR = join(homedir(), ".rdsh");
+export const JOIN_LOCK_PATH = join(RDSH_DIR, "join.lock");
+/** 探测 pid 是否存活：signal 0 不真正发信号；EPERM = 存活但无权限，ESRCH = 不存在。 */
+function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+/**
+ * 读锁。不存在/损坏/过短 → null；pid 已死（stale）→ 清除文件并返回 null。
+ * 供面板「外部托管」态判定（role=cli）与 acquire 前检测复用。
+ */
+export function readJoinLock(path = JOIN_LOCK_PATH) {
+    try {
+        if (!existsSync(path))
+            return null;
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        if (typeof raw.pid !== "number" || (raw.role !== "cli" && raw.role !== "plugin"))
+            return null;
+        if (!isAlive(raw.pid)) {
+            try {
+                rmSync(path, { force: true });
+            }
+            catch {
+                /* 忽略 */
+            }
+            return null;
+        }
+        return { pid: raw.pid, role: raw.role };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 获取锁：写入 `{pid: process.pid, role}`（目录 0700、文件 0600）。
+ * 已有**他人**（不同 pid）持有的活锁 → 拒绝（防同机双隧道）。
+ */
+export function acquireJoinLock(role, path = JOIN_LOCK_PATH) {
+    const held = readJoinLock(path);
+    if (held !== null && held.pid !== process.pid) {
+        return { ok: false, heldBy: held };
+    }
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeFileSync(path, JSON.stringify({ pid: process.pid, role }), { mode: 0o600 });
+    return { ok: true };
+}
+/** 释放锁：仅当锁是自己 pid 持有才删（不误删他人锁）。 */
+export function releaseJoinLock(path = JOIN_LOCK_PATH) {
+    try {
+        const held = readJoinLock(path);
+        if (held !== null && held.pid === process.pid) {
+            rmSync(path, { force: true });
+        }
+    }
+    catch {
+        /* 忽略 */
+    }
+}
+//# sourceMappingURL=lock.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rdsh-gateway",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "rdsh host-side component: LAN auth gateway + outbound tunnel endpoint (spawns dsh web)",
   "license": "MIT",
   "type": "module",