dsh-api-runner 0.0.0-stage → 0.2.0

package/src/service.js

@@ -0,0 +1,329 @@
+/**
+ * 本地服务管理：两种模式。
+ *
+ *  managed —— 由本插件 spawn 子进程（默认 detached，DSH 重启不影响已起服务），
+ *             pid 持久化在状态文件里，重启 = 杀进程树 + 重新 spawn + 等健康检查；
+ *  observe —— 插件不动进程（进程由 IDEA 起，idea 的 restart 按钮），只能轮询健康
+ *             检查/端口判断"是否起来了"，restart 会明确报错让用户去 IDE 里重启。
+ *
+ * 健康检查三选一（按配置存在与否）：
+ *   health.url  —— HTTP 请求，状态码等于 expectStatus（未配置则 2xx/3xx 视为通过）
+ *   health.ports—— TCP 端口可连通
+ *   都没有      —— managed 模式以"子进程仍存活"为准
+ */
+import fs from 'node:fs';
+import net from 'node:net';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { isPlainObject, isPidAlive, readStateNamespace, sleep, writeStateNamespace } from './util.js';
+
+const isWindows = process.platform === 'win32';
+
+/** 打开日志文件用于追加（失败返回 'ignore'） */
+function openAppend(logPath) {
+    if (!logPath) return 'ignore';
+    try {
+        fs.mkdirSync(path.dirname(logPath), { recursive: true });
+        return fs.openSync(logPath, 'a');
+    } catch {
+        return 'ignore';
+    }
+}
+
+/** TCP 连通性探测 */
+function probePort(host, port, timeoutMs = 1500) {
+    return new Promise((resolve) => {
+        const socket = net.connect({ host, port: Number(port) });
+        let settled = false;
+        const finish = (ok) => {
+            if (settled) return;
+            settled = true;
+            socket.destroy();
+            resolve(ok);
+        };
+        socket.setTimeout(timeoutMs, () => finish(false));
+        socket.once('connect', () => finish(true));
+        socket.once('error', () => finish(false));
+    });
+}
+
+/** HTTP 健康探测 */
+async function probeHttp(health) {
+    if (!health.url) return undefined;
+    try {
+        const response = await fetch(health.url, {
+            method: health.method || 'GET',
+            signal: AbortSignal.timeout(health.timeoutMs || 3000),
+            redirect: 'manual',
+        });
+        const expected = Number(health.expectStatus || 0);
+        const ok = expected ? response.status === expected : response.status < 400;
+        return { ok, detail: `HTTP ${response.status}` };
+    } catch (error) {
+        return { ok: false, detail: `请求失败：${error?.message || error}` };
+    }
+}
+
+export class ServiceManager {
+    /**
+     * @param {{statePath:string, homeDir:string}} options
+     */
+    constructor(options = {}) {
+        this.statePath = options.statePath || '';
+        this.children = new Map();
+        this._state = null;
+    }
+
+    _load() {
+        if (this._state) return this._state;
+        this._state = readStateNamespace(this.statePath, 'services');
+        return this._state;
+    }
+
+    _record(serviceId) {
+        const state = this._load();
+        return isPlainObject(state[serviceId]) ? state[serviceId] : undefined;
+    }
+
+    _setRecord(serviceId, record) {
+        const state = this._load();
+        if (record) state[serviceId] = record;
+        else delete state[serviceId];
+        this._flush();
+    }
+
+    _flush() {
+        if (!this.statePath || !this._state) return;
+        // 只更新 services 命名空间，保留日志游标
+        writeStateNamespace(this.statePath, 'services', this._state);
+    }
+
+    /** 当前托管的 pid（内存优先，回退状态文件，并确认存活） */
+    pidOf(service) {
+        const live = this.children.get(service.id);
+        if (live?.pid && isPidAlive(live.pid)) return live.pid;
+        const record = this._record(service.id);
+        if (record?.pid && isPidAlive(record.pid)) return record.pid;
+        return 0;
+    }
+
+    /** 健康检查：返回 {ok, checks:[{kind, ok, detail}]} */
+    async check(service) {
+        const checks = [];
+        const pid = this.pidOf(service);
+        if (service.mode === 'managed') {
+            checks.push({ kind: 'process', ok: pid > 0, detail: pid > 0 ? `pid ${pid} 存活` : '未发现托管进程' });
+        }
+        const http = await probeHttp(service.health);
+        if (http) checks.push({ kind: 'http', ...http, detail: `${service.health.url} → ${http.detail}` });
+
+        for (const port of service.health.ports || []) {
+            const ok = await probePort(service.health.host || '127.0.0.1', port, service.health.timeoutMs || 1500);
+            checks.push({ kind: 'tcp', ok, detail: `${service.health.host || '127.0.0.1'}:${port} ${ok ? '可连接' : '连接失败'}` });
+        }
+
+        if (checks.length === 0) {
+            return { ok: pid > 0, checks: [{ kind: 'process', ok: pid > 0, detail: pid > 0 ? `pid ${pid} 存活` : '无健康检查配置且无托管进程' }] };
+        }
+        // process 检查只作为辅助信息：observe 模式下没有 pid 是正常的
+        const effective = checks.filter((item) => item.kind !== 'process');
+        const ok = effective.length > 0 ? effective.every((item) => item.ok) : checks.every((item) => item.ok);
+        return { ok, checks };
+    }
+
+    /** 轮询等到健康；返回 {ok, waitedMs, checks} */
+    async waitHealthy(service, timeoutMs = service.startupTimeoutMs || 60_000) {
+        const started = Date.now();
+        const interval = Math.max(200, service.health.intervalMs || 1000);
+        let last = await this.check(service);
+        while (!last.ok && Date.now() - started < timeoutMs) {
+            await sleep(interval);
+            last = await this.check(service);
+        }
+        return { ok: last.ok, waitedMs: Date.now() - started, checks: last.checks };
+    }
+
+    /** 启动（managed）；已健康则直接返回 */
+    async start(service, options = {}) {
+        if (service.mode !== 'managed') {
+            return {
+                ok: false,
+                reason: 'OBSERVE_MODE',
+                message: `服务 ${service.id} 是 observe 模式，插件不托管进程；请在 IDEA 里启动后调用 wait/status 等待就绪。`,
+            };
+        }
+        const existing = await this.check(service);
+        if (existing.ok && !options.force) {
+            return { ok: true, alreadyRunning: true, reason: 'ALREADY_RUNNING', pid: this.pidOf(service), checks: existing.checks };
+        }
+        if (this.pidOf(service) > 0) {
+            // 进程在但不健康：先杀掉再起，避免端口冲突
+            await this.stop(service);
+        }
+        if (!service.command) {
+            return { ok: false, reason: 'NO_COMMAND', message: `服务 ${service.id} 未配置 command` };
+        }
+
+        const logFd = openAppend(service.logPath);
+        const [file, ...args] = [service.command, ...service.args];
+        let child;
+        try {
+            child = spawn(file, args, {
+                cwd: service.cwd || process.cwd(),
+                env: { ...process.env, ...service.env },
+                detached: true,
+                stdio: ['ignore', logFd, logFd],
+                shell: isWindows && /\.(cmd|bat)$/i.test(file),
+                windowsHide: true,
+            });
+        } catch (error) {
+            if (typeof logFd === 'number') {
+                try {
+                    fs.closeSync(logFd);
+                } catch {
+                    // 关闭失败无影响
+                }
+            }
+            return { ok: false, reason: 'SPAWN_FAILED', message: `启动失败：${error.message}` };
+        }
+        // 子进程已继承该 fd，父进程必须关掉自己那份，否则文件句柄泄漏、日志文件被占用
+        if (typeof logFd === 'number') {
+            try {
+                fs.closeSync(logFd);
+            } catch {
+                // 关闭失败无影响
+            }
+        }
+        child.unref?.();
+        this.children.set(service.id, child);
+
+        let exitInfo;
+        child.once('exit', (code, signal) => {
+            exitInfo = { code, signal };
+            if (this.children.get(service.id) === child) this.children.delete(service.id);
+        });
+        this._setRecord(service.id, {
+            pid: child.pid,
+            startedAt: new Date().toISOString(),
+            command: [service.command, ...service.args].join(' '),
+            cwd: service.cwd,
+        });
+
+        const health = await this.waitHealthy(service, options.timeoutMs || service.startupTimeoutMs);
+        if (health.ok) {
+            return { ok: true, pid: child.pid, waitedMs: health.waitedMs, checks: health.checks };
+        }
+        return {
+            ok: false,
+            reason: 'START_TIMEOUT',
+            pid: child.pid,
+            waitedMs: health.waitedMs,
+            checks: health.checks,
+            exited: exitInfo,
+            message: exitInfo
+                ? `进程启动后立即退出（code=${exitInfo.code}, signal=${exitInfo.signal}），检查 command/cwd 与日志`
+                : `启动后 ${health.waitedMs}ms 内健康检查未通过`,
+        };
+    }
+
+    /** 停止（managed）：Windows 用 taskkill /T /F 杀进程树，其它平台杀进程组 */
+    async stop(service) {
+        if (service.mode !== 'managed') {
+            return { ok: false, reason: 'OBSERVE_MODE', message: `服务 ${service.id} 是 observe 模式，请到 IDEA 里停止。` };
+        }
+        const pid = this.pidOf(service);
+        if (pid === 0) {
+            this._setRecord(service.id, undefined);
+            return { ok: true, alreadyStopped: true };
+        }
+        const killed = await this._killTree(pid, service.killTree !== false);
+        this.children.delete(service.id);
+        const deadline = Date.now() + (service.stopTimeoutMs || 10_000);
+        while (Date.now() < deadline && isPidAlive(pid)) await sleep(120);
+        const stillAlive = isPidAlive(pid);
+        if (!stillAlive) this._setRecord(service.id, undefined);
+        return {
+            ok: !stillAlive,
+            pid,
+            killedBy: killed,
+            stillAlive,
+            message: stillAlive ? `pid ${pid} 在 ${service.stopTimeoutMs}ms 内未退出` : `已停止 pid ${pid}`,
+        };
+    }
+
+    _killTree(pid, tree) {
+        return new Promise((resolve) => {
+            if (isWindows) {
+                const args = ['/PID', String(pid), '/T', '/F'];
+                const killer = spawn('taskkill', args, { windowsHide: true, stdio: 'ignore' });
+                killer.once('exit', (code) => {
+                    if (code === 0) {
+                        resolve('taskkill');
+                        return;
+                    }
+                    try {
+                        process.kill(pid);
+                        resolve('kill');
+                    } catch {
+                        resolve('none');
+                    }
+                });
+                killer.once('error', () => {
+                    try {
+                        process.kill(pid);
+                        resolve('kill');
+                    } catch {
+                        resolve('none');
+                    }
+                });
+                return;
+            }
+            try {
+                // detached 启动 => 子进程是进程组 leader
+                process.kill(tree ? -pid : pid, 'SIGTERM');
+                resolve('SIGTERM');
+            } catch {
+                resolve('none');
+            }
+        });
+    }
+
+    /** 重启（managed）：stop + start，返回带耗时与阶段的结果 */
+    async restart(service, options = {}) {
+        if (service.mode !== 'managed') {
+            // observe 模式：不能替用户重启，但可以等待用户手动重启后恢复
+            return {
+                ok: false,
+                reason: 'OBSERVE_MODE',
+                message: `服务 ${service.id} 是 observe 模式，插件不托管进程。请在 IDEA 里重启，然后调用 action=wait 等待健康检查通过。`,
+            };
+        }
+        const stopped = await this.stop(service);
+        if (!stopped.ok) return { ok: false, stage: 'stop', ...stopped };
+        const started = await this.start(service, { ...options, force: true });
+        return { ok: started.ok, stage: started.ok ? 'done' : 'start', stop: stopped, start: started };
+    }
+
+    /** 概览：所有配置服务的实时状态 */
+    async statusAll(services) {
+        const out = [];
+        for (const service of services) {
+            const pid = this.pidOf(service);
+            const health = await this.check(service);
+            out.push({
+                id: service.id,
+                name: service.name,
+                mode: service.mode,
+                pid: pid || undefined,
+                healthy: health.ok,
+                checks: health.checks,
+            });
+        }
+        return out;
+    }
+
+    /** 插件卸载：只保存状态，不杀进程（服务应在 DSH 重启后继续可用） */
+    dispose() {
+        this._flush();
+    }
+}

package/src/settings.js

@@ -0,0 +1,109 @@
+/**
+ * 插件级设置（跨项目共用一份）。
+ *
+ * 存在 `${DSH_HOME}/api-runner-settings.json`，与项目配置分开：
+ * 项目配置（YAML / 面板保存的接口）是「这个项目怎么调接口」，
+ * 这里是「插件把运行数据写到哪」这类机器级偏好。
+ *
+ * 结构：
+ * {
+ *   version: 1,
+ *   dataDir: "/abs/path/.dsh-api-runner",   // 空表示用 DSH_HOME；必须是绝对路径
+ *   workspace: "/abs/path/your-project",    // 面板默认项目根（可选）
+ *   mavenHome: "/abs/path/apache-maven-3.6.3" // Maven 主路径（可选；空表示自动探测）
+ * }
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { isPlainObject } from './util.js';
+
+export class SettingsStore {
+    constructor(options = {}) {
+        this.homeDir = options.homeDir || process.env.DSH_HOME || path.join(process.cwd(), '.dsh');
+        this.file = path.join(this.homeDir, 'api-runner-settings.json');
+        this._doc = undefined;
+        this._mtimeMs = -1;
+    }
+
+    _load() {
+        let stat;
+        try {
+            stat = fs.statSync(this.file);
+        } catch {
+            this._doc = { version: 1, dataDir: '', workspace: '', mavenHome: '' };
+            this._mtimeMs = -1;
+            return this._doc;
+        }
+        if (this._doc !== undefined && stat.mtimeMs === this._mtimeMs) return this._doc;
+        try {
+            const parsed = JSON.parse(fs.readFileSync(this.file, 'utf8'));
+            this._doc = isPlainObject(parsed) ? parsed : { version: 1 };
+        } catch {
+            this._doc = { version: 1 };
+        }
+        this._mtimeMs = stat.mtimeMs;
+        return this._doc;
+    }
+
+    _save(doc) {
+        fs.mkdirSync(path.dirname(this.file), { recursive: true });
+        const tmp = `${this.file}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(doc, null, 2), 'utf8');
+        fs.renameSync(tmp, this.file);
+        this._doc = doc;
+        this._mtimeMs = fs.statSync(this.file).mtimeMs;
+    }
+
+    /** 当前设置（对外展示用） */
+    read() {
+        const doc = this._load();
+        return {
+            dataDir: String(doc.dataDir || ''),
+            workspace: String(doc.workspace || ''),
+            mavenHome: String(doc.mavenHome || ''),
+            /** 生效的运行数据目录：没配就用 DSH_HOME */
+            effectiveDataDir: this.dataDir(),
+            homeDir: this.homeDir,
+            settingsFile: this.file,
+        };
+    }
+
+    /**
+     * 运行数据落盘目录。
+     * 配了 dataDir 就用它（相对路径按 DSH_HOME 解析，避免用户填了个相对路径不知道落到哪）；
+     * 否则退回 DSH_HOME，与老版本行为一致。
+     */
+    dataDir() {
+        const doc = this._load();
+        const raw = String(doc.dataDir || '').trim();
+        if (!raw) return this.homeDir;
+        return path.isAbsolute(raw) ? path.normalize(raw) : path.resolve(this.homeDir, raw);
+    }
+
+    set(patch = {}) {
+        const doc = this._load();
+        if (patch.dataDir !== undefined) {
+            const raw = String(patch.dataDir || '').trim();
+            if (raw !== '' && !path.isAbsolute(raw)) {
+                const sample = process.platform === 'win32' ? 'D:\\dsh-api-runner-data' : '/Users/you/dsh-api-runner-data';
+                throw new Error(`数据目录必须是绝对路径，例如 ${sample}`);
+            }
+            doc.dataDir = raw;
+        }
+        if (patch.workspace !== undefined) {
+            const raw = String(patch.workspace || '').trim();
+            doc.workspace = raw;
+        }
+        if (patch.mavenHome !== undefined) {
+            const raw = String(patch.mavenHome || '').trim();
+            if (raw !== '' && !path.isAbsolute(raw)) {
+                const sample = process.platform === 'win32' ? 'D:\\apache-maven-3.9.6' : '/opt/apache-maven-3.9.6';
+                throw new Error(`Maven 主路径必须是绝对路径（到安装目录为止），例如 ${sample}`);
+            }
+            doc.mavenHome = raw;
+        }
+        doc.version = 1;
+        this._save(doc);
+        return this.read();
+    }
+}

package/src/util.js

@@ -0,0 +1,182 @@
+/**
+ * 通用小工具：配置发现、模板展开、文本裁剪、进程存活判断。
+ * 本文件不依赖 cordis，可在纯 node 下单独测试。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** 是否普通对象（排除数组、null） */
+export function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** 按“字节上限”截断文本，并给出截断提示 */
+export function truncateText(text, maxBytes = 32 * 1024) {
+    if (typeof text !== 'string') return '';
+    const buf = Buffer.from(text, 'utf8');
+    if (buf.length <= maxBytes) return text;
+    // 从末尾往前找换行，避免切碎多字节字符
+    let end = maxBytes;
+    const slice = buf.subarray(0, end).toString('utf8');
+    const cut = slice.lastIndexOf('\n');
+    const body = cut > 0 ? slice.slice(0, cut) : slice;
+    return `${body}\n…[已截断，原始 ${buf.length} 字节，仅显示前 ${maxBytes} 字节]`;
+}
+
+/** 展开 ${NAME}：先查 scope，再查 process.env；查不到保持原样 */
+export function expandDollar(source, scope = {}) {
+    if (typeof source !== 'string') return source;
+    return source.replace(/\$\{([A-Za-z_][A-Za-z0-9_.-]*)\}/g, (whole, name) => {
+        if (Object.prototype.hasOwnProperty.call(scope, name) && scope[name] !== undefined && scope[name] !== null) {
+            return String(scope[name]);
+        }
+        const envValue = process.env[name];
+        return envValue === undefined ? whole : envValue;
+    });
+}
+
+/** 展开调用期占位符 {key}：只替换 vars 中存在的键，其余原样保留 */
+export function expandBraces(source, vars = {}) {
+    if (typeof source !== 'string') return source;
+    if (!vars || Object.keys(vars).length === 0) return source;
+    return source.replace(/\{([A-Za-z_][A-Za-z0-9_.-]*)\}/g, (whole, name) => {
+        return Object.prototype.hasOwnProperty.call(vars, name) ? String(vars[name]) : whole;
+    });
+}
+
+/** 递归展开对象/数组里的字符串模板 */
+export function expandDeep(value, scope = {}, vars = {}) {
+    if (typeof value === 'string') return expandBraces(expandDollar(value, scope), vars);
+    if (Array.isArray(value)) return value.map((item) => expandDeep(item, scope, vars));
+    if (isPlainObject(value)) {
+        const out = {};
+        for (const [key, item] of Object.entries(value)) out[expandBraces(expandDollar(key, scope), vars)] = expandDeep(item, scope, vars);
+        return out;
+    }
+    return value;
+}
+
+/** 沿目录向上查找配置文件，返回绝对路径或 '' */
+export function findUp(startDir, fileNames, maxDepth = 8) {
+    let dir = path.resolve(startDir || '.');
+    for (let depth = 0; depth <= maxDepth; depth += 1) {
+        for (const name of fileNames) {
+            const candidate = path.join(dir, name);
+            try {
+                if (fs.statSync(candidate).isFile()) return candidate;
+            } catch {
+                // 不存在，继续
+            }
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) break;
+        dir = parent;
+    }
+    return '';
+}
+
+/** 统一项目标识：盘符小写、正斜杠、去掉末尾斜杠 */
+export function normalizeProjectKey(cwd) {
+    if (!cwd || typeof cwd !== 'string') return '';
+    let key = path.resolve(cwd).replace(/\\/g, '/');
+    if (/^[A-Za-z]:/.test(key)) key = key[0].toLowerCase() + key.slice(1);
+    return key.replace(/\/+$/, '');
+}
+
+/** 敏感请求头脱敏（只用于展示/返回给模型前的日志副本） */
+export function redactHeaders(headers) {
+    // 兼顾写法差异：标准头（authorization/cookie）、自定义头（X-Token、X-Api-Key）、
+    // 以及名字里带 token/secret/password/key 的任意头，一律按敏感处理。
+    const exact = /^(authorization|cookie|set-cookie|proxy-authorization)$/i;
+    const fuzzy = /(^|[-_])(token|secret|password|passwd|pwd|key|auth|credential|signature)([-_]|$)/i;
+    const out = {};
+    for (const [key, value] of Object.entries(headers || {})) {
+        out[key] = exact.test(key) || fuzzy.test(key) ? maskSecret(String(value)) : value;
+    }
+    return out;
+}
+
+export function maskSecret(text) {
+    if (text.length <= 8) return '***';
+    return `${text.slice(0, 4)}***${text.slice(-4)}`;
+}
+
+/** 尝试 JSON.parse，失败返回 undefined */
+export function tryJson(text) {
+    if (typeof text !== 'string' || text.trim() === '') return undefined;
+    try {
+        return JSON.parse(text);
+    } catch {
+        return undefined;
+    }
+}
+
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, Math.max(0, ms)));
+}
+
+/** 进程是否存活（EPERM 视为存活：存在但无权限） */
+export function isPidAlive(pid) {
+    const num = Number(pid);
+    if (!Number.isInteger(num) || num <= 0) return false;
+    try {
+        process.kill(num, 0);
+        return true;
+    } catch (error) {
+        return error?.code === 'EPERM';
+    }
+}
+
+/** 相对路径按 baseDir 展开；绝对路径原样 */
+export function resolveFrom(baseDir, target) {
+    if (!target) return '';
+    return path.isAbsolute(target) ? path.normalize(target) : path.resolve(baseDir, target);
+}
+
+/**
+ * 读取状态文件里的某个命名空间。
+ * 日志游标与服务 pid 共用同一个状态文件，所以必须按命名空间分开读写，
+ * 否则一个组件写盘时会把另一个组件的记录整体抹掉。
+ */
+export function readStateNamespace(statePath, key) {
+    if (!statePath) return {};
+    try {
+        const parsed = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+        if (isPlainObject(parsed) && isPlainObject(parsed[key])) return parsed[key];
+    } catch {
+        // 首次运行或文件损坏，视为空
+    }
+    return {};
+}
+
+/** 只更新状态文件里的某个命名空间，保留其它命名空间（原子替换） */
+export function writeStateNamespace(statePath, key, value) {
+    if (!statePath) return;
+    let doc = {};
+    try {
+        const parsed = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+        if (isPlainObject(parsed)) doc = parsed;
+    } catch {
+        // 首次运行或文件损坏，从空文档开始
+    }
+    doc.version = 1;
+    doc[key] = value;
+    try {
+        fs.mkdirSync(path.dirname(statePath), { recursive: true });
+        const tmp = `${statePath}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(doc, null, 2), 'utf8');
+        fs.renameSync(tmp, statePath);
+    } catch {
+        // 状态写失败不影响本次操作
+    }
+}
+
+/** 对象深合并：后者覆盖前者，数组整体替换 */
+export function deepMerge(base, patch) {
+    if (!isPlainObject(base) || !isPlainObject(patch)) return patch === undefined ? base : patch;
+    const out = { ...base };
+    for (const [key, value] of Object.entries(patch)) {
+        out[key] = isPlainObject(value) && isPlainObject(base[key]) ? deepMerge(base[key], value) : value;
+    }
+    return out;
+}