fix(studio-server): a cold proxy copy answers 202 at once and the preview retries until it lands

This commit is contained in:
Miguel Angel Simon Sierra
2026-09-27 03:03:47 -04:00
parent 950cccdac0
commit 7007afd936
4 changed files with 166 additions and 8 deletions
+67 -1
View File
@@ -66,7 +66,19 @@ function isProxied(el: HTMLMediaElement): boolean {
return proxyVariant(el) !== null;
}
/** Stubs the proxy route's answers to the one-byte ask, in order; 202 and 503 carry a Retry-After. */
function stubProxyRoute(...statuses: number[]) {
const route = vi.fn(async () => {
const status = statuses.shift() ?? 404;
const retry = status === 202 || status === 503 ? { "Retry-After": "2" } : undefined;
return new Response(status === 206 ? "x" : null, { status, headers: retry });
});
vi.stubGlobal("fetch", route);
return route;
}
afterEach(() => {
vi.unstubAllGlobals();
vi.clearAllMocks();
vi.restoreAllMocks();
document.body.innerHTML = "";
@@ -413,14 +425,17 @@ describe("handleErrorForProxy (tertiary trigger)", () => {
expect(postRuntimeMessageMock).not.toHaveBeenCalled();
});
it("the proxy URL itself erroring: no second swap, diagnostic reports the failure instead", () => {
it("the proxy URL itself erroring: no second swap, diagnostic reports the failure instead", async () => {
const route = stubProxyRoute(502);
const el = createVideo("/video.mp4");
swapToProxy(el, HEVC_ENTRY, "proactive");
expect(el.load).toHaveBeenCalledTimes(1);
postRuntimeMessageMock.mockClear();
handleErrorForProxy(el);
await vi.waitFor(() => expect(postRuntimeMessageMock).toHaveBeenCalled());
expect(route).toHaveBeenCalledTimes(1);
expect(el.load).toHaveBeenCalledTimes(1); // no second load()/swap
expect(postRuntimeMessageMock).toHaveBeenCalledWith(
expect.objectContaining({
@@ -429,6 +444,57 @@ describe("handleErrorForProxy (tertiary trigger)", () => {
}),
);
});
it("a proxy still being made is asked again after each Retry-After, and the video reloads once it is served", async () => {
vi.useFakeTimers();
const route = stubProxyRoute(202, 503, 202, 206);
const el = createVideo("/video.mp4");
swapToProxy(el, HEVC_ENTRY, "proactive");
postRuntimeMessageMock.mockClear();
handleErrorForProxy(el);
await vi.advanceTimersByTimeAsync(60_000);
expect(route).toHaveBeenCalledTimes(4);
expect(route).toHaveBeenCalledWith(
el.src,
expect.objectContaining({ headers: { Range: "bytes=0-0" } }),
);
expect(el.load).toHaveBeenCalledTimes(2);
expect(isProxied(el)).toBe(true);
expect(postRuntimeMessageMock).not.toHaveBeenCalled();
vi.useRealTimers();
});
it("a served proxy that errors is reloaded once, then diagnosed", async () => {
stubProxyRoute(206, 206);
const el = createVideo("/video.mp4");
swapToProxy(el, HEVC_ENTRY, "proactive");
postRuntimeMessageMock.mockClear();
handleErrorForProxy(el);
await vi.waitFor(() => expect(el.load).toHaveBeenCalledTimes(2));
handleErrorForProxy(el);
await vi.waitFor(() => expect(postRuntimeMessageMock).toHaveBeenCalled());
expect(el.load).toHaveBeenCalledTimes(2);
});
it("stops asking once the element leaves the document", async () => {
vi.useFakeTimers();
const route = stubProxyRoute(202, 206);
const el = createVideo("/video.mp4");
swapToProxy(el, HEVC_ENTRY, "proactive");
handleErrorForProxy(el);
await vi.advanceTimersByTimeAsync(0);
el.remove();
await vi.advanceTimersByTimeAsync(60_000);
expect(route).toHaveBeenCalledTimes(1);
expect(el.load).toHaveBeenCalledTimes(1);
vi.useRealTimers();
});
});
describe("swapToProxy", () => {
+42 -2
View File
@@ -47,6 +47,10 @@ type ProxyTrigger = "proactive" | "reactive" | "tertiary";
// still gets its own single diagnostic.
const unavailableDiagnosedElements = new WeakSet<HTMLMediaElement>();
// Swapped elements reloaded once without having waited for their proxy, so a
// proxy that is served but will not decode is diagnosed instead of reloaded again.
const reloadedWithoutWait = new WeakSet<HTMLMediaElement>();
function currentSrcValue(el: HTMLMediaElement): string {
return el.currentSrc || el.src;
}
@@ -254,6 +258,41 @@ export function swapToProxy(
);
}
/** Asks for one byte of the proxy (an element never sees its status) while the
* server answers 202 (copy being made) or 503 (queue full), after each Retry-After. */
async function proxyServed(
href: string,
live: () => boolean,
): Promise<{ served: boolean; waited: boolean }> {
let waited = false;
while (live()) {
const res = await fetch(href, { headers: { Range: "bytes=0-0" }, cache: "no-store" }).catch(
() => null,
);
void res?.body?.cancel().catch(() => {});
if (res?.status !== 202 && res?.status !== 503) return { served: res?.ok ?? false, waited };
waited = true;
const seconds = Math.min(Number(res.headers.get("Retry-After")) || 2, 30);
await new Promise((resolveWait) => setTimeout(resolveWait, seconds * 1000));
}
return { served: false, waited };
}
/** A swapped element that errored: reload it once its proxy is served, or diagnose. */
function reloadWhenProxyServed(el: HTMLMediaElement, src: string): void {
const live = () => el.isConnected && currentSrcValue(el) === src;
void proxyServed(src, live).then(({ served, waited }) => {
if (!live()) return;
if (served && (waited || !reloadedWithoutWait.has(el))) {
if (!waited) reloadedWithoutWait.add(el);
evictMediaSyncState(el);
el.load();
return;
}
emitUnavailableDiagnostic(el, "proxy_playback_failed", src);
});
}
/**
* Proactive trigger: consult the codec map before an element's first
* `load()` and swap ahead of time when the browser is known-unlikely to
@@ -320,14 +359,15 @@ export function handleMetadataForProxy(el: HTMLMediaElement): void {
* it and `loadedmetadata` never fires. Same guards and once-per-element
* behavior as the reactive path, plus one extra skip: an entry the scan
* mapped as browser-SAFE that still errors is a corrupt-but-safe file — an
* proxy of a broken source can't help, so only diagnose.
* proxy of a broken source can't help, so only diagnose. An already-swapped
* element's error is usually its proxy still being made (202), so it waits.
*/
export function handleErrorForProxy(el: HTMLMediaElement): void {
if (isRenderMode(el)) return;
if (!isVideoElement(el)) return;
const src = currentSrcValue(el);
if (swappedElements.has(el)) {
emitUnavailableDiagnostic(el, "proxy_playback_failed", src);
reloadWhenProxyServed(el, src);
return;
}
const map = window.__HF_MEDIA_CODEC_MAP__;
@@ -956,8 +956,13 @@ describe("hf-proxy negotiation and media codec map injection (U3)", () => {
"",
);
});
const { waitForProxy, ProxyWaitTimeoutError } = await vi.importActual<
typeof import("../helpers/proxyTranscoder.js")
>("../helpers/proxyTranscoder.js");
vi.doMock("../helpers/proxyTranscoder.js", () => ({
resolveProxy,
waitForProxy,
ProxyWaitTimeoutError,
ProxyTranscodeError: FakeProxyTranscodeError,
ProxyCapacityError: FakeProxyCapacityError,
PROXY_PARAMS_VERSION: "v1",
@@ -1294,6 +1299,44 @@ describe("hf-proxy negotiation and media codec map injection (U3)", () => {
expect(res.headers.get("Retry-After")).toBe("5");
});
it("answers 202 at once while the copy is made, then serves the copy once it lands", async () => {
const projectDir = createProjectDir();
writeFileSync(join(projectDir, "clip.mp4"), "original-hevc-bytes");
const proxyPath = join(projectDir, "proxy.mp4");
let landCopy!: () => void;
const transcode = new Promise<string>((resolveCopy) => {
landCopy = () => {
writeFileSync(proxyPath, "proxy-bytes");
resolveCopy(proxyPath);
};
});
const { registerPreviewRoutes: register } = await loadPreviewModule({
resolveProxyImpl: () => transcode,
});
const { mediaProxyDemand } = await import("../helpers/mediaCodecMap.js");
const before = mediaProxyDemand().proxyRequests;
const app = new Hono();
register(app, createAdapter(projectDir));
const url = "http://localhost/projects/demo/preview/clip.mp4?hf-proxy=h264";
const pending = await Promise.race([
app.request(url),
new Promise<"held">((resolveHeld) => setTimeout(resolveHeld, 1000, "held")),
]);
expect(pending, "a cold copy must not hold the request for the transcode").not.toBe("held");
const cold = pending as Response;
expect(cold.status).toBe(202);
expect(cold.headers.get("Retry-After")).toBe("2");
expect(cold.headers.get("Cache-Control")).toBe("no-store");
expect(mediaProxyDemand().proxyRequests - before).toBe(0);
landCopy();
const ready = await app.request(url);
expect(ready.status).toBe(200);
expect(await ready.text()).toBe("proxy-bytes");
expect(mediaProxyDemand().proxyRequests - before).toBe(1);
});
it("rejects a path-traversal attempt through the proxied path (404, no transcode)", async () => {
const projectDir = createProjectDir();
const resolveProxyMock = vi.fn(async () => "should-not-be-called");
+14 -5
View File
@@ -29,8 +29,10 @@ import { isVariablesPayload, VARIABLES_PAYLOAD_ERROR } from "../helpers/variable
import { injectPreviewVariables } from "../helpers/previewVariables.js";
import {
resolveProxy,
waitForProxy,
ProxyCapacityError,
ProxyTranscodeError,
ProxyWaitTimeoutError,
} from "../helpers/proxyTranscoder.js";
import {
decideMediaProxyEligibility,
@@ -595,19 +597,26 @@ export function registerPreviewRoutes(api: Hono, adapter: PreviewApiAdapter): vo
let servedPath = file;
let servedContentType = contentType;
if (proxyVariant !== undefined) {
// Here, not at the eligibility gate above: one count per resolved proxy
// shares a unit with `prewarmsRequested`, and a revalidated repeat that
// 304s no longer counts as fresh demand.
recordProxyRequest();
try {
servedPath = await resolveProxy(project.dir, file, proxyVariant);
// A cached copy settles before any timer; a transcode never holds one of
// the browser's few connections to this host. 202 until the copy lands.
servedPath = await waitForProxy(resolveProxy(project.dir, file, proxyVariant), 0);
} catch (err) {
if (err instanceof ProxyWaitTimeoutError) {
return c.text("media proxy is being made", 202, {
"Retry-After": "2",
"Cache-Control": "no-store",
});
}
if (err instanceof ProxyCapacityError) {
return c.text(err.message, 503, { "Retry-After": "5" });
}
const message = err instanceof ProxyTranscodeError ? err.message : "proxy transcode failed";
return c.text(message, 502);
}
// After the wait, not at the eligibility gate: one count per resolved proxy
// shares a unit with `prewarmsRequested`; a 304 or a 202 is not fresh demand.
recordProxyRequest();
servedContentType = PROXY_VARIANT_CONFIG[proxyVariant].contentType;
}