From d159ec51c0fd48d803ff2dabf1ece6a335a11b4e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miguel=20=C3=81ngel?= Date: Mon, 16 Nov 2026 07:10:02 +0000 Subject: [PATCH] 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 --- .fallowrc.jsonc | 3 + packages/cli/tsup.config.ts | 1 + packages/studio-server/src/createStudioApi.ts | 6 +- .../studio-server/src/helpers/previewReads.ts | 6 +- .../src/helpers/subCompositionBuild.ts | 139 ++++++++++++++++++ .../src/helpers/subCompositionWorker.dev.mjs | 5 + .../src/helpers/subCompositionWorker.ts | 62 ++++++++ .../src/routes/preview.compDeadline.test.ts | 85 +++++++++++ packages/studio-server/src/routes/preview.ts | 99 +++++++------ packages/studio-server/tsup.config.ts | 2 + 10 files changed, 364 insertions(+), 44 deletions(-) create mode 100644 packages/studio-server/src/helpers/subCompositionBuild.ts create mode 100644 packages/studio-server/src/helpers/subCompositionWorker.dev.mjs create mode 100644 packages/studio-server/src/helpers/subCompositionWorker.ts create mode 100644 packages/studio-server/src/routes/preview.compDeadline.test.ts diff --git a/.fallowrc.jsonc b/.fallowrc.jsonc index ef1651174e..bdb3909ab1 100644 --- a/.fallowrc.jsonc +++ b/.fallowrc.jsonc @@ -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. diff --git a/packages/cli/tsup.config.ts b/packages/cli/tsup.config.ts index 11100d2300..d593a195a4 100644 --- a/packages/cli/tsup.config.ts +++ b/packages/cli/tsup.config.ts @@ -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"], diff --git a/packages/studio-server/src/createStudioApi.ts b/packages/studio-server/src/createStudioApi.ts index a099e85498..6a3532fd97 100644 --- a/packages/studio-server/src/createStudioApi.ts +++ b/packages/studio-server/src/createStudioApi.ts @@ -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); diff --git a/packages/studio-server/src/helpers/previewReads.ts b/packages/studio-server/src/helpers/previewReads.ts index cd7ea00e8a..122cfb917f 100644 --- a/packages/studio-server/src/helpers/previewReads.ts +++ b/packages/studio-server/src/helpers/previewReads.ts @@ -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 { const named = new Set(); 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 { diff --git a/packages/studio-server/src/helpers/subCompositionBuild.ts b/packages/studio-server/src/helpers/subCompositionBuild.ts new file mode 100644 index 0000000000..4ec0081576 --- /dev/null +++ b/packages/studio-server/src/helpers/subCompositionBuild.ts @@ -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; +} + +export type SubCompositionJob = BuildJob | FinishJob; +type Result = 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; +} + +/** 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(); +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( + job: J, + deadline: number, + compPath: string, +): Promise> { + 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( + work: Promise, + deadline: number, + compPath: string, +): Promise { + let timer: ReturnType | undefined; + const late = new Promise((_, reject) => { + timer = setTimeout( + () => reject(new SubCompositionDeadlineError(compPath)), + Math.max(0, deadline - performance.now()), + ); + }); + return Promise.race([work, late]).finally(() => clearTimeout(timer)); +} diff --git a/packages/studio-server/src/helpers/subCompositionWorker.dev.mjs b/packages/studio-server/src/helpers/subCompositionWorker.dev.mjs new file mode 100644 index 0000000000..64dad65e04 --- /dev/null +++ b/packages/studio-server/src/helpers/subCompositionWorker.dev.mjs @@ -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"); diff --git a/packages/studio-server/src/helpers/subCompositionWorker.ts b/packages/studio-server/src/helpers/subCompositionWorker.ts new file mode 100644 index 0000000000..73ffe6f768 --- /dev/null +++ b/packages/studio-server/src/helpers/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) }); + } +}); diff --git a/packages/studio-server/src/routes/preview.compDeadline.test.ts b/packages/studio-server/src/routes/preview.compDeadline.test.ts new file mode 100644 index 0000000000..843f682caa --- /dev/null +++ b/packages/studio-server/src/routes/preview.compDeadline.test.ts @@ -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"), ""); +writeFileSync( + join(projectDir, "scenes", "small.html"), + '

Hi

', +); +// A page a shared project could carry: big enough that building it takes seconds. +const cells = '
'.repeat( + 300_000, +); +writeFileSync( + join(projectDir, "scenes", "huge.html"), + `
${cells}
`, +); +// Big enough to take a while, small enough to build inside a patient deadline. +writeFileSync( + join(projectDir, "scenes", "large.html"), + `
${cells.slice(0, cells.length / 30)}
`, +); +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): Promise { + 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(/]*>Hi<\/p>/); + }, 90_000); +}); diff --git a/packages/studio-server/src/routes/preview.ts b/packages/studio-server/src/routes/preview.ts index a8cc8b8fb1..586a090daf 100644 --- a/packages/studio-server/src/routes/preview.ts +++ b/packages/studio-server/src/routes/preview.ts @@ -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 = ``; 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"})});})();`; -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), - `${earlyErrorsScript(adapter.runtimeUrl)}`, + `${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) diff --git a/packages/studio-server/tsup.config.ts b/packages/studio-server/tsup.config.ts index 7e4e98156c..42657ff47b 100644 --- a/packages/studio-server/tsup.config.ts +++ b/packages/studio-server/tsup.config.ts @@ -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",