termdock 1.4.261 → 1.4.263

package/dist/server/utils/supervisorClient.js

@@ -0,0 +1,151 @@
+/**
+ * launcher（`td` / `td --status` / `td --stop`）看向 supervisor 的那一侧。
+ *
+ * 与 supervisor.ts 分开是为了单向依赖：supervisor 是独立入口，不能反过来
+ * 依赖 CLI 的进程；CLI 只是它的客户端。
+ */
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { isProcessRunning, readJsonFile, SUPERVISOR_STATE_PATH } from './termdockState.js';
+import { isSupervisorState } from './supervisorProtocol.js';
+import { STOP_GRACE_MS } from './termdockState.js';
+/** supervisor.js 与 cli.js 同目录，所以从本模块（dist/server/utils/）回退一级。 */
+export function resolveSupervisorScript() {
+    return fileURLToPath(new URL('../supervisor.js', import.meta.url));
+}
+export function readSupervisorState() {
+    const state = readJsonFile(SUPERVISOR_STATE_PATH);
+    return isSupervisorState(state) ? state : null;
+}
+/**
+ * 读出 supervisor 状态，并单独给出"它现在还活着吗"。
+ *
+ * **进程死了也不删状态文件**：`gave-up` 正是它死的原因，那份记录就是结论本身；
+ * 别的 phase 下进程没了则意味着"supervisor 自己崩了，服务现在无人监督"——
+ * 两件事都必须能被告知用户。陈旧的判断交给调用方（它才知道自己在问什么），
+ * 真正的清理留给 `td --stop`。
+ */
+export function getSupervisorStatus(statePath = SUPERVISOR_STATE_PATH) {
+    const raw = readJsonFile(statePath);
+    if (!isSupervisorState(raw))
+        return null;
+    return { state: raw, alive: isProcessRunning(raw.pid) };
+}
+/**
+ * 起一个 detached 的 supervisor，并等它把子进程的结局告诉我们。
+ *
+ * 与旧实现的关键差别：这里**会等结果**。旧 `node -e` bridge 是发射后不管，
+ * 新进程起没起来只有用户下次访问才知道。
+ */
+export function spawnSupervisor(options) {
+    return new Promise((resolve) => {
+        const args = [
+            resolveSupervisorScript(),
+            '--health-url', options.healthUrl,
+            '--child', options.childEntry,
+        ];
+        if (options.healthCaPath)
+            args.push('--health-ca', options.healthCaPath);
+        if (options.version)
+            args.push('--version', options.version);
+        args.push('--', ...options.childArgs);
+        let child;
+        try {
+            child = spawn(process.execPath, args, {
+                detached: true,
+                stdio: ['ignore', options.logFileFd, options.logFileFd, 'ipc'],
+            });
+        }
+        catch (error) {
+            resolve({ ok: false, reason: 'spawn-failed', detail: error.message });
+            return;
+        }
+        let settled = false;
+        let spawnError = null;
+        // 拿到结局就断开 IPC 并 unref：supervisor 继续跑，launcher 可以退出。
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (child.connected)
+                child.disconnect();
+            child.unref();
+            resolve(result);
+        };
+        const timer = setTimeout(() => {
+            finish({ ok: false, reason: 'timeout', detail: `no ready within ${options.readyTimeoutMs}ms` });
+        }, options.readyTimeoutMs);
+        child.on('error', (error) => {
+            spawnError = error;
+            finish({ ok: false, reason: 'spawn-failed', detail: error.message });
+        });
+        child.on('message', (message) => {
+            if (!message || typeof message !== 'object' || !('type' in message))
+                return;
+            const typed = message;
+            if (typed.type === 'termdock-ready') {
+                finish({ ok: true, pid: child.pid });
+            }
+            else if (typed.type === 'termdock-startup-failed') {
+                finish({ ok: false, reason: typed.reason, detail: typed.detail });
+            }
+        });
+        child.on('exit', (code, signal) => {
+            finish({
+                ok: false,
+                reason: 'supervisor-exited',
+                detail: spawnError?.message ?? `exited (code ${code ?? 'unknown'}, signal ${signal ?? 'none'})`,
+            });
+        });
+    });
+}
+/**
+ * 停 supervisor：它是唯一该被停的东西，子进程由它负责。
+ *
+ * 先发 SIGTERM 让它自己收拾（杀子进程、删状态、退出 0）；宽限期到了还在，
+ * 才 SIGKILL。**不**在这里直接杀子进程——那会让它变成"意外死亡"从而被重启。
+ */
+export async function stopSupervisor(pid, graceMs = STOP_GRACE_MS) {
+    if (!isProcessRunning(pid)) {
+        try {
+            fs.rmSync(SUPERVISOR_STATE_PATH, { force: true });
+        }
+        catch { /* nothing to clean */ }
+        return true;
+    }
+    try {
+        process.kill(pid, 'SIGTERM');
+    }
+    catch {
+        return true;
+    }
+    const deadline = Date.now() + graceMs;
+    while (isProcessRunning(pid) && Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    if (isProcessRunning(pid)) {
+        try {
+            process.kill(pid, 'SIGKILL');
+        }
+        catch { /* already gone */ }
+        await new Promise((resolve) => setTimeout(resolve, 200));
+    }
+    try {
+        fs.rmSync(SUPERVISOR_STATE_PATH, { force: true });
+    }
+    catch { /* nothing to clean */ }
+    return !isProcessRunning(pid);
+}
+/** `td --restart`：让 supervisor 重启子进程，但继续监督。 */
+export function signalSupervisorRestart(pid) {
+    try {
+        process.kill(pid, 'SIGHUP');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export { SUPERVISOR_STATE_PATH };

package/dist/server/utils/supervisorProtocol.js

@@ -0,0 +1,159 @@
+/**
+ * supervisor ↔ server ↔ launcher 的协议，以及**纯函数**决策逻辑。
+ *
+ * 决策逻辑刻意与进程操作分开：判"这次退出算什么"必须能脱离真实进程单测，
+ * 否则唯一验证手段就只剩"手动 kill 一下看看"。
+ */
+export const SUPERVISOR_STATE_VERSION = 1;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+export function isReadyMessage(value) {
+    return isRecord(value) && value.type === 'termdock-ready';
+}
+export function isServerIntentMessage(value) {
+    if (!isRecord(value) || value.type !== 'termdock-intent')
+        return false;
+    return value.intent === 'restart-after-update' || value.intent === 'stop';
+}
+const NATIVE_CRASH_SIGNALS = new Set(['SIGSEGV', 'SIGABRT', 'SIGBUS', 'SIGILL', 'SIGFPE']);
+function exitDetail(exitCode, signal) {
+    if (signal)
+        return `signal ${signal}`;
+    if (exitCode !== null)
+        return `exit code ${exitCode}`;
+    return 'unknown termination';
+}
+/**
+ * 决定一次子进程退出意味着什么。判定顺序即优先级，改动前先想清楚：
+ * - 停止请求（supervisor 收到 SIGTERM）优先于一切，否则 `--stop` 会被当成崩溃重启，
+ *   变成"用户刚停，它自己又回来"。
+ * - 卡死判定优先于信号判定：wedge 是我们自己 SIGTERM/SIGKILL 的，否则会被
+ *   误读成"被外部终止"从而不重启。
+ * - 更新重启优先于端口冲突/未就绪：更新重启的退出码可能是 0 也可能非 0。
+ * - 手动重启排在更新重启之后：两者都是"我们让子进程重启"，但记录里要分得清
+ *   是应用了更新还是人在敲 `td --restart`。
+ */
+export function classifyChildExit(observation) {
+    const { intent, exitCode, signal, becameReady, supervisorStopRequested, restartRequested, wedge, portConflict, } = observation;
+    if (supervisorStopRequested || intent === 'stop') {
+        return {
+            event: 'stop',
+            detail: supervisorStopRequested ? 'supervisor stop requested' : 'server requested stop',
+            restart: false,
+            countAsCrash: false,
+            resetBackoff: true,
+        };
+    }
+    if (wedge) {
+        return {
+            event: 'wedge',
+            detail: 'health probes stopped responding',
+            restart: true,
+            countAsCrash: true,
+            resetBackoff: false,
+        };
+    }
+    if (intent === 'restart-after-update') {
+        return {
+            event: 'update-restart',
+            detail: 'restart requested after update',
+            restart: true,
+            countAsCrash: false,
+            resetBackoff: true,
+        };
+    }
+    if (restartRequested) {
+        return {
+            event: 'manual-restart',
+            detail: 'restart requested by termdock --restart',
+            restart: true,
+            countAsCrash: false,
+            resetBackoff: true,
+        };
+    }
+    if (portConflict) {
+        return {
+            event: 'port-conflict',
+            detail: 'port already in use',
+            restart: true,
+            countAsCrash: true,
+            resetBackoff: false,
+        };
+    }
+    if (!becameReady) {
+        return {
+            event: 'startup-failure',
+            detail: `exited before becoming ready (${exitDetail(exitCode, signal)})`,
+            restart: true,
+            countAsCrash: true,
+            resetBackoff: false,
+        };
+    }
+    if (signal) {
+        const detail = exitDetail(exitCode, signal);
+        // SIGTERM/SIGINT 但没有 intent = 有人主动停它（部署脚本的 pkill 兜底、关机流程）。
+        // 重启它会把一次有意的停机变成重启风暴，所以只记录、不重启。
+        if (signal === 'SIGTERM' || signal === 'SIGINT') {
+            return {
+                event: 'terminated-externally',
+                detail,
+                restart: false,
+                countAsCrash: false,
+                resetBackoff: true,
+            };
+        }
+        if (signal === 'SIGKILL') {
+            return {
+                event: 'killed',
+                detail,
+                restart: true,
+                countAsCrash: true,
+                resetBackoff: false,
+            };
+        }
+        if (NATIVE_CRASH_SIGNALS.has(signal)) {
+            return {
+                event: 'crash-native',
+                detail,
+                restart: true,
+                countAsCrash: true,
+                resetBackoff: false,
+            };
+        }
+        return {
+            event: 'crash',
+            detail,
+            restart: true,
+            countAsCrash: true,
+            resetBackoff: false,
+        };
+    }
+    if (exitCode === 0) {
+        return {
+            event: 'exit-zero-unexpected',
+            detail: 'exit code 0 without a stop request',
+            restart: true,
+            countAsCrash: true,
+            resetBackoff: false,
+        };
+    }
+    return {
+        event: 'crash',
+        detail: exitDetail(exitCode, signal),
+        restart: true,
+        countAsCrash: true,
+        resetBackoff: false,
+    };
+}
+export const DEFAULT_MAX_CONSECUTIVE_CRASHES = 5;
+/** 连续健康这么久就认为稳住了，把崩溃计数清零。 */
+export const CRASH_COUNTER_RESET_MS = 60_000;
+export function shouldGiveUp(consecutiveCrashes, maxCrashes = DEFAULT_MAX_CONSECUTIVE_CRASHES) {
+    return consecutiveCrashes >= maxCrashes;
+}
+export function isSupervisorState(value) {
+    return isRecord(value)
+        && value.version === SUPERVISOR_STATE_VERSION
+        && typeof value.pid === 'number';
+}

package/dist/server/utils/termdockState.js

@@ -0,0 +1,62 @@
+/**
+ * 单一来源的 Termdock 状态目录 + 原子写。CLI、supervisor、server 三方都读这里，
+ * 避免每处各拼一次路径再写出一套略有出入的读写逻辑。
+ *
+ * 依赖保持轻量（node stdlib only）：supervisor 是独立入口，不能通过这里
+ * 间接把 server 的重依赖拖进来。
+ */
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+export const TERMDOCK_DIR = path.join(os.homedir(), '.termdock');
+export const SERVER_STATE_PATH = path.join(TERMDOCK_DIR, 'server.json');
+export const SUPERVISOR_STATE_PATH = path.join(TERMDOCK_DIR, 'supervisor.json');
+export const SERVER_LOG_PATH = path.join(TERMDOCK_DIR, 'server.log');
+export const RUNTIME_METRICS_PATH = path.join(TERMDOCK_DIR, 'runtime-metrics.log');
+/** 记录"用户已看过某时刻之前的服务异常"，供界面红点判定未读。 */
+export const INCIDENT_DISMISSED_PATH = path.join(TERMDOCK_DIR, 'incident-dismissed.json');
+/** 发 SIGTERM 后等进程自行退出的宽限期，超时才 SIGKILL。CLI 与 supervisor 共用。 */
+export const STOP_GRACE_MS = 5_000;
+export function isProcessRunning(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function readJsonFile(filePath) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 原子替换（tmp + rename + 0600），照 utils/autoUpdate.ts 的 persistState 写法。
+ * 读方要么看到旧文件要么看到新文件，绝不会读到写了一半的 JSON。
+ */
+export function writeJsonStateAtomic(filePath, value) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    const temporaryPath = `${filePath}.${process.pid}.tmp`;
+    fs.writeFileSync(temporaryPath, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(temporaryPath, filePath);
+}
+export function removeJsonState(filePath) {
+    try {
+        fs.rmSync(filePath, { force: true });
+    }
+    catch {
+        // 清理失败不该影响调用方。
+    }
+}
+export function readServerState() {
+    const state = readJsonFile(SERVER_STATE_PATH);
+    if (!state || typeof state.pid !== 'number')
+        return null;
+    return state;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "termdock",
-  "version": "1.4.261",
+  "version": "1.4.263",
   "description": "A complete web-based terminal application with modern UI",
   "type": "module",
   "main": ".desktop-dist/main.js",

package/runtime-manifest.json

@@ -1,13 +1,13 @@
 {
   "schemaVersion": 1,
   "packageName": "termdock",
-  "version": "1.4.261",
+  "version": "1.4.263",
   "runtimeProtocolVersion": 1,
   "minimumDesktopVersion": "1.4.46",
   "nodeMajor": 22,
   "dependencyHash": "sha256-K4KyYJuVoQDpZsBM8ZX1Rw3MddOxAzVdp/cPm0iGZz0=",
-  "serverBundleHash": "sha256-IgrnWiH2Y+b7jVZaD+sWKUT0O2YEpFUTc4LGRTgKg3M=",
-  "clientBundleHash": "sha256-E+hi21G4vPhLVs6T+L3Q8+BYI7u43Y9BecN5yvYPb2o=",
+  "serverBundleHash": "sha256-P298/VVMPtBwuB5OMydf/x/ktRiauZC5IvJvwL2N5/8=",
+  "clientBundleHash": "sha256-UmhjK1bsiYqkurkrSz5AHkF84uC3gST7Z0Op2nhnJzw=",
   "entrypoint": "dist/server/cli.js",
   "clientEntrypoint": "dist/client/index.html"
 }