@shendeguize/remote-dsh-center 0.4.0

package/src/config-sync.js

@@ -0,0 +1,157 @@
+/**
+ * 批量配置同步的唯一规则源。
+ *
+ * 只复制「下一次拉起」使用的 profile；身份、纳管、自启、本机映射和运行态一律不碰。
+ */
+
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
+
+import { DshError } from './lib/errors.js';
+
+export const SYNC_PROFILE_FIELDS = Object.freeze([
+  'remoteWebPort',
+  'workdir',
+  'inject.env',
+  'inject.extraArgs',
+  'inject.patches',
+]);
+
+const PREVIEW_TOKEN_VERSION = 'v1';
+const PREVIEW_TOKEN_KEY = randomBytes(32);
+
+function cloneInject(value) {
+  return {
+    env: { ...(value?.env ?? {}) },
+    extraArgs: [...(value?.extraArgs ?? [])],
+    patches: [...(value?.patches ?? [])],
+  };
+}
+
+export function syncProfileOf(hostConfig) {
+  return {
+    remoteWebPort: hostConfig?.remoteWebPort ?? null,
+    workdir: hostConfig?.workdir ?? null,
+    inject: cloneInject(hostConfig?.inject),
+  };
+}
+
+function changedFields(source, target) {
+  const changed = [];
+  if (!isDeepStrictEqual(source.remoteWebPort, target.remoteWebPort)) changed.push('remoteWebPort');
+  if (!isDeepStrictEqual(source.workdir, target.workdir)) changed.push('workdir');
+  if (!isDeepStrictEqual(source.inject.env, target.inject.env)) changed.push('inject.env');
+  if (!isDeepStrictEqual(source.inject.extraArgs, target.inject.extraArgs)) changed.push('inject.extraArgs');
+  if (!isDeepStrictEqual(source.inject.patches, target.inject.patches)) changed.push('inject.patches');
+  return changed;
+}
+
+function requireHost(config, name, role) {
+  const hosts = config?.hosts;
+  if (hosts === null || typeof hosts !== 'object' || !Object.hasOwn(hosts, name)) {
+    throw new DshError('NOT_FOUND', `${role} ${name} 不存在`, { host: name });
+  }
+  const host = hosts[name];
+  if (!host) throw new DshError('NOT_FOUND', `${role} ${name} 不存在`, { host: name });
+  return host;
+}
+
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map((entry) => canonicalize(entry));
+  if (value === null || typeof value !== 'object') return value;
+  return Object.fromEntries(
+    Object.keys(value).sort().map((key) => [key, canonicalize(value[key])]),
+  );
+}
+
+function previewTokenForPlan(config, plan) {
+  const payload = {
+    source: {
+      name: plan.source,
+      profile: syncProfileOf(requireHost(config, plan.source, '源主机')),
+    },
+    targets: plan.targets
+      .map(({ name }) => ({
+        name,
+        profile: syncProfileOf(requireHost(config, name, '目标主机')),
+      }))
+      .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)),
+  };
+  const digest = createHmac('sha256', PREVIEW_TOKEN_KEY)
+    .update('dsh-center/config-sync-preview/v1\0')
+    .update(JSON.stringify(canonicalize(payload)))
+    .digest('base64url');
+  return `${PREVIEW_TOKEN_VERSION}.${digest}`;
+}
+
+function tokensEqual(actual, expected) {
+  if (typeof actual !== 'string') return false;
+  const actualBytes = Buffer.from(actual, 'utf8');
+  const expectedBytes = Buffer.from(expected, 'utf8');
+  return actualBytes.length === expectedBytes.length
+    && timingSafeEqual(actualBytes, expectedBytes);
+}
+
+export function planConfigSync(config, { source, targets } = {}) {
+  if (typeof source !== 'string' || source === '') {
+    throw new DshError('VALIDATION', '请选择源主机');
+  }
+  if (!Array.isArray(targets) || targets.length === 0) {
+    throw new DshError('VALIDATION', '至少选择一台目标主机');
+  }
+  if (new Set(targets).size !== targets.length) {
+    throw new DshError('VALIDATION', '目标主机不能重复');
+  }
+  if (targets.includes(source)) {
+    throw new DshError('VALIDATION', '源主机不能同时作为目标主机');
+  }
+
+  const profile = syncProfileOf(requireHost(config, source, '源主机'));
+  const targetPlans = targets.map((name) => {
+    const fields = changedFields(profile, syncProfileOf(requireHost(config, name, '目标主机')));
+    return { name, changed: fields.length > 0, changedFields: fields };
+  });
+
+  return {
+    source,
+    profile,
+    targets: targetPlans,
+  };
+}
+
+export function createConfigSyncPreview(config, request) {
+  const plan = planConfigSync(config, request);
+  return {
+    plan,
+    previewToken: previewTokenForPlan(config, plan),
+  };
+}
+
+export function requireConfigSyncPreview(config, request, previewToken) {
+  const preview = createConfigSyncPreview(config, request);
+  if (!tokensEqual(previewToken, preview.previewToken)) {
+    throw new DshError(
+      'CONFIG_STALE',
+      '配置同步预览已过期或无效，请重新预览后再应用',
+      { detail: '源主机或任一目标主机的同步 profile 可能已变化。' },
+    );
+  }
+  return preview.plan;
+}
+
+export function applyConfigSync(draft, plan) {
+  requireHost(draft, plan?.source, '源主机');
+  const targets = (plan?.targets ?? []).map((targetPlan) => ({
+    config: requireHost(draft, targetPlan.name, '目标主机'),
+    plan: targetPlan,
+  }));
+  const changed = [];
+  for (const { config: target, plan: targetPlan } of targets) {
+    if (!targetPlan.changed) continue;
+    target.remoteWebPort = plan.profile.remoteWebPort;
+    target.workdir = plan.profile.workdir;
+    target.inject = cloneInject(plan.profile.inject);
+    changed.push(targetPlan.name);
+  }
+  return changed;
+}

package/src/daemon.js

@@ -0,0 +1,362 @@
+/**
+ * manager 自身的生命周期设施（11 §6.4）：detach 拉起、pidfile、launchd 服务化。
+ *
+ * 只依赖 defaults（叶子），不 import server/store——「谁拉起谁」这件事必须能在
+ * server 尚未存在的情况下完成（dshc up 的第一拍）。
+ */
+
+import fs from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+import { LAUNCHD_LABEL, resolvePaths } from './defaults.js';
+import { DshError } from './lib/errors.js';
+import { monotonicMs } from './lib/clock.js';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+export const SERVER_ENTRY = path.join(HERE, 'server.js');
+export const CLI_ENTRY = path.join(HERE, 'cli.js');
+
+/** @typedef {{pid:number, port:number, mode:'foreground'|'background'|'launchd', startedAt:string}} PidInfo */
+
+function paths() {
+  return resolvePaths();
+}
+
+/** DSHC_MODE 由拉起方注入（plist / launchDetached）；缺省即前台。 */
+export function detectMode(env = process.env) {
+  const m = env.DSHC_MODE;
+  return m === 'launchd' || m === 'background' ? m : 'foreground';
+}
+
+// ── pidfile ──────────────────────────────────────────────────────────────
+
+/** @returns {PidInfo|null} */
+export function readPidfile() {
+  try {
+    const raw = JSON.parse(fs.readFileSync(paths().pidfile, 'utf8'));
+    if (!Number.isInteger(raw?.pid)) return null;
+    return raw;
+  } catch {
+    return null;
+  }
+}
+
+export function writePidfile(info) {
+  const p = paths();
+  try {
+    fs.mkdirSync(p.dir, { recursive: true });
+    const tmp = `${p.pidfile}.tmp.${process.pid}`;
+    fs.writeFileSync(tmp, `${JSON.stringify(info, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(tmp, p.pidfile);
+  } catch (err) {
+    // 没有 pidfile 就没人能找到这个 manager（stop/restart/CLI 全靠它），故必须硬失败；
+    // 但要给人话，别把 Node 的栈直接摔在用户脸上（issue #87）
+    throw new DshError('PIDFILE_WRITE_FAILED', 'manager 的运行记录写不进去，没法启动', {
+      detail: `文件：${p.pidfile}\n${err.code ?? ''} ${err.message}\n`.trim()
+        + '\n常见原因：磁盘满、所在卷变成只读、目录属主不是当前用户（比如被 sudo 跑过一次）。',
+      cause: err,
+    });
+  }
+  return info;
+}
+
+/** 仅 pid===process.pid 才删（§3.4 竞态防护：别把继任者的 pidfile 删了）。 */
+export function removePidfileIfOwn() {
+  const info = readPidfile();
+  if (info?.pid !== process.pid) return false;
+  try {
+    fs.rmSync(paths().pidfile, { force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function processAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === 'EPERM'; // 存在但非本用户
+  }
+}
+
+/** GET /api/manager/info（不经 store，daemon 要能在 server 之外独立判活）。 */
+export function fetchInfo(port, { timeoutMs = 1_500 } = {}) {
+  return new Promise((resolve) => {
+    const req = http.request(
+      { host: '127.0.0.1', port, path: '/api/manager/info', method: 'GET', timeout: timeoutMs },
+      (res) => {
+        let text = '';
+        res.setEncoding('utf8');
+        res.on('data', (c) => { text += c; });
+        res.on('end', () => {
+          if (res.statusCode !== 200) return resolve(null);
+          try {
+            resolve(JSON.parse(text));
+          } catch {
+            resolve(null);
+          }
+        });
+      },
+    );
+    req.on('timeout', () => { req.destroy(); resolve(null); });
+    req.on('error', () => resolve(null));
+    req.end();
+  });
+}
+
+/**
+ * kill(pid,0) + info 双验证（防 PID 复用，02 §9.5）。
+ * @returns {Promise<{alive:boolean, stale:boolean, info:PidInfo|null, remote:any|null}>}
+ */
+export async function aliveCheck() {
+  const info = readPidfile();
+  if (!info) return { alive: false, stale: false, info: null, remote: null };
+  if (!processAlive(info.pid)) return { alive: false, stale: true, info, remote: null };
+
+  const remote = await fetchInfo(info.port);
+  if (!remote) return { alive: false, stale: true, info, remote: null };
+  if (remote.pid !== info.pid) return { alive: false, stale: true, info, remote };
+  return { alive: true, stale: false, info, remote };
+}
+
+// ── 后台拉起 ─────────────────────────────────────────────────────────────
+
+/**
+ * detach 拉起 server（§3.4 第 7 步同款）。stdout/stderr 以 O_APPEND 重定向到 manager.log，
+ * 两进程短暂共写安全。
+ *
+ * 预算内没确认健康就把它收回来（issue #77）：留着不管的话，命令报了失败，那个进程
+ * 还在后台待着——等占着端口的人一走它自己就把端口接过去，用户手上于是有一个
+ * 「启动失败过」的 manager 在跑。
+ *
+ * `entry` / `DSHC_SERVER_ENTRY` 是测试缝（同 `DSHC_SSH_BIN` 的用法）：换一个永远不落
+ * pidfile 的假 manager，才能验「没确认健康」这条路。
+ * @returns {Promise<{pid:number, port:number|null, confirmed:boolean, reaped:boolean}>}
+ */
+export async function launchDetached({
+  port = null,
+  waitMs = Number(process.env.DSHC_UP_WAIT_MS ?? '') || 10_000,
+  env = {},
+  entry = process.env.DSHC_SERVER_ENTRY || SERVER_ENTRY,
+} = {}) {
+  const p = paths();
+  let fd;
+  try {
+    fs.mkdirSync(p.dir, { recursive: true });
+    // 后台 manager 的 stdout/stderr 就指这个 fd；开不出来它就是个没有现场的黑箱，不如不起
+    fd = fs.openSync(p.log, 'a');
+  } catch (err) {
+    throw new DshError('LOGFILE_OPEN_FAILED', 'manager 的日志文件打不开，没法启动', {
+      detail: `文件：${p.log}\n${err.code ?? ''} ${err.message}`.trim()
+        + '\n常见原因：磁盘满、所在卷变成只读、目录属主不是当前用户（比如被 sudo 跑过一次）。',
+      cause: err,
+    });
+  }
+
+  const args = [entry];
+  if (port !== null) args.push('--port', String(port));
+
+  const child = spawn(process.execPath, args, {
+    detached: true,
+    stdio: ['ignore', fd, fd],
+    env: { ...process.env, ...env, DSHC_MODE: 'background' },
+  });
+  child.unref();
+  fs.closeSync(fd);
+
+  const deadline = monotonicMs() + waitMs;
+  let confirmed = false;
+  let seenPort = port;
+  while (monotonicMs() < deadline) {
+    // eslint-disable-next-line no-await-in-loop -- 就绪轮询
+    await sleep(200);
+    const info = readPidfile();
+    if (!info) continue;
+    // eslint-disable-next-line no-await-in-loop -- 同上
+    const remote = await fetchInfo(info.port);
+    if (remote?.pid === info.pid) {
+      confirmed = true;
+      seenPort = info.port;
+      break;
+    }
+  }
+  if (confirmed) return { pid: child.pid, port: seenPort, confirmed, reaped: false };
+  return { pid: child.pid, port: seenPort, confirmed: false, reaped: await reap(child.pid) };
+}
+
+/**
+ * 收走一个没确认健康的拉起：TERM → 1s → KILL。
+ * @returns {Promise<boolean>} 真的动过手才算 true（它自己已经退了就不算）
+ */
+async function reap(pid, { graceMs = 1_000 } = {}) {
+  if (!processAlive(pid)) return false;
+  try {
+    process.kill(pid, 'SIGTERM');
+  } catch {
+    return false; // 竞态：刚好退了
+  }
+  const deadline = monotonicMs() + graceMs;
+  while (monotonicMs() < deadline && processAlive(pid)) {
+    // eslint-disable-next-line no-await-in-loop -- 等它落幕
+    await sleep(50);
+  }
+  if (processAlive(pid)) {
+    try {
+      process.kill(pid, 'SIGKILL');
+    } catch {
+      // 已退出
+    }
+  }
+  return true;
+}
+
+/**
+ * 不能 unref：CLI 是短命进程，等待期间事件循环若无句柄会直接退出，
+ * launchDetached / stopDaemon 的轮询就永远等不到结果（表现为命令静默返回）。
+ */
+const sleep = (ms) => new Promise((r) => { setTimeout(r, ms); });
+
+/**
+ * dshc down：launchd 实例走 bootout；裸后台走 TERM → 3s → KILL。
+ * @returns {Promise<{stopped:boolean, mode:string|null, forced:boolean}>}
+ */
+export async function stopDaemon({ graceMs = 3_000 } = {}) {
+  const check = await aliveCheck();
+  if (!check.info) return { stopped: false, mode: null, forced: false };
+
+  if (check.info.mode === 'launchd') {
+    await serviceUninstall({ keepPlist: true });
+    return { stopped: true, mode: 'launchd', forced: false };
+  }
+
+  const { pid } = check.info;
+  if (!processAlive(pid)) {
+    removeForeignPidfile(pid);
+    return { stopped: false, mode: check.info.mode, forced: false };
+  }
+
+  try {
+    process.kill(pid, 'SIGTERM');
+  } catch {
+    // 竞态：刚好退出
+  }
+
+  const deadline = monotonicMs() + graceMs;
+  while (monotonicMs() < deadline && processAlive(pid)) {
+    // eslint-disable-next-line no-await-in-loop -- 等待退出
+    await sleep(100);
+  }
+  let forced = false;
+  if (processAlive(pid)) {
+    forced = true;
+    try {
+      process.kill(pid, 'SIGKILL');
+    } catch {
+      // 已退出
+    }
+    await sleep(200);
+  }
+  removeForeignPidfile(pid);
+  return { stopped: true, mode: check.info.mode, forced };
+}
+
+/** 目标进程已死时清掉它留下的 pidfile（removePidfileIfOwn 只管自己那份）。 */
+function removeForeignPidfile(pid) {
+  const info = readPidfile();
+  if (info?.pid === pid) {
+    try {
+      fs.rmSync(paths().pidfile, { force: true });
+    } catch {
+      // 忽略
+    }
+  }
+}
+
+// ── launchd（ENG-15） ────────────────────────────────────────────────────
+
+export function buildPlist({
+  logPath = paths().log, execPath = process.execPath, cliEntry = CLI_ENTRY, home = process.env.DSHC_HOME ?? null,
+} = {}) {
+  // 装服务时若当前用的是自定义 DSHC_HOME，必须一起写进 plist：
+  // 否则 launchd 起来的实例会去读默认 ~/.dsh_center，等于悄悄换了一份配置
+  const envEntries = [['DSHC_MODE', 'launchd']];
+  if (home) envEntries.push(['DSHC_HOME', home]);
+  const envXml = envEntries.map(([k, v]) => `<key>${k}</key><string>${v}</string>`).join('');
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>${LAUNCHD_LABEL}</string>
+  <key>ProgramArguments</key><array>
+    <string>${execPath}</string><string>${cliEntry}</string>
+    <string>up</string><string>--foreground</string>
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>ThrottleInterval</key><integer>10</integer>
+  <key>StandardOutPath</key><string>${logPath}</string>
+  <key>StandardErrorPath</key><string>${logPath}</string>
+  <key>EnvironmentVariables</key><dict>${envXml}</dict>
+</dict></plist>
+`;
+}
+
+function launchctl(args) {
+  return new Promise((resolve) => {
+    const child = spawn('launchctl', args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (c) => { stdout += c; });
+    child.stderr.on('data', (c) => { stderr += c; });
+    child.on('error', (err) => resolve({ code: null, stdout, stderr: String(err.message) }));
+    child.on('close', (code) => resolve({ code, stdout, stderr }));
+  });
+}
+
+const domain = () => `gui/${process.getuid?.() ?? 501}`;
+const serviceTarget = () => `${domain()}/${LAUNCHD_LABEL}`;
+
+/** install：先接管裸后台实例（02 §9.3 无缝接管）→ 写 plist → bootstrap。 */
+export async function serviceInstall() {
+  const p = paths();
+  const check = await aliveCheck();
+  if (check.alive && check.info?.mode !== 'launchd') await stopDaemon();
+
+  fs.mkdirSync(path.dirname(p.plist), { recursive: true });
+  fs.writeFileSync(p.plist, buildPlist());
+
+  await launchctl(['bootout', serviceTarget()]); // 幂等：已加载则先卸
+  const res = await launchctl(['bootstrap', domain(), p.plist]);
+  return { ok: res.code === 0, plist: p.plist, stderr: res.stderr.trim() || null };
+}
+
+export async function serviceUninstall({ keepPlist = false } = {}) {
+  const p = paths();
+  const res = await launchctl(['bootout', serviceTarget()]);
+  if (!keepPlist) {
+    try {
+      fs.rmSync(p.plist, { force: true });
+    } catch {
+      // 忽略
+    }
+  }
+  return { ok: res.code === 0 || /not find|no such/i.test(res.stderr), stderr: res.stderr.trim() || null };
+}
+
+/** launchctl print 解析 state/pid。 */
+export async function serviceStatus() {
+  const p = paths();
+  const installed = fs.existsSync(p.plist);
+  const res = await launchctl(['print', serviceTarget()]);
+  if (res.code !== 0) return { installed, loaded: false, state: null, pid: null };
+  const state = /^\s*state\s*=\s*(\S+)/m.exec(res.stdout)?.[1] ?? null;
+  const pid = Number(/^\s*pid\s*=\s*(\d+)/m.exec(res.stdout)?.[1] ?? NaN);
+  return { installed, loaded: true, state, pid: Number.isInteger(pid) ? pid : null };
+}

package/src/defaults.js

@@ -0,0 +1,89 @@
+/**
+ * 出厂默认表 —— 代码内唯一允许硬编码运行参数的位置（02 §3.0）。
+ * 运行期一切参数只认 ~/.dsh_center/config.json；本表仅用于首启预填与 setup 模式兜底。
+ */
+
+import os from 'node:os';
+import path from 'node:path';
+
+export const CONFIG_VERSION = 1;
+
+export const FACTORY_DEFAULTS = Object.freeze({
+  manager: Object.freeze({ port: 7788 }),
+  defaults: Object.freeze({
+    remoteWebPort: 8899,
+    localPortRange: Object.freeze([17701, 17799]),
+  }),
+  hostDefaults: Object.freeze({
+    local: false,
+    enabled: true,
+    autoStart: false,
+    localPort: null,
+    remoteWebPort: null,
+    // null = 不注入 cd，远端 dsh 以 sshd 给的初始目录（$HOME）启动
+    workdir: null,
+    inject: Object.freeze({
+      env: Object.freeze({}),
+      extraArgs: Object.freeze([]),
+      patches: Object.freeze([]),
+    }),
+  }),
+});
+
+/** 深拷贝一份可写的主机默认配置（FACTORY_DEFAULTS 全冻结，不能直接塞进草稿）。 */
+export function newHostConfig() {
+  return {
+    local: FACTORY_DEFAULTS.hostDefaults.local,
+    enabled: FACTORY_DEFAULTS.hostDefaults.enabled,
+    autoStart: FACTORY_DEFAULTS.hostDefaults.autoStart,
+    localPort: FACTORY_DEFAULTS.hostDefaults.localPort,
+    remoteWebPort: FACTORY_DEFAULTS.hostDefaults.remoteWebPort,
+    workdir: FACTORY_DEFAULTS.hostDefaults.workdir,
+    inject: { env: {}, extraArgs: [], patches: [] },
+  };
+}
+
+/** 出厂 config 骨架（setup 未完成状态）。 */
+export function newFactoryConfig() {
+  return {
+    configVersion: CONFIG_VERSION,
+    setupCompleted: false,
+    manager: { port: FACTORY_DEFAULTS.manager.port },
+    defaults: {
+      remoteWebPort: FACTORY_DEFAULTS.defaults.remoteWebPort,
+      localPortRange: [...FACTORY_DEFAULTS.defaults.localPortRange],
+    },
+    hosts: {},
+  };
+}
+
+/**
+ * 全部持久化路径。DSHC_HOME 环境变量可整体重定向（集成测试隔离用，见 14 §2）。
+ */
+export function resolvePaths(env = process.env, homedir = os.homedir()) {
+  const dir = env.DSHC_HOME ? path.resolve(env.DSHC_HOME) : path.join(homedir, '.dsh_center');
+  return Object.freeze({
+    dir,
+    config: path.join(dir, 'config.json'),
+    state: path.join(dir, 'state.json'),
+    pidfile: path.join(dir, 'manager.pid'),
+    log: path.join(dir, 'manager.log'),
+    plist: path.join(homedir, 'Library', 'LaunchAgents', 'com.dsh-center.manager.plist'),
+  });
+}
+
+export const PATHS = resolvePaths();
+
+export const LAUNCHD_LABEL = 'com.dsh-center.manager';
+
+/** 远端落地目录（03 §1），相对远端 $HOME。 */
+export const REMOTE_DIR = '.dsh_center_remote';
+
+/**
+ * 「对每台各来一次 ssh」这类扇出的同时在飞上限（issue #85）。
+ *
+ * 取 6 是照着 sshd 的出厂 `MaxStartups 10:30:100` 来的：未完成认证的连接过 10 条就开始
+ * 被随机丢，而多台远端共用一台跳板机时这个额度是合起来算的。留 4 条余量给用户自己的
+ * ssh 会话与隧道重连。这不是用户可调项，故只在出厂表里，不进 config schema。
+ */
+export const SSH_FANOUT_LIMIT = 6;