Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
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.tsindex 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.tsindex 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);+ });}