create-windy 0.5.2 → 0.6.0

package/template/apps/server/src/report-staging/service.test-fixture.ts

@@ -0,0 +1,226 @@
+import { createHash } from "node:crypto";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  ModuleReportStagingError,
+  type ModuleReportStagingPolicyV1,
+  type ModuleReportStagingSourceReader,
+} from "@southwind-ai/server-sdk";
+import type { ArchiveProcess } from "./archive-process.js";
+import { makeTreeRemovable } from "./filesystem-io.js";
+import { ReportStagingFilesystemStore } from "./filesystem-store.js";
+import { InMemoryReportStagingRepository } from "./memory-repository.js";
+import type { ReportStagingEntryCatalog } from "./metadata-spool.js";
+import type { ReportStagingRepository } from "./repository.js";
+import { ReportStagingService } from "./service.js";
+
+const roots: string[] = [];
+
+export async function cleanupReportStagingFixtures() {
+  await Promise.all(
+    roots.splice(0).map(async (root) => {
+      await makeTreeRemovable(root);
+      await rm(root, { recursive: true, force: true });
+    }),
+  );
+}
+
+export interface ReportStagingFixtureOptions {
+  readonly policy?: ModuleReportStagingPolicyV1;
+  readonly openSource?: ModuleReportStagingSourceReader["open"];
+  readonly repository?: ReportStagingRepository;
+}
+
+export async function createFixture(
+  archive: FakeArchive = new FakeArchive(),
+  options: ReportStagingFixtureOptions = {},
+) {
+  const root = await mkdtemp(join(tmpdir(), "windy-report-staging-"));
+  roots.push(root);
+  const repository =
+    options.repository ?? new InMemoryReportStagingRepository();
+  const clock = { value: Date.parse("2026-07-31T00:00:00.000Z") };
+  const files = new ReportStagingFilesystemStore(root, archive);
+  const service = new ReportStagingService(
+    repository,
+    files,
+    () => new Date(clock.value),
+  );
+  const authorized = { value: true };
+  const audits: Array<{ action: string }> = [];
+  const source = Buffer.from("archive-bytes");
+  const stagingPolicy = options.policy ?? policy();
+  const policies = new Map([[stagingPolicy.purpose, stagingPolicy]]);
+  const port = service.createPort({
+    moduleName: "evidence",
+    ownerId: "user-1",
+    scopeHash: "a".repeat(64),
+    policies,
+    reader: {
+      open:
+        options.openSource ??
+        (async () => ({
+          id: "file-1",
+          purpose: "evidence.original",
+          filename: "report.rar",
+          mimeType: "application/vnd.rar",
+          byteSize: source.byteLength,
+          sha256: sha256(source),
+          body: new Blob([source]).stream(),
+        })),
+    },
+    signal: new AbortController().signal,
+    reauthorize: async () => authorized.value,
+    record: (action) => audits.push({ action }),
+  });
+  return {
+    root,
+    clock,
+    service,
+    files,
+    repository,
+    port,
+    policies,
+    authorized,
+    audits,
+    archive,
+  };
+}
+
+export class FakeArchive implements ArchiveProcess {
+  probeCalls = 0;
+  listCalls = 0;
+  extractCalls = 0;
+
+  async probeRar5() {
+    this.probeCalls++;
+  }
+
+  async list(
+    _archivePaths: readonly string[],
+    catalog: ReportStagingEntryCatalog,
+    _stagingPolicy: ModuleReportStagingPolicyV1,
+  ) {
+    this.listCalls++;
+    catalog.declareArchiveEntry("messages/a.txt", false, 5);
+    catalog.declareArchiveEntry("messages/b.txt", false, 4);
+    catalog.finishArchivePass(2, 9);
+    return {
+      catalog,
+      entryCount: 2,
+      expandedByteSize: catalog.expandedByteSize,
+    };
+  }
+
+  async extract(_archivePaths: readonly string[], destination: string) {
+    this.extractCalls++;
+    await mkdir(join(destination, "messages"), { recursive: true });
+    await writeFile(join(destination, "messages/a.txt"), "hello");
+    await writeFile(join(destination, "messages/b.txt"), "wind");
+  }
+}
+
+export class CancelsOnceArchive extends FakeArchive {
+  override async extract(archivePaths: readonly string[], destination: string) {
+    this.extractCalls++;
+    if (this.extractCalls === 1) {
+      throw new ModuleReportStagingError(
+        "REPORT_STAGING_CANCELLED",
+        "cancelled",
+        true,
+      );
+    }
+    await mkdir(join(destination, "messages"), { recursive: true });
+    await writeFile(join(destination, "messages/a.txt"), "hello");
+    await writeFile(join(destination, "messages/b.txt"), "wind");
+  }
+}
+
+export class WrongListingArchive extends FakeArchive {
+  constructor(private readonly mismatch: "size" | "count") {
+    super();
+  }
+
+  override async list(
+    _archivePaths: readonly string[],
+    catalog: ReportStagingEntryCatalog,
+    stagingPolicy: ModuleReportStagingPolicyV1,
+  ) {
+    catalog.declareArchiveEntry(
+      "messages/a.txt",
+      false,
+      this.mismatch === "size" ? 6 : 5,
+    );
+    if (this.mismatch !== "count") {
+      catalog.declareArchiveEntry("messages/b.txt", false, 4);
+    }
+    catalog.finishArchivePass(
+      this.mismatch === "count" ? 1 : 2,
+      catalog.expandedByteSize,
+    );
+    return {
+      catalog,
+      entryCount: this.mismatch === "count" ? 1 : 2,
+      expandedByteSize: catalog.expandedByteSize,
+    };
+  }
+}
+
+export class ExcessivePreflightArchive extends FakeArchive {
+  override async list(
+    _archivePaths: readonly string[],
+    catalog: ReportStagingEntryCatalog,
+    stagingPolicy: ModuleReportStagingPolicyV1,
+  ) {
+    catalog.declareArchiveEntry("large.bin", false, 2_000);
+    catalog.finishArchivePass(1, 2_000);
+    return {
+      catalog,
+      entryCount: 1,
+      expandedByteSize: catalog.expandedByteSize,
+    };
+  }
+}
+
+export function createInput() {
+  return {
+    purpose: "evidence.report-staging",
+    idempotencyKey: "import-batch-1",
+    sourceMode: "archive",
+    entrypoint: "report.rar",
+    sources: [
+      {
+        relativePath: "report.rar",
+        file: {
+          fileId: "file-1",
+          purpose: "evidence.original",
+          resourceType: "evidence.file",
+          resourceId: "evidence-1",
+        },
+      },
+    ],
+  } as const;
+}
+
+export function policy(): ModuleReportStagingPolicyV1 {
+  return {
+    purpose: "evidence.report-staging",
+    sourcePurposes: ["evidence.original"],
+    retentionMs: 60_000,
+    claimTtlMs: 30_000,
+    maxReadLeaseMs: 10_000,
+    maxProcessMs: 10_000,
+    maxSources: 4,
+    maxArchiveBytes: 1_024,
+    maxExpandedBytes: 4_096,
+    maxEntryBytes: 2_048,
+    maxEntries: 20,
+    maxCompressionRatio: 100,
+    maxPathDepth: 8,
+  };
+}
+
+export function sha256(value: Buffer) {
+  return createHash("sha256").update(value).digest("hex");
+}

package/template/apps/server/src/report-staging/service.test.ts

@@ -0,0 +1,314 @@
+import { chmod, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { afterEach, describe, expect, test } from "bun:test";
+import {
+  CancelsOnceArchive,
+  cleanupReportStagingFixtures,
+  createFixture,
+  createInput,
+  ExcessivePreflightArchive,
+  FakeArchive,
+  policy,
+  sha256,
+  WrongListingArchive,
+} from "./service.test-fixture.js";
+
+afterEach(cleanupReportStagingFixtures);
+
+describe("受治理报告暂存", () => {
+  test("完整封存后用 lease 分页和流式读取，授权漂移及 active lease 均 fail closed", async () => {
+    const fixture = await createFixture();
+    const ready = await fixture.port.createOrResume(createInput());
+    expect(ready).toMatchObject({
+      status: "ready",
+      sourceCount: 1,
+      entryCount: 2,
+      archiveByteSize: 13,
+      expandedByteSize: 9,
+    });
+
+    const lease = await fixture.port.acquireReadLease(ready.groupId);
+    const manifest = await fixture.port.getManifest(
+      ready.groupId,
+      lease.leaseId,
+    );
+    expect(manifest).toMatchObject({
+      version: "1",
+      entryCount: 2,
+      archiveByteSize: 13,
+      expandedByteSize: 9,
+    });
+    expect(manifest.sources[0]).not.toHaveProperty("fileId");
+
+    const first = await fixture.port.listEntries(ready.groupId, lease.leaseId, {
+      limit: 1,
+    });
+    expect(first.items).toHaveLength(1);
+    expect(first.nextCursor).toBe(first.items[0]?.entryId);
+    const second = await fixture.port.listEntries(
+      ready.groupId,
+      lease.leaseId,
+      { cursor: first.nextCursor, limit: 1 },
+    );
+    expect(second.items).toHaveLength(1);
+    const opened = await fixture.port.openEntry(
+      ready.groupId,
+      lease.leaseId,
+      first.items[0]!.entryId,
+    );
+    expect(await Bun.readableStreamToText(opened.body)).toBe("hello");
+
+    await expect(fixture.port.discard(ready.groupId)).rejects.toMatchObject({
+      code: "REPORT_STAGING_CONFLICT",
+    });
+    fixture.authorized.value = false;
+    await expect(
+      fixture.port.getManifest(ready.groupId, lease.leaseId),
+    ).rejects.toMatchObject({ code: "REPORT_STAGING_FORBIDDEN" });
+    fixture.authorized.value = true;
+    await fixture.port.closeReadLease(ready.groupId, lease.leaseId);
+    expect(await fixture.port.discard(ready.groupId)).toMatchObject({
+      status: "discarded",
+    });
+    expect(
+      fixture.audits.some(({ action }) => action === "report.staging.ready"),
+    ).toBe(true);
+  });
+
+  test("取消释放持久 claim，同一幂等输入从头重扫并封存", async () => {
+    const fixture = await createFixture(new CancelsOnceArchive());
+    await expect(
+      fixture.port.createOrResume(createInput()),
+    ).rejects.toMatchObject({
+      code: "REPORT_STAGING_CANCELLED",
+      retryable: true,
+    });
+    const ready = await fixture.port.createOrResume(createInput());
+    expect(ready.status).toBe("ready");
+    expect(fixture.archive.extractCalls).toBe(2);
+  });
+
+  test("幂等语义漂移、封存文件漂移和 TTL purge 均稳定拒绝", async () => {
+    const fixture = await createFixture();
+    const ready = await fixture.port.createOrResume(createInput());
+    await expect(
+      fixture.port.createOrResume({
+        ...createInput(),
+        entrypoint: "other.rar",
+        sources: [
+          {
+            ...createInput().sources[0]!,
+            relativePath: "other.rar",
+          },
+        ],
+      }),
+    ).rejects.toMatchObject({ code: "REPORT_STAGING_CONFLICT" });
+
+    const lease = await fixture.port.acquireReadLease(ready.groupId);
+    const page = await fixture.port.listEntries(ready.groupId, lease.leaseId);
+    const sealId = (await fixture.repository.getGroup(ready.groupId))?.sealId;
+    expect(sealId).toMatch(/^[0-9a-f]{64}$/);
+    const target = join(
+      fixture.root,
+      "groups",
+      ready.groupId.slice(4, 6),
+      ready.groupId,
+      sealId!,
+      "entries",
+      page.items[0]!.relativePath,
+    );
+    await chmod(target, 0o600);
+    await writeFile(target, "drift");
+    await expect(
+      fixture.port.openEntry(
+        ready.groupId,
+        lease.leaseId,
+        page.items[0]!.entryId,
+      ),
+    ).rejects.toMatchObject({
+      code: "REPORT_STAGING_INTEGRITY_MISMATCH",
+    });
+
+    await fixture.port.closeReadLease(ready.groupId, lease.leaseId);
+    fixture.clock.value += 61_000;
+    expect(await fixture.service.cleanupExpired()).toEqual({
+      purged: 1,
+      pending: 0,
+    });
+    expect(await fixture.port.inspect(ready.groupId)).toMatchObject({
+      status: "discarded",
+    });
+  });
+
+  test.each([
+    ["declared size", new WrongListingArchive("size")],
+    ["entry count", new WrongListingArchive("count")],
+  ])("声明与实际 %s 不一致时不进入 ready", async (_name, archive) => {
+    const fixture = await createFixture(archive);
+    await expect(
+      fixture.port.createOrResume(createInput()),
+    ).rejects.toMatchObject({
+      code: "REPORT_STAGING_INTEGRITY_MISMATCH",
+    });
+    expect(fixture.audits.at(-1)).toEqual({
+      action: "report.staging.failed",
+    });
+  });
+
+  test("声明压缩比超限时不会启动 extraction", async () => {
+    const archive = new ExcessivePreflightArchive();
+    const fixture = await createFixture(archive);
+    await expect(
+      fixture.port.createOrResume(createInput()),
+    ).rejects.toMatchObject({ code: "REPORT_STAGING_LIMIT" });
+    expect(archive.extractCalls).toBe(0);
+  });
+
+  test("archive entrypoint 必须是 sources[0]，后续卷顺序不能由 Host 猜测", async () => {
+    const fixture = await createFixture();
+    const source = createInput().sources[0]!;
+    await expect(
+      fixture.port.createOrResume({
+        ...createInput(),
+        entrypoint: "report.part1.rar",
+        sources: [
+          { ...source, relativePath: "report.part2.rar" },
+          { ...source, relativePath: "report.part1.rar" },
+        ],
+      }),
+    ).rejects.toMatchObject({ code: "REPORT_STAGING_INVALID_INPUT" });
+    expect(fixture.archive).toMatchObject({
+      probeCalls: 0,
+      listCalls: 0,
+      extractCalls: 0,
+    });
+  });
+
+  test("expanded 模式直接封存显式文件，HTML 不会隐式进入归档进程", async () => {
+    const fixture = await createFixture();
+    const ready = await fixture.port.createOrResume({
+      ...createInput(),
+      sourceMode: "expanded",
+      entrypoint: "report/index.html",
+      sources: [
+        {
+          ...createInput().sources[0]!,
+          relativePath: "report/index.html",
+        },
+      ],
+    });
+    expect(ready).toMatchObject({
+      sourceMode: "expanded",
+      status: "ready",
+      sourceCount: 1,
+      entryCount: 1,
+      archiveByteSize: 13,
+      expandedByteSize: 13,
+    });
+    expect(fixture.archive).toMatchObject({
+      probeCalls: 0,
+      listCalls: 0,
+      extractCalls: 0,
+    });
+
+    const lease = await fixture.port.acquireReadLease(ready.groupId);
+    const manifest = await fixture.port.getManifest(
+      ready.groupId,
+      lease.leaseId,
+    );
+    expect(manifest).toMatchObject({
+      sourceMode: "expanded",
+      entrypoint: "report/index.html",
+      sources: [],
+    });
+    const page = await fixture.port.listEntries(ready.groupId, lease.leaseId);
+    expect(page.items[0]).toMatchObject({
+      relativePath: "report/index.html",
+      byteSize: 13,
+    });
+  });
+
+  test("expanded 总量只受 expanded cap 约束，不误用 archive cap", async () => {
+    const fixture = await createFixture(new FakeArchive(), {
+      policy: {
+        ...policy(),
+        maxArchiveBytes: 8,
+        maxExpandedBytes: 64,
+        maxEntryBytes: 64,
+      },
+    });
+    const ready = await fixture.port.createOrResume({
+      ...createInput(),
+      sourceMode: "expanded",
+      entrypoint: "report/index.html",
+      sources: [
+        {
+          ...createInput().sources[0]!,
+          relativePath: "report/index.html",
+        },
+      ],
+    });
+    expect(ready).toMatchObject({
+      status: "ready",
+      archiveByteSize: 13,
+      expandedByteSize: 13,
+    });
+  });
+
+  test("每个 source 流立即受剩余总字节预算约束", async () => {
+    const first = Buffer.from("123456");
+    const declaredSecond = Buffer.from("ab");
+    const driftingSecond = Buffer.from("abcdef");
+    const fixture = await createFixture(new FakeArchive(), {
+      policy: { ...policy(), maxArchiveBytes: 10 },
+      openSource: async ({ fileId }) => {
+        const primary = fileId === "file-1";
+        return {
+          id: fileId,
+          purpose: "evidence.original",
+          filename: `${fileId}.rar`,
+          mimeType: "application/vnd.rar",
+          byteSize: primary ? first.byteLength : declaredSecond.byteLength,
+          sha256: sha256(primary ? first : declaredSecond),
+          body: new Blob([primary ? first : driftingSecond]).stream(),
+        };
+      },
+    });
+    await expect(
+      fixture.port.createOrResume({
+        ...createInput(),
+        sources: [
+          createInput().sources[0]!,
+          {
+            relativePath: "report.r00",
+            file: {
+              ...createInput().sources[0]!.file,
+              fileId: "file-2",
+              resourceId: "evidence-2",
+            },
+          },
+        ],
+      }),
+    ).rejects.toMatchObject({ code: "REPORT_STAGING_LIMIT" });
+  });
+
+  test("inspect 核对策略摘要，close/discard 在策略漂移后仍可清理", async () => {
+    const fixture = await createFixture();
+    const ready = await fixture.port.createOrResume(createInput());
+    const lease = await fixture.port.acquireReadLease(ready.groupId);
+    fixture.policies.set(policy().purpose, {
+      ...policy(),
+      maxExpandedBytes: policy().maxExpandedBytes - 1,
+    });
+
+    await expect(fixture.port.inspect(ready.groupId)).rejects.toMatchObject({
+      code: "REPORT_STAGING_CONFLICT",
+    });
+    await expect(
+      fixture.port.closeReadLease(ready.groupId, lease.leaseId),
+    ).resolves.toBeUndefined();
+    await expect(fixture.port.discard(ready.groupId)).resolves.toMatchObject({
+      status: "discarded",
+    });
+  });
+});