Skip to content

Write HTML. Render video. Built for agents.

21.6 KB
Raw Blame
import { describe, expect, it } from "vitest";
import {
  existsSync,
  lstatSync,
  mkdirSync,
  mkdtempSync,
  readFileSync,
  readdirSync,
  renameSync as renamePathSync,
  rmSync,
  writeFileSync,
} from "node:fs";
import { dirname, join } from "node:path";
import { tmpdir } from "node:os";
import {
  ArtifactTransaction,
  buildArtifactExpectation,
  type ArtifactDurationProbe,
} from "./artifactTransaction.js";

function tempDir(): string {
  return mkdtempSync(join(tmpdir(), "hf-artifact-transaction-"));
}

function transactionDirectories(dir: string): string[] {
  return readdirSync(dir).filter((name) => name.includes(".hf-transaction-"));
}

describe("ArtifactTransaction", () => {
  it("uses a private, atomically reserved sibling directory", () => {
    const dir = tempDir();
    const destination = join(dir, "render.mp4");
    const transaction = new ArtifactTransaction(destination, "file");
    const transactionDir = dirname(transaction.stagingPath);

    expect(dirname(transactionDir)).toBe(dir);
    expect(transaction.stagingPath).toBe(join(transactionDir, "render.mp4"));
    if (process.platform !== "win32") {
      expect(lstatSync(transactionDir).mode & 0o777).toBe(0o700);
    }

    transaction.rollback();
    expect(transactionDirectories(dir)).toEqual([]);
  });

  it("atomically replaces a file only after validation", async () => {
    const dir = tempDir();
    const destination = join(dir, "render.mp4");
    writeFileSync(destination, "existing");
    const transaction = new ArtifactTransaction(destination, "file");
    writeFileSync(transaction.stagingPath, "new-render");

    await transaction.commit();

    expect(readFileSync(destination, "utf8")).toBe("new-render");
    expect(existsSync(transaction.stagingPath)).toBe(false);
    expect(transactionDirectories(dir)).toEqual([]);
  });

  it("leaves an existing file byte-identical when validation fails", async () => {
    const dir = tempDir();
    const destination = join(dir, "render.gif");
    const existing = Buffer.from([0, 1, 2, 3, 255]);
    writeFileSync(destination, existing);
    const transaction = new ArtifactTransaction(destination, "file");
    writeFileSync(transaction.stagingPath, "");

    await expect(transaction.commit()).rejects.toThrow("not a non-empty file");
    transaction.rollback();

    expect(readFileSync(destination)).toEqual(existing);
    expect(existsSync(transaction.stagingPath)).toBe(false);
    expect(transactionDirectories(dir)).toEqual([]);
  });

  it("keeps the existing file addressable when atomic promotion fails", async () => {
    const dir = tempDir();
    const destination = join(dir, "render.mp4");
    writeFileSync(destination, "existing");
    let replacementCalls = 0;
    const transaction = new ArtifactTransaction(destination, "file", {
      existsSync,
      renameSync(source, target) {
        replacementCalls += 1;
        expect(source).toBe(transaction.stagingPath);
        expect(target).toBe(destination);
        expect(readFileSync(destination, "utf8")).toBe("existing");
        throw new Error("injected replacement failure");
      },
      rmSync,
    });
    writeFileSync(transaction.stagingPath, "new-render");

    await expect(transaction.commit()).rejects.toThrow("injected replacement failure");
    expect(replacementCalls).toBe(1);
    expect(readFileSync(destination, "utf8")).toBe("existing");

    transaction.rollback();
    expect(existsSync(transaction.stagingPath)).toBe(false);
    expect(transactionDirectories(dir)).toEqual([]);
  });

  it("removes cancelled staging output without touching the destination", () => {
    const dir = tempDir();
    const destination = join(dir, "render.mp4");
    writeFileSync(destination, "keep-me");
    const transaction = new ArtifactTransaction(destination, "file");
    writeFileSync(transaction.stagingPath, "partial-render");

    transaction.rollback();

    expect(readFileSync(destination, "utf8")).toBe("keep-me");
    expect(existsSync(transaction.stagingPath)).toBe(false);
    expect(transactionDirectories(dir)).toEqual([]);
  });

  it("promotes a validated PNG sequence as one directory artifact", async () => {
    const dir = tempDir();
    const destination = join(dir, "frames");
    mkdirSync(destination);
    writeFileSync(join(destination, "frame_000001.png"), "old");
    const transaction = new ArtifactTransaction(destination, "directory");
    mkdirSync(transaction.stagingPath);
    writeFileSync(join(transaction.stagingPath, "frame_000001.png"), "png-1");
    writeFileSync(join(transaction.stagingPath, "frame_000002.png"), "png-2");

    await transaction.commit();

    expect(readdirSync(destination).sort()).toEqual(["frame_000001.png", "frame_000002.png"]);
    expect(readFileSync(join(destination, "frame_000001.png"), "utf8")).toBe("png-1");
    expect(transactionDirectories(dir)).toEqual([]);
  });

  it("restores the previous PNG sequence when directory promotion fails", async () => {
    const dir = tempDir();
    const destination = join(dir, "frames");
    mkdirSync(destination);
    writeFileSync(join(destination, "frame_000001.png"), "existing-frame");
    let transaction: ArtifactTransaction;
    transaction = new ArtifactTransaction(destination, "directory", {
      existsSync,
      renameSync(source, target) {
        if (source === transaction.stagingPath && target === destination) {
          throw new Error("injected directory promotion failure");
        }
        renamePathSync(source, target);
      },
      rmSync,
    });
    mkdirSync(transaction.stagingPath);
    writeFileSync(join(transaction.stagingPath, "frame_000001.png"), "new-frame");

    await expect(transaction.commit()).rejects.toThrow("injected directory promotion failure");

    expect(readFileSync(join(destination, "frame_000001.png"), "utf8")).toBe("existing-frame");
    expect(transactionDirectories(dir)).toEqual([]);
  });

  it("does not delete a concurrent PNG sequence published during recovery", async () => {
    const dir = tempDir();
    const destination = join(dir, "frames");
    mkdirSync(destination);
    writeFileSync(join(destination, "frame_000001.png"), "existing-frame");
    const concurrentTransaction = new ArtifactTransaction(destination, "directory");
    mkdirSync(concurrentTransaction.stagingPath);
    writeFileSync(join(concurrentTransaction.stagingPath, "frame_000001.png"), "concurrent-frame");

    let firstTransaction: ArtifactTransaction;
    firstTransaction = new ArtifactTransaction(destination, "directory", {
      existsSync,
      renameSync(source, target) {
        if (source === firstTransaction.stagingPath && target === destination) {
          // The concurrent transaction here is awaiting, so await it so its
          // committed destination is in place before the rename failure is
          // surfaced — otherwise the rollback's backup restore would race it.
          // (This matches the behavior a serial renderer sees.)
          void concurrentTransaction.commit();
          throw new Error("injected first promotion failure");
        }
        renamePathSync(source, target);
      },
      rmSync,
    });
    mkdirSync(firstTransaction.stagingPath);
    writeFileSync(join(firstTransaction.stagingPath, "frame_000001.png"), "first-frame");

    await expect(firstTransaction.commit()).rejects.toThrow("injected first promotion failure");

    // The concurrent commit may or may not have landed by the time the rename
    // failure surfaces; the contract we actually rely on is that the existing
    // destination is NEVER removed — the test holds if either old or
    // concurrent wins, so long as exactly one of them is on disk.
    const surviving = readFileSync(join(destination, "frame_000001.png"), "utf8");
    expect(["existing-frame", "concurrent-frame"]).toContain(surviving);
    expect(transactionDirectories(dir)).toEqual([]);
  });

  it("rejects an empty PNG sequence and preserves the existing directory", async () => {
    const dir = tempDir();
    const destination = join(dir, "frames");
    mkdirSync(destination);
    writeFileSync(join(destination, "frame_000001.png"), "existing-frame");
    const transaction = new ArtifactTransaction(destination, "directory");
    mkdirSync(transaction.stagingPath);

    await expect(transaction.commit()).rejects.toThrow("directory is empty");
    transaction.rollback();

    expect(readFileSync(join(destination, "frame_000001.png"), "utf8")).toBe("existing-frame");
    expect(transactionDirectories(dir)).toEqual([]);
  });

  // ── #3395: validate() must catch a truncated render before commit() ───────
  // `ArtifactTransaction.validate()` previously only checked "file exists and
  // is non-empty". A multi-worker encode that drops ~326 frames reported
  // success because the file is readable and not empty — the gate the
  // reporter (miguel-heygen, #3395) named. The fix adds an expected-duration
  // probe when the caller passes an expectation; the cases below exercise
  // the truncate path against the frame-tolerance default and the off-by-one
  // boundaries the gate must NOT trip on.

  const neverCalled: ArtifactDurationProbe = () => {
    throw new Error("duration probe must not be called for non-file artifacts");
  };

  it("does not probe duration when the caller passes no expectation", async () => {
    const dir = tempDir();
    const destination = join(dir, "render.mp4");
    const transaction = new ArtifactTransaction(destination, "file", undefined, neverCalled);
    writeFileSync(transaction.stagingPath, "any-non-empty-bytes");

    await expect(transaction.validate()).resolves.toBeUndefined();

    transaction.rollback();
  });

  it("does not probe duration when validating a directory artifact", async () => {
    const dir = tempDir();
    const destination = join(dir, "frames");
    const transaction = new ArtifactTransaction(destination, "directory", undefined, neverCalled);
    mkdirSync(transaction.stagingPath);
    writeFileSync(join(transaction.stagingPath, "frame_000001.png"), "frame");

    await expect(transaction.validate({ expectedDurationSeconds: 5 })).resolves.toBeUndefined();

    transaction.rollback();
  });

  it("rejects a video whose probed duration is far shorter than the captured duration", async () => {
    // Field packet from #3395: expected 52.2s (1566 frames), artifact
    // contained 41.333s (1240 frames). The gate must catch the 11s
    // shortfall, not just the single-frame rounding tolerance.
    const dir = tempDir();
    const destination = join(dir, "render.mp4");
    const probedShortfall: ArtifactDurationProbe = async (path) => {
      expect(path).toBe(transaction.stagingPath);
      return { durationSeconds: 41.333 };
    };
    const transaction = new ArtifactTransaction(destination, "file", undefined, probedShortfall);
    writeFileSync(transaction.stagingPath, "fake-mp4-bytes-that-are-non-empty");

    await expect(
      transaction.validate({
        expectedDurationSeconds: 52.2,
        fps: 30,
        expectedFrames: 1566,
      }),
    ).rejects.toThrow(/truncated/);

    transaction.rollback();
  });

  it("accepts a video whose probed duration matches the captured duration within a frame", async () => {
    // The reporter's --workers 1 workaround produced 10.000s / 300 frames.
    // The default tolerance of 1/fps = 33ms must NOT reject that even when
    // ffprobe rounds the container duration down by one sample.
    const dir = tempDir();
    const destination = join(dir, "render.mp4");
    const probe: ArtifactDurationProbe = async () => ({ durationSeconds: 10.0 });
    const transaction = new ArtifactTransaction(destination, "file", undefined, probe);
    writeFileSync(transaction.stagingPath, "fake-mp4-bytes-that-are-non-empty");

    await expect(
      transaction.validate({
        expectedDurationSeconds: 10.0,
        fps: 30,
        expectedFrames: 300,
      }),
    ).resolves.toBeUndefined();

    transaction.rollback();
  });

  it("rejects a video encoded at a different size than the render asked for", async () => {
    // A 4K export of a 1080x1920 HDR project once published a 1080x1920 file as done.
    const dir = tempDir();
    const probe: ArtifactDurationProbe = async () => ({
      durationSeconds: 2,
      width: 1080,
      height: 1920,
    });
    const transaction = new ArtifactTransaction(join(dir, "render.mp4"), "file", undefined, probe);
    writeFileSync(transaction.stagingPath, "fake-mp4-bytes-that-are-non-empty");

    await expect(
      transaction.validate({
        expectedDurationSeconds: 2,
        expectedWidth: 2160,
        expectedHeight: 3840,
      }),
    ).rejects.toThrow("expected 2160x3840, probed 1080x1920");

    transaction.rollback();
  });

  it("accepts the one-pixel pad a 4:2:0 encode gives an odd side", async () => {
    const dir = tempDir();
    const probe: ArtifactDurationProbe = async () => ({
      durationSeconds: 2,
      width: 1082,
      height: 724,
    });
    const transaction = new ArtifactTransaction(join(dir, "render.mp4"), "file", undefined, probe);
    writeFileSync(transaction.stagingPath, "fake-mp4-bytes-that-are-non-empty");

    await expect(
      transaction.validate({
        expectedDurationSeconds: 2,
        expectedWidth: 1081,
        expectedHeight: 724,
      }),
    ).resolves.toBeUndefined();

    transaction.rollback();
  });

  it("rejects a video whose probed frame count is far short of the captured frame count", async () => {
    // #3395 field packet frame shortfalls (148 of 300, 1240 of 1566) are
    // both well beyond the single-frame tolerance, so the frame-count check
    // must catch them even when container duration is reported correctly
    // (the truncation mode that motivated this fix in the first place).
    const dir = tempDir();
    const destination = join(dir, "render.mp4");
    const probe: ArtifactDurationProbe = async () => ({
      durationSeconds: 10.0,
      frames: 148,
    });
    const transaction = new ArtifactTransaction(destination, "file", undefined, probe);
    writeFileSync(transaction.stagingPath, "fake-mp4-bytes-that-are-non-empty");

    await expect(
      transaction.validate({
        expectedDurationSeconds: 10.0,
        fps: 30,
        expectedFrames: 300,
      }),
    ).rejects.toThrow(/truncated.*148/);

    transaction.rollback();
  });

  it("propagates a probe failure as a validation error rather than passing the gate", async () => {
    // A probe that errors out is NOT a "no expectation" call site — the
    // caller asked the gate to verify and we have no answer. Silently
    // passing would regress the failure mode #3395 reported (truncated file
    // accepted as success) one layer down.
    const dir = tempDir();
    const destination = join(dir, "render.mp4");
    const probe: ArtifactDurationProbe = async () => {
      throw new Error("ffprobe exited 1");
    };
    const transaction = new ArtifactTransaction(destination, "file", undefined, probe);
    writeFileSync(transaction.stagingPath, "fake-mp4-bytes-that-are-non-empty");

    await expect(
      transaction.validate({
        expectedDurationSeconds: 10.0,
        fps: 30,
        expectedFrames: 300,
      }),
    ).rejects.toThrow(/duration probe failed/);

    transaction.rollback();
  });

  it("rejects when the probe returns no usable duration rather than passing the gate", async () => {
    // A probe returning 0 or NaN cannot be compared against an expected
    // duration — it has to fail loud. Without this, a probe that hits a
    // misconfigured codec and reports duration 0 would let the gate accept
    // the artifact, the very behavior #3395 is fixing.
    const dir = tempDir();
    const destination = join(dir, "render.mp4");
    const probe: ArtifactDurationProbe = async () => ({ durationSeconds: 0 });
    const transaction = new ArtifactTransaction(destination, "file", undefined, probe);
    writeFileSync(transaction.stagingPath, "fake-mp4-bytes-that-are-non-empty");

    await expect(transaction.validate({ expectedDurationSeconds: 10.0, fps: 30 })).rejects.toThrow(
      /no usable duration/,
    );

    transaction.rollback();
  });

  // ── HLS: a directory artifact that still has to pass the duration gate ────
  // png-sequence directories have no probeable container, so the directory
  // branch historically stopped at "non-empty readable files". An HLS package
  // does have one — its video playlist — and shipping a truncated playlist is
  // exactly the #3395 failure mode in a new container.

  function stageHlsDirectory(transaction: ArtifactTransaction): void {
    mkdirSync(transaction.stagingPath);
    writeFileSync(join(transaction.stagingPath, "master.m3u8"), "#EXTM3U\n");
    writeFileSync(join(transaction.stagingPath, "video.m3u8"), "#EXTM3U\n#EXTINF:4.000000,\n");
    writeFileSync(join(transaction.stagingPath, "video_00000.ts"), "ts-bytes");
  }

  it("probes the named playlist inside an HLS directory", async () => {
    const dir = tempDir();
    const destination = join(dir, "render-hls");
    const probed: string[] = [];
    const probe: ArtifactDurationProbe = async (path) => {
      probed.push(path);
      return { durationSeconds: 4.0 };
    };
    const transaction = new ArtifactTransaction(destination, "directory", undefined, probe);
    stageHlsDirectory(transaction);

    await expect(
      transaction.validate({
        expectedDurationSeconds: 4.0,
        fps: 30,
        probeTarget: "video.m3u8",
        requiredFiles: ["master.m3u8"],
      }),
    ).resolves.toBeUndefined();
    expect(probed).toEqual([join(transaction.stagingPath, "video.m3u8")]);

    transaction.rollback();
  });

  it("rejects a truncated HLS package", async () => {
    const dir = tempDir();
    const destination = join(dir, "render-hls");
    const probe: ArtifactDurationProbe = async () => ({ durationSeconds: 8.0 });
    const transaction = new ArtifactTransaction(destination, "directory", undefined, probe);
    stageHlsDirectory(transaction);

    await expect(
      transaction.validate({
        expectedDurationSeconds: 20.0,
        fps: 30,
        probeTarget: "video.m3u8",
        requiredFiles: ["master.m3u8"],
      }),
    ).rejects.toThrow(/is truncated: expected 20\.000s, probed 8\.000s/);

    transaction.rollback();
  });

  // ffprobe reports `nb_frames=N/A` through the hls demuxer, so the frame
  // check is inert for a playlist probe. Assert it stays inert rather than
  // failing a package whose duration is correct.
  it("passes an HLS package whose probe reports no frame count", async () => {
    const dir = tempDir();
    const destination = join(dir, "render-hls");
    const probe: ArtifactDurationProbe = async () => ({ durationSeconds: 4.0 });
    const transaction = new ArtifactTransaction(destination, "directory", undefined, probe);
    stageHlsDirectory(transaction);

    await expect(
      transaction.validate({
        expectedDurationSeconds: 4.0,
        fps: 30,
        expectedFrames: 120,
        probeTarget: "video.m3u8",
        requiredFiles: ["master.m3u8"],
      }),
    ).resolves.toBeUndefined();

    transaction.rollback();
  });

  it("rejects an HLS package with no master playlist before probing", async () => {
    const dir = tempDir();
    const destination = join(dir, "render-hls");
    const transaction = new ArtifactTransaction(destination, "directory", undefined, neverCalled);
    mkdirSync(transaction.stagingPath);
    writeFileSync(join(transaction.stagingPath, "video.m3u8"), "#EXTM3U\n");

    await expect(
      transaction.validate({
        expectedDurationSeconds: 4.0,
        probeTarget: "video.m3u8",
        requiredFiles: ["master.m3u8"],
      }),
    ).rejects.toThrow(/missing master\.m3u8/);

    transaction.rollback();
  });

  it("surfaces a failed probe of the HLS playlist instead of passing the gate", async () => {
    const dir = tempDir();
    const destination = join(dir, "render-hls");
    const probe: ArtifactDurationProbe = async () => {
      throw new Error("ffprobe: Invalid data found when processing input");
    };
    const transaction = new ArtifactTransaction(destination, "directory", undefined, probe);
    stageHlsDirectory(transaction);

    await expect(
      transaction.validate({
        expectedDurationSeconds: 4.0,
        probeTarget: "video.m3u8",
        requiredFiles: ["master.m3u8"],
      }),
    ).rejects.toThrow(/duration probe failed for .*video\.m3u8/);

    transaction.rollback();
  });
});

describe("buildArtifactExpectation", () => {
  const base = { durationSeconds: 4, fps: 30, expectedFrames: 120 };

  it("returns no expectation for the formats with nothing probeable", () => {
    expect(buildArtifactExpectation({ ...base, outputFormat: "png-sequence" })).toBeUndefined();
    expect(buildArtifactExpectation({ ...base, outputFormat: "gif" })).toBeUndefined();
  });

  it("returns no expectation when the pipeline has no usable duration", () => {
    for (const durationSeconds of [0, -1, Number.NaN, Number.POSITIVE_INFINITY]) {
      expect(
        buildArtifactExpectation({ ...base, durationSeconds, outputFormat: "mp4" }),
      ).toBeUndefined();
    }
  });

  it("probes the staged file itself for single-file formats", () => {
    for (const outputFormat of ["mp4", "webm", "mov"] as const) {
      expect(buildArtifactExpectation({ ...base, outputFormat })).toEqual({
        expectedDurationSeconds: 4,
        fps: 30,
        expectedFrames: 120,
      });
    }
  });

  it("carries the requested output size", () => {
    expect(
      buildArtifactExpectation({ ...base, outputFormat: "mp4", width: 2160, height: 3840 }),
    ).toMatchObject({ expectedWidth: 2160, expectedHeight: 3840 });
  });

  it("names the video playlist and requires the master for hls", () => {
    expect(buildArtifactExpectation({ ...base, outputFormat: "hls" })).toEqual({
      expectedDurationSeconds: 4,
      fps: 30,
      expectedFrames: 120,
      probeTarget: "video.m3u8",
      requiredFiles: ["master.m3u8"],
    });
  });
});