fix(studio-server): bound preview stills and keep proxy work to the Studio's own pages (#8007)

* fix(studio-server): bound preview stills and keep proxy work to the Studio's own pages

- Queue at most 16 stills behind the 4 being made; past that, answer 503 with Retry-After.
- Refuse a still past the end of the source before starting ffmpeg (404).
- Refuse a ?hf-proxy request on a plain preview path when another site asks for it. The
  Studio's own opaque frames already load through the frame-token path, and sandboxed
  thumbnail captures now do too.

— Rames

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

* chore(studio-server): raise packed size budget for the still-queue and cross-site checks

The bounded still queue, the past-end refusal and the cross-site proxy
check add about 2.2 KB to the packed studio-server (180252 bytes in CI).

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
James Russo
2026-11-17 03:09:21 +00:00
committed by GitHub
co-authored by Claude Opus 5.5
parent 581a43bb6a
commit bffe8d5985
12 changed files with 230 additions and 19 deletions
+23 -3
View File
@@ -4,7 +4,11 @@ import { PREVIEW_FOR_ANOTHER_SITE_META } from "@hyperframes/core/studio-preview-
import type { StudioApiAdapter } from "./types.js";
import { registerProjectRoutes } from "./routes/projects.js";
import { registerFileRoutes } from "./routes/files.js";
import { PREVIEW_CAPTURE_PARAM, registerPreviewRoutes } from "./routes/preview.js";
import {
PREVIEW_CAPTURE_PARAM,
PREVIEW_PROXY_PARAM,
registerPreviewRoutes,
} from "./routes/preview.js";
import { registerLintRoutes } from "./routes/lint.js";
import { registerRenderRoutes } from "./routes/render.js";
import { registerImageThumbnailRoutes } from "./routes/imageThumbnail.js";
@@ -30,7 +34,11 @@ import {
} from "./helpers/requestIdentity.js";
import { previewErrorPage } from "./helpers/previewErrorPage.js";
import type { CaptureSandboxOption } from "./helpers/captureLoads.js";
import { createFrameTokens, serveTokenPreviewPaths } from "./helpers/opaqueFrameLoads.js";
import {
createFrameTokens,
loadedThroughFrameToken,
serveTokenPreviewPaths,
} from "./helpers/opaqueFrameLoads.js";
async function answerRefusedFrameWithPage(c: Context, next: Next) {
await next();
@@ -91,6 +99,13 @@ const sandboxPreviewForAnotherSiteOrCapture =
if (anotherSite) await markPreviewForAnotherSite(c);
};
async function refuseProxyWorkForAnotherSite(c: Context, next: Next) {
const proxyWork = c.req.query(PREVIEW_PROXY_PARAM) !== undefined;
if (proxyWork && fromAnotherSite(c) && !loadedThroughFrameToken(c.req.raw))
return c.text("forbidden: media proxy requested by another site", 403);
return next();
}
const refuseForAnotherSite = (what: string) => async (c: Context, next: Next) => {
if (fromAnotherSite(c))
return c.json({ error: `forbidden: ${what} requested by another site` }, 403);
@@ -130,6 +145,7 @@ export function createStudioApi(adapter: StudioApiAdapter, options: StudioApiOpt
() => undefined,
);
api.use("/projects/:id/preview/*", serveTokenPreviewPaths(api, frameTokens, resolveProjectId));
api.use("/projects/:id/preview/*", refuseProxyWorkForAnotherSite);
api.use(
"/projects/:id/preview/*",
sandboxPreviewForAnotherSiteOrCapture(sandboxThumbnailCaptures),
@@ -224,7 +240,11 @@ export function createStudioApi(adapter: StudioApiAdapter, options: StudioApiOpt
});
registerLintRoutes(api, adapter);
registerRenderRoutes(api, adapter);
registerThumbnailRoutes(api, adapter);
registerThumbnailRoutes(
api,
adapter,
sandboxThumbnailCaptures ? frameTokens.tokenFor : undefined,
);
registerImageThumbnailRoutes(api, adapter);
registerSelectionRoutes(api, adapter);
registerRecoveryDraftRoutes(api, adapter);
@@ -1,5 +1,5 @@
import { describe, expect, it } from "vitest";
import { createJobSlots, JobAbandonedError } from "./jobSlots.js";
import { createJobSlots, JobAbandonedError, JobQueueFullError } from "./jobSlots.js";
const gate = () => {
let open: () => void = () => {};
@@ -35,4 +35,21 @@ describe("createJobSlots", () => {
await expect(next).resolves.toBe("next");
expect(started).toBe(false);
});
it("refuses a job once the queue is full, and takes jobs again as it drains", async () => {
const run = createJobSlots(1, 1);
const first = gate();
const running = run(() => first.opened);
const queued = run(async () => "queued");
let started = false;
const refused = run(async () => {
started = true;
});
await expect(refused).rejects.toBeInstanceOf(JobQueueFullError);
first.open();
await running;
await expect(queued).resolves.toBe("queued");
await expect(run(async () => "later")).resolves.toBe("later");
expect(started).toBe(false);
});
});
+10 -2
View File
@@ -5,8 +5,15 @@ export class JobAbandonedError extends Error {
}
}
/** Runs at most `limit` jobs at once; a waiter whose signal aborts leaves the queue without starting. */
export function createJobSlots(limit: number) {
export class JobQueueFullError extends Error {
constructor() {
super("job queue is full; retry shortly");
this.name = "JobQueueFullError";
}
}
/** Runs at most `limit` jobs at once and queues at most `maxWaiting` more; an aborted waiter leaves without starting. */
export function createJobSlots(limit: number, maxWaiting = Number.POSITIVE_INFINITY) {
let running = 0;
const waiting: Array<() => void> = [];
@@ -17,6 +24,7 @@ export function createJobSlots(limit: number) {
running++;
return resolve();
}
if (waiting.length >= maxWaiting) return reject(new JobQueueFullError());
const leave = () => {
waiting.splice(waiting.indexOf(start), 1);
reject(new JobAbandonedError());
@@ -88,6 +88,10 @@ async function underToken(res: Response, headers: Headers, projectId: string, to
return new Response(html, { status: res.status, headers });
}
const frameTokenLoads = new WeakSet<Request>();
export const loadedThroughFrameToken = (request: Request) => frameTokenLoads.has(request);
// Every opaque frame sends `Origin: null`, so the grant goes only to `preview/~<token>/` paths, which only the
// Studio's own pages can learn. The token path serves the plain path's response, its document re-based under the token.
export function serveTokenPreviewPaths(
@@ -107,6 +111,7 @@ export function serveTokenPreviewPaths(
if (answersProxyPreflight(c, url))
return new Response(null, { status: 204, headers: PROXY_PREFLIGHT_ANSWER });
const req = new Request(url, { method: c.req.method, headers: c.req.raw.headers });
frameTokenLoads.add(req);
const res = await api.fetch(req);
return underToken(res, tokenPathHeaders(c, res, url.pathname), projectId, token);
};
@@ -2135,6 +2135,24 @@ describe("resolveStill", () => {
},
);
it("starts no ffmpeg for a still past the end of the source", async () => {
const spy = createSpawnSpy();
const { resolveStill, StillPastEndError } = await loadModule(
spy.spawn,
FFMPEG_PATH,
false,
null,
undefined,
2,
);
const projectDir = tmpProject();
const clip = join(projectDir, "clip.mp4");
writeFileSync(clip, "clip");
await expect(resolveStill(projectDir, clip, 2.5)).rejects.toBeInstanceOf(StillPastEndError);
expect(spy.calls).toHaveLength(0);
});
it("starts no ffmpeg for a request that already left", async () => {
const { calls, ask } = await stillSetup();
const gone = new AbortController();
@@ -119,6 +119,13 @@ export class ProxyCapacityError extends ProxyTranscodeError {
}
}
export class StillPastEndError extends ProxyTranscodeError {
constructor() {
super("media still is past the end of the source", null, "");
this.name = "StillPastEndError";
}
}
export class ProxySourceOutsideProjectError extends ProxyTranscodeError {
constructor() {
super("media proxy source must be addressed through the project", null, "");
@@ -1221,6 +1228,9 @@ async function makeStill(
if (!ffmpegPath) throw new FfmpegUnavailableError();
const metadata = await probeMediaMetadata(source.sourcePath);
if (metadata.probeError === NOT_MEDIA) throw new ProxyTranscodeError(NOT_MEDIA, null, "");
if (metadata.durationSeconds !== undefined && at > metadata.durationSeconds) {
throw new StillPastEndError();
}
const filter = await buildVideoFilter(ffmpegPath, source.sourcePath, metadata, false, box);
mkdirWithinProject(source.projectDir, dirname(cachePath));
const tempPath = join(dirname(cachePath), `.tmp-${randomUUID()}-${basename(cachePath)}`);
@@ -318,3 +318,39 @@ describe("an opaque preview frame's wait for a video's proxy copy", () => {
]);
});
});
describe("a media proxy asked for by another site", () => {
const ask = (prefix: string, site: string) =>
api.request(`http://localhost/projects/demo/preview/${prefix}clip.mp4?hf-proxy=h264`, {
headers: { "sec-fetch-site": site },
});
it.each(["cross-site", "same-site"])(
"is refused on the plain path to a %s request",
async (site) => {
const res = await ask("", site);
expect(res.status).toBe(403);
expect(await res.text()).toBe("forbidden: media proxy requested by another site");
},
);
it("is refused on the plain path even with a still query", async () => {
const res = await api.request(
"http://localhost/projects/demo/preview/clip.mp4?hf-proxy=h264&hf-proxy-still=1",
{ headers: { "sec-fetch-site": "cross-site" } },
);
expect(res.status).toBe(403);
});
it("goes through under the project's frame token, and from the Studio itself", async () => {
expect((await ask(`~${token}/`, "cross-site")).status).not.toBe(403);
expect((await ask("", "same-origin")).status).not.toBe(403);
});
it("leaves another site's plain load of a video without the proxy query alone", async () => {
const res = await api.request("http://localhost/projects/demo/preview/clip.mp4", {
headers: { "sec-fetch-site": "cross-site" },
});
expect(res.status).not.toBe(403);
});
});
@@ -1695,10 +1695,14 @@ describe("hf-proxy negotiation and media codec map injection (U3)", () => {
"",
);
});
const { waitForProxy, ProxyWaitTimeoutError, PROXY_PENDING_RETRY_AFTER_SECONDS } =
await vi.importActual<typeof import("../helpers/proxyTranscoder.js")>(
"../helpers/proxyTranscoder.js",
);
const {
waitForProxy,
ProxyWaitTimeoutError,
PROXY_PENDING_RETRY_AFTER_SECONDS,
StillPastEndError,
} = await vi.importActual<typeof import("../helpers/proxyTranscoder.js")>(
"../helpers/proxyTranscoder.js",
);
vi.doMock("../helpers/proxyTranscoder.js", () => ({
resolveProxy,
resolveStill:
@@ -1713,6 +1717,7 @@ describe("hf-proxy negotiation and media codec map injection (U3)", () => {
retryProxyCopy: (_dir: string, file: string) => void opts.retried?.push(file),
ProxyTranscodeError: FakeProxyTranscodeError,
ProxyCapacityError: FakeProxyCapacityError,
StillPastEndError,
PROXY_PARAMS_VERSION: "v1",
getProxyCachePath: () => "",
}));
@@ -1953,6 +1958,24 @@ describe("hf-proxy negotiation and media codec map injection (U3)", () => {
expect(resolveStillMock).toHaveBeenCalledTimes(1);
});
it("answers a still past the end of the video with a 404", async () => {
const projectDir = createProjectDir();
writeFileSync(join(projectDir, "clip.mp4"), "original-hevc-bytes");
const { registerPreviewRoutes: register } = await loadPreviewModule({
resolveStillImpl: async () => {
const { StillPastEndError } = await import("../helpers/proxyTranscoder.js");
throw new StillPastEndError();
},
});
const app = new Hono();
register(app, createAdapter(projectDir));
const res = await app.request(
"http://localhost/projects/demo/preview/clip.mp4?hf-proxy=h264&hf-proxy-still=9999",
);
expect(res.status).toBe(404);
});
it("makes at most four new stills at once, and serves a finished still without waiting", async () => {
const projectDir = createProjectDir();
writeFileSync(join(projectDir, "clip.mp4"), "original-hevc-bytes");
@@ -1985,14 +2008,14 @@ describe("hf-proxy negotiation and media codec map injection (U3)", () => {
register(app, createAdapter(projectDir));
const url = "http://localhost/projects/demo/preview/clip.mp4?hf-proxy=h264&hf-proxy-still=";
const made = Array.from({ length: 40 }, (_, i) => app.request(`${url}${i}`));
const made = Array.from({ length: 20 }, (_, i) => app.request(`${url}${i}`));
await vi.waitFor(() => expect(finishers).toHaveLength(4));
const finished = await app.request(`${url}99`);
expect(finished.status).toBe(200);
expect(finishers).toHaveLength(4);
let ended = 0;
while (ended < 40) {
while (ended < 20) {
await vi.waitFor(() => expect(finishers.length).toBeGreaterThan(0));
finishers.shift()?.();
ended++;
@@ -2001,6 +2024,45 @@ describe("hf-proxy negotiation and media codec map injection (U3)", () => {
expect(mostRunning).toBe(4);
});
it("turns a still away with a 503 once four are being made and sixteen wait", async () => {
const projectDir = createProjectDir();
writeFileSync(join(projectDir, "clip.mp4"), "original-hevc-bytes");
const stillPath = join(projectDir, "still.jpg");
writeFileSync(stillPath, "jpegbytes");
const finishers: Array<() => void> = [];
const resolveStillMock = vi.fn(
async (
_dir: string,
_file: string,
_at: number,
_box?: { width: number; height: number },
startUncachedStill?: (make: () => Promise<string>) => Promise<string>,
) =>
startUncachedStill!(async () => {
await new Promise<void>((resolve) => finishers.push(resolve));
return stillPath;
}),
);
const { registerPreviewRoutes: register } = await loadPreviewModule({
resolveStillImpl: resolveStillMock,
});
const app = new Hono();
register(app, createAdapter(projectDir));
const url = "http://localhost/projects/demo/preview/clip.mp4?hf-proxy=h264&hf-proxy-still=";
const accepted = Array.from({ length: 20 }, (_, i) => app.request(`${url}${i}`));
await vi.waitFor(() => expect(resolveStillMock).toHaveBeenCalledTimes(20));
const turnedAway = await app.request(`${url}20`);
expect(turnedAway.status).toBe(503);
expect(turnedAway.headers.get("Retry-After")).toBe("5");
for (let ended = 0; ended < 20; ended++) {
await vi.waitFor(() => expect(finishers.length).toBeGreaterThan(0));
finishers.shift()?.();
}
for (const res of await Promise.all(accepted)) expect(res.status).toBe(200);
});
it("makes a still again for a request that shared a waiter whose client left", async () => {
const projectDir = createProjectDir();
writeFileSync(join(projectDir, "clip.mp4"), "original-hevc-bytes");
+9 -3
View File
@@ -89,6 +89,7 @@ import {
ProxyTranscodeError,
ProxyWaitTimeoutError,
PROXY_PENDING_RETRY_AFTER_SECONDS,
StillPastEndError,
} from "../helpers/proxyTranscoder.js";
import {
decideMediaProxyEligibility,
@@ -109,10 +110,10 @@ import {
import { requestSubPath } from "../helpers/requestSubPath.js";
import { lazyPreviewImages } from "../helpers/lazyPreviewImages.js";
import { corsProjectVideos } from "../helpers/captureVideos.js";
import { createJobSlots, JobAbandonedError } from "../helpers/jobSlots.js";
import { createJobSlots, JobAbandonedError, JobQueueFullError } from "../helpers/jobSlots.js";
const PROJECT_SIGNATURE_META = "hyperframes-project-signature";
const runStillJob = createJobSlots(4);
const runStillJob = createJobSlots(4, 16);
function escapeGsapUrl(url: string): string {
return url.replace(/&/g, "&amp;").replace(/"/g, "&quot;");
@@ -359,6 +360,7 @@ function previewVariablesFromRequest(rawVariables: string | undefined):
/** Captures screenshot right after a seek, so they get every image eager; media loads near the playhead. */
export const PREVIEW_CAPTURE_PARAM = "hf-capture";
export const PREVIEW_PROXY_PARAM = "hf-proxy";
export function scriptJson(value: unknown): string {
return JSON.stringify(value)
@@ -756,7 +758,7 @@ export function registerPreviewRoutes(
// only a video asset can be proxied, and only when auto-proxy is enabled
// for this adapter/project. Checked BEFORE any transcode or 304 shortcut
// so a bogus/disabled request never spawns ffmpeg.
const proxyParam = c.req.query("hf-proxy");
const proxyParam = c.req.query(PREVIEW_PROXY_PARAM);
const boxParam = c.req.query(PREVIEW_PROXY_BOX_PARAM);
const proxyBox = boxParam === undefined ? undefined : parsePreviewProxyBox(boxParam);
const lightRequested = c.req.query(PREVIEW_PROXY_LIGHT_PARAM) !== undefined;
@@ -807,6 +809,10 @@ export function registerPreviewRoutes(
headers: { "Content-Type": "image/jpeg", "Cache-Control": "private, max-age=3600" },
});
} catch (err) {
if (err instanceof JobQueueFullError) {
return c.text(err.message, 503, { "Retry-After": "5" });
}
if (err instanceof StillPastEndError) return c.text("not found", 404);
if (isProjectRootMissing(err)) throw err;
return c.text("media still failed", 502);
}
@@ -84,6 +84,28 @@ describe("registerThumbnailRoutes", () => {
expect(loaded).toEqual([`?${PREVIEW_CAPTURE_PARAM}=1`, `?${PREVIEW_CAPTURE_PARAM}=1`]);
});
it("loads the capture page under the project's frame token when given one", async () => {
const adapter = createAdapter();
await writeComposition(adapter, 1920, 1080);
const app = new Hono();
const token = "t".repeat(43);
registerThumbnailRoutes(app, adapter, (projectId) => (projectId === "demo" ? token : ""));
const loaded: string[] = [];
vi.mocked(adapter.generateThumbnail!).mockImplementation(async ({ previewUrl }) => {
const url = new URL(previewUrl);
loaded.push(url.pathname + url.search);
return Buffer.from("thumb");
});
await app.request("http://localhost/projects/demo/thumbnail/index.html?t=6");
await app.request("http://localhost/projects/demo/thumbnail/scenes%2Fb.html?t=6");
expect(loaded).toEqual([
`/api/projects/demo/preview/~${token}?${PREVIEW_CAPTURE_PARAM}=1`,
`/api/projects/demo/preview/~${token}/comp/scenes/b.html?${PREVIEW_CAPTURE_PARAM}=1`,
]);
});
it("forwards selector queries to thumbnail generation", async () => {
const adapter = createAdapter();
const app = new Hono();
+10 -3
View File
@@ -126,7 +126,11 @@ function manifestKey(file: string): { key: string; mtimeMs: number } {
return { key: `_${hash}`, mtimeMs: Math.round(manifest.mtimeMs) };
}
export function registerThumbnailRoutes(api: Hono, adapter: StudioApiAdapter): void {
export function registerThumbnailRoutes(
api: Hono,
adapter: StudioApiAdapter,
frameTokenForCapture?: (projectId: string) => string,
): void {
api.get("/projects/:id/thumbnail/*", async (c) => {
if (!adapter.generateThumbnail) {
return c.json({ error: "Thumbnails not available" }, 501);
@@ -194,10 +198,13 @@ export function registerThumbnailRoutes(api: Hono, adapter: StudioApiAdapter): v
const origin = thumbnailPreviewOrigin(adapter.serverOrigin?.(), c.req.header("host"));
if (!origin) return c.json({ error: "thumbnail needs a loopback Host" }, 400);
const projectUrl = `${origin}/api/projects/${encodeURIComponent(project.id)}`;
const preview = frameTokenForCapture
? `preview/~${frameTokenForCapture(project.id)}`
: "preview";
const previewPath =
compPath === "index.html"
? `${projectUrl}/preview`
: `${projectUrl}/preview/comp/${compPath.split("/").map(encodeURIComponent).join("/")}`;
? `${projectUrl}/${preview}`
: `${projectUrl}/${preview}/comp/${compPath.split("/").map(encodeURIComponent).join("/")}`;
const previewUrl = `${previewPath}?${PREVIEW_CAPTURE_PARAM}=1`;
// Cache
+1 -1
View File
@@ -56,7 +56,7 @@
"unpacked": 26703858
},
"@hyperframes/studio-server": {
"packed": 178000,
"packed": 182000,
"unpacked": 690000
}
}