mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 19:36:04 +00:00
* fix(player): stop re-encoding the composition query Every src the player sets goes through withShaderQueryParams, which parsed the author's whole query with URLSearchParams and re-serialised it with toString(). That is a form encoder: it writes a space as +, while callers percent-encode and read back with decodeURIComponent. Those two codecs are not inverses, so any space in any query value arrived corrupted. It ran even when there was nothing to inject. With no shader attributes both params are deleted, so the round-trip was pure loss, on every src, for every consumer. Append the two params to the raw query instead of re-serialising it. The player now hands a composition its query back byte-identical. Empirically space was the only casualty: plus, ampersand, equals, hash, percent, question mark, quotes and non-ASCII all survived a URLSearchParams round-trip. That is narrow, but a space in a headline or in SVG path data is the common case, and invalid path data renders nothing at all. Latent until now: no shipped consumer depended on query preservation, so this surfaced only once compositions began carrying variable payloads. * fix(cli): serve the runtime ahead of every author script injectRuntime appended its script before </body>, so it landed after any inline script the composition carried. At the moment a composition's own script ran, window.__hyperframes was undefined and getVariables() was unreachable: our documented API did not exist at the point authors are told to call it. Served order was gsap at line 6, the composition's init script at 20, the runtime at 37. A probe inside the composition's IIFE recorded hfTypeAtInit undefined with no variable keys, and the element rendered its hardcoded fallback rather than the declared value. The runtime is designed to load early. Its entry assigns __timelines, installs the authored-opacity capture (whose own comment says it must run while the document is still parsing), and exposes __hyperframes synchronously, deferring real work to DOMContentLoaded. End-of-body injection defeated all three, and nothing in it needs a parsed DOM, so no defer is wanted. Injects at head start instead, reusing the placement cascade injectScriptsAtHeadStart already implemented rather than adding a fourth copy of it. Head start rather than the closing tag so the runtime also precedes author scripts inside head. injectRuntime has exactly one consumer, the play server's composition route. Every other surface reaches the runtime through the bundler, which already injects into head, or deliberately serves raw. Two registry blocks had independently worked around this by parsing the authored attribute themselves. Those stay, but the workaround is no longer the only way to read a variable at init.
316 lines
12 KiB
TypeScript
316 lines
12 KiB
TypeScript
import { afterEach, describe, expect, it, vi } from "vitest";
|
|
import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
|
|
import { tmpdir } from "node:os";
|
|
import { join } from "node:path";
|
|
import { Hono } from "hono";
|
|
import type { ProjectDir } from "../utils/project.js";
|
|
|
|
// `registerCompositionRoute` reaches these two studio-server helpers via a
|
|
// module, since both files sit at the same depth under packages/cli/src/.
|
|
//
|
|
// The error class lives inside this `vi.hoisted` block (not a plain top-level
|
|
// `class`) because `vi.mock` factories run during static-import resolution —
|
|
// before any of the test file's own top-level statements execute — so a
|
|
// `class` declared below would still be in its temporal dead zone.
|
|
const mocks = vi.hoisted(() => {
|
|
class FakeProxyTranscodeError extends Error {
|
|
readonly exitCode: number | null;
|
|
readonly stderrTail: string;
|
|
constructor(message: string, exitCode: number | null = null, stderrTail = "") {
|
|
super(message);
|
|
this.name = "ProxyTranscodeError";
|
|
this.exitCode = exitCode;
|
|
this.stderrTail = stderrTail;
|
|
}
|
|
}
|
|
class FakeProxyCapacityError extends FakeProxyTranscodeError {
|
|
constructor(message = "media proxy queue is full") {
|
|
super(message);
|
|
this.name = "ProxyCapacityError";
|
|
}
|
|
}
|
|
return {
|
|
resolveProxy: vi.fn<(projectDir: string, absoluteSourcePath: string) => Promise<string>>(
|
|
// Benign default so `injectMediaCodecMap`'s fire-and-forget pre-warm
|
|
// (called for every hostile map entry) always gets a promise to
|
|
// `.catch()`, even in tests that don't care about the proxy path.
|
|
async () => "/unused-prewarm-proxy-path",
|
|
),
|
|
scanProjectMediaCodecMap: vi.fn<
|
|
(
|
|
...args: unknown[]
|
|
) => Promise<
|
|
Record<
|
|
string,
|
|
{ codecName: string; browserHostile: boolean; representativeMime: string | null }
|
|
>
|
|
>
|
|
>(async () => ({})),
|
|
ProxyTranscodeError: FakeProxyTranscodeError,
|
|
ProxyCapacityError: FakeProxyCapacityError,
|
|
};
|
|
});
|
|
const FakeProxyTranscodeError = mocks.ProxyTranscodeError;
|
|
|
|
const mediaMocks = vi.hoisted(() => ({
|
|
probeAssetCodec: vi.fn(async () => ({
|
|
codecName: "hevc",
|
|
browserHostile: true,
|
|
representativeMime: "video/mp4",
|
|
hasAlpha: false,
|
|
})),
|
|
decideMediaProxyEligibility: vi.fn((facts: { browserHostile: boolean } | null) =>
|
|
facts?.browserHostile ? { eligible: true } : { eligible: false, reason: "browser_safe_codec" },
|
|
),
|
|
isProxyVariant: (value: string) => value === "h264" || value === "vp8",
|
|
isProxyVariantRequest: (value: string) => value === "auto" || value === "h264" || value === "vp8",
|
|
proxyVariantFor: (facts: { hasAlpha?: boolean }) => (facts.hasAlpha ? "vp8" : "h264"),
|
|
resolveProxyVariantRequest: (request: "auto" | "h264" | "vp8", facts: { hasAlpha?: boolean }) => {
|
|
const expected = facts.hasAlpha ? "vp8" : "h264";
|
|
return request === "auto" || request === expected ? expected : null;
|
|
},
|
|
PROXY_VARIANT_CONFIG: {
|
|
h264: { extension: ".mp4", contentType: "video/mp4" },
|
|
vp8: { extension: ".webm", contentType: "video/webm" },
|
|
},
|
|
}));
|
|
|
|
vi.mock("@hyperframes/studio-server/proxy-transcoder", () => ({
|
|
resolveProxy: mocks.resolveProxy,
|
|
ProxyTranscodeError: mocks.ProxyTranscodeError,
|
|
ProxyCapacityError: mocks.ProxyCapacityError,
|
|
}));
|
|
vi.mock("@hyperframes/studio-server/media-codec-map", () => mediaMocks);
|
|
|
|
// The shared injection helper ships as a self-contained dist bundle (its copy
|
|
// of scanProjectMediaCodecMap is inlined), so it must be mocked wholesale —
|
|
// mocking the media-codec-map subpath can't reach inside it. The fake mirrors
|
|
// the real contract (scan → inject tag) via this file's scan mock so the
|
|
// existing injection assertions stay meaningful.
|
|
vi.mock("@hyperframes/studio-server/media-proxy-preview", () => ({
|
|
injectMediaCodecMapIntoHtml: vi.fn(
|
|
async (html: string, projectDir: string, htmlSources: unknown[]) => {
|
|
const map = await mocks.scanProjectMediaCodecMap(projectDir, htmlSources);
|
|
const tag = `<script data-hf-media-codec-map>window.__HF_MEDIA_CODEC_MAP__=${JSON.stringify(map)};</script>`;
|
|
return html.includes("</head>")
|
|
? html.replace("</head>", `${tag}\n</head>`)
|
|
: `${tag}\n${html}`;
|
|
},
|
|
),
|
|
}));
|
|
|
|
const { registerCompositionRoute } = await import("./play.js");
|
|
|
|
let dir: string | undefined;
|
|
|
|
function tmpProject(): ProjectDir {
|
|
dir = mkdtempSync(join(tmpdir(), "hf-play-test-"));
|
|
return { dir, name: "test-project", indexPath: join(dir, "index.html") };
|
|
}
|
|
|
|
afterEach(() => {
|
|
mocks.resolveProxy.mockReset();
|
|
mocks.resolveProxy.mockResolvedValue("/unused-prewarm-proxy-path");
|
|
mocks.scanProjectMediaCodecMap.mockReset();
|
|
mediaMocks.probeAssetCodec.mockClear();
|
|
mediaMocks.decideMediaProxyEligibility.mockClear();
|
|
mocks.scanProjectMediaCodecMap.mockResolvedValue({});
|
|
if (dir) rmSync(dir, { recursive: true, force: true });
|
|
dir = undefined;
|
|
});
|
|
|
|
it("serves direct VP8 proxy requests for alpha sources", async () => {
|
|
const project = tmpProject();
|
|
writeFileSync(join(project.dir, "clip.mov"), "alpha-prores");
|
|
mediaMocks.probeAssetCodec.mockResolvedValueOnce({
|
|
codecName: "prores",
|
|
browserHostile: true,
|
|
representativeMime: "video/quicktime",
|
|
hasAlpha: true,
|
|
});
|
|
const proxyPath = join(project.dir, "proxy.webm");
|
|
writeFileSync(proxyPath, "vp8-alpha-proxy");
|
|
mocks.resolveProxy.mockResolvedValueOnce(proxyPath);
|
|
const app = await buildApp(project, true);
|
|
|
|
const res = await app.request("/composition/clip.mov?hf-proxy=auto");
|
|
|
|
expect(res.status).toBe(200);
|
|
expect(res.headers.get("content-type")).toBe("video/webm");
|
|
expect(mocks.resolveProxy).toHaveBeenCalledWith(
|
|
project.dir,
|
|
join(project.dir, "clip.mov"),
|
|
"vp8",
|
|
);
|
|
});
|
|
|
|
async function buildApp(project: ProjectDir, autoProxy: boolean): Promise<Hono> {
|
|
const app = new Hono();
|
|
await registerCompositionRoute(app, project, autoProxy);
|
|
return app;
|
|
}
|
|
|
|
describe("registerCompositionRoute", () => {
|
|
it("answers a Range request on a plain asset with 206 + the requested byte slice", async () => {
|
|
const project = tmpProject();
|
|
writeFileSync(join(project.dir, "clip.mp4"), Buffer.from("0123456789", "utf-8"));
|
|
const app = await buildApp(project, true);
|
|
|
|
const res = await app.request("/composition/clip.mp4", { headers: { Range: "bytes=2-5" } });
|
|
|
|
expect(res.status).toBe(206);
|
|
expect(res.headers.get("accept-ranges")).toBe("bytes");
|
|
expect(res.headers.get("content-range")).toBe("bytes 2-5/10");
|
|
expect(await res.text()).toBe("2345");
|
|
});
|
|
|
|
it("serves the resolved proxy's bytes for ?hf-proxy=h264 on a hostile asset", async () => {
|
|
const project = tmpProject();
|
|
writeFileSync(join(project.dir, "clip.mp4"), "original-hevc-bytes");
|
|
const proxyPath = join(project.dir, "proxy.mp4");
|
|
writeFileSync(proxyPath, "transcoded-h264-bytes");
|
|
mocks.resolveProxy.mockResolvedValue(proxyPath);
|
|
const app = await buildApp(project, true);
|
|
|
|
const res = await app.request("/composition/clip.mp4?hf-proxy=h264");
|
|
|
|
expect(res.status).toBe(200);
|
|
expect(await res.text()).toBe("transcoded-h264-bytes");
|
|
expect(mocks.resolveProxy).toHaveBeenCalledWith(
|
|
project.dir,
|
|
join(project.dir, "clip.mp4"),
|
|
"h264",
|
|
);
|
|
});
|
|
|
|
it("serves ?hf-proxy=h264 for a .mov hostile asset as Content-Type video/mp4 (the proxy IS mp4)", async () => {
|
|
const project = tmpProject();
|
|
writeFileSync(join(project.dir, "clip.mov"), "original-prores-bytes");
|
|
const proxyPath = join(project.dir, "proxy.mp4");
|
|
writeFileSync(proxyPath, "transcoded-h264-bytes");
|
|
mocks.resolveProxy.mockResolvedValue(proxyPath);
|
|
const app = await buildApp(project, true);
|
|
|
|
const res = await app.request("/composition/clip.mov?hf-proxy=h264");
|
|
|
|
expect(res.status).toBe(200);
|
|
expect(res.headers.get("content-type")).toBe("video/mp4");
|
|
expect(await res.text()).toBe("transcoded-h264-bytes");
|
|
});
|
|
|
|
it.each(["mxf", "mts", "m2ts", "ts"])(
|
|
"recognizes .%s camera/container media as proxy-eligible video",
|
|
async (extension) => {
|
|
const project = tmpProject();
|
|
writeFileSync(join(project.dir, `clip.${extension}`), "hostile-video-bytes");
|
|
const proxyPath = join(project.dir, "proxy.mp4");
|
|
writeFileSync(proxyPath, "transcoded-h264-bytes");
|
|
mocks.resolveProxy.mockResolvedValue(proxyPath);
|
|
const app = await buildApp(project, true);
|
|
|
|
const res = await app.request(`/composition/clip.${extension}?hf-proxy=h264`);
|
|
|
|
expect(res.status).toBe(200);
|
|
expect(await res.text()).toBe("transcoded-h264-bytes");
|
|
},
|
|
);
|
|
|
|
it("answers 502 (not a silent failure) when the proxy transcode fails", async () => {
|
|
const project = tmpProject();
|
|
writeFileSync(join(project.dir, "clip.mp4"), "original-hevc-bytes");
|
|
mocks.resolveProxy.mockRejectedValue(
|
|
new FakeProxyTranscodeError("ffmpeg exited with code 1", 1),
|
|
);
|
|
const app = await buildApp(project, true);
|
|
|
|
const res = await app.request("/composition/clip.mp4?hf-proxy=h264");
|
|
|
|
expect(res.status).toBe(502);
|
|
});
|
|
|
|
it("answers a retryable 503 when the proxy queue is full", async () => {
|
|
const project = tmpProject();
|
|
writeFileSync(join(project.dir, "clip.mp4"), "original-hevc-bytes");
|
|
mocks.resolveProxy.mockRejectedValue(new mocks.ProxyCapacityError());
|
|
const app = await buildApp(project, true);
|
|
|
|
const res = await app.request("/composition/clip.mp4?hf-proxy=h264");
|
|
|
|
expect(res.status).toBe(503);
|
|
expect(res.headers.get("retry-after")).toBe("1");
|
|
});
|
|
|
|
it("404s ?hf-proxy=h264 for a non-video asset without attempting a transcode", async () => {
|
|
const project = tmpProject();
|
|
writeFileSync(join(project.dir, "image.png"), "not-a-video");
|
|
const app = await buildApp(project, true);
|
|
|
|
const res = await app.request("/composition/image.png?hf-proxy=h264");
|
|
|
|
expect(res.status).toBe(404);
|
|
expect(mocks.resolveProxy).not.toHaveBeenCalled();
|
|
});
|
|
|
|
it("serves the runtime script ahead of every author script", async () => {
|
|
// Compositions read `window.__hyperframes.getVariables()` from an inline
|
|
// script at init. A runtime injected before </body> loads after that script,
|
|
// so the documented API is undefined exactly where authors are told to call
|
|
// it. Pin the ordering at the served-document boundary.
|
|
const project = tmpProject();
|
|
writeFileSync(
|
|
join(project.dir, "index.html"),
|
|
[
|
|
'<html><head><script src="https://cdn.example/gsap.js"></script></head>',
|
|
'<body><div id="root"></div>',
|
|
"<script>window.__probe = typeof window.__hyperframes;</script>",
|
|
"</body></html>",
|
|
].join(""),
|
|
);
|
|
const app = await buildApp(project, false);
|
|
|
|
const html = await (await app.request("/composition/index.html")).text();
|
|
|
|
const runtimeIndex = html.indexOf('<script src="/runtime.js">');
|
|
expect(runtimeIndex).toBeGreaterThanOrEqual(0);
|
|
const firstAuthorScriptIndex = html.search(/<script(?! src="\/runtime\.js")/);
|
|
expect(firstAuthorScriptIndex).toBeGreaterThan(runtimeIndex);
|
|
});
|
|
|
|
it("injects __HF_MEDIA_CODEC_MAP__ into served composition HTML", async () => {
|
|
const project = tmpProject();
|
|
writeFileSync(join(project.dir, "index.html"), "<html><head></head><body></body></html>");
|
|
mocks.scanProjectMediaCodecMap.mockResolvedValue({
|
|
"/clip.mp4": {
|
|
codecName: "hevc",
|
|
browserHostile: true,
|
|
representativeMime: 'video/mp4; codecs="hvc1.1.6.L120.B0"',
|
|
},
|
|
});
|
|
const app = await buildApp(project, true);
|
|
|
|
const res = await app.request("/composition/index.html");
|
|
const html = await res.text();
|
|
|
|
expect(html).toContain("__HF_MEDIA_CODEC_MAP__");
|
|
expect(html).toContain("/clip.mp4");
|
|
});
|
|
|
|
it("opt-out (autoProxy=false) skips codec-map injection and 404s the proxy param", async () => {
|
|
const project = tmpProject();
|
|
writeFileSync(join(project.dir, "index.html"), "<html><head></head><body></body></html>");
|
|
writeFileSync(join(project.dir, "clip.mp4"), "original-hevc-bytes");
|
|
mocks.scanProjectMediaCodecMap.mockResolvedValue({
|
|
"/clip.mp4": { codecName: "hevc", browserHostile: true, representativeMime: null },
|
|
});
|
|
const app = await buildApp(project, false);
|
|
|
|
const htmlRes = await app.request("/composition/index.html");
|
|
expect(await htmlRes.text()).not.toContain("__HF_MEDIA_CODEC_MAP__");
|
|
expect(mocks.scanProjectMediaCodecMap).not.toHaveBeenCalled();
|
|
|
|
const proxyRes = await app.request("/composition/clip.mp4?hf-proxy=h264");
|
|
expect(proxyRes.status).toBe(404);
|
|
expect(mocks.resolveProxy).not.toHaveBeenCalled();
|
|
});
|
|
});
|