Skip to content

Write HTML. Render video. Built for agents.

fix(cli): snapshot --proxy exits once its frames are written, without waiting for copies (#5895)

Miguel Ángel35c03a509e0e
diff --git a/packages/cli/src/utils/staticProjectServer.test.ts b/packages/cli/src/utils/staticProjectServer.test.ts
index abd60a17aa..49cec4c265 100644
--- a/packages/cli/src/utils/staticProjectServer.test.ts
+++ b/packages/cli/src/utils/staticProjectServer.test.ts
@@ -8,6 +8,7 @@ import {
serveStaticProjectHtml,
type StaticProjectServer,
} from "./staticProjectServer.js";
+import { injectMediaCodecMapIntoHtml } from "@hyperframes/studio-server/media-proxy-preview";
// `serveStaticProjectHtml` reaches these two studio-server helpers via a
// absolute module regardless of which file's relative specifier reaches it).
@@ -34,7 +35,15 @@ const mocks = vi.hoisted(() => {
}
}
return {
- resolveProxy: vi.fn<(projectDir: string, absoluteSourcePath: string) => Promise<string>>(
+ resolveProxy: vi.fn<
+ (
+ projectDir: string,
+ absoluteSourcePath: string,
+ variant?: string,
+ box?: unknown,
+ options?: { signal?: AbortSignal },
+ ) => Promise<string>
+ >(
// Benign default so `injectMediaCodecMap`'s fire-and-forget pre-warm
// (called for every hostile map entry) always gets a promise to
// `.catch()`, even in tests that don't care about the proxy path.
@@ -338,6 +347,8 @@ describe("serveStaticProjectHtml transparent media proxies", () => {
projectDir,
join(projectDir, "clip.mp4"),
"h264",
+ undefined,
+ { signal: expect.any(AbortSignal) },
);
});
@@ -355,7 +366,9 @@ describe("serveStaticProjectHtml transparent media proxies", () => {
const res = await fetch(`${server.url}clip.${extension}?hf-proxy=h264`);
expect(res.status).toBe(200);
expect(await res.text()).toBe("transcoded-h264-bytes");
- expect(mocks.resolveProxy).toHaveBeenCalledWith(projectDir, sourcePath, "h264");
+ expect(mocks.resolveProxy).toHaveBeenCalledWith(projectDir, sourcePath, "h264", undefined, {
+ signal: expect.any(AbortSignal),
+ });
},
);
@@ -382,6 +395,8 @@ describe("serveStaticProjectHtml transparent media proxies", () => {
projectDir,
join(projectDir, "clip.mov"),
"vp8",
+ undefined,
+ { signal: expect.any(AbortSignal) },
);
});
@@ -417,6 +432,33 @@ describe("serveStaticProjectHtml transparent media proxies", () => {
expect(res.status).toBe(404);
expect(mocks.resolveProxy).not.toHaveBeenCalled();
});
+
+ it("stops the copies it started, pre-warmed or asked for, when it closes", async () => {
+ mocks.scanProjectMediaCodecMap.mockResolvedValue({
+ "/clip.mp4": { codecName: "hevc", browserHostile: true, representativeMime: null },
+ });
+ const projectDir = mk();
+ writeFileSync(join(projectDir, "clip.mp4"), "original-hevc-bytes");
+ let asked: AbortSignal | undefined;
+ mocks.resolveProxy.mockImplementation(
+ (_dir, _path, _variant, _box, options) =>
+ new Promise((_resolve, reject) => {
+ asked = options?.signal;
+ asked?.addEventListener("abort", () => reject(asked?.reason));
+ }),
+ );
+ const closing = await serveStaticProjectHtml(projectDir, "<html><head></head></html>");
+ const held = fetch(`${closing.url}clip.mp4?hf-proxy=h264`);
+ await vi.waitFor(() => expect(asked).toBeDefined());
+ const injected = vi.mocked(injectMediaCodecMapIntoHtml).mock.calls.at(-1) as unknown[];
+ const prewarms = injected[5] as AbortSignal | undefined;
+
+ await closing.close();
+
+ expect(prewarms?.aborted).toBe(true);
+ expect(asked?.aborted).toBe(true);
+ expect((await held).status).toBe(500);
+ });
});
describe("serveStaticProjectHtml when a sandbox refuses listen()", () => {
diff --git a/packages/cli/src/utils/staticProjectServer.ts b/packages/cli/src/utils/staticProjectServer.ts
index 0031a8a130..f6804b004d 100644
--- a/packages/cli/src/utils/staticProjectServer.ts
+++ b/packages/cli/src/utils/staticProjectServer.ts
@@ -208,6 +208,7 @@ async function serveProxyRequest(
autoProxy: boolean,
rangeHeader: string | undefined,
res: ServerResponse,
+ signal: AbortSignal,
): Promise<void> {
const contentType = getMimeType(filePath);
if (!autoProxy || !contentType.startsWith("video/")) {
@@ -235,7 +236,7 @@ async function serveProxyRequest(
return;
}
recordProxyRequest();
- const proxyPath = await resolveProxy(projectDir, filePath, variant);
+ const proxyPath = await resolveProxy(projectDir, filePath, variant, undefined, { signal });
// The await above can span a whole transcode; the client may be gone.
if (res.writableEnded || res.destroyed) return;
serveFileWithRange(proxyPath, rangeHeader, res, PROXY_VARIANT_CONFIG[variant].contentType);
@@ -260,7 +261,10 @@ export async function serveStaticProjectHtml(
// this function inherit it in one place; computed once since `html` is
// static for the lifetime of this server, not re-scanned per request.
const autoProxy = resolveAutoProxy(projectDir, autoProxyOverride);
- const servedHtml = autoProxy ? await injectMediaCodecMap(html, projectDir, [{ html }]) : html;
+ const copies = new AbortController();
+ const servedHtml = autoProxy
+ ? await injectMediaCodecMap(html, projectDir, [{ html }], undefined, true, copies.signal)
+ : html;
// fallow-ignore-next-line complexity
const server = createServer((req, res) => {
@@ -292,6 +296,7 @@ export async function serveStaticProjectHtml(
autoProxy,
req.headers.range,
res,
+ copies.signal,
);
} else {
serveFileWithRange(filePath, req.headers.range, res);
@@ -329,6 +334,7 @@ export async function serveStaticProjectHtml(
url,
port: 0,
close: async () => {
+ copies.abort();
inProcessAnswers.delete(new URL(url).origin);
},
answer,
@@ -340,6 +346,7 @@ export async function serveStaticProjectHtml(
port,
close: () =>
new Promise<void>((resolveClose) => {
+ copies.abort();
server.close(() => resolveClose());
}),
};
diff --git a/packages/studio-server/src/helpers/mediaProxyPreview.test.ts b/packages/studio-server/src/helpers/mediaProxyPreview.test.ts
index 2d80020266..d4196703df 100644
--- a/packages/studio-server/src/helpers/mediaProxyPreview.test.ts
+++ b/packages/studio-server/src/helpers/mediaProxyPreview.test.ts
@@ -75,6 +75,8 @@ describe("injectMediaCodecMapIntoHtml pre-warm", () => {
projectDir,
resolve(projectDir, "videos/broll.mov"),
"h264",
+ undefined,
+ { signal: undefined },
);
// Both entries still reach the client: the browser-side canPlayType check
// owns whether a VP9 asset needs a proxy, and that contract is unchanged.
diff --git a/packages/studio-server/src/helpers/mediaProxyPreview.ts b/packages/studio-server/src/helpers/mediaProxyPreview.ts
index f76e683b6a..d3c62ce775 100644
--- a/packages/studio-server/src/helpers/mediaProxyPreview.ts
+++ b/packages/studio-server/src/helpers/mediaProxyPreview.ts
@@ -93,6 +93,8 @@ export async function injectMediaCodecMapIntoHtml(
htmlSources: HtmlSourceLike[],
probeCache?: MediaCodecProbeCache,
prewarm = true,
+ /** Aborting it stops the pre-warms nobody else waits for. */
+ signal?: AbortSignal,
): Promise<string> {
let map: MediaCodecMap;
try {
@@ -113,6 +115,8 @@ export async function injectMediaCodecMapIntoHtml(
projectDir,
resolve(projectDir, rootRelativePathname.replace(/^\/+/, "")),
proxyVariantFor(facts),
+ undefined,
+ { signal },
).catch(() => {
// Swallowed: the pre-warm is best-effort. A real `?hf-proxy=` request
// for this asset hears the remembered failure (502) or re-attempts it.
diff --git a/packages/studio-server/src/helpers/proxyTranscoder.test.ts b/packages/studio-server/src/helpers/proxyTranscoder.test.ts
index f593d41e7e..06fa94c158 100644
--- a/packages/studio-server/src/helpers/proxyTranscoder.test.ts
+++ b/packages/studio-server/src/helpers/proxyTranscoder.test.ts
@@ -1,5 +1,5 @@
-import { execFileSync, spawnSync } from "node:child_process";
-import { EventEmitter } from "node:events";
+import { execFileSync, spawn as realSpawn, spawnSync, type ChildProcess } from "node:child_process";
+import { EventEmitter, once } from "node:events";
import {
existsSync,
mkdtempSync,
@@ -59,7 +59,7 @@ function createFakeProc(): FakeProc {
return proc;
}
-type SpawnOptions = { windowsHide?: boolean };
+type SpawnOptions = { windowsHide?: boolean; signal?: AbortSignal };
type SpawnCall = { command: string; args: string[]; options?: SpawnOptions; proc: FakeProc };
type SpawnImpl = (command: string, args: string[], options?: SpawnOptions) => FakeProc;
@@ -821,7 +821,7 @@ describe("resolveProxy", () => {
await thumb;
});
- it("lets a caller leave a started copy without stopping it", async () => {
+ it("stops a started copy once its last caller leaves, and starts afresh on the next ask", async () => {
const { calls, resolveProxy, projectDir } = await oneSlot();
const clip = clips(projectDir, ["running"]);
@@ -829,11 +829,51 @@ describe("resolveProxy", () => {
resolveProxy(projectDir, clip.running!, "h264", undefined, { signal }),
);
- succeed(calls[0]!);
+ expect(calls[0]!.options?.signal?.aborted).toBe(true);
+ calls[0]!.proc.emit("close", null, "SIGKILL");
await flush(12);
- await expect(resolveProxy(projectDir, clip.running!)).resolves.toBeTruthy();
+ const again = resolveProxy(projectDir, clip.running!);
+ await flush();
+ expect(calls).toHaveLength(2);
+ succeed(calls[1]!);
+ await expect(again).resolves.toBeTruthy();
+ });
+
+ it("keeps a started copy while a caller without a signal still waits", async () => {
+ const { calls, resolveProxy, projectDir } = await oneSlot();
+ const clip = clips(projectDir, ["running"]);
+ const kept = resolveProxy(projectDir, clip.running!);
+
+ await askThenLeave((signal) =>
+ resolveProxy(projectDir, clip.running!, "h264", undefined, { signal }),
+ );
+
+ expect(calls[0]!.options?.signal?.aborted).not.toBe(true);
+ succeed(calls[0]!);
+ await expect(kept).resolves.toBeTruthy();
expect(calls).toHaveLength(1);
});
+
+ it.skipIf(process.platform === "win32")(
+ "kills the running ffmpeg when its last caller leaves",
+ async () => {
+ let child: ChildProcess | undefined;
+ const neverFinishes = (_command: string, _args: string[], options?: SpawnOptions) => {
+ child = realSpawn(process.execPath, ["-e", "setInterval(() => {}, 1000)"], options);
+ return child as unknown as FakeProc;
+ };
+ const { resolveProxy } = await loadModule(neverFinishes, FFMPEG_PATH);
+ const projectDir = tmpProject();
+ const clip = clips(projectDir, ["running"]);
+
+ await askThenLeave((signal) =>
+ resolveProxy(projectDir, clip.running!, "h264", undefined, { signal }),
+ );
+
+ const [, exitSignal] = child!.exitCode === null ? await once(child!, "exit") : [];
+ expect(exitSignal).toBe("SIGKILL");
+ },
+ );
});
it("honors bounded concurrency and queue environment overrides", async () => {
diff --git a/packages/studio-server/src/helpers/proxyTranscoder.ts b/packages/studio-server/src/helpers/proxyTranscoder.ts
index f67a33bb71..001534af3b 100644
--- a/packages/studio-server/src/helpers/proxyTranscoder.ts
+++ b/packages/studio-server/src/helpers/proxyTranscoder.ts
@@ -19,9 +19,9 @@ import { mkdirWithinProject, realpath, realProjectRoot } from "./safePath.js";
* project routes (U3/U4) to serve a `?hf-proxy=` request; never used on
* the render path (render always sees the original file).
*
- * A started ffmpeg child is never killed for one caller: every caller of a cache
- * key shares it (in-flight dedupe below). A caller's `signal` only detaches that
- * caller, and drops the copy while it is still queued with no caller left.
+ * Every caller of a cache key shares one ffmpeg child (in-flight dedupe below). A
+ * caller's `signal` detaches that caller; once no caller is left, the copy is
+ * dropped from the queue or its ffmpeg is killed.
*/
export const PROXY_PARAMS_VERSION = "v5";
@@ -231,11 +231,12 @@ interface ProxyJob {
callers: number;
/** Set while the job waits for a slot. */
queued?: { start: () => void; drop: () => void };
+ abandoned: AbortController;
}
class ProxyDroppedError extends ProxyTranscodeError {
constructor() {
- super("media proxy copy dropped: every caller left before it started", null, "");
+ super("media proxy copy dropped: every caller left", null, "");
this.name = "ProxyDroppedError";
}
}
@@ -296,7 +297,13 @@ function prioritize(job: ProxyJob): void {
function leave(job: ProxyJob): void {
job.callers--;
- if (job.callers === 0) job.queued?.drop();
+ if (job.callers > 0) return;
+ if (job.queued) {
+ job.queued.drop();
+ return;
+ }
+ forget(job);
+ job.abandoned.abort();
}
// --- per-key in-flight dedupe ----------------------------------------------
@@ -413,6 +420,7 @@ async function runFfmpeg(
outputPath: string,
variant: ProxyVariant,
box: PreviewProxyBox | undefined,
+ signal: AbortSignal,
): Promise<void> {
const metadata = await probeMediaMetadata(sourcePath);
const ffmpegPath = findFfBinary("ffmpeg", { configuredMustExist: true });
@@ -493,10 +501,12 @@ async function runFfmpeg(
// global transcode slots: the child is killed and the slot released via
// the caller's finally. Generous because long assets transcode at
// roughly real time; a healthy encode of any authoring asset fits.
+ signal.throwIfAborted();
const proc = spawn(ffmpegPath, args, {
stdio: ["ignore", "ignore", "pipe"],
timeout: TRANSCODE_TIMEOUT_MS,
killSignal: "SIGKILL",
+ signal,
windowsHide: true,
});
let stderrTail = "";
@@ -504,6 +514,7 @@ async function runFfmpeg(
stderrTail = (stderrTail + chunk.toString()).slice(-STDERR_TAIL_MAX_CHARS);
});
proc.on("error", (err) => {
+ if (signal.aborted) return;
reject(new FfmpegUnavailableError(`failed to spawn ffmpeg: ${err.message}`, stderrTail));
});
proc.on("close", (code, signal) => {
@@ -547,7 +558,7 @@ async function transcodeToCache(
mkdirWithinProject(projectDir, cacheDir);
const tempPath = join(cacheDir, `.tmp-${randomUUID()}-${basename(cachePath)}`);
try {
- await runFfmpeg(absoluteSourcePath, tempPath, variant, box);
+ await runFfmpeg(absoluteSourcePath, tempPath, variant, box, job.abandoned.signal);
renameSync(tempPath, cachePath);
maintainProxyCache(cacheDir);
return cachePath;
@@ -615,6 +626,7 @@ export async function resolveProxy(
cachePath,
priority: options.priority === true,
callers: 0,
+ abandoned: new AbortController(),
};
const promise = transcodeToCache(
job,
@@ -625,7 +637,9 @@ export async function resolveProxy(
box,
)
.catch((err: unknown) => {
- if (!(err instanceof ProxyDroppedError)) rememberFailure(cachePath, err);
+ if (!(err instanceof ProxyDroppedError) && !job.abandoned.signal.aborted) {
+ rememberFailure(cachePath, err);
+ }
throw err;
})
.finally(() => {