mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 07:50:13 +00:00
feat(producer): fail a render whose variables the page does not declare (#7548)
* feat(producer): fail a render whose variables the page does not declare * chore(producer): keep the comment share and the dead-code audit clean for the variables check
This commit is contained in:
@@ -11,7 +11,7 @@ import { hideTimedClipsUntilFirstPass, keepInlineHideRulesForOlderShaders } from
|
||||
import { fitTextFontSize } from "../text/fitTextFontSize";
|
||||
import { pretext } from "../text/pretext";
|
||||
import { assetUrl } from "./assetUrl";
|
||||
import { getVariables } from "./getVariables";
|
||||
import { getDeclaredVariableSources, getVariables } from "./getVariables";
|
||||
import { clearRuntimeData, registerRuntimeDataHandler, setRuntimeData } from "./runtimeData";
|
||||
import { runScriptsAfterFonts } from "./afterFonts";
|
||||
import { AFTER_FONTS_SCRIPTS } from "../compiler/scriptRuns";
|
||||
@@ -27,6 +27,7 @@ type HyperframeWindow = Window & {
|
||||
assetUrl: typeof assetUrl;
|
||||
fitTextFontSize: typeof fitTextFontSize;
|
||||
getVariables: typeof getVariables;
|
||||
getDeclaredVariableSources: typeof getDeclaredVariableSources;
|
||||
pretext: typeof pretext;
|
||||
registerRuntimeDataHandler: typeof registerRuntimeDataHandler;
|
||||
setRuntimeData: typeof setRuntimeData;
|
||||
@@ -60,6 +61,7 @@ deferMediaUntilDue();
|
||||
assetUrl,
|
||||
fitTextFontSize,
|
||||
getVariables,
|
||||
getDeclaredVariableSources,
|
||||
pretext,
|
||||
registerRuntimeDataHandler,
|
||||
setRuntimeData,
|
||||
|
||||
@@ -2,7 +2,12 @@
|
||||
* @vitest-environment jsdom
|
||||
*/
|
||||
import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
|
||||
import { getVariables, readDeclaredDefaults, resetUnknownEnumWarnings } from "./getVariables";
|
||||
import {
|
||||
getDeclaredVariableSources,
|
||||
getVariables,
|
||||
readDeclaredDefaults,
|
||||
resetUnknownEnumWarnings,
|
||||
} from "./getVariables";
|
||||
|
||||
const VARIABLES_ATTR = "data-composition-variables";
|
||||
|
||||
@@ -451,3 +456,35 @@ describe("css variable injection (figma brand-token chain)", () => {
|
||||
expect(getVariables()["figma:brand"]).toBe("#445566");
|
||||
});
|
||||
});
|
||||
|
||||
describe("getDeclaredVariableSources", () => {
|
||||
afterEach(() => {
|
||||
setDeclared(null);
|
||||
document.body.innerHTML = "";
|
||||
(window as Window & { __hfVariablesByComp?: unknown }).__hfVariablesByComp = undefined;
|
||||
});
|
||||
|
||||
it("lists <html> first, then every other declarer in document order", () => {
|
||||
setDeclared("[1]");
|
||||
document.body.innerHTML = `<div ${VARIABLES_ATTR}="[2]"></div><p ${VARIABLES_ATTR}="[3]"></p>`;
|
||||
expect(getDeclaredVariableSources()).toEqual(["[1]", "[2]", "[3]"]);
|
||||
});
|
||||
|
||||
it("is empty when nothing declares variables", () => {
|
||||
expect(getDeclaredVariableSources()).toEqual([]);
|
||||
});
|
||||
|
||||
it("leaves out a sub-composition's declaration, which has its own scope", () => {
|
||||
setDeclared("[1]");
|
||||
document.body.innerHTML = `<div data-composition-id="sub"><span ${VARIABLES_ATTR}="[9]"></span></div>`;
|
||||
(window as Window & { __hfVariablesByComp?: unknown }).__hfVariablesByComp = { sub: {} };
|
||||
expect(getDeclaredVariableSources()).toEqual(["[1]"]);
|
||||
});
|
||||
|
||||
it("is the scope getVariables merges, so a later declarer's default wins", () => {
|
||||
setDeclared(JSON.stringify([{ id: "a", type: "string", label: "A", default: "html" }]));
|
||||
document.body.innerHTML = `<div ${VARIABLES_ATTR}='${JSON.stringify([{ id: "a", type: "string", label: "A", default: "div" }])}'></div>`;
|
||||
expect(getVariables()).toEqual({ a: "div" });
|
||||
expect(getDeclaredVariableSources()).toHaveLength(2);
|
||||
});
|
||||
});
|
||||
|
||||
@@ -27,15 +27,7 @@ export function getVariables<
|
||||
>(): Partial<T> {
|
||||
if (typeof document === "undefined") return {} as Partial<T>;
|
||||
|
||||
// <html> first, then any element carrying the attribute (later declarers win), then render-time
|
||||
// overrides. A sub-composition's declaration is its own scope's, read from its scoped table.
|
||||
const declarers = new Set<Element>();
|
||||
if (document.documentElement?.hasAttribute("data-composition-variables")) {
|
||||
declarers.add(document.documentElement);
|
||||
}
|
||||
for (const el of Array.from(document.querySelectorAll("[data-composition-variables]"))) {
|
||||
if (!scopedVariablesFor(el)) declarers.add(el);
|
||||
}
|
||||
const declarers = topLevelDeclarers();
|
||||
const declaredDefaults: Record<string, unknown> = {};
|
||||
for (const el of declarers) {
|
||||
Object.assign(declaredDefaults, readDeclaredDefaults(el));
|
||||
@@ -47,6 +39,30 @@ export function getVariables<
|
||||
return merged as Partial<T>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Top-level declarers: `<html>` first, then others outside a sub-composition's scope; a later one wins.
|
||||
* `getVariables` merges these, and `getDeclaredVariableSources` hands the same elements to a strict render.
|
||||
*/
|
||||
function topLevelDeclarers(): Set<Element> {
|
||||
const declarers = new Set<Element>();
|
||||
if (document.documentElement?.hasAttribute("data-composition-variables")) {
|
||||
declarers.add(document.documentElement);
|
||||
}
|
||||
for (const el of Array.from(document.querySelectorAll("[data-composition-variables]"))) {
|
||||
if (!scopedVariablesFor(el)) declarers.add(el);
|
||||
}
|
||||
return declarers;
|
||||
}
|
||||
|
||||
/** The raw `data-composition-variables` text of each top-level declarer, in precedence order (later wins). */
|
||||
export function getDeclaredVariableSources(): string[] {
|
||||
if (typeof document === "undefined") return [];
|
||||
return Array.from(
|
||||
topLevelDeclarers(),
|
||||
(el) => el.getAttribute("data-composition-variables") ?? "",
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* An enum variable given a value outside its declared `options` is coerced to
|
||||
* the composition's default by the composition's own guard. That fallback is
|
||||
|
||||
@@ -557,3 +557,8 @@ export {
|
||||
pipeLaunchClosedOnMac,
|
||||
sandboxDeniedRemediation,
|
||||
} from "./services/sandboxLaunch.js";
|
||||
export {
|
||||
VariablesInvalidError,
|
||||
type VariablesIssue,
|
||||
type VariablesInvalidMetadata,
|
||||
} from "./services/variablesCheck.js";
|
||||
|
||||
@@ -130,6 +130,7 @@ import {
|
||||
} from "./chromeMemorySampler.js";
|
||||
import { sampleProcessRss } from "../utils/processRss.js";
|
||||
import type { CompositionLengthSource } from "@hyperframes/core/runtime/composition-length";
|
||||
import { assertVariablesMatchPage } from "./variablesCheck.js";
|
||||
export { isMemoryExhaustionError, isTransientBrowserError } from "./captureFailure.js";
|
||||
|
||||
export type { CaptureOptions, CaptureResult, CaptureBufferResult, CapturePerfSummary };
|
||||
@@ -234,6 +235,8 @@ export interface CaptureSession {
|
||||
scriptLoadCauses?: ScriptLoadCause[];
|
||||
/** Uncaught page errors; a timed-out timeline wait with any of these becomes a script failure. */
|
||||
pageErrors: string[];
|
||||
/** True once this session honoured `options.strictVariables`: the check ran and passed. */
|
||||
strictVariablesChecked?: boolean;
|
||||
/** The first VFX chain error; its frames would lack the effect, so it stops the render. */
|
||||
vfxFailure?: string;
|
||||
/** Outcome of the sub-composition timeline wait: ready | timeout | script_failure. */
|
||||
@@ -3078,6 +3081,13 @@ export async function describeThrowSite(
|
||||
return ` [thrown at: ${where}]`;
|
||||
}
|
||||
|
||||
/** When the session asks for strict variables, refuse a render whose variables the page does not declare. */
|
||||
async function checkStrictVariables(session: CaptureSession): Promise<void> {
|
||||
if (!session.options.strictVariables) return;
|
||||
await assertVariablesMatchPage(session.page, session.options.variables);
|
||||
session.strictVariablesChecked = true;
|
||||
}
|
||||
|
||||
export async function initializeSession(session: CaptureSession): Promise<void> {
|
||||
const { page, serverUrl } = session;
|
||||
|
||||
@@ -3220,6 +3230,7 @@ export async function initializeSession(session: CaptureSession): Promise<void>
|
||||
session.config?.playerReadyTimeout ?? DEFAULT_CONFIG.playerReadyTimeout;
|
||||
await pollHfReady(page, pageReadyTimeout);
|
||||
logInitPhase("pollHfReady complete");
|
||||
await checkStrictVariables(session);
|
||||
|
||||
await waitForSubCompositionTimelines(session, page, pageReadyTimeout);
|
||||
logInitPhase(`pollSubCompositionTimelines complete (${session.subTimelineWaitOutcome})`);
|
||||
@@ -3362,6 +3373,7 @@ export async function initializeSession(session: CaptureSession): Promise<void>
|
||||
session.config?.playerReadyTimeout ?? DEFAULT_CONFIG.playerReadyTimeout;
|
||||
await pollHfReady(page, pageReadyTimeout);
|
||||
logInitPhase("pollHfReady complete");
|
||||
await checkStrictVariables(session);
|
||||
|
||||
await waitForSubCompositionTimelines(session, page, pageReadyTimeout);
|
||||
logInitPhase(`pollSubCompositionTimelines complete (${session.subTimelineWaitOutcome})`);
|
||||
|
||||
@@ -0,0 +1,149 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
import type { Page } from "puppeteer-core";
|
||||
import {
|
||||
assertVariablesMatchPage,
|
||||
VariablesInvalidError,
|
||||
variablesIssues,
|
||||
type VariablesIssue,
|
||||
} from "./variablesCheck.js";
|
||||
|
||||
const declare = (...decls: object[]): string => JSON.stringify(decls);
|
||||
const title = { id: "title", type: "string", label: "Title", default: "x" };
|
||||
const speed = { id: "speed", type: "number", label: "Speed", default: 1 };
|
||||
const theme = {
|
||||
id: "theme",
|
||||
type: "enum",
|
||||
label: "Theme",
|
||||
default: "dark",
|
||||
options: [
|
||||
{ value: "dark", label: "Dark" },
|
||||
{ value: "light", label: "Light" },
|
||||
],
|
||||
};
|
||||
|
||||
describe("variablesIssues", () => {
|
||||
it("has nothing to check when the render passes no variables", () => {
|
||||
expect(variablesIssues({}, null)).toEqual([]);
|
||||
});
|
||||
|
||||
it("accepts variables the page declares with matching types", () => {
|
||||
expect(variablesIssues({ title: "Hi", speed: 2 }, [declare(title, speed)])).toEqual([]);
|
||||
});
|
||||
|
||||
it("names a variable the page does not declare", () => {
|
||||
expect(variablesIssues({ titel: "Hi" }, [declare(title)])).toEqual([
|
||||
{ kind: "undeclared", variableId: "titel" },
|
||||
]);
|
||||
});
|
||||
|
||||
it("names the declared and the given type of a mismatch, never the value", () => {
|
||||
const issues = variablesIssues({ speed: "fast and secret" }, [declare(speed)]);
|
||||
expect(issues).toEqual([
|
||||
{ kind: "type-mismatch", variableId: "speed", expected: "number", actual: "string" },
|
||||
]);
|
||||
expect(JSON.stringify(issues)).not.toContain("secret");
|
||||
});
|
||||
|
||||
it("names an enum value outside its options without echoing the value", () => {
|
||||
const issues = variablesIssues({ theme: "purple-secret" }, [declare(theme)]);
|
||||
expect(issues).toEqual([{ kind: "enum-out-of-range", variableId: "theme" }]);
|
||||
});
|
||||
|
||||
it("lets a later declarer win a duplicate id, as the runtime merges them", () => {
|
||||
const first = declare({ ...speed, type: "string", default: "slow" });
|
||||
expect(variablesIssues({ speed: 2 }, [first, declare(speed)])).toEqual([]);
|
||||
expect(variablesIssues({ speed: 2 }, [declare(speed), first])).toHaveLength(1);
|
||||
});
|
||||
|
||||
it("fails closed when the runtime offers no declarations to read", () => {
|
||||
expect(variablesIssues({ title: "Hi" }, null)).toEqual([{ kind: "declarations-unreadable" }]);
|
||||
});
|
||||
|
||||
it.each([["not json"], ['{"id":"title"}']])(
|
||||
"does not call a variable undeclared when a declaration cannot be read (%s)",
|
||||
(broken) => {
|
||||
expect(variablesIssues({ title: "Hi" }, [broken])).toEqual([
|
||||
{ kind: "declarations-unreadable" },
|
||||
]);
|
||||
},
|
||||
);
|
||||
|
||||
it("does not call a variable undeclared when one entry of the list is malformed", () => {
|
||||
const source = declare(speed, { id: "title" });
|
||||
expect(variablesIssues({ title: "Hi" }, [source])).toEqual([
|
||||
{ kind: "declarations-unreadable" },
|
||||
]);
|
||||
expect(variablesIssues({ speed: 2 }, [source])).toEqual([]);
|
||||
});
|
||||
});
|
||||
|
||||
describe("VariablesInvalidError", () => {
|
||||
it("is a user-owned, non-retryable VARIABLES_INVALID the producer can transport", () => {
|
||||
const error = new VariablesInvalidError([{ kind: "undeclared", variableId: "titel" }]);
|
||||
expect(error.code).toBe("VARIABLES_INVALID");
|
||||
expect(error.owner).toBe("user");
|
||||
expect(error.retryable).toBe(false);
|
||||
expect(error.message).toBe('Variable "titel" is not declared in data-composition-variables.');
|
||||
});
|
||||
|
||||
it("keeps ten issues and says how many there were", () => {
|
||||
const undeclared = (n: number): VariablesIssue => ({ kind: "undeclared", variableId: `v${n}` });
|
||||
const error = new VariablesInvalidError([
|
||||
undeclared(0),
|
||||
...Array.from({ length: 24 }, (_, i) => undeclared(i + 1)),
|
||||
]);
|
||||
expect(error.publicMetadata.issues).toHaveLength(10);
|
||||
expect(error.publicMetadata.total).toBe(25);
|
||||
});
|
||||
|
||||
it("cuts a long name and strips control characters before it is carried anywhere", () => {
|
||||
const nameOf = (overrides: Record<string, unknown>): string | undefined => {
|
||||
const [issue] = variablesIssues(overrides, [declare(title)]);
|
||||
return issue && "variableId" in issue ? issue.variableId : undefined;
|
||||
};
|
||||
const long = nameOf({ [`${"a".repeat(200)}\n\u0000b`]: 1 });
|
||||
expect(long).toHaveLength(64);
|
||||
expect([...(long ?? "")].some((ch) => ch.charCodeAt(0) < 32)).toBe(false);
|
||||
expect(nameOf({ "a\nb": 1 })).toBe("a?b");
|
||||
});
|
||||
});
|
||||
|
||||
function pageReturning(value: unknown): Page {
|
||||
return { evaluate: async () => value } as unknown as Page;
|
||||
}
|
||||
|
||||
describe("assertVariablesMatchPage", () => {
|
||||
it("passes without reading the page when there are no variables", async () => {
|
||||
const page = {
|
||||
evaluate: async () => {
|
||||
throw new Error("must not be read");
|
||||
},
|
||||
} as unknown as Page;
|
||||
await expect(assertVariablesMatchPage(page, undefined)).resolves.toBeUndefined();
|
||||
await expect(assertVariablesMatchPage(page, {})).resolves.toBeUndefined();
|
||||
});
|
||||
|
||||
it("passes when the page declares the variables", async () => {
|
||||
await expect(
|
||||
assertVariablesMatchPage(pageReturning([declare(title)]), { title: "Hi" }),
|
||||
).resolves.toBeUndefined();
|
||||
});
|
||||
|
||||
it("refuses with VARIABLES_INVALID naming the variable", async () => {
|
||||
await expect(
|
||||
assertVariablesMatchPage(pageReturning([declare(title)]), { titel: "Hi" }),
|
||||
).rejects.toMatchObject({
|
||||
code: "VARIABLES_INVALID",
|
||||
message: expect.stringContaining("titel"),
|
||||
});
|
||||
});
|
||||
|
||||
it("refuses when the page's runtime cannot list its declarations", async () => {
|
||||
await expect(
|
||||
assertVariablesMatchPage(pageReturning(null), { title: "Hi" }),
|
||||
).rejects.toMatchObject({
|
||||
code: "VARIABLES_INVALID",
|
||||
publicMetadata: { issues: [{ kind: "declarations-unreadable" }] },
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,108 @@
|
||||
import type { Page } from "puppeteer-core";
|
||||
import { readCompositionVariables } from "@hyperframes/parsers/composition";
|
||||
import { validateVariables, type VariableValidationIssue } from "@hyperframes/core";
|
||||
|
||||
const MAX_ISSUES = 10;
|
||||
const MAX_ID_CHARS = 64;
|
||||
|
||||
/** One reason a render's variables were refused. Never carries a value the caller supplied. */
|
||||
export type VariablesIssue =
|
||||
| { kind: "undeclared"; variableId: string }
|
||||
| { kind: "type-mismatch"; variableId: string; expected: string; actual: string }
|
||||
| { kind: "enum-out-of-range"; variableId: string }
|
||||
| { kind: "declarations-unreadable" };
|
||||
|
||||
export interface VariablesInvalidMetadata {
|
||||
issues: VariablesIssue[];
|
||||
/** How many issues there were before the list was cut to its bound. */
|
||||
total: number;
|
||||
}
|
||||
|
||||
/** The render's variables do not match what the page declares, or the declarations could not be read. */
|
||||
export class VariablesInvalidError extends Error {
|
||||
readonly code = "VARIABLES_INVALID" as const;
|
||||
// The producer server reads these off the error for the wire envelope.
|
||||
readonly owner = "user" as const;
|
||||
readonly retryable = false as const;
|
||||
readonly publicMetadata: VariablesInvalidMetadata;
|
||||
|
||||
constructor(issues: readonly [VariablesIssue, ...VariablesIssue[]]) {
|
||||
const shown = issues.slice(0, MAX_ISSUES);
|
||||
super(describeIssue(issues[0]));
|
||||
this.name = "VariablesInvalidError";
|
||||
this.publicMetadata = { issues: shown, total: issues.length };
|
||||
}
|
||||
}
|
||||
|
||||
function describeIssue(issue: VariablesIssue): string {
|
||||
switch (issue.kind) {
|
||||
case "undeclared":
|
||||
return `Variable "${issue.variableId}" is not declared in data-composition-variables.`;
|
||||
case "type-mismatch":
|
||||
return `Variable "${issue.variableId}" expected ${issue.expected}, got ${issue.actual}.`;
|
||||
case "enum-out-of-range":
|
||||
return `Variable "${issue.variableId}" is not one of its declared options.`;
|
||||
case "declarations-unreadable":
|
||||
return "The page's data-composition-variables could not be read, so the variables cannot be checked.";
|
||||
default:
|
||||
return issue satisfies never;
|
||||
}
|
||||
}
|
||||
|
||||
/** A name the caller chose, cut and stripped of control characters before it is echoed anywhere. */
|
||||
function boundedId(id: string): string {
|
||||
return Array.from(id.slice(0, MAX_ID_CHARS), (ch) => {
|
||||
const code = ch.charCodeAt(0);
|
||||
return code < 32 || code === 127 ? "?" : ch;
|
||||
}).join("");
|
||||
}
|
||||
|
||||
function toIssue(issue: VariableValidationIssue): VariablesIssue {
|
||||
const variableId = boundedId(issue.variableId);
|
||||
switch (issue.kind) {
|
||||
case "undeclared":
|
||||
return { kind: "undeclared", variableId };
|
||||
case "type-mismatch":
|
||||
return { kind: "type-mismatch", variableId, expected: issue.expected, actual: issue.actual };
|
||||
case "enum-out-of-range":
|
||||
return { kind: "enum-out-of-range", variableId };
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Issues between `overrides` and the page's declarations (`getDeclaredVariableSources`). Declarations that cannot
|
||||
* all be read never yield "undeclared". Empty overrides need no check.
|
||||
*/
|
||||
export function variablesIssues(
|
||||
overrides: Record<string, unknown>,
|
||||
sources: readonly string[] | null,
|
||||
): VariablesIssue[] {
|
||||
if (Object.keys(overrides).length === 0) return [];
|
||||
if (sources === null) return [{ kind: "declarations-unreadable" }];
|
||||
const read = sources.map(readCompositionVariables);
|
||||
const byId = new Map(read.flatMap((r) => r.declarations).map((decl) => [decl.id, decl]));
|
||||
const issues = validateVariables(overrides, [...byId.values()]).map(toIssue);
|
||||
if (read.every((r) => r.complete)) return issues;
|
||||
return issues.map((issue) =>
|
||||
issue.kind === "undeclared" ? { kind: "declarations-unreadable" } : issue,
|
||||
);
|
||||
}
|
||||
|
||||
/** Read the page's declaration sources through its runtime; null when the runtime does not offer them. */
|
||||
async function readDeclaredVariableSources(page: Page): Promise<string[] | null> {
|
||||
const sources: unknown = await page.evaluate(
|
||||
`window.__hyperframes?.getDeclaredVariableSources?.() ?? null`,
|
||||
);
|
||||
return Array.isArray(sources) && sources.every((s) => typeof s === "string") ? sources : null;
|
||||
}
|
||||
|
||||
/** Throws `VariablesInvalidError` when the render's variables do not match the page; run once the page is ready. */
|
||||
export async function assertVariablesMatchPage(
|
||||
page: Page,
|
||||
overrides: Record<string, unknown> | undefined,
|
||||
): Promise<void> {
|
||||
const values = overrides ?? {};
|
||||
if (Object.keys(values).length === 0) return;
|
||||
const [first, ...rest] = variablesIssues(values, await readDeclaredVariableSources(page));
|
||||
if (first) throw new VariablesInvalidError([first, ...rest]);
|
||||
}
|
||||
@@ -253,6 +253,11 @@ export interface CaptureOptions {
|
||||
* `--variables-file <path>`. Must be a JSON-serializable plain object.
|
||||
*/
|
||||
variables?: Record<string, unknown>;
|
||||
/**
|
||||
* Check `variables` against the page's `data-composition-variables` once it is ready, before any frame;
|
||||
* a mismatch or unreadable declarations end the session with `VariablesInvalidError`. Off by default.
|
||||
*/
|
||||
strictVariables?: boolean;
|
||||
/**
|
||||
* When `true`, the BeginFrame warmup loop driven during page navigation
|
||||
* runs exactly `LOCKED_WARMUP_TICKS` (60) iterations regardless of how
|
||||
|
||||
@@ -13,6 +13,8 @@ export { fontShorthandFamilies, parseFontShorthand } from "./fontShorthand.js";
|
||||
export { decodeUrlPathVariants } from "./utils/urlPath.js";
|
||||
export {
|
||||
parseCompositionVariables,
|
||||
readCompositionVariables,
|
||||
type ReadCompositionVariables,
|
||||
isCompositionVariable,
|
||||
isFontValue,
|
||||
isImageValue,
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
import { describe, it, expect } from "vitest";
|
||||
import { isCompositionVariable, parseCompositionVariables } from "./compositionVariables.js";
|
||||
import {
|
||||
isCompositionVariable,
|
||||
parseCompositionVariables,
|
||||
readCompositionVariables,
|
||||
} from "./compositionVariables.js";
|
||||
import type { CompositionVariable } from "./types.js";
|
||||
|
||||
describe("font/image declaration defaults", () => {
|
||||
@@ -51,3 +55,34 @@ describe("font/image declaration defaults", () => {
|
||||
expect(parseCompositionVariables(element)).toEqual([]);
|
||||
});
|
||||
});
|
||||
|
||||
describe("readCompositionVariables", () => {
|
||||
const title = { id: "title", type: "string", label: "Title", default: "x" };
|
||||
|
||||
it("reads every declaration of a well-formed attribute as complete", () => {
|
||||
expect(readCompositionVariables(JSON.stringify([title]))).toEqual({
|
||||
declarations: [title],
|
||||
complete: true,
|
||||
});
|
||||
});
|
||||
|
||||
it("treats an absent attribute as complete and empty", () => {
|
||||
expect(readCompositionVariables(null)).toEqual({ declarations: [], complete: true });
|
||||
expect(readCompositionVariables("")).toEqual({ declarations: [], complete: true });
|
||||
});
|
||||
|
||||
it("keeps the valid entries and reports incomplete when one is malformed", () => {
|
||||
expect(readCompositionVariables(JSON.stringify([title, { id: "broken" }]))).toEqual({
|
||||
declarations: [title],
|
||||
complete: false,
|
||||
});
|
||||
});
|
||||
|
||||
it("reports incomplete for invalid JSON and for a payload that is not an array", () => {
|
||||
expect(readCompositionVariables("{")).toEqual({ declarations: [], complete: false });
|
||||
expect(readCompositionVariables('{"id":"title"}')).toEqual({
|
||||
declarations: [],
|
||||
complete: false,
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
@@ -76,6 +76,24 @@ export function isCompositionVariable(v: unknown): v is CompositionVariable {
|
||||
return true;
|
||||
}
|
||||
|
||||
export interface ReadCompositionVariables {
|
||||
declarations: CompositionVariable[];
|
||||
complete: boolean;
|
||||
}
|
||||
|
||||
/** Valid declarations in the raw attribute text; `complete` is false when anything in it was dropped or unreadable. */
|
||||
export function readCompositionVariables(raw: string | null | undefined): ReadCompositionVariables {
|
||||
if (!raw) return { declarations: [], complete: true };
|
||||
try {
|
||||
const parsed: unknown = JSON.parse(raw);
|
||||
if (!Array.isArray(parsed)) return { declarations: [], complete: false };
|
||||
const declarations = parsed.filter(isCompositionVariable);
|
||||
return { declarations, complete: declarations.length === parsed.length };
|
||||
} catch {
|
||||
return { declarations: [], complete: false };
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Parse the typed variable declarations from an element's
|
||||
* `data-composition-variables` attribute. Malformed entries (wrong shape,
|
||||
@@ -83,20 +101,7 @@ export function isCompositionVariable(v: unknown): v is CompositionVariable {
|
||||
* absent attribute, invalid JSON, or a non-array payload yields `[]`.
|
||||
*/
|
||||
export function parseCompositionVariables(htmlEl: Element): CompositionVariable[] {
|
||||
const variablesAttr = htmlEl.getAttribute("data-composition-variables");
|
||||
if (!variablesAttr) {
|
||||
return [];
|
||||
}
|
||||
|
||||
try {
|
||||
const parsed = JSON.parse(variablesAttr);
|
||||
if (!Array.isArray(parsed)) {
|
||||
return [];
|
||||
}
|
||||
return parsed.filter(isCompositionVariable);
|
||||
} catch {
|
||||
return [];
|
||||
}
|
||||
return readCompositionVariables(htmlEl.getAttribute("data-composition-variables")).declarations;
|
||||
}
|
||||
|
||||
/**
|
||||
|
||||
@@ -29,6 +29,7 @@
|
||||
"src/services/fileServer.listenError.test.ts",
|
||||
"src/services/healthWorker.test.ts",
|
||||
"src/services/scriptFailureAttribution.test.ts",
|
||||
"src/services/strictVariablesSession.test.ts",
|
||||
"src/services/hyperframeLint.file-race.test.ts",
|
||||
"src/services/assetMediaType.test.ts",
|
||||
"src/services/htmlCompiler.mediaType.test.ts",
|
||||
|
||||
@@ -66,6 +66,24 @@ describe("RenderRequest", () => {
|
||||
).toBe("off");
|
||||
});
|
||||
|
||||
it("carries strictVariables through the in-process and distributed adapters, and refuses a non-boolean", () => {
|
||||
const value = request();
|
||||
value.options.strictVariables = true;
|
||||
expect(renderConfigFromRequest(value).strictVariables).toBe(true);
|
||||
const config = distributedConfigFromRequest(value);
|
||||
expect(config.strictVariables).toBe(true);
|
||||
expect(
|
||||
renderRequestFromDistributedConfig({
|
||||
projectDir: value.projectDir,
|
||||
outputPath: value.outputPath,
|
||||
config,
|
||||
}).options.strictVariables,
|
||||
).toBe(true);
|
||||
expect(() =>
|
||||
parseRenderRequest({ ...value, options: { ...value.options, strictVariables: "yes" } }),
|
||||
).toThrow(/strictVariables must be a boolean/);
|
||||
});
|
||||
|
||||
it("carries the delivery encoder options through every adapter", () => {
|
||||
const value = request();
|
||||
Object.assign(value.options, {
|
||||
|
||||
@@ -68,6 +68,7 @@ export interface RenderRequestOptions {
|
||||
chromaSubsampling?: RenderConfig["chromaSubsampling"];
|
||||
pageMotionBlur?: RenderConfig["pageMotionBlur"];
|
||||
variables?: Record<string, unknown>;
|
||||
strictVariables?: boolean;
|
||||
outputResolution?: CanvasResolution;
|
||||
outputResolutionAspectAgnostic?: boolean;
|
||||
engineConfig: EngineConfig;
|
||||
@@ -216,6 +217,9 @@ function assertRequestOptionObjects(options: Record<string, unknown>): void {
|
||||
if (options.variables !== undefined && !isPlainObject(options.variables)) {
|
||||
throw new Error("Render request variables must be a JSON object");
|
||||
}
|
||||
if (options.strictVariables !== undefined && typeof options.strictVariables !== "boolean") {
|
||||
throw new Error("Render request strictVariables must be a boolean");
|
||||
}
|
||||
if (options.distributed !== undefined) assertDistributedOptions(options.distributed);
|
||||
}
|
||||
|
||||
@@ -350,6 +354,7 @@ export function distributedConfigFromRequest(
|
||||
abortSignal: runtime.abortSignal,
|
||||
planDirSizeLimitBytes: distributed.planDirSizeLimitBytes,
|
||||
variables: options.variables,
|
||||
strictVariables: options.strictVariables,
|
||||
};
|
||||
}
|
||||
|
||||
@@ -400,6 +405,7 @@ export function renderRequestFromDistributedConfig(input: {
|
||||
...optionalProperty("strictness", config.strictness),
|
||||
...optionalProperty("entryFile", config.entryFile),
|
||||
...optionalProperty("variables", config.variables),
|
||||
...optionalProperty("strictVariables", config.strictVariables),
|
||||
} satisfies CreateRenderRequestInput["options"];
|
||||
return createRenderRequest({
|
||||
projectDir: input.projectDir,
|
||||
|
||||
@@ -4,7 +4,7 @@ import {
|
||||
assertVideoExtractionSucceeded,
|
||||
VideoExtractionStageError,
|
||||
} from "./services/render/stages/extractVideosStage.js";
|
||||
import type { ExtractionResult } from "@hyperframes/engine";
|
||||
import { VariablesInvalidError, type ExtractionResult } from "@hyperframes/engine";
|
||||
import { AssetMediaTypeMismatchError } from "./services/assetMediaType.js";
|
||||
import { EncoderInterruptedError } from "./services/render/encoderInterruption.js";
|
||||
import { RenderStageStalledError } from "./services/render/observability.js";
|
||||
@@ -139,3 +139,16 @@ describe("extractSafeRenderErrorCode", () => {
|
||||
).toBeUndefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe("VARIABLES_INVALID", () => {
|
||||
it("is transported with its owner, no retry and bounded issue metadata", () => {
|
||||
const error = new VariablesInvalidError([{ kind: "undeclared", variableId: "titel" }]);
|
||||
expect(extractSafeRenderErrorCode(error)).toBe("VARIABLES_INVALID");
|
||||
expect(extractSafeRenderErrorMetadata(error)).toEqual({
|
||||
errorCode: "VARIABLES_INVALID",
|
||||
errorOwner: "user",
|
||||
retryable: false,
|
||||
errorMetadata: { issues: [{ kind: "undeclared", variableId: "titel" }], total: 1 },
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
@@ -114,6 +114,8 @@ interface RenderInput {
|
||||
* composition's declared defaults, ignoring per-request overrides.
|
||||
*/
|
||||
variables?: Record<string, unknown>;
|
||||
/** Fails with `VARIABLES_INVALID` before any frame if `variables` mismatch the page's declarations. Default off. */
|
||||
strictVariables?: boolean;
|
||||
/**
|
||||
* Output resolution preset (e.g. `landscape-4k`). Drives the same
|
||||
* `resolveDeviceScaleFactor` supersampling path the local CLI uses — Chrome
|
||||
@@ -166,6 +168,12 @@ export function extractSafeRenderErrorMetadata(
|
||||
};
|
||||
}
|
||||
|
||||
function strictVariablesResult(job: RenderJob): { strictVariablesChecked?: boolean } {
|
||||
return job.strictVariablesChecked === undefined
|
||||
? {}
|
||||
: { strictVariablesChecked: job.strictVariablesChecked };
|
||||
}
|
||||
|
||||
function parseServerFps(value: unknown): RenderInput["fps"] {
|
||||
if (typeof value !== "number" && typeof value !== "string") return DEFAULT_SERVER_FPS;
|
||||
const parsed = parseFps(value);
|
||||
@@ -246,7 +254,7 @@ export function parseRenderOptions(body: Record<string, unknown>): Omit<RenderIn
|
||||
chromaSubsampling,
|
||||
} = encoder.ok ? encoder.options : {};
|
||||
|
||||
const { variables, outputResolution, outputResolutionAspectAgnostic } =
|
||||
const { variables, strictVariables, outputResolution, outputResolutionAspectAgnostic } =
|
||||
parseRenderOverrides(body);
|
||||
|
||||
return {
|
||||
@@ -269,6 +277,7 @@ export function parseRenderOptions(body: Record<string, unknown>): Omit<RenderIn
|
||||
format,
|
||||
outputDynamicRange,
|
||||
variables,
|
||||
strictVariables,
|
||||
outputResolution,
|
||||
outputResolutionAspectAgnostic,
|
||||
videoFrameFormat,
|
||||
@@ -287,11 +296,13 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
|
||||
*/
|
||||
function parseRenderOverrides(body: Record<string, unknown>): {
|
||||
variables?: Record<string, unknown>;
|
||||
strictVariables?: boolean;
|
||||
outputResolution?: CanvasResolution;
|
||||
outputResolutionAspectAgnostic?: boolean;
|
||||
} {
|
||||
// Only forward a plain JSON object. Arrays / primitives / null → undefined.
|
||||
const variables = isPlainObject(body.variables) ? body.variables : undefined;
|
||||
const strictVariables = body.strictVariables === true ? true : undefined;
|
||||
// Accept canonical presets and aliases ("4k", "landscape-4k", …).
|
||||
const rawOutputResolution =
|
||||
typeof body.outputResolution === "string" ? body.outputResolution : undefined;
|
||||
@@ -304,7 +315,7 @@ function parseRenderOverrides(body: Record<string, unknown>): {
|
||||
const outputResolutionAspectAgnostic = outputResolution
|
||||
? isAspectAgnosticResolutionAlias(rawOutputResolution)
|
||||
: undefined;
|
||||
return { variables, outputResolution, outputResolutionAspectAgnostic };
|
||||
return { variables, strictVariables, outputResolution, outputResolutionAspectAgnostic };
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -334,6 +345,7 @@ function buildRenderJobConfig(input: RenderInput, outputPath: string, log: Produ
|
||||
strictness: input.strictness,
|
||||
entryFile: input.entryFile,
|
||||
variables: input.variables,
|
||||
strictVariables: input.strictVariables,
|
||||
outputResolution: input.outputResolution,
|
||||
outputResolutionAspectAgnostic: input.outputResolutionAspectAgnostic,
|
||||
videoFrameFormat: input.videoFrameFormat,
|
||||
@@ -413,6 +425,9 @@ function validateRenderOverrides(body: Record<string, unknown>): string | undefi
|
||||
if (body.variables !== undefined && !isPlainObject(body.variables)) {
|
||||
return 'variables must be a JSON object keyed by variable id (e.g. {"title":"Hello"})';
|
||||
}
|
||||
if (body.strictVariables !== undefined && typeof body.strictVariables !== "boolean") {
|
||||
return "strictVariables must be a boolean";
|
||||
}
|
||||
if (
|
||||
body.outputDynamicRange !== undefined &&
|
||||
parseServerOutputDynamicRange(body.outputDynamicRange) === undefined
|
||||
@@ -843,6 +858,7 @@ export function createRenderHandlers(options: HandlerOptions = {}): RenderHandle
|
||||
outcome: job.outcome ?? "completed",
|
||||
warnings: job.warnings,
|
||||
perf: job.perfSummary ?? null,
|
||||
...strictVariablesResult(job),
|
||||
});
|
||||
} catch (error) {
|
||||
const durationMs = Date.now() - t0;
|
||||
@@ -946,6 +962,7 @@ export function createRenderHandlers(options: HandlerOptions = {}): RenderHandle
|
||||
warnings: job.warnings,
|
||||
perf: job.perfSummary ?? null,
|
||||
producerVersion: readProducerVersion(),
|
||||
...strictVariablesResult(job),
|
||||
}),
|
||||
});
|
||||
} catch (error) {
|
||||
|
||||
@@ -308,6 +308,8 @@ export interface DistributedRenderConfig extends Pick<RenderRequestOptions, "pag
|
||||
* rather than mid-plan; the producer-side throw is the fallback.
|
||||
*/
|
||||
variables?: Record<string, unknown>;
|
||||
/** Fails with `VARIABLES_INVALID` before any frame if `variables` mismatch the page's declarations. Default off. */
|
||||
strictVariables?: boolean;
|
||||
}
|
||||
|
||||
/** Shared local representation consumed by both distributed plan transports. */
|
||||
@@ -322,6 +324,8 @@ export interface LocalExecutionPlan extends Partial<ReferenceBackgroundResult> {
|
||||
format: DistributedFormat;
|
||||
ffmpegVersion: string;
|
||||
producerVersion: string;
|
||||
/** Present when `strictVariables` was asked; true only if this producer honoured it. */
|
||||
strictVariablesChecked?: boolean;
|
||||
}
|
||||
|
||||
export interface BuildLocalExecutionPlanOptions {
|
||||
@@ -384,6 +388,8 @@ export interface PlanResult extends Partial<ReferenceBackgroundResult> {
|
||||
format: DistributedFormat;
|
||||
ffmpegVersion: string;
|
||||
producerVersion: string;
|
||||
/** Present when `strictVariables` was asked; true only if this producer honoured it. */
|
||||
strictVariablesChecked?: boolean;
|
||||
}
|
||||
|
||||
/** Applies the same audio correctness policy used by the in-process renderer. */
|
||||
@@ -1228,6 +1234,7 @@ async function compilePlanComposition(
|
||||
logger: config.logger,
|
||||
producerConfig: cfg,
|
||||
variables: config.variables,
|
||||
strictVariables: config.strictVariables,
|
||||
pageMotionBlur: config.pageMotionBlur,
|
||||
});
|
||||
const entryFile = config.entryFile ?? "index.html";
|
||||
@@ -1392,6 +1399,7 @@ async function compilePlanComposition(
|
||||
logPlanStage(log, "reference_background", stageStarted);
|
||||
}
|
||||
compiled = probeResult.compiled;
|
||||
job.strictVariablesChecked = probeResult.strictVariablesChecked;
|
||||
job.duration = probeResult.duration;
|
||||
job.totalFrames = probeResult.totalFrames;
|
||||
const totalFrames = probeResult.totalFrames;
|
||||
@@ -1832,6 +1840,9 @@ export async function buildLocalExecutionPlan(
|
||||
format: config.format,
|
||||
ffmpegVersion,
|
||||
producerVersion,
|
||||
...(job.strictVariablesChecked === undefined
|
||||
? {}
|
||||
: { strictVariablesChecked: job.strictVariablesChecked }),
|
||||
};
|
||||
}
|
||||
|
||||
@@ -1894,5 +1905,8 @@ export async function plan(
|
||||
format: executionPlan.format,
|
||||
ffmpegVersion: executionPlan.ffmpegVersion,
|
||||
producerVersion: executionPlan.producerVersion,
|
||||
...(executionPlan.strictVariablesChecked === undefined
|
||||
? {}
|
||||
: { strictVariablesChecked: executionPlan.strictVariablesChecked }),
|
||||
};
|
||||
}
|
||||
|
||||
@@ -160,6 +160,7 @@ export interface PlanV2WithPublisherOptions {
|
||||
readonly remoteFiles?: BuildLocalExecutionPlanOptions["remoteFiles"];
|
||||
readonly chunksCarryAudio?: boolean;
|
||||
readonly deferAudio?: boolean;
|
||||
readonly onPlanned?: (summary: { readonly strictVariablesChecked?: boolean }) => void;
|
||||
}
|
||||
|
||||
export interface PlanV2MaterializationResult {
|
||||
@@ -772,7 +773,7 @@ export async function planV2WithPublisher(
|
||||
const stagingRoot = createStagingDir(options.stagingParentDir ?? tmpdir(), ".execution-plan-");
|
||||
const digests: PlanFileDigests = new Map();
|
||||
try {
|
||||
await buildLocalExecutionPlan(projectDir, config, stagingRoot, {
|
||||
const planned = await buildLocalExecutionPlan(projectDir, config, stagingRoot, {
|
||||
executionPlanSizeLimitBytes: Number.MAX_SAFE_INTEGER,
|
||||
deferVideoExtraction: true,
|
||||
remoteFiles: options.remoteFiles,
|
||||
@@ -789,6 +790,7 @@ export async function planV2WithPublisher(
|
||||
sliceChunkAudio: true,
|
||||
deferAudio: options.deferAudio,
|
||||
});
|
||||
options.onPlanned?.({ strictVariablesChecked: planned.strictVariablesChecked });
|
||||
return await publishExecutionPlan(stagingRoot, publisher, { digests, log: config.logger });
|
||||
} catch (error) {
|
||||
try {
|
||||
|
||||
@@ -272,6 +272,9 @@ export function validateDistributedRenderConfig(
|
||||
if (config.variables !== undefined) {
|
||||
validateVariablesPayload(config.variables);
|
||||
}
|
||||
if (config.strictVariables !== undefined && typeof config.strictVariables !== "boolean") {
|
||||
throw new InvalidConfigError("config.strictVariables", "must be a boolean");
|
||||
}
|
||||
if (config.engineConfig !== undefined) {
|
||||
try {
|
||||
validateEngineConfigSnapshot(config.engineConfig);
|
||||
|
||||
@@ -444,6 +444,7 @@ export interface SyntheticRenderJobInput {
|
||||
producerConfig?: RenderConfig["producerConfig"];
|
||||
/** Render-time overrides consumed by the plan browser probe. */
|
||||
variables?: RenderConfig["variables"];
|
||||
strictVariables?: RenderConfig["strictVariables"];
|
||||
pageMotionBlur?: RenderConfig["pageMotionBlur"];
|
||||
}
|
||||
|
||||
@@ -472,6 +473,7 @@ export function buildSyntheticRenderJob(input: SyntheticRenderJobInput): RenderJ
|
||||
strictness: input.strictness,
|
||||
producerConfig: input.producerConfig,
|
||||
variables: input.variables,
|
||||
strictVariables: input.strictVariables,
|
||||
pageMotionBlur: input.pageMotionBlur,
|
||||
};
|
||||
return createRenderJob(renderConfig);
|
||||
|
||||
@@ -82,7 +82,7 @@ import {
|
||||
writeCompiledArtifacts,
|
||||
type CompositionMetadata,
|
||||
} from "../shared.js";
|
||||
import type { RenderJob } from "../../renderOrchestrator.js";
|
||||
import type { RenderConfig, RenderJob } from "../../renderOrchestrator.js";
|
||||
import { isActionableProbeFailure } from "./probeFailures.js";
|
||||
import { preflightCompositionAssetMediaTypes } from "../../assetMediaType.js";
|
||||
import { resolveCaptureSurface } from "../captureImageFormat.js";
|
||||
@@ -126,6 +126,7 @@ function durationToFrameCount(duration: number, fps: number): number {
|
||||
}
|
||||
|
||||
export interface ProbeStageResult {
|
||||
strictVariablesChecked: boolean | undefined;
|
||||
/** May be reassigned from `recompileWithResolutions`. */
|
||||
compiled: CompiledComposition;
|
||||
/** Created when `needsBrowser` was true; `null` otherwise. */
|
||||
@@ -325,6 +326,20 @@ function hasRuntimeMediaChanges(html: string): boolean {
|
||||
* that shape is measured statically and must never reach the band's `applied`
|
||||
* cohort (review finding, R4).
|
||||
*/
|
||||
/** A strict render with variables to check needs the loaded page; with none there is nothing to read. */
|
||||
function checksVariablesInBrowser(config: RenderConfig): boolean {
|
||||
return config.strictVariables === true && Object.keys(config.variables ?? {}).length > 0;
|
||||
}
|
||||
|
||||
/** Reported `strictVariables`: undefined if not asked; true if checked or nothing needed checking; else false. */
|
||||
export function strictVariablesAttestation(
|
||||
config: RenderConfig,
|
||||
probeSession: CaptureSession | null,
|
||||
): boolean | undefined {
|
||||
if (config.strictVariables !== true) return undefined;
|
||||
return !checksVariablesInBrowser(config) || probeSession?.strictVariablesChecked === true;
|
||||
}
|
||||
|
||||
export function probeRequiresBrowser(args: {
|
||||
durationSeconds: number;
|
||||
unresolvedCompositionCount: number;
|
||||
@@ -332,8 +347,10 @@ export function probeRequiresBrowser(args: {
|
||||
hasScriptedAudio: boolean;
|
||||
hasVariableMedia: boolean;
|
||||
hasInsertedMedia: boolean;
|
||||
requiresVariablesCheck?: boolean;
|
||||
}): boolean {
|
||||
return (
|
||||
args.requiresVariablesCheck === true ||
|
||||
args.durationSeconds <= 0 ||
|
||||
args.unresolvedCompositionCount > 0 ||
|
||||
args.hasAutoStart ||
|
||||
@@ -405,6 +422,7 @@ export async function runProbeStage(input: ProbeStageInput): Promise<ProbeStageR
|
||||
hasScriptedAudio,
|
||||
hasVariableMedia,
|
||||
hasInsertedMedia,
|
||||
requiresVariablesCheck: checksVariablesInBrowser(job.config),
|
||||
});
|
||||
|
||||
try {
|
||||
@@ -446,6 +464,7 @@ export async function runProbeStage(input: ProbeStageInput): Promise<ProbeStageR
|
||||
job.config.quality,
|
||||
),
|
||||
variables: job.config.variables,
|
||||
strictVariables: job.config.strictVariables,
|
||||
deviceScaleFactor,
|
||||
motionBlur,
|
||||
pageMotionBlur: job.config.pageMotionBlur,
|
||||
@@ -922,6 +941,7 @@ export async function runProbeStage(input: ProbeStageInput): Promise<ProbeStageR
|
||||
}
|
||||
|
||||
return {
|
||||
strictVariablesChecked: strictVariablesAttestation(job.config, probeSession),
|
||||
compiled,
|
||||
fileServer,
|
||||
probeSession,
|
||||
|
||||
@@ -0,0 +1,49 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
import type { CaptureSession } from "@hyperframes/engine";
|
||||
import type { RenderConfig } from "../../renderOrchestrator.js";
|
||||
import { probeRequiresBrowser, strictVariablesAttestation } from "./probeStage.js";
|
||||
|
||||
const noBrowserNeeded = {
|
||||
durationSeconds: 5,
|
||||
unresolvedCompositionCount: 0,
|
||||
hasAutoStart: false,
|
||||
hasScriptedAudio: false,
|
||||
hasVariableMedia: false,
|
||||
hasInsertedMedia: false,
|
||||
};
|
||||
|
||||
const config = (extra: Partial<RenderConfig>): RenderConfig => extra as RenderConfig;
|
||||
const session = (checked: boolean | undefined): CaptureSession =>
|
||||
({ strictVariablesChecked: checked }) as CaptureSession;
|
||||
|
||||
describe("probeRequiresBrowser", () => {
|
||||
it("needs a browser to check variables against the loaded page", () => {
|
||||
expect(probeRequiresBrowser(noBrowserNeeded)).toBe(false);
|
||||
expect(probeRequiresBrowser({ ...noBrowserNeeded, requiresVariablesCheck: true })).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe("strictVariablesAttestation", () => {
|
||||
it("says nothing when strict variables were not asked", () => {
|
||||
expect(strictVariablesAttestation(config({ variables: { a: 1 } }), null)).toBeUndefined();
|
||||
expect(strictVariablesAttestation(config({ strictVariables: false }), null)).toBeUndefined();
|
||||
});
|
||||
|
||||
it("attests a pass when the probe session checked the page", () => {
|
||||
const asked = config({ strictVariables: true, variables: { a: 1 } });
|
||||
expect(strictVariablesAttestation(asked, session(true))).toBe(true);
|
||||
});
|
||||
|
||||
it("does not attest when variables needed checking and no session checked them", () => {
|
||||
const asked = config({ strictVariables: true, variables: { a: 1 } });
|
||||
expect(strictVariablesAttestation(asked, null)).toBe(false);
|
||||
expect(strictVariablesAttestation(asked, session(undefined))).toBe(false);
|
||||
});
|
||||
|
||||
it("attests when there are no variables, which have nothing to check", () => {
|
||||
expect(strictVariablesAttestation(config({ strictVariables: true }), null)).toBe(true);
|
||||
expect(strictVariablesAttestation(config({ strictVariables: true, variables: {} }), null)).toBe(
|
||||
true,
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -481,6 +481,7 @@ export interface RenderConfig {
|
||||
* `--variables-file <path>`. Must be a JSON-serializable plain object.
|
||||
*/
|
||||
variables?: Record<string, unknown>;
|
||||
strictVariables?: boolean;
|
||||
/**
|
||||
* Override the output resolution via Chrome `deviceScaleFactor` (DPR).
|
||||
* The composition's authored dimensions are unchanged. See
|
||||
@@ -791,6 +792,7 @@ export interface RenderStageProgress {
|
||||
|
||||
export interface RenderJob extends Partial<ReferenceBackgroundResult> {
|
||||
id: string;
|
||||
strictVariablesChecked?: boolean;
|
||||
config: RenderConfig;
|
||||
status: RenderStatus;
|
||||
progress: number;
|
||||
@@ -3464,6 +3466,7 @@ async function executeRenderPipeline(input: {
|
||||
compositionHash = computeCompositionObservabilityHash(compiled.html);
|
||||
fileServer = probeResult.fileServer;
|
||||
probeSession = probeResult.probeSession;
|
||||
job.strictVariablesChecked = probeResult.strictVariablesChecked;
|
||||
lastBrowserConsole = probeResult.lastBrowserConsole;
|
||||
let resolvedCaptureBeyondViewport = probeSession?.options.captureBeyondViewport;
|
||||
if (resolvedCaptureBeyondViewport !== undefined) {
|
||||
|
||||
@@ -10,6 +10,7 @@ const SAFE_RENDER_ERROR_CODES = new Set<string>([
|
||||
"RENDER_TOO_SLOW",
|
||||
"RENDER_STAGE_STALLED",
|
||||
"PAGE_NEVER_READY",
|
||||
"VARIABLES_INVALID",
|
||||
]);
|
||||
|
||||
/**
|
||||
|
||||
@@ -0,0 +1,134 @@
|
||||
import { afterAll, beforeAll, describe, expect, it } from "vitest";
|
||||
import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join } from "node:path";
|
||||
import { closeCaptureSession, createCaptureSession, initializeSession } from "@hyperframes/engine";
|
||||
import type { CaptureOptions } from "@hyperframes/engine";
|
||||
import { createFileServer } from "./fileServer.js";
|
||||
import { compileForRender } from "./htmlCompiler.js";
|
||||
import { writeCompiledArtifacts } from "./render/shared.js";
|
||||
|
||||
// Real Chromium on the render path: the compiled page carries the runtime, and the session's own
|
||||
// readiness poll runs before the variables are checked against what the page declares.
|
||||
const DECLARED = JSON.stringify([
|
||||
{ id: "title", type: "string", label: "Title", default: "Hi" },
|
||||
{ id: "speed", type: "number", label: "Speed", default: 1 },
|
||||
]);
|
||||
const page = (htmlAttributes: string) => `<!doctype html>
|
||||
<html ${htmlAttributes}><body style="margin:0">
|
||||
<div data-composition-id="main" data-start="0" data-duration="1" data-width="160" data-height="120" data-no-timeline></div>
|
||||
</body></html>`;
|
||||
|
||||
let root: string;
|
||||
beforeAll(() => {
|
||||
root = mkdtempSync(join(tmpdir(), "hf-strict-variables-"));
|
||||
});
|
||||
afterAll(() => {
|
||||
rmSync(root, { recursive: true, force: true });
|
||||
});
|
||||
|
||||
async function openSession(html: string, options: Partial<CaptureOptions>) {
|
||||
const projectDir = mkdtempSync(join(root, "case-"));
|
||||
const workDir = mkdtempSync(join(root, "work-"));
|
||||
writeFileSync(join(projectDir, "index.html"), html);
|
||||
const compiled = await compileForRender(
|
||||
projectDir,
|
||||
join(projectDir, "index.html"),
|
||||
join(workDir, "downloads"),
|
||||
);
|
||||
writeCompiledArtifacts(compiled, workDir, false);
|
||||
const server = await createFileServer({
|
||||
projectDir,
|
||||
compiledDir: join(workDir, "compiled"),
|
||||
port: 0,
|
||||
});
|
||||
const session = await createCaptureSession(
|
||||
server.url,
|
||||
join(workDir, "frames"),
|
||||
{
|
||||
width: 160,
|
||||
height: 120,
|
||||
fps: { num: 30, den: 1 },
|
||||
format: "jpeg",
|
||||
quality: 80,
|
||||
...options,
|
||||
},
|
||||
null,
|
||||
{ browserGpuMode: "software", playerReadyTimeout: 10_000 },
|
||||
);
|
||||
return {
|
||||
session,
|
||||
close: async () => {
|
||||
await closeCaptureSession(session).catch(() => {});
|
||||
server.close();
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
async function initialize(options: Partial<CaptureOptions>) {
|
||||
const { session, close } = await openSession(
|
||||
page(`data-composition-variables='${DECLARED}'`),
|
||||
options,
|
||||
);
|
||||
try {
|
||||
await initializeSession(session);
|
||||
return session.strictVariablesChecked;
|
||||
} finally {
|
||||
await close();
|
||||
}
|
||||
}
|
||||
|
||||
describe("strictVariables on a capture session", () => {
|
||||
it("lets a session start when the page declares the variables, and says it checked", async () => {
|
||||
expect(
|
||||
await initialize({ variables: { title: "Hello", speed: 2 }, strictVariables: true }),
|
||||
).toBe(true);
|
||||
}, 60_000);
|
||||
|
||||
it("refuses a variable the page does not declare, naming it, before any frame", async () => {
|
||||
await expect(
|
||||
initialize({ variables: { titel: "Hello" }, strictVariables: true }),
|
||||
).rejects.toMatchObject({
|
||||
code: "VARIABLES_INVALID",
|
||||
owner: "user",
|
||||
retryable: false,
|
||||
message: 'Variable "titel" is not declared in data-composition-variables.',
|
||||
});
|
||||
}, 60_000);
|
||||
|
||||
it("refuses a value of the wrong type without echoing it", async () => {
|
||||
const result = initialize({ variables: { speed: "fast-secret" }, strictVariables: true });
|
||||
await expect(result).rejects.toMatchObject({
|
||||
code: "VARIABLES_INVALID",
|
||||
publicMetadata: {
|
||||
issues: [
|
||||
{ kind: "type-mismatch", variableId: "speed", expected: "number", actual: "string" },
|
||||
],
|
||||
},
|
||||
});
|
||||
await expect(result).rejects.not.toThrow(/fast-secret/);
|
||||
}, 60_000);
|
||||
|
||||
it("refuses when the page's declarations cannot be read, not as undeclared", async () => {
|
||||
const { session, close } = await openSession(page(`data-composition-variables='{broken'`), {
|
||||
variables: { title: "Hello" },
|
||||
strictVariables: true,
|
||||
});
|
||||
try {
|
||||
await expect(initializeSession(session)).rejects.toMatchObject({
|
||||
code: "VARIABLES_INVALID",
|
||||
publicMetadata: { issues: [{ kind: "declarations-unreadable" }] },
|
||||
});
|
||||
} finally {
|
||||
await close();
|
||||
}
|
||||
}, 60_000);
|
||||
|
||||
it("checks nothing and still says it checked when there are no variables", async () => {
|
||||
expect(await initialize({ strictVariables: true })).toBe(true);
|
||||
}, 60_000);
|
||||
|
||||
it("does not check, and does not say it did, when strict variables were not asked", async () => {
|
||||
expect(await initialize({ variables: { titel: "Hello" } })).toBeUndefined();
|
||||
}, 60_000);
|
||||
});
|
||||
Reference in New Issue
Block a user