fix(lint): run Studio and producer lint off the host's own thread (#7974)

* fix(lint): run Studio and producer lint off the host's own thread

A composition that sends the linter's parser into a runaway froze or
crashed the long-lived hosts that lint it in their own process.

CLI Studio's single-page lint now runs in a child process with a heap
cap and a 15 s limit. Producer /lint (runHyperframeLint) runs on a
worker thread with the same limits. A page that times out, runs out of
memory, or whose child or thread ends without an answer gets one
lint_aborted error finding and is never linted in the host process.
Studio's project lint keeps its timeout and gains a heap cap.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* fix(producer): cap concurrent /lint workers at two

Each lint worker can hold up to 512 MB, so parallel /lint requests
multiplied that without bound. At most two run at once; the rest wait
in order, and a request still waiting when its own 15 s runs out gets
the lint_aborted result.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
Vance Ingalls
2026-11-16 12:10:39 -08:00
committed by GitHub
co-authored by Claude Sonnet 5.5
parent 95e4e7f880
commit 778a005641
15 changed files with 439 additions and 18 deletions
+9
View File
@@ -1,6 +1,8 @@
import "./utils/hideChildConsoles.js";
import "./utils/windowsExeSearch.js";
import { readFile, rm } from "node:fs/promises";
import { constants, setPriority } from "node:os";
import { lintHyperframeHtml } from "@hyperframes/lint";
import { runBrowserInstall } from "./browser/installRun.js";
import { ensureBrowser, releaseOwnedBrowserInstallLock } from "./browser/manager.js";
import { lintProject } from "./utils/lintProject.js";
@@ -48,6 +50,13 @@ async function runMode(): Promise<unknown> {
input.host ? { host: input.host } : undefined,
);
}
if (mode === "lint-html") {
try {
return await lintHyperframeHtml(await readFile(input.htmlPath, "utf-8"), input.opts);
} finally {
await rm(input.htmlPath, { force: true });
}
}
if (mode === "orphan-cleanup") {
const killed = killOrphanedProcesses();
if (killed > 0) await new Promise((resolve) => setTimeout(resolve, 600));
@@ -3,12 +3,15 @@ import * as fs from "node:fs";
import * as path from "node:path";
import { tmpdir } from "node:os";
// Studio must lint outside its own process; any in-process project lint fails the request.
// Studio must lint outside its own process; any in-process project or page lint fails the request.
vi.mock("@hyperframes/lint", async (importOriginal) => ({
...(await importOriginal<typeof import("@hyperframes/lint")>()),
lintProject: () => {
throw new Error("project lint ran on the Studio server's event loop");
},
lintHyperframeHtml: () => {
throw new Error("page lint ran on the Studio server's event loop");
},
}));
const { createStudioServer } = await import("./studioServer.js");
@@ -24,6 +27,9 @@ beforeEach(() => {
<div id="root" data-composition-id="main" data-width="320" data-height="180"></div>
</body></html>`,
);
// Not linked from the entry, so the project lint skips it and the route lints it as a page.
fs.mkdirSync(path.join(root, "loose"));
fs.writeFileSync(path.join(root, "loose", "page.html"), `<div>no composition</div>`);
server = createStudioServer({ projectDir: root, projectName: "film" });
});
@@ -40,4 +46,12 @@ describe("studio lint", () => {
expect(response.status).toBe(200);
expect(body.findings?.some((f) => f.message.includes("window.__timelines"))).toBe(true);
}, 60_000);
it("lints a page the project lint skips in a separate process too", async () => {
const response = await server.app.request("/api/projects/film/lint");
const body = (await response.json()) as { findings?: Array<{ file?: string }> };
expect(response.status).toBe(200);
expect(body.findings?.some((f) => f.file === "loose/page.html")).toBe(true);
}, 60_000);
});
+9 -5
View File
@@ -49,6 +49,7 @@ import { recordFolder } from "../utils/projectRecords.js";
import { outsideAssetsAllowed } from "../utils/receivedRender.js";
import { insideHostApp } from "../utils/desktopApp.js";
import { runRenderSetupWorker } from "../utils/cancellableProcess.js";
import { lintHtmlOutOfProcess } from "../utils/lintHtmlWorker.js";
import { acquireRenderLock, describeRenderLockHolder } from "../utils/renderLock.js";
import type { ProjectLintResult } from "@hyperframes/lint";
import { resolveRenderBrowser } from "../browser/preflight.js";
@@ -110,6 +111,7 @@ const STUDIO_MANUAL_EDITS_PATH = ".hyperframes/studio-manual-edits.json";
const RENDER_SHUTDOWN_WAIT_MS = 2_000;
const LINT_WORKER_TIMEOUT_MS = 120_000;
const LINT_WORKER_HEAP_MB = 1024;
// Vite emits only content-hashed files under dist/assets; hand-authored
// public/ files land at the dist root. The route is the signal because the
@@ -618,10 +620,7 @@ export function createStudioServer(options: StudioServerOptions): StudioServer {
if (resolve(dir) === resolve(projectDir)) cachedProjectSignature = null;
},
async lint(html, opts) {
const { lintHyperframeHtml } = await import("@hyperframes/lint");
return await lintHyperframeHtml(html, { ...opts, host: "studio" });
},
lint: (html, opts) => lintHtmlOutOfProcess(html, { ...opts, host: "studio" }),
// Out of process: linting a large composition is seconds of synchronous parsing, and on
// this event loop it stalls every other Studio request, the preview included.
@@ -629,7 +628,12 @@ export function createStudioServer(options: StudioServerOptions): StudioServer {
runRenderSetupWorker<ProjectLintResult>(
"lint",
{ projectDir: dir, host: "studio", background: true },
{ maxBufferBytes: 8 * 1024 * 1024, signal, timeoutMs: LINT_WORKER_TIMEOUT_MS },
{
execArgv: [`--max-old-space-size=${LINT_WORKER_HEAP_MB}`],
maxBufferBytes: 8 * 1024 * 1024,
signal,
timeoutMs: LINT_WORKER_TIMEOUT_MS,
},
),
runtimeUrl: "/api/runtime.js",
+6 -4
View File
@@ -210,17 +210,19 @@ function tsxLoaderFromCliInstall(): string {
}
export async function runRenderSetupWorker<T>(
mode: "browser" | "browser-install" | "lint" | "orphan-cleanup",
mode: "browser" | "browser-install" | "lint" | "lint-html" | "orphan-cleanup",
input: unknown,
options: CancellableProcessOptions,
{ execArgv: nodeFlags = [], ...options }: CancellableProcessOptions & { execArgv?: string[] },
): Promise<T> {
const sourceMode = import.meta.url.endsWith(".ts");
const workerUrl = new URL(
sourceMode ? "../renderSetupWorker.ts" : "./renderSetupWorker.js",
import.meta.url,
);
const execArgv =
sourceMode && !process.versions.bun ? ["--import", tsxLoaderFromCliInstall()] : [];
const execArgv = [
...nodeFlags,
...(sourceMode && !process.versions.bun ? ["--import", tsxLoaderFromCliInstall()] : []),
];
let result: CancellableProcessResult;
try {
result = await runCancellableProcess(
@@ -0,0 +1,50 @@
import { existsSync } from "node:fs";
import { dirname } from "node:path";
import { describe, expect, it } from "vitest";
import { lintHyperframeHtml } from "@hyperframes/lint";
import { runCancellableProcess, runRenderSetupWorker } from "./cancellableProcess.js";
import { lintHtmlOutOfProcess } from "./lintHtmlWorker.js";
const PAGE = `<html><body><div id="root" data-composition-id="main" data-width="1920" data-height="1080"></div></body></html>`;
const OPTS = { filePath: "index.html", host: "studio" as const };
const withoutTimings = ({ timings: _timings, ...rest }: Record<string, unknown>) => rest;
describe("lintHtmlOutOfProcess", () => {
// The second page is past the ~128 KB an env var can carry, so it only lints if the page travels in a file.
it.each([PAGE, PAGE.replace("</body>", `<!-- ${"x".repeat(300_000)} -->\n</body>`)])(
"lints a %#-th page in a child to what the linter returns in process",
async (html) => {
let pageDir = "";
const run = ((mode, input, options) => {
pageDir = dirname((input as { htmlPath: string }).htmlPath);
return runRenderSetupWorker(mode, input, options);
}) as typeof runRenderSetupWorker;
const result = await lintHtmlOutOfProcess(html, OPTS, { run });
expect(withoutTimings({ ...result })).toEqual(
withoutTimings({ ...(await lintHyperframeHtml(html, OPTS)) }),
);
expect(existsSync(pageDir)).toBe(false);
},
30_000,
);
it("answers a child that never answers with the lint_aborted error, and does not lint here", async () => {
// A real child that never exits, stopped by the runner's own time limit.
const hang = ((_mode, _input, options) =>
runCancellableProcess(process.execPath, ["--eval", "setInterval(() => {}, 1000)"], {
timeoutMs: options.timeoutMs,
})) as typeof runRenderSetupWorker;
const began = performance.now();
const result = await lintHtmlOutOfProcess(PAGE, OPTS, { run: hang, timeoutMs: 300 });
expect(performance.now() - began).toBeLessThan(10_000);
expect([result.ok, result.errorCount, result.warningCount, result.infoCount]).toEqual([
false,
1,
0,
0,
]);
expect(result.findings.map(({ code, severity, file }) => [code, severity, file])).toEqual([
["lint_aborted", "error", "index.html"],
]);
});
});
+68
View File
@@ -0,0 +1,68 @@
import { mkdtemp, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import type { HyperframeLinterOptions, HyperframeLintResult } from "@hyperframes/lint";
import { runRenderSetupWorker } from "./cancellableProcess.js";
/** A real composition lints in about a second at a few tens of MB of heap; this is where a runaway is stopped. */
const LINT_HTML_HEAP_MB = 512;
const LINT_HTML_TIMEOUT_MS = 15_000;
type LintHtmlTestHooks = { run?: typeof runRenderSetupWorker; timeoutMs?: number };
/** The linter's own result shape for a page it could not check: one error, never linted in this process. */
function abortedLintResult(
opts: HyperframeLinterOptions | undefined,
afterMs: number,
): HyperframeLintResult {
return {
ok: false,
errorCount: 1,
warningCount: 0,
infoCount: 0,
findings: [
{
code: "lint_aborted",
severity: "error",
message:
"This composition's script could not be checked: linting it ran too long or out of memory, so it was stopped. A very large or deeply nested script is the usual cause.",
...(opts?.filePath && { file: opts.filePath }),
},
],
timings: { totalMs: afterMs, groupMs: {}, slowestRule: "", slowestRuleMs: 0 },
};
}
/**
* Lints one page in a child process with a heap cap and a time limit, so a long-lived host (Studio)
* survives a page that sends the parser into a runaway: that page's lint is the `lint_aborted`
* error. The child timing out, dying or exiting without a result never falls back to linting here.
*/
export async function lintHtmlOutOfProcess(
html: string,
opts: HyperframeLinterOptions | undefined,
{ run = runRenderSetupWorker, timeoutMs = LINT_HTML_TIMEOUT_MS }: LintHtmlTestHooks = {},
): Promise<HyperframeLintResult> {
// The runner hands its input over in an env var, which a large page would overflow: the page goes in a file.
const dir = await mkdtemp(join(tmpdir(), "hf-lint-"));
const htmlPath = join(dir, "page.html");
try {
await writeFile(htmlPath, html);
const began = performance.now();
try {
return await run<HyperframeLintResult>(
"lint-html",
{ htmlPath, opts },
{
execArgv: [`--max-old-space-size=${LINT_HTML_HEAP_MB}`],
maxBufferBytes: 8 * 1024 * 1024,
timeoutMs,
},
);
} catch {
return abortedLintResult(opts, Math.round(performance.now() - began));
}
} finally {
await rm(dir, { recursive: true, force: true });
}
}