zipcalm 0.0.0-stage → 1.0.2

package/server/plugins/formats/_shared/tar/writer.js

@@ -0,0 +1,206 @@
+// tar 系列的**写入侧**：收集条目（与 zip 同规则）+ 流式写出（可选压缩层）
+//
+// 一个实现服务 tar / tar.gz / tar.zst —— 三种格式的归档层完全相同，差别只在压缩层。
+// 边界（INV-15）：只读源文件、只写 ctx.tempPath，不删源、不预检、不排队。
+
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { PassThrough } from 'node:stream';
+
+import * as tar from 'tar';
+
+import { ERROR_CODES, apiError } from '../../../../lib/errors.js';
+import { createThrottledReporter } from '../../../../lib/throttle.js';
+import { pipelineWith } from '../streams.js';
+import { createCompressStream } from './compression.js';
+
+/** 求多个目录的公共祖先（用于一次 Pack 覆盖所有源；名字取相对它的路径） */
+export function commonAncestor(dirs) {
+  if (dirs.length === 0) return path.sep;
+  let parts = path.resolve(dirs[0]).split(path.sep);
+  for (const dir of dirs.slice(1)) {
+    const other = path.resolve(dir).split(path.sep);
+    let index = 0;
+    while (index < parts.length && index < other.length && parts[index] === other[index]) index += 1;
+    parts = parts.slice(0, index);
+  }
+  const base = parts.join(path.sep);
+  return base === '' ? path.sep : base;
+}
+
+/**
+ * 收集条目（与 zip 同规则：目录保留顶层名、不跟随符号链接），并算出一个公共祖先作为 `cwd`。
+ *
+ * 关于包内名字：node-tar v7 的流式写入是 `Pack({cwd}) + add(相对路径)`，没有 v6 那种"任意指定包内名"的入口。
+ * 所以做法是 `cwd = 各源父目录的公共祖先`、名字取相对路径 —— 常规用法（同一目录下的多个源）下名字与
+ * zip 侧完全一致（`源名/子路径/文件`）；若调用方把**不同父目录**的源混在一个任务里，
+ * 包内名字会带上必要的中间目录（避免冲突），这是本格式已知的命名边界。
+ */
+export async function collectEntries(ctx) {
+  const fileEntries = [];
+  const sourceParents = [];
+  const sourceStats = new Map();
+  const skipped = [];
+  // 黑名单命中项（由编排层传入）：收集阶段就不放进包
+  const shouldSkip = typeof (ctx.options && ctx.options.shouldSkip) === 'function' ? ctx.options.shouldSkip : null;
+  let skippedSymlinks = 0;
+
+  for (const source of ctx.sources) {
+    const sourceName = source.name || path.basename(source.absPath);
+    sourceParents.push(path.dirname(source.absPath));
+    const collected = await collectSource(source, sourceName, skippedSymlinks, shouldSkip, skipped);
+    skippedSymlinks = collected.skippedSymlinks;
+    fileEntries.push(...collected.entries);
+    sourceStats.set(sourceName, { count: collected.entries.length, bytes: collected.bytes });
+  }
+
+  const base = commonAncestor(sourceParents);
+  for (const fileEntry of fileEntries) {
+    fileEntry.name = path.relative(base, fileEntry.absPath).split(path.sep).join('/');
+  }
+
+  return {
+    items: fileEntries,
+    base,
+    sourceStats,
+    totalBytes: fileEntries.reduce((sum, fileEntry) => sum + fileEntry.size, 0),
+    totalFiles: fileEntries.length,
+    skippedSymlinks,
+    skipped,
+  };
+}
+
+/** 单个源 → 条目列表（文件直接用；目录递归；符号链接跳过并计数） */
+async function collectSource(source, sourceName, skipped, shouldSkip, skippedEntries) {
+  let skippedSymlinks = skipped;
+  const entries = [];
+
+  /** 命中就记账并返回 true（调用方据此 continue） */
+  const recordSkip = (absPath, name, segments) => {
+    if (!shouldSkip) return false;
+    const hit = shouldSkip({ name, segments });
+    if (!hit) return false;
+    skippedEntries.push({ absPath, pattern: hit.pattern, layer: hit.layer });
+    return true;
+  };
+
+  if (source.kind === 'file') {
+    const fileStat = await fsp.lstat(source.absPath).catch(() => null);
+    if (!fileStat || !fileStat.isFile()) {
+      throw apiError(ERROR_CODES.PATH_NOT_FOUND, '源文件在扫描后已不可用', { source: sourceName });
+    }
+    if (recordSkip(source.absPath, path.basename(source.absPath), [sourceName])) {
+      return { entries, bytes: 0, skippedSymlinks };
+    }
+    entries.push({ absPath: source.absPath, size: fileStat.size, sourceName });
+    return { entries, bytes: fileStat.size, skippedSymlinks };
+  }
+
+  let bytes = 0;
+  const walk = async (dirAbs, prefix) => {
+    const dirents = await fsp.readdir(dirAbs, { withFileTypes: true });
+    for (const dirent of dirents) {
+      const childAbs = path.join(dirAbs, dirent.name);
+      if (dirent.isSymbolicLink()) {
+        skippedSymlinks += 1;
+        continue;
+      }
+      if (dirent.isDirectory()) {
+        await walk(childAbs, `${prefix}/${dirent.name}`);
+      } else if (dirent.isFile()) {
+        // 目录名规则（如 @eaDir）也参与匹配：segments 用完整相对路径
+        if (recordSkip(childAbs, dirent.name, `${prefix}/${dirent.name}`.split('/'))) continue;
+        const fileStat = await fsp.lstat(childAbs);
+        entries.push({ absPath: childAbs, size: fileStat.size, sourceName });
+        bytes += fileStat.size;
+      }
+    }
+  };
+  await walk(source.absPath, sourceName);
+  return { entries, bytes, skippedSymlinks };
+}
+
+/** 建好写入链路：Pack（纯 JS 打包）→ 压缩层（可省）→ 输出流 */
+function openTarPipeline(ctx, collected, stats) {
+  const output = fs.createWriteStream(ctx.tempPath);
+  const pack = new tar.Pack({ cwd: collected.base, portable: true, gzip: false });
+  const compressor = createCompressStream(stats.compression, stats.level);
+  const done = pipelineWith([pack, compressor || new PassThrough(), output], stats.signal);
+  return { pack, done };
+}
+
+/** 把条目逐个加进 Pack（每个条目检查一次取消信号：大目录要能及时中断） */
+function addEntriesToPack(pack, fileItems, signal) {
+  for (const fileEntry of fileItems) {
+    if (signal && signal.aborted) throw apiError(ERROR_CODES.ABORTED, '任务已取消');
+    pack.add(fileEntry.name);
+  }
+  pack.end();
+}
+
+/** 把执行器抛出的错误翻译成契约错误（取消 → ABORTED，其余原样上抛） */
+function mapTarFailure(error, signal) {
+  if (error && (error.name === 'AbortError' || (signal && signal.aborted))) {
+    return apiError(ERROR_CODES.ABORTED, '任务已取消');
+  }
+  return error;
+}
+
+/**
+ * 写入归档：单个 `Pack({ cwd })` 一次性写全部条目 → 套压缩层 → 输出到 tempPath。
+ *
+ * 进度粒度说明（诚实交代）：node-tar v7 的流式写入不暴露"逐条写完"的回调，所以这里**按源**上报
+ * （`currentFile` 为源名，`processedBytes/processedFiles` 是精确累计值）。zip 侧是逐条事件，粒度更细。
+ */
+export async function writeTarStream(ctx, collected, stats) {
+  const report = createThrottledReporter(ctx.onProgress || (() => {}), { intervalMs: 100 });
+  const startedAt = Date.now();
+  const { items, totalBytes, totalFiles } = collected;
+  const { pack, done } = openTarPipeline(ctx, collected, stats);
+
+  try {
+    addEntriesToPack(pack, items, stats.signal);
+    reportBySource(collected.sourceStats, { report, totalBytes, totalFiles });
+    await done;
+  } catch (error) {
+    await discardTemp(ctx.tempPath);
+    throw mapTarFailure(error, stats.signal);
+  }
+
+  // 产物大小：stat 失败（理论上不会）就当 0，不用 existsSync 先探一次（同步 I/O）
+  const bytesOut = await fsp.stat(ctx.tempPath).then((stat) => stat.size).catch(() => 0);
+  return {
+    outputPath: ctx.tempPath,
+    entries: totalFiles,
+    bytesIn: totalBytes,
+    bytesOut,
+    durationMs: Date.now() - startedAt,
+    skippedSymlinks: collected.skippedSymlinks,
+    // 契约 v2 §3.4 条款 10：实际进包条目的**源绝对路径**（进程内使用，不进 API）。
+    // INV-02 删除集合的第一手依据；禁止用包内路径（name = 相对 cwd 的包内名）反推源路径。
+    entryPaths: items.map((item) => item.absPath),
+    // INV-03 ⑤ 进包时快照（size 基准）：collectEntries 已 stat 过，原样带出给删除前复核
+    entryStats: items.map((item) => [item.absPath, { sizeBytes: item.size }]),
+  };
+}
+
+/** 按源汇总进度（每个源记一次，避免"进度瞬间 100%"的假象） */
+function reportBySource(sourceStats, { report, totalBytes, totalFiles }) {
+  let processedBytes = 0;
+  let processedFiles = 0;
+  for (const [sourceName, sourceStat] of sourceStats) {
+    processedBytes += sourceStat.bytes;
+    processedFiles += sourceStat.count;
+    report({ processedBytes, totalBytes, processedFiles, totalFiles, currentFile: sourceName });
+  }
+}
+
+/** 失败/取消时清掉半成品（rm --force：不存在的路径不算错；清理失败不掩盖原始错误） */
+async function discardTemp(tempPath) {
+  try {
+    await fsp.rm(tempPath, { force: true });
+  } catch {
+    /* 见上 */
+  }
+}

package/server/plugins/formats/_shared/tarFamily.js

@@ -0,0 +1,207 @@
+// tar 系列格式包工厂（tar / tar.gz / tar.zst 共用一个实现，只是压缩层不同）
+//
+// 为什么要工厂：三种格式的**归档层完全相同**（node-tar 写/读 tar），差别只在外面套不套 gzip/zstd。
+// 各写一份 = 三份 zip-slip 判定与三份进度逻辑，迟早漂移。这里压缩层是策略参数：
+//   none  → 直通（.tar）
+//   gzip  → node:zlib gzip（.tar.gz）
+//   zstd  → **node:zlib 内置 zstd**（Node ≥ 22.15）；不可用时回退系统 `zstd` 命令（ZC_ZSTD_BIN 可覆盖）
+//
+// 安全：条目判定与写出复用 `_shared/entrySafety.js`（与 zip **同一套** zip-slip 防护）。
+// 边界（INV-15）：格式包不删源文件、不做预检、不排队、不落盘任务状态。
+//
+// 文件分工（本文件只放契约面与装配，实现拆到 _shared/tar/ 下，单文件不超过约定行数）：
+//   _shared/tar/compression.js —— 压缩层策略与 zstd 回退链
+//   _shared/tar/writer.js      —— 收集条目 + 流式写出
+//   _shared/tar/reader.js      —— 流式解析 + 错误映射
+
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import zlib from 'node:zlib';
+
+import * as tar from 'tar';
+
+import { ERROR_CODES, apiError } from '../../../lib/errors.js';
+import { assertCreatable } from './createGuards.js';
+import { planTargets } from './entrySafety.js';
+import { builtinZstdUsable, findZstdBinary } from './tar/compression.js';
+import { collectEntries, writeTarStream } from './tar/writer.js';
+import { mapArchiveError, parseArchive, readEntryBuffer, toApiEntry } from './tar/reader.js';
+
+/** 压得动的文本/结构化数据 vs 已压缩格式：用于 estimate 的粗估（M4 只求"够算预检分母"） */
+const ALREADY_COMPRESSED = /\.(jpe?g|png|gif|webp|heic|mp4|mkv|mov|mp3|flac|zip|7z|rar|gz|bz2|xz|zst|docx|xlsx|pptx)$/i;
+
+// ===== 契约面实现 =====
+// 全部写成「模块级函数 + spec 参数」：一是审计要求单函数 ≤50 行代码，二是每个动作可独立单测。
+// 工厂（文件末尾）只做装配，不含逻辑。
+
+async function pluginAvailable(spec) {
+  // node-tar 可用性就看真实用到的入口：Pack（写）/ list（读）
+  if (typeof tar.Pack !== 'function' || typeof tar.list !== 'function') return false;
+  if (spec.compression === 'gzip') return typeof zlib.createGzip === 'function';
+  if (spec.compression === 'zstd') return builtinZstdUsable() || Boolean(findZstdBinary());
+  return true;
+}
+
+async function pluginUnavailableReason(spec) {
+  if (await pluginAvailable(spec)) return null;
+  if (spec.compression === 'zstd') {
+    return `zstd 不可用：Node 内置 zstd 需要 Node ≥ 22.15（当前 ${process.version}），且系统未找到 zstd 命令（可用 ZC_ZSTD_BIN 指定路径）`;
+  }
+  return `${spec.id} 依赖（node-tar / node:zlib）未正确安装`;
+}
+
+/** 粗估：tar 不压（≈1.0 + 头部开销）；gzip/zstd 按"是否已压缩格式"给经验比值 */
+async function pluginEstimate(spec, inputBytes, options = {}) {
+  const bytes = Number.isFinite(inputBytes) && inputBytes > 0 ? inputBytes : 0;
+  const names = Array.isArray(options.sample && options.sample.names) ? options.sample.names : [];
+  const everyEntryAlreadyCompressed = names.length > 0 && names.every((entryName) => ALREADY_COMPRESSED.test(entryName));
+  const ratioTable = ESTIMATED_RATIO[spec.compression];
+  const ratioOf = typeof ratioTable === 'number'
+    ? ratioTable
+    : (everyEntryAlreadyCompressed ? ratioTable.alreadyCompressed : ratioTable.mixed);
+  const headerOverhead = TAR_BLOCK_BYTES * Math.max(1, names.length || 1);
+  return {
+    estimatedBytes: Math.ceil(bytes * ratioOf) + (spec.compression === 'none' ? headerOverhead : 0),
+    ratio: ratioOf,
+    basis: 'heuristic',
+    confidence: 'low',
+  };
+}
+
+async function pluginCreate(spec, ctx) {
+  await assertCreatable(ctx, () => pluginAvailable(spec), spec.id);
+  const collected = await collectEntries(ctx);
+  const level = Number.isInteger(ctx.options && ctx.options.level) ? ctx.options.level : (spec.defaultLevel || 6);
+  const written = await writeTarStream(ctx, collected, {
+    compression: spec.compression,
+    level,
+    signal: ctx.options && ctx.options.signal,
+  });
+  // 契约 v2：把黑名单跳过项回报给编排层（它负责换成 userPath 并排除出删除集合）
+  return { ...written, skipped: collected.skipped || [] };
+}
+
+async function pluginList(spec, archivePath) {
+  const entries = [];
+  try {
+    await parseArchive(archivePath, spec.compression, (entry) => {
+      entries.push(toApiEntry(entry));
+      entry.resume(); // 目录/不需要内容的场景要显式放流，否则解析器会卡住
+    });
+  } catch (error) {
+    throw mapArchiveError(error, archivePath);
+  }
+  return { entries, count: entries.length, truncated: false };
+}
+
+/** 完整性校验：tar 没有 CRC，走契约允许的 `read-all`（逐条目读通 + 大小一致） */
+async function pluginTest(spec, archivePath) {
+  const failures = [];
+  let checked = 0;
+  try {
+    await parseArchive(archivePath, spec.compression, async (entry) => {
+      const info = toApiEntry(entry);
+      if (info.type === 'dir') {
+        entry.resume();
+        return;
+      }
+      const buffer = await readEntryBuffer(entry);
+      if (buffer.length !== info.size) {
+        failures.push({ entry: info.name, reason: `解压后大小不符（期望 ${info.size}，实际 ${buffer.length}）` });
+      }
+      checked += 1;
+    });
+  } catch (error) {
+    // 解析/解压失败（截断、损坏的 gzip/zstd 流）→ 归档损坏
+    throw mapArchiveError(error, archivePath);
+  }
+  return { ok: failures.length === 0, checked, failures, strategy: 'read-all' };
+}
+
+/** 第一遍：只收集条目名与类型（**不落盘**），交给共用判定做 zip-slip + 覆盖检查 */
+async function collectEntryMeta(spec, archivePath) {
+  const meta = [];
+  try {
+    await parseArchive(archivePath, spec.compression, (entry) => {
+      meta.push({
+        name: entry.path || entry.name || '',
+        isDir: entry.type === 'Directory',
+        size: Number(entry.size || 0),
+        link: entry.type === 'SymbolicLink' || entry.type === 'Link',
+      });
+      entry.resume();
+    });
+  } catch (error) {
+    throw mapArchiveError(error, archivePath);
+  }
+  return meta;
+}
+
+/** 预先建好所有目标目录：第二遍必须**同步**接管条目流，不能在里面 await mkdir */
+async function prepareTargetDirs(plan) {
+  for (const plannedEntry of plan) {
+    if (plannedEntry.isDir) await fsp.mkdir(plannedEntry.targetPath, { recursive: true });
+    else await fsp.mkdir(path.dirname(plannedEntry.targetPath), { recursive: true });
+  }
+}
+
+async function pluginExtract(spec, ctx) {
+  if (!(await pluginAvailable(spec))) {
+    throw apiError(ERROR_CODES.FORMAT_UNAVAILABLE, `${spec.id} 格式当前不可用`);
+  }
+  const startedAt = Date.now();
+  const targetDir = path.resolve(ctx.targetDir);
+  const overwrite = Boolean(ctx.options && ctx.options.overwrite);
+
+  const meta = await collectEntryMeta(spec, ctx.archivePath);
+  const planned = await planTargets(meta.map((entryMeta, index) => ({ ...entryMeta, index })), targetDir, overwrite);
+  await prepareTargetDirs(planned.plan);
+
+  // 第二遍：按顺序把每个条目的数据写到判定好的目标路径
+  let cursor = 0;
+  await parseArchive(ctx.archivePath, spec.compression, (entry) => {
+    const plannedEntry = planned.plan[cursor];
+    cursor += 1;
+    if (!plannedEntry || plannedEntry.isDir) {
+      entry.resume();
+      return null;
+    }
+    // 同步 attach：pipeline 立即开始消费该条目
+    return pipeline(entry, fs.createWriteStream(plannedEntry.targetPath));
+  });
+
+  return {
+    targetDir,
+    entries: cursor,
+    bytesOut: planned.totalBytes,
+    durationMs: Date.now() - startedAt,
+  };
+}
+
+/**
+ * tar 系列格式包工厂：只做契约面装配，不含任何逻辑。
+ * @param {{id: string, name: string, ext: string, extAliases?: string[], mime: string,
+ *          compression: 'none'|'gzip'|'zstd', levelRange?: [number, number], defaultLevel?: number}} spec
+ */
+export function createTarPlugin(spec) {
+  return {
+    id: spec.id,
+    name: spec.name,
+    ext: spec.ext,
+    extAliases: spec.extAliases || [],
+    mime: spec.mime,
+    levelRange: spec.levelRange,
+    defaultLevel: spec.defaultLevel,
+    // 能力声明（docs/19 §4.1）：TAR/gzip/zstd 规范无加密 → 空数组（前端据此置灰密码开关）
+    capabilities: spec.capabilities || [],
+    available: () => pluginAvailable(spec),
+    unavailableReason: () => pluginUnavailableReason(spec),
+    estimate: (inputBytes, options) => pluginEstimate(spec, inputBytes, options),
+    create: (ctx) => pluginCreate(spec, ctx),
+    extract: (ctx) => pluginExtract(spec, ctx),
+    list: (archivePath) => pluginList(spec, archivePath),
+    test: (archivePath) => pluginTest(spec, archivePath),
+  };
+}