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:
Miguel Ángel
2026-11-11 08:46:13 +00:00
committed by GitHub
parent 9bab57ab48
commit f312fca7e2
25 changed files with 690 additions and 31 deletions
+3 -1
View File
@@ -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,
+38 -1
View File
@@ -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);
});
});
+25 -9
View File
@@ -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
+5
View File
@@ -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]);
}
+5
View File
@@ -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
+2
View File
@@ -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,
});
});
});
+19 -14
View File
@@ -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, {
+6
View File
@@ -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,
+14 -1
View File
@@ -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 },
});
});
});
+19 -2
View File
@@ -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);
});