@lasting-beauty/chat-hub 0.1.0-beta.1

package/cli/data-lifecycle.mjs

@@ -0,0 +1,203 @@
+import { createHash, randomUUID } from 'node:crypto';
+import {
+  chmodSync,
+  cpSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { deploymentPaths } from './deploy.mjs';
+
+export function createStoppedBackup({
+  rootDirectory = '/',
+  kind = 'manual',
+  now = Date.now(),
+} = {}) {
+  if (!['manual', 'upgrade', 'restore-safety'].includes(kind)) {
+    throw new Error('备份类型无效');
+  }
+  const dataDirectory = rootedPath(rootDirectory, deploymentPaths.data);
+  const backupRoot = rootedPath(rootDirectory, deploymentPaths.backups);
+  if (!existsSync(dataDirectory) || !statSync(dataDirectory).isDirectory()) {
+    throw new Error('Chat Hub 数据目录不存在');
+  }
+  assertNoSymbolicLinks(dataDirectory);
+  mkdirSync(backupRoot, { recursive: true, mode: 0o700 });
+  chmodSync(backupRoot, 0o700);
+  const stamp = new Date(now).toISOString().replaceAll(':', '').replaceAll('.', '-');
+  const backupDirectory = join(backupRoot, `${kind}-${stamp}-${randomUUID().slice(0, 8)}`);
+  mkdirSync(backupDirectory, { mode: 0o700 });
+  const copiedData = join(backupDirectory, 'data');
+  try {
+    cpSync(dataDirectory, copiedData, { recursive: true, errorOnExist: true, force: false });
+    const databasePath = join(copiedData, 'chat-hub.sqlite');
+    const manifest = {
+      version: 1,
+      kind,
+      createdAt: new Date(now).toISOString(),
+      sourceDataDirectory: deploymentPaths.data,
+      database: existsSync(databasePath)
+        ? { relativePath: 'data/chat-hub.sqlite', sha256: sha256File(databasePath) }
+        : null,
+      includesMasterKey: false,
+    };
+    writeFileSync(
+      join(backupDirectory, 'manifest.json'),
+      `${JSON.stringify(manifest, null, 2)}\n`,
+      {
+        mode: 0o600,
+      },
+    );
+    return { backupDirectory, manifest };
+  } catch (error) {
+    rmSync(backupDirectory, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+export function validateBackup(backup, rootDirectory = '/') {
+  const backupRoot = rootedPath(rootDirectory, deploymentPaths.backups);
+  const requested = isAbsolute(backup) ? resolve(backup) : resolve(backupRoot, backup);
+  const pathFromRoot = relative(backupRoot, requested);
+  if (
+    !pathFromRoot ||
+    pathFromRoot.startsWith('..') ||
+    isAbsolute(pathFromRoot) ||
+    pathFromRoot.includes('/') ||
+    pathFromRoot.includes('\\')
+  ) {
+    throw new Error('恢复目标必须是备份目录中的一个直接子目录');
+  }
+  const manifestPath = join(requested, 'manifest.json');
+  const dataDirectory = join(requested, 'data');
+  if (!existsSync(manifestPath) || !existsSync(dataDirectory)) throw new Error('备份内容不完整');
+  assertNoSymbolicLinks(requested);
+  const manifest = parseManifest(readFileSync(manifestPath, 'utf8'));
+  if (manifest.database) {
+    const databasePath = join(requested, manifest.database.relativePath);
+    if (!existsSync(databasePath) || sha256File(databasePath) !== manifest.database.sha256) {
+      throw new Error('备份数据库校验和不匹配');
+    }
+    const header = readFileSync(databasePath).subarray(0, 16).toString('utf8');
+    if (header !== 'SQLite format 3\0') throw new Error('备份数据库不是有效的 SQLite 文件');
+  }
+  return { backupDirectory: requested, dataDirectory, manifest };
+}
+
+export function stageRestore({ backup, rootDirectory = '/' }) {
+  const validated = validateBackup(backup, rootDirectory);
+  const dataDirectory = rootedPath(rootDirectory, deploymentPaths.data);
+  const parent = dirname(dataDirectory);
+  const suffix = randomUUID();
+  const staged = join(parent, `.chat-hub.restore-${suffix}`);
+  const previous = join(parent, `.chat-hub.previous-${suffix}`);
+  if (!existsSync(dataDirectory)) throw new Error('当前 Chat Hub 数据目录不存在');
+  cpSync(validated.dataDirectory, staged, { recursive: true, errorOnExist: true, force: false });
+  try {
+    renameSync(dataDirectory, previous);
+    renameSync(staged, dataDirectory);
+  } catch (error) {
+    if (existsSync(previous) && !existsSync(dataDirectory)) renameSync(previous, dataDirectory);
+    rmSync(staged, { recursive: true, force: true });
+    throw error;
+  }
+  let finalized = false;
+  return {
+    backupDirectory: validated.backupDirectory,
+    dataDirectory,
+    rollback() {
+      if (finalized) return;
+      const failed = join(parent, `.chat-hub.failed-${suffix}`);
+      if (existsSync(dataDirectory)) renameSync(dataDirectory, failed);
+      if (existsSync(previous)) renameSync(previous, dataDirectory);
+      rmSync(failed, { recursive: true, force: true });
+      rmSync(staged, { recursive: true, force: true });
+      finalized = true;
+    },
+    commit() {
+      if (finalized) return;
+      rmSync(previous, { recursive: true, force: true });
+      rmSync(staged, { recursive: true, force: true });
+      finalized = true;
+    },
+  };
+}
+
+export function pruneUpgradeBackups(rootDirectory = '/', retain = 3) {
+  if (!Number.isInteger(retain) || retain < 1) throw new Error('升级备份保留数量无效');
+  const backupRoot = rootedPath(rootDirectory, deploymentPaths.backups);
+  if (!existsSync(backupRoot)) return [];
+  const candidates = readdirSync(backupRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && entry.name.startsWith('upgrade-'))
+    .map((entry) => ({
+      name: entry.name,
+      path: join(backupRoot, entry.name),
+      modifiedAt: statSync(join(backupRoot, entry.name)).mtimeMs,
+    }))
+    .sort((left, right) => right.modifiedAt - left.modifiedAt);
+  const removed = [];
+  for (const entry of candidates.slice(retain)) {
+    const checked = validateBackup(entry.name, rootDirectory);
+    rmSync(checked.backupDirectory, { recursive: true, force: true });
+    removed.push(entry.path);
+  }
+  return removed;
+}
+
+function parseManifest(serialized) {
+  const value = JSON.parse(serialized);
+  if (!value || typeof value !== 'object' || value.version !== 1) {
+    throw new Error('备份清单版本无效');
+  }
+  if (!['manual', 'upgrade', 'restore-safety'].includes(value.kind)) {
+    throw new Error('备份清单类型无效');
+  }
+  if (typeof value.createdAt !== 'string' || value.includesMasterKey !== false) {
+    throw new Error('备份清单字段无效');
+  }
+  if (
+    value.database !== null &&
+    (!value.database ||
+      value.database.relativePath !== 'data/chat-hub.sqlite' ||
+      typeof value.database.sha256 !== 'string' ||
+      !/^[a-f0-9]{64}$/.test(value.database.sha256))
+  ) {
+    throw new Error('备份数据库清单无效');
+  }
+  return value;
+}
+
+function sha256File(path) {
+  return createHash('sha256').update(readFileSync(path)).digest('hex');
+}
+
+function assertNoSymbolicLinks(directory) {
+  const queue = [directory];
+  while (queue.length > 0) {
+    const current = queue.pop();
+    const metadata = lstatSync(current);
+    if (metadata.isSymbolicLink())
+      throw new Error(`数据或备份中不允许符号链接：${basename(current)}`);
+    if (!metadata.isDirectory()) continue;
+    for (const entry of readdirSync(current)) queue.push(join(current, entry));
+  }
+}
+
+function rootedPath(rootDirectory, absolutePath) {
+  const root = resolve(rootDirectory);
+  if (!isAbsolute(absolutePath)) throw new Error('生命周期目标路径必须是绝对路径');
+  if (root === resolve('/')) return absolutePath;
+  const target = resolve(root, absolutePath.replace(/^[/\\]+/, ''));
+  const pathFromRoot = relative(root, target);
+  if (pathFromRoot.startsWith('..') || isAbsolute(pathFromRoot)) {
+    throw new Error('生命周期目标越出测试根目录');
+  }
+  return target;
+}