Skip to content

Write HTML. Render video. Built for agents.

fix(studio-server): the preview's proxy copy jumps queued thumbnails, and abandoned copies drop (#5340)

Miguel Ángel5eb2a96fc274
diff --git a/packages/studio-server/src/helpers/proxyTranscoder.test.ts b/packages/studio-server/src/helpers/proxyTranscoder.test.ts
index 4519598b44..3e0007b51e 100644
--- a/packages/studio-server/src/helpers/proxyTranscoder.test.ts
+++ b/packages/studio-server/src/helpers/proxyTranscoder.test.ts
@@ -11,7 +11,7 @@ import {
writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { basename, join } from "node:path";
import { hdrToSdrToneMapFilter } from "@hyperframes/core";
import { findFfBinary } from "@hyperframes/parsers/ff-binaries";
import { afterEach, describe, expect, it, vi } from "vitest";
@@ -533,6 +533,242 @@ describe("resolveProxy", () => {
await expect(retry).resolves.toBeTruthy();
});
+ describe("queue order and callers that leave", () => {
+ function clipOf(call: SpawnCall): string {
+ return basename(call.args[call.args.indexOf("-i") + 1]!, ".mov");
+ }
+
+ function clips(projectDir: string, names: string[]): Record<string, string> {
+ return Object.fromEntries(
+ names.map((name) => {
+ const path = join(projectDir, `${name}.mov`);
+ writeFileSync(path, name);
+ return [name, path];
+ }),
+ );
+ }
+
+ async function askThenLeave(ask: (signal: AbortSignal) => Promise<string>): Promise<void> {
+ const leaving = new AbortController();
+ const left = ask(leaving.signal);
+ await flush();
+ leaving.abort();
+ await expect(left).rejects.toBe(leaving.signal.reason);
+ }
+
+ async function oneSlot(queue = 8, slots = 1) {
+ process.env.HYPERFRAMES_PROXY_MAX_CONCURRENCY = String(slots);
+ process.env.HYPERFRAMES_PROXY_MAX_QUEUE = String(queue);
+ const spy = createSpawnSpy();
+ return { ...spy, ...(await loadModule(spy.spawn, FFMPEG_PATH)), projectDir: tmpProject() };
+ }
+
+ it("moves another project's activity mark when its ask is refused, and copies it once there is room", async () => {
+ const { calls, resolveProxy, ProxyCapacityError, proxyActivityMark, projectDir } =
+ await oneSlot(0);
+ const busyProject = tmpProject();
+ const running = resolveProxy(busyProject, clips(busyProject, ["running"]).running!);
+ const target = clips(projectDir, ["target"]).target!;
+ const before = proxyActivityMark(projectDir);
+
+ await expect(resolveProxy(projectDir, target)).rejects.toBeInstanceOf(ProxyCapacityError);
+ expect(proxyActivityMark(projectDir)).not.toBe(before);
+
+ succeed(calls[0]!);
+ await running;
+ const retry = resolveProxy(projectDir, target);
+ await flush();
+ expect(calls.map(clipOf)).toEqual(["running", "target"]);
+ succeed(calls[1]!);
+ await retry;
+ });
+
+ it("starts a priority copy before queued thumbnails, even when the queue is full", async () => {
+ const { calls, resolveProxy, ProxyCapacityError, projectDir } = await oneSlot(1);
+ const clip = clips(projectDir, ["running", "thumb", "late", "preview"]);
+
+ const running = resolveProxy(projectDir, clip.running!);
+ const thumb = resolveProxy(projectDir, clip.thumb!);
+ await expect(resolveProxy(projectDir, clip.late!)).rejects.toBeInstanceOf(ProxyCapacityError);
+ const preview = resolveProxy(projectDir, clip.preview!, "h264", undefined, {
+ priority: true,
+ });
+ await flush();
+
+ succeed(calls[0]!);
+ await running;
+ await flush();
+ expect(clipOf(calls[1]!)).toBe("preview");
+ succeed(calls[1]!);
+ await preview;
+ await flush();
+ expect(clipOf(calls[2]!)).toBe("thumb");
+ succeed(calls[2]!);
+ await thumb;
+ });
+
+ it("moves an already queued copy forward when the preview asks for it", async () => {
+ const { calls, resolveProxy, projectDir } = await oneSlot();
+ const clip = clips(projectDir, ["running", "first", "second"]);
+
+ const asks = [
+ resolveProxy(projectDir, clip.running!),
+ resolveProxy(projectDir, clip.first!),
+ resolveProxy(projectDir, clip.second!),
+ resolveProxy(projectDir, clip.second!, "h264", undefined, { priority: true }),
+ ];
+ await flush();
+ succeed(calls[0]!);
+ await flush(12);
+
+ expect(clipOf(calls[1]!)).toBe("second");
+ succeed(calls[1]!);
+ await flush(12);
+ succeed(calls[2]!);
+ await Promise.all(asks);
+ expect(calls).toHaveLength(3);
+ });
+
+ it("drops a queued copy once its only caller leaves, without remembering a failure", async () => {
+ const { calls, resolveProxy, projectDir } = await oneSlot();
+ const clip = clips(projectDir, ["running", "thumb"]);
+ const scrolledOff = new AbortController();
+
+ const running = resolveProxy(projectDir, clip.running!);
+ const thumb = resolveProxy(projectDir, clip.thumb!, "h264", undefined, {
+ signal: scrolledOff.signal,
+ });
+ await flush();
+ scrolledOff.abort();
+ await expect(thumb).rejects.toBe(scrolledOff.signal.reason);
+
+ succeed(calls[0]!);
+ await running;
+ await flush(12);
+ expect(calls).toHaveLength(1);
+
+ const again = resolveProxy(projectDir, clip.thumb!);
+ await flush();
+ expect(calls).toHaveLength(2);
+ succeed(calls[1]!);
+ await expect(again).resolves.toBeTruthy();
+ });
+
+ it.each([
+ ["another caller with a signal", true],
+ ["a caller without a signal", false],
+ ])("keeps a shared queued copy while %s still waits", async (_label, withSignal) => {
+ const { calls, resolveProxy, projectDir } = await oneSlot();
+ const clip = clips(projectDir, ["running", "shared"]);
+
+ const running = resolveProxy(projectDir, clip.running!);
+ const staying = resolveProxy(
+ projectDir,
+ clip.shared!,
+ "h264",
+ undefined,
+ withSignal ? { signal: new AbortController().signal } : {},
+ );
+ await askThenLeave((signal) =>
+ resolveProxy(projectDir, clip.shared!, "h264", undefined, { signal }),
+ );
+
+ succeed(calls[0]!);
+ await running;
+ await flush(12);
+ expect(clipOf(calls[1]!)).toBe("shared");
+ succeed(calls[1]!);
+ await expect(staying).resolves.toBeTruthy();
+ });
+
+ it("makes the copy when the preview asks in the same moment the last thumbnail leaves", async () => {
+ const { calls, resolveProxy, projectDir } = await oneSlot();
+ const clip = clips(projectDir, ["running", "handoff"]);
+ const leaving = new AbortController();
+
+ const running = resolveProxy(projectDir, clip.running!);
+ const thumb = resolveProxy(projectDir, clip.handoff!, "h264", undefined, {
+ signal: leaving.signal,
+ });
+ await flush();
+ leaving.abort();
+ const preview = resolveProxy(projectDir, clip.handoff!, "h264", undefined, {
+ priority: true,
+ });
+ await expect(thumb).rejects.toBe(leaving.signal.reason);
+
+ succeed(calls[0]!);
+ await running;
+ await flush(12);
+ expect(clipOf(calls[1]!)).toBe("handoff");
+ succeed(calls[1]!);
+ await expect(preview).resolves.toBeTruthy();
+ });
+
+ it("keeps one copy per clip when a dropped copy settles after its replacement started", async () => {
+ const { calls, resolveProxy, projectDir } = await oneSlot(8, 2);
+ const clip = clips(projectDir, ["first", "second", "handoff"]);
+ const leaving = new AbortController();
+
+ const running = [
+ resolveProxy(projectDir, clip.first!),
+ resolveProxy(projectDir, clip.second!),
+ ];
+ const thumb = resolveProxy(projectDir, clip.handoff!, "h264", undefined, {
+ signal: leaving.signal,
+ });
+ await flush();
+ leaving.abort();
+ const preview = resolveProxy(projectDir, clip.handoff!);
+ await expect(thumb).rejects.toBe(leaving.signal.reason);
+ await flush(12);
+ const later = resolveProxy(projectDir, clip.handoff!);
+
+ succeed(calls[0]!);
+ succeed(calls[1]!);
+ await Promise.all(running);
+ await flush(12);
+ expect(calls.map(clipOf).filter((name) => name === "handoff")).toHaveLength(1);
+ succeed(calls[2]!);
+ await expect(Promise.all([preview, later])).resolves.toHaveLength(2);
+ });
+
+ it("accepts a priority ask in the same moment a normal ask for that clip was refused", async () => {
+ const { calls, resolveProxy, ProxyCapacityError, projectDir } = await oneSlot(1);
+ const clip = clips(projectDir, ["running", "thumb", "late"]);
+
+ const running = resolveProxy(projectDir, clip.running!);
+ const thumb = resolveProxy(projectDir, clip.thumb!);
+ const refused = resolveProxy(projectDir, clip.late!);
+ const preview = resolveProxy(projectDir, clip.late!, "h264", undefined, { priority: true });
+ await expect(refused).rejects.toBeInstanceOf(ProxyCapacityError);
+
+ succeed(calls[0]!);
+ await running;
+ await flush(12);
+ expect(clipOf(calls[1]!)).toBe("late");
+ succeed(calls[1]!);
+ await expect(preview).resolves.toBeTruthy();
+ await flush(12);
+ succeed(calls[2]!);
+ await thumb;
+ });
+
+ it("lets a caller leave a started copy without stopping it", async () => {
+ const { calls, resolveProxy, projectDir } = await oneSlot();
+ const clip = clips(projectDir, ["running"]);
+
+ await askThenLeave((signal) =>
+ resolveProxy(projectDir, clip.running!, "h264", undefined, { signal }),
+ );
+
+ succeed(calls[0]!);
+ await flush(12);
+ await expect(resolveProxy(projectDir, clip.running!)).resolves.toBeTruthy();
+ expect(calls).toHaveLength(1);
+ });
+ });
+
it("honors bounded concurrency and queue environment overrides", async () => {
process.env.HYPERFRAMES_PROXY_MAX_CONCURRENCY = "1";
process.env.HYPERFRAMES_PROXY_MAX_QUEUE = "0";
diff --git a/packages/studio-server/src/helpers/proxyTranscoder.ts b/packages/studio-server/src/helpers/proxyTranscoder.ts
index e585b11fae..110cbe907a 100644
--- a/packages/studio-server/src/helpers/proxyTranscoder.ts
+++ b/packages/studio-server/src/helpers/proxyTranscoder.ts
@@ -19,15 +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).
*
- * IMPORTANT — request-lifecycle detachment: nothing here accepts or wires an
- * AbortSignal. `resolveProxy` returns a promise shared by every concurrent
- * caller for the same cache key (in-flight dedupe below); if a route handler
- * killed the ffmpeg child on client abort (page reload, HMR), every other
- * caller waiting on that same promise would fail too, and the next request
- * would restart a transcode that may have been minutes into a long asset.
- * Callers MUST let the child run to completion regardless of request
- * cancellation and simply let the held response also abort — the cache
- * entry still lands for the next request.
+ * 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.
*/
export const PROXY_PARAMS_VERSION = "v5";
@@ -222,40 +216,93 @@ export function getProxyCachePath(
}
// --- global concurrency limiter -------------------------------------------
-// ponytail: a bare counter + FIFO wait queue is the whole semaphore; no
-// dependency pulled in for this. Both element-triggered and pre-warm calls
-// go through the same `resolveProxy` entry point, so both queue here.
+// ponytail: a counter + one wait queue is the whole semaphore. Priority copies
+// queue ahead of the rest and are never refused for a full queue, so a few
+// priority asks (the copy a viewer is waiting on) can exceed the cap.
+
+/** One copy per cache key, shared by every caller asking for it. */
+interface ProxyJob {
+ cachePath: string;
+ priority: boolean;
+ /** Callers still waiting; one without a signal never leaves, so its copy is always made. */
+ callers: number;
+ /** Set while the job waits for a slot. */
+ queued?: { start: () => void; drop: () => void };
+}
+
+class ProxyDroppedError extends ProxyTranscodeError {
+ constructor() {
+ super("media proxy copy dropped: every caller left before it started", null, "");
+ this.name = "ProxyDroppedError";
+ }
+}
let activeTranscodes = 0;
-const waitQueue: Array<() => void> = [];
+const waitQueue: ProxyJob[] = [];
+
+function enqueue(job: ProxyJob): void {
+ const firstNormal = job.priority ? waitQueue.findIndex((queued) => !queued.priority) : -1;
+ if (firstNormal === -1) waitQueue.push(job);
+ else waitQueue.splice(firstNormal, 0, job);
+}
+
+function dequeue(job: ProxyJob): void {
+ const index = waitQueue.indexOf(job);
+ if (index !== -1) waitQueue.splice(index, 1);
+}
-function acquireSlot(): Promise<void> {
+function acquireSlot(job: ProxyJob): Promise<void> {
+ if (activeTranscodes < MAX_CONCURRENT_TRANSCODES) {
+ activeTranscodes++;
+ return Promise.resolve();
+ }
return new Promise((resolveSlot, reject) => {
- const tryAcquire = (): void => {
- if (activeTranscodes < MAX_CONCURRENT_TRANSCODES) {
+ job.queued = {
+ start: () => {
+ job.queued = undefined;
activeTranscodes++;
resolveSlot();
- } else {
- if (waitQueue.length >= MAX_QUEUED_TRANSCODES) {
- reject(new ProxyCapacityError());
- return;
- }
- waitQueue.push(tryAcquire);
- }
+ },
+ drop: () => {
+ job.queued = undefined;
+ dequeue(job);
+ forget(job);
+ reject(new ProxyDroppedError());
+ },
};
- tryAcquire();
+ enqueue(job);
});
}
+function queueIsFull(): boolean {
+ return activeTranscodes >= MAX_CONCURRENT_TRANSCODES && waitQueue.length >= MAX_QUEUED_TRANSCODES;
+}
+
function releaseSlot(): void {
activeTranscodes--;
- const next = waitQueue.shift();
- if (next) next();
+ waitQueue.shift()?.queued?.start();
+}
+
+function prioritize(job: ProxyJob): void {
+ if (job.priority) return;
+ job.priority = true;
+ if (!job.queued) return;
+ dequeue(job);
+ enqueue(job);
+}
+
+function leave(job: ProxyJob): void {
+ job.callers--;
+ if (job.callers === 0) job.queued?.drop();
}
// --- per-key in-flight dedupe ----------------------------------------------
-const inFlight = new Map<string, Promise<string>>();
+const inFlight = new Map<string, { promise: Promise<string>; job: ProxyJob }>();
+
+function forget(job: ProxyJob): void {
+ if (inFlight.get(job.cachePath)?.job === job) inFlight.delete(job.cachePath);
+}
function maintainProxyCache(cacheDir: string): void {
try {
@@ -462,13 +509,14 @@ async function runFfmpeg(
}
async function transcodeToCache(
+ job: ProxyJob,
projectDir: string,
absoluteSourcePath: string,
cachePath: string,
variant: ProxyVariant,
box: PreviewProxyBox | undefined,
): Promise<string> {
- await acquireSlot();
+ await acquireSlot(job);
try {
// Another caller may have finished (or a pre-warm beat us) while queued.
if (existsSync(cachePath)) return cachePath;
@@ -491,14 +539,14 @@ async function transcodeToCache(
}
}
-let settledProxyCount = 0;
+let proxyActivity = 0;
-/** Null while a copy for this project is being made; otherwise a mark that moves when any copy finishes. */
+/** Null while this project has a copy in progress; otherwise a mark that moves when any copy finishes or is refused. */
export function proxyActivityMark(projectDir: string): string | null {
- if (!existsSync(projectDir)) return String(settledProxyCount);
+ if (!existsSync(projectDir)) return String(proxyActivity);
const cacheDir = join(realpath(projectDir), CACHE_DIR_NAME) + sep;
for (const cachePath of inFlight.keys()) if (cachePath.startsWith(cacheDir)) return null;
- return String(settledProxyCount);
+ return String(proxyActivity);
}
/**
@@ -510,13 +558,17 @@ export function proxyActivityMark(projectDir: string): string | null {
* nonzero exit) — callers (route handlers) decide how to surface that (502).
* A `box` makes a smaller preview-only copy with its own cache entry; without
* one the copy keeps the source size (CLI play, static servers, publish).
+ * `priority` moves the copy ahead of every normal queued copy; a `signal`
+ * lets this caller leave (see the detachment note at the top of this file).
*/
export async function resolveProxy(
projectDir: string,
absoluteSourcePath: string,
variant: ProxyVariant = "h264",
box?: PreviewProxyBox,
+ options: ResolveProxyOptions = {},
): Promise<string> {
+ options.signal?.throwIfAborted();
const source = canonicalizeProxySource(projectDir, absoluteSourcePath);
const cachePath = getCanonicalProxyCachePath(source, variant, box);
if (existsSync(cachePath)) {
@@ -531,18 +583,56 @@ export async function resolveProxy(
failedTranscodes.delete(cachePath);
}
- const existing = inFlight.get(cachePath);
- if (existing) return existing;
-
- const promise = transcodeToCache(source.projectDir, source.sourcePath, cachePath, variant, box)
- .catch((err: unknown) => {
- if (!(err instanceof ProxyCapacityError)) rememberFailure(cachePath, err);
- throw err;
- })
- .finally(() => {
- inFlight.delete(cachePath);
- settledProxyCount += 1;
- });
- inFlight.set(cachePath, promise);
- return promise;
+ let entry = inFlight.get(cachePath);
+ if (!entry) {
+ if (!options.priority && queueIsFull()) {
+ proxyActivity += 1;
+ throw new ProxyCapacityError();
+ }
+ const job: ProxyJob = {
+ cachePath,
+ priority: options.priority === true,
+ callers: 0,
+ };
+ const promise = transcodeToCache(
+ job,
+ source.projectDir,
+ source.sourcePath,
+ cachePath,
+ variant,
+ box,
+ )
+ .catch((err: unknown) => {
+ if (!(err instanceof ProxyDroppedError)) rememberFailure(cachePath, err);
+ throw err;
+ })
+ .finally(() => {
+ forget(job);
+ proxyActivity += 1;
+ });
+ entry = { promise, job };
+ inFlight.set(cachePath, entry);
+ }
+ if (options.priority) prioritize(entry.job);
+ return joinJob(entry.promise, entry.job, options.signal);
+}
+
+export interface ResolveProxyOptions {
+ priority?: boolean;
+ signal?: AbortSignal;
+}
+
+function joinJob(promise: Promise<string>, job: ProxyJob, signal?: AbortSignal): Promise<string> {
+ job.callers++;
+ if (!signal) return promise;
+ return new Promise((resolveJoin, rejectJoin) => {
+ const onAbort = (): void => {
+ leave(job);
+ rejectJoin(signal.reason);
+ };
+ signal.addEventListener("abort", onAbort, { once: true });
+ promise
+ .finally(() => signal.removeEventListener("abort", onAbort))
+ .then(resolveJoin, rejectJoin);
+ });
}