fix(studio-server): sub-composition previews build off the request thread within a deadline (#7857)

* test(studio-server): a sub-composition build past its deadline is refused off the request thread

* fix(studio-server): sub-composition previews build off the request thread within a deadline

* fix(studio-server): every parse of a sub-composition page runs on the build worker

* test(studio-server): a page built inside its deadline keeps the request thread free

* test(studio-server): a refused page leaves the next one built whole, hf-ids and all

* chore(studio-server): the build worker's comments fit its package's share
This commit is contained in:
Miguel Ángel
2026-11-16 07:10:02 +00:00
committed by GitHub
parent 9f85cf0a25
commit d159ec51c0
10 changed files with 364 additions and 44 deletions
+3
View File
@@ -57,6 +57,9 @@
"packages/producer/src/services/healthWorkerThread.ts",
// Render-setup worker, spawned by path from cancellableProcess.ts.
"packages/cli/src/renderSetupWorker.ts",
// Sub-composition build worker, started by path from subCompositionBuild.ts (.dev.mjs from source under Node).
"packages/studio-server/src/helpers/subCompositionWorker.ts",
"packages/studio-server/src/helpers/subCompositionWorker.dev.mjs",
// Update/skills cache refresh, spawned detached by path from backgroundChecks.ts.
"packages/cli/src/backgroundChecksWorker.ts",
// Parakeet decode worker, spawned by path from whisper/sherpa.ts.
+1
View File
@@ -22,6 +22,7 @@ export default defineConfig({
backgroundChecksWorker: "src/backgroundChecksWorker.ts",
sherpaWorker: "src/whisper/sherpaWorker.ts",
shaderTransitionWorker: "../producer/src/services/shaderTransitionWorker.ts",
subCompositionWorker: "../studio-server/src/helpers/subCompositionWorker.ts",
api: "src/api.ts",
},
format: ["esm"],
@@ -115,6 +115,7 @@ function urlScheme(url: string): string | undefined {
export interface StudioApiOptions extends CaptureSandboxOption {
allowedHosts?: readonly string[];
subCompositionDeadlineMs?: number;
}
export function createStudioApi(adapter: StudioApiAdapter, options: StudioApiOptions = {}): Hono {
@@ -217,7 +218,10 @@ export function createStudioApi(adapter: StudioApiAdapter, options: StudioApiOpt
registerProjectRoutes(api, adapter);
registerFileRoutes(api, adapter);
registerPreviewRoutes(api, adapter, { sandboxThumbnailCaptures });
registerPreviewRoutes(api, adapter, {
sandboxThumbnailCaptures,
subCompositionDeadlineMs: options.subCompositionDeadlineMs,
});
registerLintRoutes(api, adapter);
registerRenderRoutes(api, adapter);
registerThumbnailRoutes(api, adapter);
@@ -75,6 +75,10 @@ export function recordPreviewRead(projectDir: string, filePath: string): void {
}
export function recordPreviewReferences(projectDir: string, html: string): void {
for (const path of previewReferences(html)) recordPreviewRead(projectDir, path);
}
export function previewReferences(html: string): Set<string> {
const named = new Set<string>();
const add = (reference: string) => {
const url = reference.trim();
@@ -112,7 +116,7 @@ export function recordPreviewReferences(projectDir: string, html: string): void
if (isElement(node)) scanElement(node);
}
}
for (const path of named) recordPreviewRead(projectDir, path);
return named;
}
export function recordPreviewBuilt(projectDir: string): void {
@@ -0,0 +1,139 @@
import { existsSync } from "node:fs";
import { dirname, join } from "node:path";
import { fileURLToPath, pathToFileURL } from "node:url";
import { Worker } from "node:worker_threads";
export interface BuildJob {
kind: "build";
projectDir: string;
compPath: string;
compFile: string;
runtimeUrl: string;
baseHref: string;
gsapBaseUrl?: string;
}
export interface FinishJob {
kind: "finish";
html: string;
runtimeUrl: string;
signature: string;
projectDir: string;
compPath: string;
options: { capture: boolean; gsapBaseUrl: string; sandboxedCapture: boolean };
variables?: Record<string, unknown>;
}
export type SubCompositionJob = BuildJob | FinishJob;
type Result<J> = J extends BuildJob ? { html: string; references: string[] } | null : string;
export class SubCompositionDeadlineError extends Error {
constructor(compPath: string) {
super(`${compPath} took too long to build`);
this.name = "SubCompositionDeadlineError";
}
}
export const SUB_COMPOSITION_DEADLINE_MS = 30_000;
interface Pending {
job: SubCompositionJob;
resolve: (result: unknown) => void;
reject: (error: Error) => void;
timer: ReturnType<typeof setTimeout>;
}
/** The worker beside this module: the built .js in dist (studio-server's and the CLI's). From source, Bun runs the
* .ts itself; Node needs the .mjs start, which loads it through tsx (its relative .js imports name .ts files). */
function workerEntry(): URL {
const here = dirname(fileURLToPath(import.meta.url));
const built = join(here, "subCompositionWorker.js");
if (existsSync(built)) return pathToFileURL(built);
const source = process.versions.bun ? "subCompositionWorker.ts" : "subCompositionWorker.dev.mjs";
return pathToFileURL(join(here, source));
}
// Jobs in the order the worker runs them: the first is the one it is running.
const pending = new Map<number, Pending>();
let worker: Worker | null = null;
let nextId = 0;
function startWorker(): Worker {
const started = new Worker(workerEntry());
started.unref();
started.on(
"message",
({ id, result, error }: { id: number; result?: unknown; error?: string }) => {
const job = pending.get(id);
if (!job) return;
pending.delete(id);
clearTimeout(job.timer);
if (error !== undefined) job.reject(new Error(error));
else job.resolve(result);
},
);
started.on("error", (error: unknown) =>
replace(started, error instanceof Error ? error : new Error(String(error))),
);
started.on("exit", (code) => replace(started, new Error(`the build worker exited (${code})`)));
return started;
}
/** Ends `from` if it is still the worker. A crash (`failed`) fails every job it held, since any of them may be what
* crashed it; after the running job's deadline, the rest go to a fresh worker. */
function replace(from: Worker, failed?: Error): void {
if (worker !== from) return;
worker = null;
void from.terminate();
if (failed) {
for (const [id, job] of pending) {
pending.delete(id);
clearTimeout(job.timer);
job.reject(failed);
}
return;
}
if (pending.size === 0) return;
const next = (worker = startWorker());
for (const [id, job] of pending) next.postMessage({ id, job: job.job });
}
/** `job` on the build worker, refused past `deadline` (performance.now() time). Only the running job's deadline ends
* the worker; a queued job past its own is dropped. @param compPath names the page in the refusal */
export function runOffThread<J extends SubCompositionJob>(
job: J,
deadline: number,
compPath: string,
): Promise<Result<J>> {
const id = nextId++;
return new Promise((resolve, reject) => {
const timer = setTimeout(
() => {
const running = pending.keys().next().value === id;
pending.delete(id);
reject(new SubCompositionDeadlineError(compPath));
if (running && worker) replace(worker);
},
Math.max(0, deadline - performance.now()),
);
timer.unref?.();
pending.set(id, { job, resolve: resolve as (result: unknown) => void, reject, timer });
(worker ??= startWorker()).postMessage({ id, job });
});
}
/** `work`, refused past `deadline`; the work itself goes on, as nothing can end it. */
export function withinDeadline<T>(
work: Promise<T>,
deadline: number,
compPath: string,
): Promise<T> {
let timer: ReturnType<typeof setTimeout> | undefined;
const late = new Promise<never>((_, reject) => {
timer = setTimeout(
() => reject(new SubCompositionDeadlineError(compPath)),
Math.max(0, deadline - performance.now()),
);
});
return Promise.race([work, late]).finally(() => clearTimeout(timer));
}
@@ -0,0 +1,5 @@
// The build worker from source under Node: tsx resolves its relative .js imports to the .ts files beside them.
import { register } from "tsx/esm/api";
register();
await import("./subCompositionWorker.ts");
@@ -0,0 +1,62 @@
// Builds sub-composition preview pages off the request thread; the route keeps the host's transform and media probes.
import { readFileSync } from "node:fs";
import { parentPort } from "node:worker_threads";
import { ensureHfIds } from "@hyperframes/parsers/hf-ids";
import { injectStudioPreviewAugmentations, withPreviewRuntime } from "../routes/preview.js";
import { previewReferences } from "./previewReads.js";
import { injectPreviewVariables } from "./previewVariables.js";
import { withRootImportMap } from "./rootImportMap.js";
import { buildSubCompositionHtml } from "./subComposition.js";
import type { BuildJob, FinishJob, SubCompositionJob } from "./subCompositionBuild.js";
/** The page with its runtime and the files it names, hf-ids pinned to the source's; null once the file is gone. */
function build(job: BuildJob): { html: string; references: string[] } | null {
const { projectDir, compPath, compFile, runtimeUrl, baseHref, gsapBaseUrl } = job;
let pinned: string | undefined;
if (/\.html?$/i.test(compPath)) {
try {
pinned = ensureHfIds(readFileSync(compFile, "utf-8"));
} catch {
return null; // removed between the route's stat and this read
}
}
const built = buildSubCompositionHtml(
projectDir,
compPath,
runtimeUrl,
baseHref,
pinned,
gsapBaseUrl,
);
if (!built) return null;
const html = withPreviewRuntime(withRootImportMap(built, baseHref), runtimeUrl);
return { html, references: [...previewReferences(html)] };
}
function finish({
html,
runtimeUrl,
signature,
projectDir,
compPath,
options,
variables,
}: FinishJob): string {
const augmented = injectStudioPreviewAugmentations(
ensureHfIds(html),
runtimeUrl,
signature,
projectDir,
compPath,
options,
);
return variables ? injectPreviewVariables(augmented, variables) : augmented;
}
parentPort?.on("message", ({ id, job }: { id: number; job: SubCompositionJob }) => {
try {
parentPort?.postMessage({ id, result: job.kind === "build" ? build(job) : finish(job) });
} catch (error) {
parentPort?.postMessage({ id, error: error instanceof Error ? error.message : String(error) });
}
});
@@ -0,0 +1,85 @@
// @vitest-environment node
import { afterAll, describe, expect, it } from "vitest";
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { createStudioApi } from "../createStudioApi";
import type { StudioApiAdapter } from "../types";
const projectDir = mkdtempSync(join(tmpdir(), "hf-preview-comp-deadline-"));
mkdirSync(join(projectDir, "scenes"));
writeFileSync(join(projectDir, "index.html"), "<html><head></head><body></body></html>");
writeFileSync(
join(projectDir, "scenes", "small.html"),
'<div data-composition-id="small" data-width="320" data-height="180"><p>Hi</p></div>',
);
// A page a shared project could carry: big enough that building it takes seconds.
const cells = '<div class="c" style="background:url(a.png)"><img src="b.png"></div>'.repeat(
300_000,
);
writeFileSync(
join(projectDir, "scenes", "huge.html"),
`<div data-composition-id="huge" data-width="320" data-height="180">${cells}</div>`,
);
// Big enough to take a while, small enough to build inside a patient deadline.
writeFileSync(
join(projectDir, "scenes", "large.html"),
`<div data-composition-id="large" data-width="320" data-height="180">${cells.slice(0, cells.length / 30)}</div>`,
);
afterAll(() => rmSync(projectDir, { recursive: true, force: true }));
const adapter: StudioApiAdapter = {
listProjects: () => [],
resolveProject: async (id: string) => ({ id, dir: projectDir }),
bundle: async () => null,
lint: async () => ({ findings: [] }),
runtimeUrl: "/api/runtime.js",
rendersDir: () => join(projectDir, "renders"),
startRender: () => ({ id: "job", status: "rendering", progress: 0, outputPath: "/tmp/out.mp4" }),
};
const DEADLINE_MS = 200;
const api = createStudioApi(adapter, { subCompositionDeadlineMs: DEADLINE_MS });
// Both share the one build worker; this one waits for a fresh worker to start.
const patient = createStudioApi(adapter, { subCompositionDeadlineMs: 60_000 });
const comp = (file: string, on = api) =>
on.request(`http://localhost/projects/demo/preview/comp/scenes/${file}`);
/** The longest the request thread went without running a timer while `work` ran. */
async function longestStall(work: Promise<unknown>): Promise<number> {
let last = performance.now();
let longest = 0;
const tick = setInterval(() => {
const now = performance.now();
longest = Math.max(longest, now - last);
last = now;
}, 10);
await work;
clearInterval(tick);
return longest;
}
describe("a sub-composition preview build", () => {
// fails without the fix: the page built on the request thread, holding the server until it finished.
it("past its deadline is refused, and the request thread stays free while it builds", async () => {
let status = 0;
const stall = await longestStall(comp("huge.html").then((res) => (status = res.status)));
expect(status).toBe(503);
expect(stall).toBeLessThan(DEADLINE_MS);
}, 30_000);
// Rames on #7857: the passes after the build parse the page too; they run on the worker as well.
it("inside its deadline is served whole, and the request thread stays free for all of it", async () => {
let res: Response | undefined;
const stall = await longestStall(comp("large.html", patient).then((answer) => (res = answer)));
expect(res?.status).toBe(200);
expect((await res?.text())?.length).toBeGreaterThan(cells.length / 30);
expect(stall).toBeLessThan(DEADLINE_MS);
}, 90_000);
it("after a refused one, the next page still builds", async () => {
expect((await comp("huge.html")).status).toBe(503);
const res = await comp("small.html", patient);
expect(res.status).toBe(200);
expect(await res.text()).toMatch(/<p[^>]*>Hi<\/p>/);
}, 90_000);
});
+57 -42
View File
@@ -48,7 +48,13 @@ import {
import { getMimeType } from "../helpers/mime.js";
import { serveWhileOpen } from "../helpers/servedFiles.js";
import { openRangeEnd } from "../helpers/mediaRange.js";
import { buildSubCompositionHtml, hasBaseElement } from "../helpers/subComposition.js";
import { hasBaseElement } from "../helpers/subComposition.js";
import {
runOffThread,
SUB_COMPOSITION_DEADLINE_MS,
SubCompositionDeadlineError,
withinDeadline,
} from "../helpers/subCompositionBuild.js";
import { withRootImportMap } from "../helpers/rootImportMap.js";
import { withRootPathsRelative } from "../helpers/rootPaths.js";
import {
@@ -156,7 +162,7 @@ function parseStudioMotionManifestContent(content: string): {
}
/** Preview hooks must install before authored head scripts register media consumers. */
function withPreviewRuntime(html: string, runtimeUrl: string): string {
export function withPreviewRuntime(html: string, runtimeUrl: string): string {
const tag = `<script ${RUNTIME_BOOTSTRAP_ATTR}="1" src="${runtimeUrl}"></script>`;
return insertRuntimeTag(stripEmbeddedRuntimeScripts(html), tag, true);
}
@@ -370,9 +376,9 @@ var name=e.error&&e.error.constructor&&e.error.constructor.name,path="";
try{var url=e.filename&&new URL(e.filename,window.location.href);if(url&&url.origin===window.location.origin)path=url.pathname}catch(_){}
kinds.push({name:known[name]===1?name:"other",origin:!path?"unknown":path===runtime?"runtime":path.indexOf("/api/projects/")===0?"project":"studio"})});})();</script>`;
function injectStudioPreviewAugmentations(
export function injectStudioPreviewAugmentations(
html: string,
adapter: StudioApiAdapter,
runtimeUrl: string,
signature: string,
projectDir: string,
activeCompositionPath: string,
@@ -385,7 +391,7 @@ function injectStudioPreviewAugmentations(
)
: injectTagsAtHeadStart(
lazyPreviewImages(html),
`<meta name="${STUDIO_PREVIEW_MARK_META}">${earlyErrorsScript(adapter.runtimeUrl)}`,
`<meta name="${STUDIO_PREVIEW_MARK_META}">${earlyErrorsScript(runtimeUrl)}`,
);
const withFallback = injectGsapCdnFallback(
injectProjectSignature(
@@ -491,7 +497,10 @@ function resolvePreviewGsapBaseUrl(adapter: PreviewApiAdapter): string {
export function registerPreviewRoutes(
api: Hono,
adapter: PreviewApiAdapter,
{ sandboxThumbnailCaptures = false }: { sandboxThumbnailCaptures?: boolean } = {},
{
sandboxThumbnailCaptures = false,
subCompositionDeadlineMs,
}: { sandboxThumbnailCaptures?: boolean; subCompositionDeadlineMs?: number } = {},
): void {
const gsapBaseUrl = resolvePreviewGsapBaseUrl(adapter);
const gsapEtagSalt = `:gsap:${createHash("sha1").update(gsapBaseUrl).digest("hex").slice(0, 12)}`;
@@ -547,7 +556,7 @@ export function registerPreviewRoutes(
// Also covers elements the adapter injected; ids already present are kept.
bundled = injectStudioPreviewAugmentations(
ensureHfIds(await transformPreviewHtml(bundled, adapter, project, mainCompositionPath)),
adapter,
adapter.runtimeUrl,
signature,
project.dir,
mainCompositionPath,
@@ -578,7 +587,7 @@ export function registerPreviewRoutes(
);
let fallbackAugmented = injectStudioPreviewAugmentations(
await transformPreviewHtml(fallbackHtml, adapter, project, fallback.compositionPath),
adapter,
adapter.runtimeUrl,
signature,
project.dir,
fallback.compositionPath,
@@ -639,17 +648,6 @@ export function registerPreviewRoutes(
return c.html(html, 200, previewCacheHeaders(etag));
});
/** Ids minted from the raw file before the build rewrites attributes, so they match the source's;
* in memory only, since a write here reaches the watcher as an outside edit. null: the file vanished. */
function pinSubCompHfIds(compFile: string, compPath: string): string | undefined | null {
if (!/\.html?$/i.test(compPath)) return undefined;
try {
return ensureHfIds(readFileSync(compFile, "utf-8"));
} catch {
return null;
}
}
// Sub-composition preview
// fallow-ignore-next-line complexity
api.get("/projects/:id/preview/comp/*", async (c) => {
@@ -687,30 +685,47 @@ export function registerPreviewRoutes(
});
}
const stamped = pinSubCompHfIds(compFile, compPath);
if (stamped === null) return c.text("not found", 404); // file removed between stat and read
const baseHref = previewBaseHref(project.id);
let html = buildSubCompositionHtml(
project.dir,
compPath,
adapter.runtimeUrl,
baseHref,
stamped,
gsapBaseUrl,
);
if (!html) return c.text("not found", 404);
html = withPreviewRuntime(withRootImportMap(html, baseHref), adapter.runtimeUrl);
recordPreviewReferences(project.dir, html);
html = ensureHfIds(await transformPreviewHtml(html, adapter, project, compPath));
html = injectStudioPreviewAugmentations(html, adapter, signature, project.dir, compPath, {
capture,
gsapBaseUrl,
sandboxedCapture: sandboxThumbnailCaptures,
});
if (previewVariables) html = injectPreviewVariables(html, previewVariables);
html = await injectMediaCodecMap(html, adapter, project.dir, compPath, mediaCodecProbeCache);
return c.html(html, 200, previewCacheHeaders(etag));
// A shared project's page can be anything: every pass that parses it runs on the build worker, and the request
// has one deadline, the host's transform and the media probes included.
const deadline = performance.now() + (subCompositionDeadlineMs ?? SUB_COMPOSITION_DEADLINE_MS);
const job = { projectDir: project.dir, compPath, runtimeUrl: adapter.runtimeUrl };
try {
const built = await runOffThread(
{ kind: "build", ...job, compFile, baseHref, gsapBaseUrl },
deadline,
compPath,
);
if (!built) return c.text("not found", 404);
for (const path of built.references) recordPreviewRead(project.dir, path);
const transformed = await withinDeadline(
transformPreviewHtml(built.html, adapter, project, compPath),
deadline,
compPath,
);
const options = { capture, gsapBaseUrl, sandboxedCapture: sandboxThumbnailCaptures };
const finish = { kind: "finish" as const, ...job, html: transformed, signature, options };
const html = await runOffThread(
{ ...finish, ...(previewVariables && { variables: previewVariables }) },
deadline,
compPath,
);
const probed = injectMediaCodecMap(
html,
adapter,
project.dir,
compPath,
mediaCodecProbeCache,
);
return c.html(
await withinDeadline(probed, deadline, compPath),
200,
previewCacheHeaders(etag),
);
} catch (error) {
if (error instanceof SubCompositionDeadlineError) return c.text(error.message, 503);
throw error;
}
});
// Static asset serving (with range request support for audio/video seeking)
+2
View File
@@ -3,6 +3,8 @@ import { defineConfig } from "tsup";
export default defineConfig({
entry: {
index: "src/index.ts",
// Beside the chunks that start it (subCompositionBuild.ts looks next to itself).
subCompositionWorker: "src/helpers/subCompositionWorker.ts",
"helpers/screenshotClip": "src/helpers/screenshotClip.ts",
"helpers/mediaCodecMap": "src/helpers/mediaCodecMap.ts",
"helpers/proxyTranscoder": "src/helpers/proxyTranscoder.ts",