@shendeguize/remote-dsh-center 0.4.0

package/src/patchsync.js

@@ -0,0 +1,310 @@
+/**
+ * patch 同步器（12 §4）。
+ *
+ * 落在业务层而非 src/lib/：它依赖 lib/ssh + lib/proto 两个叶子，放进 lib/ 会破坏
+ * 「lib 之间只允许 proto → shq 一条边」的防环规则（11 §1.3）。RMT-07 允许并入
+ * launcher.js，此处单独成文件只为可单测。
+ */
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { DshError } from './lib/errors.js';
+import { buildPatchCleanupScript, kvOne, parseProtoOutput } from './lib/proto.js';
+import {
+  execFailure,
+  localCopy,
+  prepareLocalCopyTarget,
+  scpTo,
+  sshExec,
+} from './lib/ssh.js';
+import { REMOTE_DIR } from './defaults.js';
+
+const HASH_PREFIX_LEN = 12;
+const LOCAL_NAME_ATTEMPT_LIMIT = 256;
+
+/** SHA-256；流式读文件，不整读内存。 */
+function digestFile(file) {
+  return new Promise((resolve, reject) => {
+    const hash = crypto.createHash('sha256');
+    const stream = fs.createReadStream(file);
+    stream.on('error', reject);
+    stream.on('data', (chunk) => hash.update(chunk));
+    stream.on('end', () => resolve(hash.digest('hex')));
+  });
+}
+
+/** SHA-256 前 12 位 hex。 */
+export async function hashFile(file) {
+  return (await digestFile(file)).slice(0, HASH_PREFIX_LEN);
+}
+
+/** 本地 basename → 远端安全名片段（12 §4.2）。 */
+export function safeBase(localPath) {
+  let base = path.basename(localPath).replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 64);
+  base = base.replace(/^[-.]+/, '');
+  return base === '' ? 'patch' : base;
+}
+
+/** 内容变则名变，天然免疫「本地改了远端还是旧的」。 */
+export function remoteName(hash, localPath) {
+  return `${hash}-${safeBase(localPath)}`;
+}
+
+/**
+ * 建立本次清单。任一文件不可读即快败（patch 缺失会静默改变 dsh 行为，宁可失败）。
+ * @param {string[]} patches 本地绝对路径
+ * @returns {Promise<{localPath:string, hash:string, contentHash:string,
+ *   size:number, remoteName:string}[]>}
+ */
+export async function buildManifest(patches) {
+  const manifest = [];
+  for (const localPath of patches) {
+    let stat;
+    try {
+      fs.accessSync(localPath, fs.constants.R_OK);
+      stat = fs.statSync(localPath);
+      if (!stat.isFile()) throw new Error('不是普通文件');
+    } catch (err) {
+      throw new DshError('VALIDATION', `patch 文件不可读：${localPath}`, { detail: String(err.message ?? err) });
+    }
+    // eslint-disable-next-line no-await-in-loop -- 顺序读文件，避免同时开大量句柄
+    const contentHash = await digestFile(localPath);
+    const hash = contentHash.slice(0, HASH_PREFIX_LEN);
+    manifest.push({
+      localPath,
+      hash,
+      contentHash,
+      size: stat.size,
+      remoteName: remoteName(hash, localPath),
+    });
+  }
+  return manifest;
+}
+
+function localTargetIdentity(target) {
+  const lexical = path.resolve(target);
+  try {
+    fs.lstatSync(lexical);
+  } catch (err) {
+    if (err?.code === 'ENOENT') return { lexical, real: lexical, exists: false };
+    throw new DshError('LOCAL_COPY_FAILED', '本机 patch 目标路径不可访问', {
+      detail: `路径：${target}\n${String(err.message ?? err)}`,
+      cause: err instanceof Error ? err : undefined,
+    });
+  }
+
+  try {
+    return { lexical, real: fs.realpathSync(lexical), exists: true };
+  } catch {
+    // dangling symlink / 无权读取的既有项也算占用；不能把它当成空位覆盖。
+    return { lexical, real: null, exists: true };
+  }
+}
+
+async function inspectLocalTarget(remoteName) {
+  const rel = `${REMOTE_DIR}/patches/${remoteName}`;
+  const { target } = await prepareLocalCopyTarget(rel);
+  return { rel, ...localTargetIdentity(target) };
+}
+
+function identityKeys(identity) {
+  return [...new Set([identity.lexical, identity.real].filter(Boolean))];
+}
+
+function sourceIdentity(item) {
+  try {
+    const lexical = path.resolve(item.localPath);
+    const real = fs.realpathSync(item.localPath);
+    const key = crypto
+      .createHash('sha256')
+      .update(lexical)
+      .update('\0')
+      .update(real)
+      .digest('hex')
+      .slice(0, 16);
+    return { lexical, real, key };
+  } catch (err) {
+    throw new DshError('VALIDATION', `patch 文件真实路径不可读：${item.localPath}`, {
+      detail: String(err.message ?? err),
+      cause: err instanceof Error ? err : undefined,
+    });
+  }
+}
+
+function alternateLocalName(item, sourceKey, attempt) {
+  const contentKey = item.contentHash.slice(0, 16);
+  const ordinal = attempt === 0 ? '' : `-${attempt}`;
+  return `${contentKey}-local-${sourceKey}${ordinal}-${safeBase(item.localPath)}`;
+}
+
+async function localTargetHasContent(target, item) {
+  if (!target.exists || target.real === null) return false;
+  try {
+    const stat = fs.statSync(target.lexical);
+    if (!stat.isFile() || stat.size !== item.size) return false;
+    return await digestFile(target.lexical) === item.contentHash;
+  } catch {
+    // 无法证明内容相同就必须避让，不能覆盖未知既有项。
+    return false;
+  }
+}
+
+function reservationFor(target, reservations, contentHash) {
+  const claims = identityKeys(target)
+    .map((key) => reservations.get(key))
+    .filter(Boolean);
+  return {
+    conflict: claims.some((claim) => claim !== contentHash),
+    matching: claims.some((claim) => claim === contentHash),
+  };
+}
+
+function reserveTarget(target, reservations, contentHash) {
+  for (const key of identityKeys(target)) reservations.set(key, contentHash);
+}
+
+function noSafeLocalTarget(item) {
+  const sourceKey = crypto
+    .createHash('sha256')
+    .update(path.resolve(item.localPath))
+    .digest('hex')
+    .slice(0, HASH_PREFIX_LEN);
+  return new DshError('LOCAL_COPY_FAILED', '本机 patch 找不到不会覆盖既有文件的安全目标', {
+    detail: `源：${item.localPath}\n已检查初始目标与 ${LOCAL_NAME_ATTEMPT_LIMIT} 个稳定候选（源摘要 ${sourceKey}）`,
+  });
+}
+
+/**
+ * 本机源与生成物共用 patches/ 命名空间。既有目标只有在与当前源是同一真实文件、
+ * 或逐内容摘要相等时才可复用；否则依次尝试由内容+源身份摘要生成的稳定安全名。
+ * 整个计划完成前不复制任何文件，故不会因执行顺序覆盖后续源。
+ */
+async function planLocalManifest(manifest) {
+  const sources = manifest.map(sourceIdentity);
+  const reservations = new Map();
+  const planned = [];
+
+  for (let index = 0; index < manifest.length; index += 1) {
+    const item = manifest[index];
+    const source = sources[index];
+    let selected = null;
+
+    for (let attempt = -1; attempt < LOCAL_NAME_ATTEMPT_LIMIT; attempt += 1) {
+      const selectedName = attempt < 0
+        ? item.remoteName
+        : alternateLocalName(item, source.key, attempt);
+      // eslint-disable-next-line no-await-in-loop -- 候选必须逐个查真实路径与内容，且循环有硬上限
+      const target = await inspectLocalTarget(selectedName);
+      const reservation = reservationFor(target, reservations, item.contentHash);
+      if (reservation.conflict) continue;
+
+      if (target.exists) {
+        const sameSource = target.real !== null && target.real === source.real;
+        // eslint-disable-next-line no-await-in-loop -- 已存在候选必须先证明内容相同，绝不盲目覆盖
+        if (!sameSource && !(await localTargetHasContent(target, item))) continue;
+        selected = { ...item, remoteName: selectedName, copyNeeded: false };
+      } else {
+        selected = {
+          ...item,
+          remoteName: selectedName,
+          copyNeeded: !reservation.matching,
+        };
+      }
+
+      reserveTarget(target, reservations, item.contentHash);
+      break;
+    }
+
+    if (selected === null) throw noSafeLocalTarget(item);
+    planned.push(selected);
+  }
+  return planned;
+}
+
+/**
+ * 同步流程（12 §4.3）：清单 → 远端清理协议（本机永久跳过）→ 只传 hash 变更文件 →
+ * 返回新的 patchSync 记录与 PATCH_ARGS 用的目标名清单（按 manifest 顺序）。
+ *
+ * 本机 patches/ 与用户文件共用命名空间，无法可靠区分旧生成物和用户源，所以只由
+ * localCopy 原子覆盖当前目标，绝不主动删除目录内其他文件；远端仍先清理旧目标。
+ *
+ * @param {string} host
+ * @param {string[]} patches
+ * @param {{files:Record<string,{hash:string,remoteName:string,syncedAt:string|null}>}} previous
+ * @param {{signal?:AbortSignal, local?:boolean}} [opts]
+ */
+export async function syncPatches(
+  host,
+  patches,
+  previous = { files: {} },
+  { signal, local = false } = {},
+) {
+  const baseManifest = await buildManifest(patches);
+  const manifest = local ? await planLocalManifest(baseManifest) : baseManifest;
+  const keepNames = manifest.map((m) => m.remoteName);
+
+  if (!local) {
+    // 远端清理先行：删除旧 hash 与已移除项，并兼职保证目录存在。
+    const cleanup = buildPatchCleanupScript({ keepNames });
+    const cleanRes = await sshExec(host, cleanup, { signal });
+    const cleanErr = execFailure(host, 'patch 目录清理', cleanRes);
+    if (cleanErr) throw cleanErr;
+    const cleanOut = parseProtoOutput(cleanRes.stdout, { requireDone: 'CLEAN_DONE' });
+    if (kvOne(cleanOut, 'ERR') === 'mkdir') {
+      throw new DshError('INTERNAL', `远端无法创建 patch 目录（${host}）`, {
+        host,
+        detail: cleanRes.stdout,
+      });
+    }
+  }
+
+  const files = {};
+  let uploaded = 0;
+  let skipped = 0;
+
+  for (const item of manifest) {
+    const prior = previous?.files?.[item.localPath];
+    if (local && !item.copyNeeded) {
+      const samePrior = prior
+        && prior.hash === item.hash
+        && prior.remoteName === item.remoteName
+        && prior.syncedAt;
+      files[item.localPath] = samePrior
+        ? { ...prior, remoteName: item.remoteName }
+        : {
+          hash: item.hash,
+          remoteName: item.remoteName,
+          syncedAt: new Date().toISOString(),
+        };
+      skipped += 1;
+      continue;
+    }
+    if (
+      prior
+      && prior.hash === item.hash
+      && !local
+      && prior.syncedAt
+    ) {
+      files[item.localPath] = { ...prior, remoteName: item.remoteName };
+      skipped += 1;
+      continue;
+    }
+    const rel = `${REMOTE_DIR}/patches/${item.remoteName}`;
+    // eslint-disable-next-line no-await-in-loop -- 逐文件上载，失败即整体快败
+    const res = local
+      ? await localCopy(item.localPath, rel, { signal })
+      : await scpTo(host, item.localPath, rel, { signal });
+    const err = execFailure(host, `patch 上载 ${path.basename(item.localPath)}`, res);
+    if (err) throw err;
+    files[item.localPath] = {
+      hash: item.hash,
+      remoteName: item.remoteName,
+      syncedAt: new Date().toISOString(),
+    };
+    uploaded += 1;
+  }
+
+  return { patchSync: { files }, remoteNames: keepNames, uploaded, skipped };
+}

package/src/ports.js

@@ -0,0 +1,93 @@
+/**
+ * 本机映射端口分配（02 §6）：区间内取第一个「config 未占用 ∧ 本机未监听」的端口。
+ * 分配即回写 config.hosts[x].localPort，此后固定——保证 iframe 地址与浏览器书签稳定。
+ */
+
+import net from 'node:net';
+
+import { DshError } from './lib/errors.js';
+import * as store from './store.js';
+
+/** 试绑探测。单测可经 _setProbe 注入假实现。 */
+const DEFAULT_PROBE = (port) => new Promise((resolve) => {
+  const srv = net.createServer();
+  srv.once('error', () => resolve(false));
+  srv.once('listening', () => srv.close(() => resolve(true)));
+  srv.listen(port, '127.0.0.1');
+});
+
+let probeFree = DEFAULT_PROBE;
+
+export function isFree(port) {
+  return probeFree(port);
+}
+
+/** 测试注入点；传 null/undefined 复位为真实试绑。 */
+export function _setProbe(fn) {
+  probeFree = typeof fn === 'function' ? fn : DEFAULT_PROBE;
+}
+
+/**
+ * 分配闸（issue #94）。
+ *
+ * 一次分配是「读 config 算已占用 → await 试绑 → 回写 config」：读在 await 之前、
+ * 写在之后。两台同时进来，两边看到的都是同一份旧账，于是分到同一个号。而 localPort
+ * 是分配即回写、此后固定的（iframe 地址和书签要稳），撞号会被**永久**写进 config——
+ * 后面那几台的隧道每次都撞 `bind: Address already in use`，被判成 local-port-busy 挂起，
+ * 提示还让用户去找「占端口的进程」，可占号的正是 manager 自己的另一条隧道。重启修不回来。
+ *
+ * 跑得到这条路的是 `runAutoStart`/`recoverState`：它们走 mapPool，一次 6 台在飞，
+ * 而全新安装的那几台恰好都还没有 localPort。
+ * @type {Promise<unknown>}
+ */
+let allocChain = Promise.resolve();
+
+/**
+ * localPort 决策。config 已有 → 直接返回；否则区间内分配并回写（整段串行）。
+ * @param {string} name
+ * @returns {Promise<number>}
+ * @throws {DshError} PORT_EXHAUSTED
+ */
+export async function ensureLocalPort(name) {
+  const host = store.getConfig().hosts[name];
+  if (!host) throw new DshError('NOT_FOUND', `未知主机：${name}`, { host: name });
+  if (host.localPort !== null && host.localPort !== undefined) return host.localPort;
+
+  // 前序成败都不阻断后续（与 hostQueue 同一套写法）
+  const run = () => allocate(name);
+  const p = allocChain.then(run, run);
+  allocChain = p.then(() => {}, () => {});
+  return p;
+}
+
+/** 闸内执行：从这里到回写之间没有别的分配能插进来。 */
+async function allocate(name) {
+  const config = store.getConfig();
+  const host = config.hosts[name];
+  // 排队期间主机可能被删掉，也可能已由并发的同名请求分到了号——两样都要重查
+  if (!host) throw new DshError('NOT_FOUND', `未知主机：${name}`, { host: name });
+  if (host.localPort !== null && host.localPort !== undefined) return host.localPort;
+
+  const [lo, hi] = config.defaults.localPortRange;
+  const taken = new Set(
+    Object.values(config.hosts)
+      .map((h) => h.localPort)
+      .filter((p) => Number.isInteger(p)),
+  );
+
+  for (let p = lo; p <= hi; p += 1) {
+    if (taken.has(p)) continue;
+    // eslint-disable-next-line no-await-in-loop -- 顺序探测才能取「第一个」可用端口
+    if (!(await isFree(p))) continue;
+    store.updateConfig((draft) => {
+      draft.hosts[name].localPort = p;
+    });
+    return p;
+  }
+
+  throw new DshError(
+    'PORT_EXHAUSTED',
+    `本机映射端口区间 ${lo}-${hi} 已耗尽，无法为 ${name} 分配`,
+    { host: name, detail: `已占用：${[...taken].sort((a, b) => a - b).join(', ')}` },
+  );
+}

package/src/prober.js

@@ -0,0 +1,185 @@
+/**
+ * 并行探测（03 §2 / 12 §1.1 协议），驱动 phase: unknown → ready/no_dsh/unreachable。
+ */
+
+import { logEvent } from './lib/bus.js';
+import { buildProbeScript, kvOne, parseProtoOutput } from './lib/proto.js';
+import { hostQueue, localExec, sshExec } from './lib/ssh.js';
+import { PROBE_PROTECTED_PHASES } from './lib/machine.js';
+import { asDshError } from './lib/errors.js';
+import { mapPool } from './lib/pool.js';
+import { SSH_FANOUT_LIMIT } from './defaults.js';
+import * as store from './store.js';
+
+/**
+ * @typedef {{ok:boolean, phase:'ready'|'no_dsh'|'unreachable', dshPath:string|null,
+ *   version:string|null, dshHome:string|null, profileWeb:boolean, runningRaw:string,
+ *   noDshReason:'missing-bin'|'no-web-profile'|null, stderr:string,
+ *   manualInstances:{pid:number,args:string}[]}} ProbeResult
+ */
+
+/** `ps -eo pid,args` 行 → {pid, args}。 */
+export function parseRunningBlock(raw) {
+  const out = [];
+  for (const line of String(raw ?? '').split('\n')) {
+    const m = /^\s*(\d+)\s+(.*\S)\s*$/.exec(line);
+    if (!m) continue;
+    out.push({ pid: Number(m[1]), args: m[2] });
+  }
+  return out;
+}
+
+/**
+ * 把探测 stdout 解析为 ProbeResult（纯函数，喂样本即可单测）。
+ * @param {{code:number|null, stdout:string, stderr:string, timedOut:boolean, aborted:boolean}} res
+ * @param {{local?:boolean}} [opts]
+ * @returns {ProbeResult}
+ */
+export function interpretProbe(res, { local = false } = {}) {
+  const rawStderr = res.stderr ?? '';
+  let failureStderr = rawStderr;
+  if (local) {
+    const summary = res.timedOut
+      ? '本机探测超时'
+      : res.aborted
+        ? '本机探测被中止'
+        : `本机探测命令执行失败（退出码 ${res.code ?? '未知'}）`;
+    failureStderr = rawStderr ? `${summary}\n${rawStderr}` : summary;
+  }
+  const base = {
+    ok: false,
+    phase: 'unreachable',
+    dshPath: null,
+    version: null,
+    dshHome: null,
+    profileWeb: false,
+    runningRaw: '',
+    noDshReason: null,
+    stderr: failureStderr,
+    manualInstances: [],
+  };
+
+  if (res.timedOut || res.aborted || res.code !== 0) return base;
+
+  let out;
+  try {
+    out = parseProtoOutput(res.stdout, { requireDone: 'PROBE_DONE' });
+  } catch (err) {
+    // 协议输出不可解析：不是「连不上」，但也无法判定 dsh 状态 → 按 unreachable 呈现并留证
+    const detail = err.detail ?? err.message;
+    return { ...base, stderr: local ? `本机探测输出无法解析：${detail}` : detail };
+  }
+
+  const bin = kvOne(out, 'DSH_BIN');
+  const runningRaw = out.blocks.RUNNING_DSH_WEB ?? '';
+  const manualInstances = parseRunningBlock(runningRaw);
+  const dshHome = kvOne(out, 'DSH_HOME');
+  const profileWeb = kvOne(out, 'PROFILE_WEB') === 'yes';
+
+  if (!bin || bin === 'MISSING') {
+    return {
+      ...base,
+      phase: 'no_dsh',
+      noDshReason: 'missing-bin',
+      dshHome,
+      runningRaw,
+      manualInstances,
+      stderr: '',
+    };
+  }
+
+  const common = {
+    ok: true,
+    dshPath: bin,
+    version: kvOne(out, 'DSH_VERSION') || null,
+    dshHome,
+    profileWeb,
+    runningRaw,
+    manualInstances,
+    stderr: '',
+  };
+
+  if (!profileWeb) {
+    return { ...base, ...common, ok: false, phase: 'no_dsh', noDshReason: 'no-web-profile' };
+  }
+  return { ...base, ...common, phase: 'ready' };
+}
+
+/**
+ * 纯探测（不写 state）。dshc init 第 3 步复用（setup 时 server 尚不存在，
+ * 「操作收敛到 server」的前提不成立，见 11 §1.3 例外条款）。
+ * @returns {Promise<ProbeResult>}
+ */
+export async function probeOnce(host, { local = false, timeoutMs, signal } = {}) {
+  const command = buildProbeScript();
+  const res = local
+    ? await localExec(command, { timeoutMs, signal })
+    : await sshExec(host, command, { timeoutMs, signal });
+  return interpretProbe(res, { local });
+}
+
+/** 单行 stderr 摘要（长文本不进环形缓冲，11 §7.2）。 */
+function summarize(stderr) {
+  const line = String(stderr ?? '')
+    .split('\n')
+    .map((l) => l.trim())
+    .find((l) => l !== '');
+  if (!line) return null;
+  return line.length > 200 ? `${line.slice(0, 197)}…` : line;
+}
+
+/** 队列内探测并应用：probeOnce → setPhase(3 分类) + state.probe + manualInstances 并入。 */
+export async function probeHost(name) {
+  return hostQueue(name).run('probe', async (signal) => {
+    // 队首才重取 HostView：排队期间 reload 可能已换了配置快照，运输类型只认当前 config。
+    const local = store.getHostView(name)?.local === true;
+    const result = await probeOnce(name, { local, signal });
+    applyProbe(name, result);
+    return result;
+  });
+}
+
+/**
+ * 结果应用。starting/running/degraded 期间禁止探测改写 phase——只刷新 manualInstances
+ * 与 probe 详情（11 §2.2）。
+ */
+export function applyProbe(name, result) {
+  const phaseNow = store.getPhase(name);
+  const protectedPhase = PROBE_PROTECTED_PHASES.includes(phaseNow);
+
+  const managedPid = store.getHostState(name)?.web?.pid ?? null;
+  const manual = result.manualInstances.filter((i) => i.pid !== managedPid);
+
+  store.mutateHostState(name, (entry) => {
+    entry.probe = {
+      dshPath: result.dshPath,
+      version: result.version,
+      dshHome: result.dshHome,
+      profileWeb: result.profileWeb,
+      noDshReason: result.noDshReason,
+      at: new Date().toISOString(),
+      errorSummary: result.phase === 'unreachable' ? summarize(result.stderr) : null,
+    };
+    entry.manualInstances = manual;
+  });
+
+  if (!protectedPhase) {
+    store.setPhase(name, result.phase, 'prober.probeHost');
+  }
+  return result;
+}
+
+/**
+ * 并行触发全量/指定探测，立即返回（202 语义）；结果经 SSE。
+ * @param {string[]|null} names
+ * @returns {Promise<PromiseSettledResult<any>[]>} 供 server 启动序列 await
+ */
+export function probeAll(names = null) {
+  const targets = names ?? store.listHostNames();
+  // 有闸：主机一多，无闸的扇出会把共用跳板机的 MaxStartups 打爆（issue #85）
+  return mapPool(targets, (name) => probeHost(name).catch((err) => {
+    const e = asDshError(err);
+    logEvent(name, 'warn', `探测失败：${e.message}`, e.detail);
+    throw e;
+  }), SSH_FANOUT_LIMIT);
+}