@logictan/dsh-config-manager 0.1.60

package/src/core/cache-cleaner.test.ts

@@ -0,0 +1,169 @@
+/**
+ * cache-cleaner 测试：缓存自动清理的保留期 / 白名单边界 / 容错。
+ * 使用真实临时目录（node:os tmpdir）+ node:fs 真实读写（与 plugin-cli.fs.test.ts 同模式）。
+ * 覆盖：
+ *   - tmp：过期 .zip 删、新 .zip 留、非 zip 文件留、dsh-sync-pull-* 目录超期删
+ *   - exports：过期导出 zip 删、新导出 zip 留、非 zip 文件留
+ *   - 保留期边界（恰好等于保留期 → 不删）、目录不存在 → 不抛错
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import {
+  cleanupCaches,
+  TMP_RETENTION_DEFAULT_MS,
+  EXPORTS_RETENTION_DEFAULT_MS,
+} from './cache-cleaner.ts';
+
+/** 建独立临时数据目录，返回 { root, tmpDir, exportsDir, cleanup } */
+async function makeDataDir(): Promise<{
+  root: string;
+  tmpDir: string;
+  exportsDir: string;
+  cleanup: () => Promise<void>;
+}> {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-cm-cache-'));
+  const tmpDir = path.join(root, 'tmp');
+  const exportsDir = path.join(root, 'exports');
+  await fs.mkdir(tmpDir, { recursive: true });
+  await fs.mkdir(exportsDir, { recursive: true });
+  return {
+    root,
+    tmpDir,
+    exportsDir,
+    cleanup: () => fs.rm(root, { recursive: true, force: true }),
+  };
+}
+
+/** 把目标 mtime 拨到指定毫秒（Windows 精度足够，测试用秒级偏移） */
+async function touch(p: string, mtimeMs: number): Promise<void> {
+  const st = await fs.stat(p);
+  await fs.utimes(p, st.atimeMs ? new Date(st.atimeMs) : new Date(), new Date(mtimeMs));
+}
+
+test('tmp：过期 .zip 删、新 .zip 留、非 zip 文件留', async () => {
+  const d = await makeDataDir();
+  try {
+    const now = Date.now();
+    const oldZip = path.join(d.tmpDir, 'upload-old.zip');
+    const newZip = path.join(d.tmpDir, 'upload-new.zip');
+    const txt = path.join(d.tmpDir, 'notes.txt');
+    await fs.writeFile(oldZip, Buffer.alloc(10));
+    await fs.writeFile(newZip, Buffer.alloc(20));
+    await fs.writeFile(txt, 'keep me');
+    await touch(oldZip, now - TMP_RETENTION_DEFAULT_MS - 1000); // 超期 1s
+    await touch(newZip, now - 1000); // 新
+
+    const report = await cleanupCaches({
+      tmpDir: d.tmpDir,
+      exportsDir: d.exportsDir,
+      now: () => now,
+    });
+
+    assert.equal(report.removed, 1, '只删超期 zip');
+    assert.equal(report.freedBytes, 10, '释放字节 = 被删文件 size');
+    assert.equal(await fs.readFile(newZip).then((b) => b.length), 20, '新 zip 保留');
+    assert.equal(await fs.readFile(txt, 'utf8'), 'keep me', '非 zip 文件保留');
+    await assert.rejects(() => fs.stat(oldZip), '超期 zip 已删');
+    assert.ok(report.detail.some((s) => s.includes('upload-old.zip')), 'detail 含删除记录');
+  } finally {
+    await d.cleanup();
+  }
+});
+
+test('tmp：dsh-sync-pull-* 临时目录超期删、新目录留', async () => {
+  const d = await makeDataDir();
+  try {
+    const now = Date.now();
+    const oldDir = path.join(d.tmpDir, 'dsh-sync-pull-abc');
+    const newDir = path.join(d.tmpDir, 'dsh-sync-pull-def');
+    const otherDir = path.join(d.tmpDir, 'keep-dir');
+    await fs.mkdir(path.join(oldDir, 'inner'), { recursive: true });
+    await fs.mkdir(path.join(newDir, 'inner'), { recursive: true });
+    await fs.mkdir(otherDir, { recursive: true });
+    await fs.writeFile(path.join(oldDir, 'inner', 'snapshot.zip'), Buffer.alloc(5));
+    await touch(oldDir, now - TMP_RETENTION_DEFAULT_MS - 5000);
+    await touch(newDir, now - 1000);
+
+    const report = await cleanupCaches({
+      tmpDir: d.tmpDir,
+      exportsDir: d.exportsDir,
+      now: () => now,
+    });
+
+    assert.equal(report.removed, 1, '只删超期 sync 临时目录');
+    await assert.rejects(() => fs.stat(oldDir), '超期 sync 目录整棵已删');
+    assert.ok(await fs.stat(newDir), '新 sync 目录保留');
+    assert.ok(await fs.stat(otherDir), '无关目录保留');
+  } finally {
+    await d.cleanup();
+  }
+});
+
+test('exports：过期导出 zip 删、新导出 zip 留、非 zip 文件留', async () => {
+  const d = await makeDataDir();
+  try {
+    const now = Date.now();
+    const oldExport = path.join(d.exportsDir, 'dsh-config-old.zip');
+    const newExport = path.join(d.exportsDir, 'dsh-config-new.zip');
+    const readme = path.join(d.exportsDir, 'readme.txt');
+    await fs.writeFile(oldExport, Buffer.alloc(15));
+    await fs.writeFile(newExport, Buffer.alloc(25));
+    await fs.writeFile(readme, 'keep');
+    await touch(oldExport, now - EXPORTS_RETENTION_DEFAULT_MS - 1000); // 超期 1s
+    await touch(newExport, now - 1000); // 新
+
+    const report = await cleanupCaches({
+      tmpDir: d.tmpDir,
+      exportsDir: d.exportsDir,
+      now: () => now,
+    });
+
+    assert.equal(report.removed, 1, '只删超期导出 zip');
+    assert.equal(report.freedBytes, 15, '释放字节 = 被删文件 size');
+    await assert.rejects(() => fs.stat(oldExport), '超期导出 zip 已删');
+    assert.ok(await fs.stat(newExport), '新导出 zip 保留');
+    assert.equal(await fs.readFile(readme, 'utf8'), 'keep', '非 zip 文件保留');
+    assert.ok(report.detail.some((s) => s.includes('exports/')), 'detail 含 exports 删除记录');
+  } finally {
+    await d.cleanup();
+  }
+});
+
+test('保留期边界：恰好等于保留期 → 不删（超期判定为严格大于）', async () => {
+  const d = await makeDataDir();
+  try {
+    const now = Date.now();
+    const zip = path.join(d.tmpDir, 'upload-boundary.zip');
+    await fs.writeFile(zip, Buffer.alloc(3));
+    await touch(zip, now - TMP_RETENTION_DEFAULT_MS); // 恰好 = 保留期
+
+    const report = await cleanupCaches({
+      tmpDir: d.tmpDir,
+      exportsDir: d.exportsDir,
+      now: () => now,
+    });
+
+    assert.equal(report.removed, 0, '边界文件不删');
+    assert.ok(await fs.stat(zip), '边界 zip 保留');
+  } finally {
+    await d.cleanup();
+  }
+});
+
+test('容错：目录不存在 → 不抛错、removed=0', async () => {
+  const d = await makeDataDir();
+  try {
+    const report = await cleanupCaches({
+      tmpDir: path.join(d.root, 'no-such-tmp'),
+      exportsDir: path.join(d.root, 'no-such-exports'),
+    });
+    assert.equal(report.removed, 0);
+    assert.equal(report.errors, 2, '两个缺失目录各记一次尽力而为跳过');
+  } finally {
+    await d.cleanup();
+  }
+});

package/src/core/cache-cleaner.ts

@@ -0,0 +1,121 @@
+/**
+ * 缓存自动清理：只清「可重建 / 一次性」的临时文件与导出副本。
+ *
+ * 清理面（保留期内一律不删）：
+ *  - `tmp/`：过期 `.zip` 暂存 + SyncEngine 遗留的 `dsh-sync-pull-*` 目录；
+ *  - `exports/`：过期的导出产物 ZIP（导出时用户已下载/另存到本地）。
+ *
+ * **不清理**：`snapshots/`（回滚安全网）与 `sync/`（同步状态/快照）—— 它们是用户数据。
+ *
+ * 失败语义：任何单项失败只计入 `errors`，不影响主流程（调用方仅记日志）。
+ */
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+/** 临时文件缺省保留期：24h（供刷新恢复等窗口继续消费） */
+export const TMP_RETENTION_DEFAULT_MS = 24 * 60 * 60 * 1000
+
+/** 导出产物缺省保留期：7 天（导出时用户已通过浏览器下载/另存到本地，host 端副本按周回收） */
+export const EXPORTS_RETENTION_DEFAULT_MS = 7 * 24 * 60 * 60 * 1000
+
+/** SyncEngine 在 zipDir（即 tmpDir）下 mkdtemp 的目录前缀（用完即删，崩溃残留由清理兜底） */
+const SYNC_TMP_DIR_PREFIX = 'dsh-sync-pull-'
+
+export interface CacheCleanupOptions {
+  /** 临时目录（$DSH_HOME/dsh-config-manager/tmp） */
+  tmpDir: string
+  /** 导出产物目录（$DSH_HOME/dsh-config-manager/exports） */
+  exportsDir: string
+  /** 临时文件保留期（缺省 24h） */
+  tmpRetentionMs?: number
+  /** 导出产物保留期（缺省 7 天） */
+  exportsRetentionMs?: number
+  /** 时间源（测试注入；缺省 Date.now） */
+  now?: () => number
+}
+
+export interface CacheCleanupResult {
+  /** 删除条目数（文件 + 目录） */
+  removed: number
+  /** 释放字节数（仅被删文件的 size 累计；目录删除统计为 0） */
+  freedBytes: number
+  /** 单项失败数（不影响主流程） */
+  errors: number
+  /** 每条删除记录（相对 dataDir 的描述 + 字节数），供日志/审计 */
+  detail: string[]
+}
+
+/** 目录是否超期（stat 失败保守视为未超期 → 不删） */
+async function isExpired(target: string, retentionMs: number, nowMs: number): Promise<boolean> {
+  try {
+    const st = await fs.stat(target)
+    return nowMs - st.mtimeMs > retentionMs
+  } catch {
+    return false
+  }
+}
+
+/** 删除一个文件/目录并计入报告；目录的 freedBytes 统计为 0（递归统计不划算，用途仅是日志） */
+async function removeEntry(target: string, label: string, result: CacheCleanupResult): Promise<void> {
+  try {
+    let size = 0
+    try {
+      const st = await fs.stat(target)
+      size = st.isFile() ? st.size : 0
+    } catch {
+      /* stat 失败仍尝试删除（rm 自己会兜底不存在） */
+    }
+    await fs.rm(target, { recursive: true, force: true })
+    result.removed += 1
+    result.freedBytes += size
+    result.detail.push(`${label} (${size} bytes)`)
+  } catch {
+    result.errors += 1
+  }
+}
+
+/**
+ * 执行一次缓存清理（幂等；可重复调用）。
+ * 只清理超期（超过保留期）的缓存/临时条目，其余一律保留。
+ */
+export async function cleanupCaches(opts: CacheCleanupOptions): Promise<CacheCleanupResult> {
+  const nowMs = (opts.now ?? Date.now)()
+  const tmpRetentionMs = opts.tmpRetentionMs ?? TMP_RETENTION_DEFAULT_MS
+  const exportsRetentionMs = opts.exportsRetentionMs ?? EXPORTS_RETENTION_DEFAULT_MS
+  const result: CacheCleanupResult = { removed: 0, freedBytes: 0, errors: 0, detail: [] }
+
+  // 1) tmpDir：过期 .zip（同步/解密暂存）与 SyncEngine 遗留的 dsh-sync-pull-* 目录
+  try {
+    const entries = await fs.readdir(opts.tmpDir, { withFileTypes: true })
+    for (const entry of entries) {
+      const target = path.join(opts.tmpDir, entry.name)
+      const isTmpish =
+        (entry.isFile() && entry.name.endsWith('.zip')) ||
+        (entry.isDirectory() && entry.name.startsWith(SYNC_TMP_DIR_PREFIX))
+      if (!isTmpish) continue
+      if (await isExpired(target, tmpRetentionMs, nowMs)) {
+        await removeEntry(target, `tmp/${entry.name}`, result)
+      }
+    }
+  } catch {
+    // tmpDir 不存在/不可读 → 跳过（尽力而为）
+    result.errors += 1
+  }
+
+  // 2) exportsDir：过期的导出产物 .zip（导出时已下载/另存到本地，host 端副本按保留期回收）
+  try {
+    const entries = await fs.readdir(opts.exportsDir, { withFileTypes: true })
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith('.zip')) continue
+      const target = path.join(opts.exportsDir, entry.name)
+      if (await isExpired(target, exportsRetentionMs, nowMs)) {
+        await removeEntry(target, `exports/${entry.name}`, result)
+      }
+    }
+  } catch {
+    // exportsDir 不存在/不可读 → 跳过
+    result.errors += 1
+  }
+
+  return result
+}