dsh-config-manager 0.1.85 → 0.2.0

package/src/utils/workdir-lock.test.ts

@@ -15,8 +15,10 @@ import path from 'node:path';
 import {
   DEFAULT_WORKDIR_LOCK_STALE_MS,
   WorkdirLockError,
+  pruneDeadWorkdirLocksOnce,
   resetWorkdirLockChainsForTest,
   withWorkdirLock,
+  workdirLockHolderAlive,
   workdirLockPath,
 } from './workdir-lock.ts';
 
@@ -65,8 +67,9 @@ test('不同工作副本：互不阻塞（锁按目录隔离）', async (t) => {
 
 test('等锁超时：别人持有锁且未过期 → 抛 WorkdirLockError（而不是无限等待）', async (t) => {
   const dir = await makeDir(t);
-  // 模拟另一个进程正在持有锁（文件已存在、mtime 新鲜 → 不会被当成陈旧锁回收）
-  await fs.writeFile(workdirLockPath(dir), JSON.stringify({ pid: 999999, token: 'other-process' }));
+  // 模拟另一个**仍然存活**的进程持有锁（mtime 新鲜、pid 存在 ⇒ 两条回收路径都不该触发）。
+  // 必须用真实存活 pid：死 pid 的锁现在会立即回收（见下一条用例），不再进入等待。
+  await fs.writeFile(workdirLockPath(dir), JSON.stringify({ pid: process.pid, token: 'other-process' }));
   await assert.rejects(
     withWorkdirLock(dir, async () => 'never', { timeoutMs: 30, sleep: fastSleep }),
     (err: unknown) => {
@@ -79,22 +82,92 @@ test('等锁超时：别人持有锁且未过期 → 抛 WorkdirLockError（而
   await fs.access(workdirLockPath(dir));
 });
 
-test('陈旧锁回收：holder 崩溃留下的锁（超过 stale 阈值）→ 自动接管', async (t) => {
+test('holder pid 已死：立即回收锁，不等 staleMs（DSH 重启/崩溃现场，2026-10-27）', async (t) => {
   const dir = await makeDir(t);
   const lockPath = workdirLockPath(dir);
-  await fs.writeFile(lockPath, JSON.stringify({ pid: 999999, token: 'dead' }));
+  // 取一个必然不存在的 pid，并先证明判定本身是对的，免得把环境差异伪装成通过
+  const deadPid = 4_000_000;
+  assert.equal(workdirLockHolderAlive(deadPid), false, '前提：该 pid 必须不存在（否则本用例无意义）');
+  await fs.writeFile(lockPath, JSON.stringify({ pid: deadPid, token: 'dead-holder' }));
+  const t0 = Date.now();
+  assert.equal(await withWorkdirLock(dir, async () => 'ok'), 'ok');
+  assert.ok(Date.now() - t0 < 500, '死 holder 的锁必须立即回收，绝不能等到 staleMs（15 分钟）');
+  await assert.rejects(fs.access(lockPath), '释放后锁文件必须消失');
+});
+
+test('陈旧锁回收：holder 仍存活但锁文件超过 stale 阈值 → 自动接管', async (t) => {
+  const dir = await makeDir(t);
+  const lockPath = workdirLockPath(dir);
+  // pid 存活 ⇒ pid 路径不回收，只能走 mtime 兜底（覆盖 holder 卡死、永远不释放 finally 的情形）
+  await fs.writeFile(lockPath, JSON.stringify({ pid: process.pid, token: 'hung-holder' }));
   const stale = new Date(Date.now() - DEFAULT_WORKDIR_LOCK_STALE_MS - 60_000);
   await fs.utimes(lockPath, stale, stale);
   assert.equal(await withWorkdirLock(dir, async () => 'ok'), 'ok');
   await assert.rejects(fs.access(lockPath), '释放后锁文件必须消失');
 });
 
+test('读不出的 holder 一律退回 mtime 规则：新鲜锁仍须等待，不得盲抢', async (t) => {
+  const dir = await makeDir(t);
+  const lockPath = workdirLockPath(dir);
+  await fs.writeFile(lockPath, 'not-json'); // 半写入/旧格式：判不了 holder 是否存活
+  await assert.rejects(
+    withWorkdirLock(dir, async () => 'never', { timeoutMs: 30, sleep: fastSleep }),
+    (err: unknown) => err instanceof WorkdirLockError,
+  );
+  await fs.access(lockPath);
+});
+
+test('链上排队也计入超时：排在长任务后面的调用按时失败，且绝不执行 fn', async (t) => {
+  const dir = await makeDir(t);
+  const slow = withWorkdirLock(dir, async () => {
+    await new Promise((r) => setTimeout(r, 400));
+    return 'slow';
+  });
+  let quickRan = false;
+  const t0 = Date.now();
+  await assert.rejects(
+    withWorkdirLock(dir, async () => { quickRan = true; return 'quick'; }, { timeoutMs: 60 }),
+    (err: unknown) => err instanceof WorkdirLockError,
+  );
+  const elapsed = Date.now() - t0;
+  assert.ok(elapsed < 350, '排队到上限就必须失败，不能等前一个长任务跑完（实测 ' + String(elapsed) + 'ms）');
+  assert.equal(quickRan, false, '已超时放弃的调用绝不允许随后仍去驱动工作副本');
+  assert.equal(await slow, 'slow');
+});
+
 test('异常也释放锁：fn 抛错后下一次仍能拿到锁（不会把后续同步永久卡死）', async (t) => {
   const dir = await makeDir(t);
   await assert.rejects(withWorkdirLock(dir, async () => { throw new Error('boom'); }), /boom/);
   assert.equal(await withWorkdirLock(dir, async () => 'ok'), 'ok');
 });
 
+test('一次性清扫：holder 已死的残留锁被删，活锁与读不出的锁一律保留', async (t) => {
+  const dir = await makeDir(t); // 顺便重置一次性清扫标记
+  const suffix = String(Date.now()) + String(Math.random()).slice(2, 8);
+  const deadPath = path.join(os.tmpdir(), 'dshcm-workdir-' + suffix + 'a.lock');
+  const alivePath = path.join(os.tmpdir(), 'dshcm-workdir-' + suffix + 'b.lock');
+  const opaquePath = path.join(os.tmpdir(), 'dshcm-workdir-' + suffix + 'c.lock');
+  // pid 复用陷阱：pid 现在还活着，但它声明的工作目录早已不存在、锁也过了 staleMs
+  const reusedPath = path.join(os.tmpdir(), 'dshcm-workdir-' + suffix + 'd.lock');
+  const goneDir = path.join(os.tmpdir(), 'dshcm-gone-' + suffix);
+  await fs.writeFile(deadPath, JSON.stringify({ pid: 4_000_000, token: 'dead', workDir: dir }));
+  await fs.writeFile(alivePath, JSON.stringify({ pid: process.pid, token: 'alive', workDir: dir }));
+  await fs.writeFile(opaquePath, 'not-json');
+  await fs.writeFile(reusedPath, JSON.stringify({ pid: process.pid, token: 'reused', workDir: goneDir }));
+  const old = new Date(Date.now() - DEFAULT_WORKDIR_LOCK_STALE_MS - 60_000);
+  await fs.utimes(reusedPath, old, old);
+  t.after(async () => {
+    await Promise.all([deadPath, alivePath, opaquePath, reusedPath].map((f) => fs.rm(f, { force: true })));
+  });
+
+  await pruneDeadWorkdirLocksOnce();
+
+  await assert.rejects(fs.access(deadPath), 'holder 已死的残留锁必须被清掉');
+  await fs.access(alivePath); // 活锁 + 工作目录还在 ⇒ 动不得
+  await fs.access(opaquePath); // 读不出 holder ⇒ 保守保留
+  await assert.rejects(fs.access(reusedPath), '工作目录已消失且过了 staleMs ⇒ pid 复用造成的僵尸锁应清掉');
+});
+
 test('锁按绝对路径归一：同一目录的不同写法共享一把锁', async (t) => {
   const dir = await makeDir(t);
   let active = 0;

package/src/utils/workdir-lock.ts

@@ -19,7 +19,10 @@
  *  - 锁文件放 `os.tmpdir()`（按工作目录绝对路径哈希命名），**不写进工作副本**：
  *    工作副本还没 clone 出来也能先锁住，且绝不让 `git status` 看到脏文件；
  *  - 跨进程独占用 `open(path,'wx')`（O_EXCL，原子）；等待方轮询，超时抛 WorkdirLockError；
- *  - holder 崩溃留下的陈旧锁按 mtime 回收（超过 staleMs 才回收，避免误抢仍在跑的长时间任务）；
+ *  - holder 崩溃留下的陈旧锁：先问 holder pid 是否还存在（ESRCH ⇒ 已被杀，立即回收），
+ *    读不出 pid 或进程仍存活时才按 mtime 超过 staleMs 回收（避免误抢仍在跑的长时间任务）；
+ *  - 等待方是**有界**的：等文件锁与进程内链上排队共用同一个 timeoutMs 上限，超时即抛，
+ *    绝不在界面早已放弃之后仍去驱动工作副本；
  *  - 进程内再串一条 Promise 链：同进程两个 GitTransport 实例（autosync / 路由）共用同一条链，
  *    不依赖文件锁的轮询延迟。
  */
@@ -75,6 +78,91 @@ export function workdirLockPath(workDir: string): string {
   return path.join(os.tmpdir(), `dshcm-workdir-${workdirLockKey(workDir)}.lock`);
 }
 
+/**
+ * holder 进程是否还活着（三态：true = 存活、false = 确定已死、null = 判不了）。
+ *
+ * 为什么必须问：holder 被强杀时（DSH 重启 / 崩溃 / 任务管理器结束进程）`finally` 不会执行，
+ * 锁文件就留在 tmpdir 里；只按 mtime 判定要等满 staleMs（15 分钟）才接管。这段窗口里**所有**
+ * 同步与只读自检都排在锁上 —— 真机 2026-10-27：DSH 重启踩在一次 push 中间，pid 28888 的锁留在
+ * %TEMP%，之后每次打开同步页 `GET /sync/status` 都要等满 10 s 预算再 503。
+ *
+ * 误差方向：只有 `ESRCH`（pid 完全不存在）才判死；`EPERM`（进程存在但无权发信号，如 Linux 跨用户）
+ * 判活；pid 复用也会把「别人的锁」判成活 —— 两种误判都偏向保守（最多退化成 mtime 规则），
+ * 绝不会把仍在跑的 holder 的锁抢走。
+ */
+export function workdirLockHolderAlive(pid: unknown): boolean | null {
+  if (typeof pid !== 'number' || !Number.isInteger(pid) || pid <= 0) return null;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    const code = (err as { code?: string }).code;
+    if (code === 'ESRCH') return false;
+    if (code === 'EPERM') return true;
+    return null;
+  }
+}
+
+/** 读锁文件里记录的 holder（读不出 / 半写入 / 不是对象 ⇒ null，一律退回 mtime 规则） */
+async function readLockHolder(lockPath: string): Promise<{ pid: unknown; workDir: unknown } | null> {
+  try {
+    const parsed: unknown = JSON.parse(await fs.readFile(lockPath, 'utf8'));
+    if (parsed === null || typeof parsed !== 'object') return null;
+    const holder = parsed as { pid?: unknown; workDir?: unknown };
+    return { pid: holder.pid, workDir: holder.workDir };
+  } catch {
+    return null;
+  }
+}
+
+const LOCK_FILE_PREFIX = 'dshcm-workdir-';
+let pruneScheduled = false;
+
+/**
+ * 一次性清扫本机所有「holder 已死」的工作副本锁（每进程只跑一次）。
+ *
+ * 为什么需要：pid 回收只在**自己被这把锁挡住时**生效，而残留锁可能属于早已不再使用的工作目录
+ * （换过仓库、换过数据目录、临时实例）—— 它们永远不会再被查询，却一直躺在 %TEMP%（真机 2026-10-27
+ * 见到 8 个，最久 3.4 天）。只删 pid 确定不存在的锁：读不出 holder 的不动（保守，宁可留下）。
+ */
+export async function pruneDeadWorkdirLocksOnce(): Promise<void> {
+  if (pruneScheduled) return;
+  pruneScheduled = true;
+  const dir = os.tmpdir();
+  let names: string[];
+  try {
+    names = await fs.readdir(dir);
+  } catch {
+    return;
+  }
+  const remove = async (lockPath: string): Promise<void> => {
+    try {
+      await fs.unlink(lockPath);
+    } catch {
+      // 别人同时也在清扫 / 已被释放：无事可做
+    }
+  };
+  await Promise.all(names
+    .filter((name) => name.startsWith(LOCK_FILE_PREFIX) && name.endsWith('.lock'))
+    .map(async (name) => {
+      const lockPath = path.join(dir, name);
+      const holder = await readLockHolder(lockPath);
+      if (holder === null) return; // 读不出 holder：保守留下
+      const alive = workdirLockHolderAlive(holder.pid);
+      if (alive === false) return await remove(lockPath); // holder 确定已死
+      if (alive !== true) return; // 判不了：留下
+      // pid 复用陷阱：holder pid 此刻可能属于一个毫不相干的进程（本机实测 2026-10-27：一条测试残留锁的
+      // pid 9704 已被 `NoiseCancelingEngine.exe` 复用）。只有「它声明的工作目录确实不存在 + 锁已过
+      // staleMs」才清 —— 那说明 holder 早就不在这把锁上了，而不是正在干活。
+      const st = await fs.stat(lockPath).catch(() => null);
+      if (st === null || Date.now() - st.mtimeMs <= DEFAULT_WORKDIR_LOCK_STALE_MS) return;
+      const workDir = typeof holder.workDir === 'string' ? holder.workDir : '';
+      if (workDir === '') return;
+      if (await fs.stat(workDir).then(() => true, () => false)) return;
+      await remove(lockPath);
+    }));
+}
+
 async function tryAcquire(lockPath: string, workDir: string, staleMs: number, now: () => number): Promise<(() => Promise<void>) | null> {
   const token = randomUUID();
   try {
@@ -98,7 +186,17 @@ async function tryAcquire(lockPath: string, workDir: string, staleMs: number, no
   } catch (err) {
     const code = (err as { code?: string }).code;
     if (code !== 'EEXIST') throw err;
-    // 陈旧锁回收：holder 崩溃/被杀后留下的文件不能让同步永久卡死
+    // ① holder pid 已经不存在 ⇒ 这把锁必然陈旧，立即回收，不等 staleMs（重启/崩溃后的现场）
+    const holder = await readLockHolder(lockPath);
+    if (workdirLockHolderAlive(holder?.pid) === false) {
+      try {
+        await fs.unlink(lockPath);
+      } catch {
+        // 别人刚好也判定并回收、或 holder 的 finally 刚好跑到：下一轮重试即可
+      }
+      return null;
+    }
+    // ② 读不出 holder / holder 仍存活 ⇒ 只有超过 staleMs 才视为崩溃残留（绝不抢正在跑的长任务）
     try {
       const st = await fs.stat(lockPath);
       if (now() - st.mtimeMs > staleMs) await fs.unlink(lockPath);
@@ -127,8 +225,16 @@ export async function withWorkdirLock<T>(
   const key = workdirLockKey(workDir);
   const lockPath = workdirLockPath(workDir);
 
+  // 顺带清扫本机别的死 holder 残留（每进程一次，失败不影响本次取锁）
+  void pruneDeadWorkdirLocksOnce().catch(() => undefined);
+
+  // 计时必须在进入串行链**之前**取：链上排队同样属于「在等这把锁」。否则一个只读调用排在
+  // 上一个 300 s 的同步后面时，计时从轮到它那一刻才清零，超时上限形同失效（2026-10-27 现场）。
+  const started = now();
+
   const run = async (): Promise<T> => {
-    const started = now();
+    // 排队期间调用方已超时放弃：轮到它时直接失败，**不执行 fn**，免得被遗弃的请求稍后仍去驱动工作副本
+    if (now() - started >= timeoutMs) throw new WorkdirLockError(workDir, now() - started);
     // 先同步做一次尝试，再进入轮询：无竞争的常见情形零额外延迟
     let release = await tryAcquire(lockPath, workDir, staleMs, now);
     while (release === null) {
@@ -149,14 +255,25 @@ export async function withWorkdirLock<T>(
   // 链里只保留「尾巴」的完成状态，异常不向下游传染
   const tail = current.then(() => undefined, () => undefined);
   chains.set(key, tail);
+
+  // 硬上界：timeoutMs 是「拿到锁」的上限，不是「开始计时后」的上限。只用 run 内的计时不够 ——
+  // 排在长任务后面的调用永远轮不到自己计时，界面就被历史任务拖着走。这里直接对链头 race，
+  // 超时 reject；被放弃的 run 之后还会被链唤醒，但入口的过期检查让它立刻抛（不碰工作副本）。
+  let rejectDeadline: ((reason: Error) => void) | undefined;
+  const deadline = new Promise<never>((_, reject) => { rejectDeadline = reject; });
+  const timer = setTimeout(() => { rejectDeadline?.(new WorkdirLockError(workDir, timeoutMs)); }, timeoutMs);
+  // unref：这个计时器不该拖住进程退出（缺省 300 s）
+  if (typeof timer.unref === 'function') timer.unref();
   try {
-    return await current;
+    return await Promise.race([current, deadline]);
   } finally {
+    clearTimeout(timer);
     if (chains.get(key) === tail) chains.delete(key);
   }
 }
 
-/** 仅供测试：清空进程内串行链（不影响磁盘上的锁文件） */
+/** 仅供测试：清空进程内串行链与一次性清扫标记（不影响磁盘上的锁文件） */
 export function resetWorkdirLockChainsForTest(): void {
   chains.clear();
+  pruneScheduled = false;
 }