Files
hyperframes/packages/engine/src/utils/renderProvenance.test.ts
T
Miguel Ángel cdc86117c7 fix(engine): a render from an app that bundles the engine stamps the engine's version (#6686)
* fix(engine): a render from an app that bundles the engine stamps the engine's version

* test(engine): the bundled-layout fixture names a generic app
2026-10-28 17:51:43 +00:00

352 lines
13 KiB
TypeScript

import { spawnSync } from "node:child_process";
import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterEach, beforeEach, describe, expect, it } from "vitest";
import { getFfmpegBinary, getFfprobeBinary } from "./ffmpegBinaries.js";
import {
PROVENANCE_RENDERER_NAME,
PROVENANCE_RENDERER_TAG,
PROVENANCE_VERSION,
PROVENANCE_VERSION_TAG,
readRenderProvenance,
renderProvenanceArgs,
resolveOwnVersionFrom,
} from "./renderProvenance.js";
import {
applyFaststart,
buildEncoderArgs,
encodeFramesChunkedConcat,
muxVideoWithAudio,
} from "../services/chunkEncoder.js";
/** Same probe the ffmpeg-dependent suites use: ask the binary, don't assume it. */
const HAS_FFMPEG = spawnSync(getFfmpegBinary(), ["-version"], { encoding: "utf-8" }).status === 0;
describe("renderProvenanceArgs", () => {
it("tags the renderer and version", () => {
const args = renderProvenanceArgs("out.mp4");
expect(args).toContain(`${PROVENANCE_RENDERER_TAG}=${PROVENANCE_RENDERER_NAME}`);
expect(args).toContain(`${PROVENANCE_VERSION_TAG}=${PROVENANCE_VERSION}`);
});
it("carries nothing that identifies the machine or the project", () => {
// Provenance is renderer identity only. A path, username or composition
// name here would travel with every distributed file.
const values = renderProvenanceArgs("/home/someone/projects/secret-launch/out.mp4")
.filter((a) => a.includes("="))
.join(" ");
expect(values).not.toMatch(/secret-launch|someone|\/home\//);
});
it("adds use_metadata_tags for the mov-family containers only", () => {
for (const ext of ["mp4", "mov", "m4v"]) {
expect(renderProvenanceArgs(`out.${ext}`)).toContain("-movflags");
}
expect(renderProvenanceArgs("out.webm")).not.toContain("-movflags");
});
it("matches the container case-insensitively", () => {
expect(renderProvenanceArgs("OUT.MP4")).toContain("-movflags");
});
it("uses the additive + form so it cannot clobber an earlier -movflags", () => {
// Regression guard. A bare `use_metadata_tags` resets the flag field and
// silently drops `+faststart` set earlier in the same command: tags still
// probe correctly, but the moov atom moves to the end of the file. The
// real-encode case below proves the behaviour; this pins the argument.
const args = renderProvenanceArgs("out.mp4");
expect(args[args.indexOf("-movflags") + 1]).toBe("+use_metadata_tags");
});
});
describe("readRenderProvenance", () => {
it("reads mp4-cased tags", () => {
expect(
readRenderProvenance({ hyperframes_renderer: "hyperframes", hyperframes_version: "1.2.3" }),
).toEqual({ renderer: "hyperframes", version: "1.2.3" });
});
it("reads matroska-uppercased tags", () => {
// Matroska uppercases keys on read; a case-sensitive lookup would work on
// mp4 and miss every webm.
expect(
readRenderProvenance({ HYPERFRAMES_RENDERER: "hyperframes", HYPERFRAMES_VERSION: "1.2.3" }),
).toEqual({ renderer: "hyperframes", version: "1.2.3" });
});
it("returns null when there is no provenance", () => {
expect(readRenderProvenance({ major_brand: "isom" })).toBeNull();
expect(readRenderProvenance(undefined)).toBeNull();
});
});
describe.skipIf(!HAS_FFMPEG)("provenance survives a real encode", () => {
let dir: string;
beforeEach(() => {
dir = mkdtempSync(join(tmpdir(), "hf-provenance-"));
});
afterEach(() => {
rmSync(dir, { recursive: true, force: true });
});
const run = (args: string[]): void => {
const res = spawnSync(getFfmpegBinary(), args, { encoding: "utf-8" });
if (res.status !== 0) throw new Error(`ffmpeg failed: ${res.stderr ?? ""}`);
};
/** Format tags as ffprobe reports them, which is the only thing that counts. */
const formatTags = (file: string): Record<string, string> => {
const res = spawnSync(
getFfprobeBinary(),
["-v", "error", "-show_entries", "format_tags", "-of", "json", "--", file],
{ encoding: "utf-8" },
);
if (res.status !== 0) throw new Error(`ffprobe failed: ${res.stderr ?? ""}`);
const parsed = JSON.parse(res.stdout) as { format?: { tags?: Record<string, string> } };
return parsed.format?.tags ?? {};
};
const source = (): string => {
const src = join(dir, "src.mp4");
run([
"-v",
"error",
"-f",
"lavfi",
"-i",
"testsrc=size=160x120:rate=15:duration=1",
"-c:v",
"libx264",
"-pix_fmt",
"yuv420p",
"-y",
src,
]);
return src;
};
// The whole point of the feature: assert against the encoded file, not the
// argument array. mp4 accepts `-metadata` for an unknown key and then
// silently discards it, so an args-only test passes while every shipped mp4
// carries no provenance at all.
it.each(["mp4", "mov", "webm"])("round-trips through a real %s encode", (ext) => {
const out = join(dir, `out.${ext}`);
const codec = ext === "webm" ? ["-c:v", "libvpx-vp9", "-b:v", "200k"] : ["-c:v", "libx264"];
run([
"-v",
"error",
"-i",
source(),
...codec,
"-pix_fmt",
"yuv420p",
...renderProvenanceArgs(out),
"-y",
out,
]);
expect(readRenderProvenance(formatTags(out))).toEqual({
renderer: PROVENANCE_RENDERER_NAME,
version: PROVENANCE_VERSION,
});
});
it("keeps +faststart working alongside the provenance flag", () => {
// Guards the clobber directly: with a non-additive `use_metadata_tags` the
// tags below still pass while the moov atom silently moves to the end.
const out = join(dir, "faststart.mp4");
run([
"-v",
"error",
"-i",
source(),
"-c",
"copy",
"-movflags",
"+faststart",
...renderProvenanceArgs(out),
"-y",
out,
]);
expect(readRenderProvenance(formatTags(out))).not.toBeNull();
// faststart means the moov atom precedes mdat. Read the whole file and
// compare offsets: both atoms are always present, so a missing one would
// mean the file is malformed rather than merely unoptimised.
const bytes = readFileSync(out);
const moov = bytes.indexOf("moov", 0, "latin1");
const mdat = bytes.indexOf("mdat", 0, "latin1");
expect(moov).toBeGreaterThan(-1);
expect(mdat).toBeGreaterThan(-1);
expect(moov).toBeLessThan(mdat);
});
// The in-process sibling of the distributed-assemble regression. This path
// does its own concat-copy straight to the deliverable, and the concat
// demuxer does not carry the chunks' container metadata through — so for a
// no-audio mov (mux skipped, faststart only copies mov) the concat is the
// last container write and the tags have to be re-asserted there. mp4 would
// hide this: faststart re-muxes it and puts them back.
it("survives the in-process chunked-encode concat for a no-audio mov", async () => {
const framesDir = join(dir, "frames");
mkdirSync(framesDir, { recursive: true });
// 70 frames against a 30-frame chunk size gives 3 chunks, so the concat
// step actually runs. A single chunk would skip it entirely.
run([
"-v",
"error",
"-f",
"lavfi",
"-i",
"testsrc=size=160x120:rate=30:duration=2.34",
"-frames:v",
"70",
"-start_number",
"0",
"-y",
join(framesDir, "frame_%06d.png"),
]);
const out = join(dir, "chunked.mov");
const result = await encodeFramesChunkedConcat(
framesDir,
"frame_%06d.png",
out,
{ fps: { num: 30, den: 1 }, width: 160, height: 120, preset: "ultrafast" },
30,
);
expect(result.success).toBe(true);
expect(readRenderProvenance(formatTags(out))).toEqual({
renderer: PROVENANCE_RENDERER_NAME,
version: PROVENANCE_VERSION,
});
}, 60_000);
it("survives the encode -> mux -> faststart chain that produces a delivered mp4", async () => {
// The stage that actually bites: `muxVideoWithAudio` and `applyFaststart`
// each run their own ffmpeg over the encoder's output. Tagging only at the
// encode stage passes an args test and still ships an mp4 with no
// provenance, because the mux drops unknown keys on the way through.
const encoded = join(dir, "encoded.mp4");
run([
"-v",
"error",
"-i",
source(),
...buildEncoderArgs({ fps: { num: 15, den: 1 }, width: 160, height: 120 }, [], encoded),
]);
expect(readRenderProvenance(formatTags(encoded))).not.toBeNull();
const audio = join(dir, "audio.m4a");
run([
"-v",
"error",
"-f",
"lavfi",
"-i",
"sine=frequency=440:duration=1",
"-c:a",
"aac",
"-y",
audio,
]);
const muxed = join(dir, "muxed.mp4");
expect((await muxVideoWithAudio(encoded, audio, muxed)).success).toBe(true);
expect(readRenderProvenance(formatTags(muxed))).not.toBeNull();
const delivered = join(dir, "delivered.mp4");
expect((await applyFaststart(muxed, delivered)).success).toBe(true);
expect(readRenderProvenance(formatTags(delivered))).toEqual({
renderer: PROVENANCE_RENDERER_NAME,
version: PROVENANCE_VERSION,
});
});
});
describe("resolveOwnVersionFrom", () => {
let root: string;
const write = (rel: string, body: unknown) => {
const dir = join(root, rel);
mkdirSync(dir, { recursive: true });
writeFileSync(join(dir, "package.json"), JSON.stringify(body));
};
beforeEach(() => {
root = mkdtempSync(join(tmpdir(), "hf-version-"));
});
afterEach(() => {
rmSync(root, { recursive: true, force: true });
});
it("finds the version at the package root itself", () => {
write(".", { name: "hyperframes", version: "1.2.3" });
expect(resolveOwnVersionFrom(root)).toBe("1.2.3");
});
it("walks up from a nested build directory — the published <pkg>/dist/ layout", () => {
write(".", { name: "hyperframes", version: "0.8.71" });
mkdirSync(join(root, "dist"), { recursive: true });
expect(resolveOwnVersionFrom(join(root, "dist"))).toBe("0.8.71");
});
it("walks up from the repo src/utils depth too", () => {
write("packages/engine", { name: "@hyperframes/engine", version: "4.5.6" });
mkdirSync(join(root, "packages/engine/src/utils"), { recursive: true });
expect(resolveOwnVersionFrom(join(root, "packages/engine/src/utils"))).toBe("4.5.6");
});
it("IGNORES a foreign package.json above us — the hoisted-install trap", () => {
// This is the whole point of matching on name. A bare "first package.json
// found while walking up" returns 9.9.9 here: a confident wrong version,
// which is the same class of defect as the sentinel it replaces.
write(".", { name: "some-consumer-app", version: "9.9.9" });
mkdirSync(join(root, "node_modules/hyperframes/dist"), { recursive: true });
expect(resolveOwnVersionFrom(join(root, "node_modules/hyperframes/dist"))).toBe("unresolved");
});
it("prefers our own root over a foreign one further up", () => {
write(".", { name: "some-consumer-app", version: "9.9.9" });
write("node_modules/hyperframes", { name: "hyperframes", version: "0.8.71" });
mkdirSync(join(root, "node_modules/hyperframes/dist"), { recursive: true });
expect(resolveOwnVersionFrom(join(root, "node_modules/hyperframes/dist"))).toBe("0.8.71");
});
it("reads the installed engine when an app bundles it into its own dist", () => {
write(".", { name: "some-server-app", version: "0.0.0" });
write("node_modules/@hyperframes/engine", {
name: "@hyperframes/engine",
version: "0.8.212",
exports: { "./package.json": "./package.json" },
});
mkdirSync(join(root, "dist"), { recursive: true });
expect(resolveOwnVersionFrom(join(root, "dist"))).toBe("0.8.212");
});
it("returns the sentinel, not a foreign version, when our root declares none", () => {
write(".", { name: "some-consumer-app", version: "9.9.9" });
write("node_modules/hyperframes", { name: "hyperframes" });
expect(resolveOwnVersionFrom(join(root, "node_modules/hyperframes"))).toBe("unresolved");
});
it("steps over a malformed package.json and keeps walking", () => {
write("pkg", { name: "hyperframes", version: "7.7.7" });
mkdirSync(join(root, "pkg/dist"), { recursive: true });
writeFileSync(join(root, "pkg/dist/package.json"), "{ not json");
expect(resolveOwnVersionFrom(join(root, "pkg/dist"))).toBe("7.7.7");
});
it("returns the sentinel when nothing matches", () => {
mkdirSync(join(root, "a/b/c"), { recursive: true });
expect(resolveOwnVersionFrom(join(root, "a/b/c"))).toBe("unresolved");
});
it("the sentinel is not semver-shaped, so it cannot be read as a version", () => {
expect(resolveOwnVersionFrom(root)).toBe("unresolved");
expect(/^\d+\.\d+\.\d+/.test("unresolved")).toBe(false);
});
});