From 74b4f1e8c3cb0058583c6d9048708519a6d94417 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miguel=20=C3=81ngel?= Date: Thu, 16 Jul 2026 23:02:01 -0400 Subject: [PATCH] feat(cli): serve proxies from play and the static project server (#2593) * feat(studio-server): serve H.264 proxies from the preview route Wires the codec manifest and the transcoder into the preview surface: the route negotiates a proxy via a query param and serves it through the existing range and ETag machinery, composition HTML carries a codec map for the runtime, and hostile assets pre-warm so a first play does not wait on a cold transcode. Exposes the three subpath exports the CLI surfaces consume upstack. Drops the TEMP fallow entry added with the transcoder: it has real importers now. * fix(studio-server): publish media proxy exports * fix(parsers): scan HTML comments linearly * feat(cli): let projects opt out of automatic proxying Adds media.autoProxy to hyperframes.json plus --proxy/--no-proxy flags, and forwards the resolved value into the studio and preview servers and the vite adapter. Lands before the runtime slice that turns auto-proxying on, so the switch exists before there is any behavior to switch off. * fix(cli): align media config schema * feat(core): swap undecodable video to its proxy at runtime Adds the browser-side half: before first load the runtime consults the injected codec map and swaps a hostile source to its proxy, and if a video still reports zero decodable width it rescues it reactively. An HEVC file carrying AAC fires no error event, so zero videoWidth, not the error event, is the reliable signal. Audio elements and alpha sources are never proxied, render mode never proxies, and each swap evicts the element's stale sync state and reports once. This completes the loop: auto-proxying is live for preview and studio from here. The opt-out (media.autoProxy, --no-proxy) shipped in the previous slice. * feat(cli): serve proxies from play, present, and the static project server Adds proxy negotiation to the CLI-side servers and gives play byte-range serving it never had, so a swapped video can seek. The static project server behind check, snapshot, compare and friends injects the codec map once, so all of its callers inherit the behavior; snapshot forwards its own proxy flag. * fix(cli): serve proxies for camera formats --- packages/cli/src/commands/play.test.ts | 273 ++++++++++++++++++ packages/cli/src/commands/play.ts | 115 ++++++-- packages/cli/src/commands/snapshot.test.ts | 7 + packages/cli/src/commands/snapshot.ts | 10 +- packages/cli/src/utils/compositionServer.ts | 86 ++++-- .../cli/src/utils/staticProjectServer.test.ts | 240 ++++++++++++++- packages/cli/src/utils/staticProjectServer.ts | 85 +++++- packages/studio-server/src/helpers/mime.ts | 6 + 8 files changed, 778 insertions(+), 44 deletions(-) create mode 100644 packages/cli/src/commands/play.test.ts diff --git a/packages/cli/src/commands/play.test.ts b/packages/cli/src/commands/play.test.ts new file mode 100644 index 000000000..95d493ac4 --- /dev/null +++ b/packages/cli/src/commands/play.test.ts @@ -0,0 +1,273 @@ +import { afterEach, describe, expect, it, vi } from "vitest"; +import { mkdtempSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { Hono } from "hono"; +import type { ProjectDir } from "../utils/project.js"; + +// `registerCompositionRoute` reaches these two studio-server helpers via a +// module, since both files sit at the same depth under packages/cli/src/. +// +// The error class lives inside this `vi.hoisted` block (not a plain top-level +// `class`) because `vi.mock` factories run during static-import resolution — +// before any of the test file's own top-level statements execute — so a +// `class` declared below would still be in its temporal dead zone. +const mocks = vi.hoisted(() => { + class FakeProxyTranscodeError extends Error { + readonly exitCode: number | null; + readonly stderrTail: string; + constructor(message: string, exitCode: number | null = null, stderrTail = "") { + super(message); + this.name = "ProxyTranscodeError"; + this.exitCode = exitCode; + this.stderrTail = stderrTail; + } + } + class FakeProxyCapacityError extends FakeProxyTranscodeError { + constructor(message = "media proxy queue is full") { + super(message); + this.name = "ProxyCapacityError"; + } + } + return { + resolveProxy: vi.fn<(projectDir: string, absoluteSourcePath: string) => Promise>( + // 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. + async () => "/unused-prewarm-proxy-path", + ), + scanProjectMediaCodecMap: vi.fn< + ( + ...args: unknown[] + ) => Promise< + Record< + string, + { codecName: string; browserHostile: boolean; representativeMime: string | null } + > + > + >(async () => ({})), + ProxyTranscodeError: FakeProxyTranscodeError, + ProxyCapacityError: FakeProxyCapacityError, + }; +}); +const FakeProxyTranscodeError = mocks.ProxyTranscodeError; + +const mediaMocks = vi.hoisted(() => ({ + probeAssetCodec: vi.fn(async () => ({ + codecName: "hevc", + browserHostile: true, + representativeMime: "video/mp4", + hasAlpha: false, + })), + decideMediaProxyEligibility: vi.fn( + (facts: { hasAlpha: boolean; browserHostile: boolean } | null) => + facts?.hasAlpha ? { eligible: false, reason: "alpha_source" } : { eligible: true }, + ), +})); + +vi.mock("@hyperframes/studio-server/proxy-transcoder", () => ({ + resolveProxy: mocks.resolveProxy, + ProxyTranscodeError: mocks.ProxyTranscodeError, + ProxyCapacityError: mocks.ProxyCapacityError, +})); +vi.mock("@hyperframes/studio-server/media-codec-map", () => mediaMocks); + +// The shared injection helper ships as a self-contained dist bundle (its copy +// of scanProjectMediaCodecMap is inlined), so it must be mocked wholesale — +// mocking the media-codec-map subpath can't reach inside it. The fake mirrors +// the real contract (scan → inject tag) via this file's scan mock so the +// existing injection assertions stay meaningful. +vi.mock("@hyperframes/studio-server/media-proxy-preview", () => ({ + injectMediaCodecMapIntoHtml: vi.fn( + async (html: string, projectDir: string, htmlSources: unknown[]) => { + const map = await mocks.scanProjectMediaCodecMap(projectDir, htmlSources); + const tag = ``; + return html.includes("") + ? html.replace("", `${tag}\n`) + : `${tag}\n${html}`; + }, + ), +})); + +const { registerCompositionRoute } = await import("./play.js"); + +let dir: string | undefined; + +function tmpProject(): ProjectDir { + dir = mkdtempSync(join(tmpdir(), "hf-play-test-")); + return { dir, name: "test-project", indexPath: join(dir, "index.html") }; +} + +afterEach(() => { + mocks.resolveProxy.mockReset(); + mocks.resolveProxy.mockResolvedValue("/unused-prewarm-proxy-path"); + mocks.scanProjectMediaCodecMap.mockReset(); + mediaMocks.probeAssetCodec.mockClear(); + mediaMocks.decideMediaProxyEligibility.mockClear(); + mocks.scanProjectMediaCodecMap.mockResolvedValue({}); + if (dir) rmSync(dir, { recursive: true, force: true }); + dir = undefined; +}); + +it("rejects direct proxy requests for alpha sources", async () => { + const project = tmpProject(); + writeFileSync(join(project.dir, "clip.mov"), "alpha-prores"); + mediaMocks.probeAssetCodec.mockResolvedValueOnce({ + codecName: "prores", + browserHostile: true, + representativeMime: "video/quicktime", + hasAlpha: true, + }); + mediaMocks.decideMediaProxyEligibility.mockReturnValueOnce({ + eligible: false, + reason: "alpha_source", + }); + const app = await buildApp(project, true); + + const res = await app.request("/composition/clip.mov?hf-proxy=h264"); + + expect(res.status).toBe(422); + expect(await res.text()).toContain("alpha_source"); + expect(mocks.resolveProxy).not.toHaveBeenCalled(); +}); + +async function buildApp(project: ProjectDir, autoProxy: boolean): Promise { + const app = new Hono(); + await registerCompositionRoute(app, project, autoProxy); + return app; +} + +describe("registerCompositionRoute", () => { + it("answers a Range request on a plain asset with 206 + the requested byte slice", async () => { + const project = tmpProject(); + writeFileSync(join(project.dir, "clip.mp4"), Buffer.from("0123456789", "utf-8")); + const app = await buildApp(project, true); + + const res = await app.request("/composition/clip.mp4", { headers: { Range: "bytes=2-5" } }); + + expect(res.status).toBe(206); + expect(res.headers.get("accept-ranges")).toBe("bytes"); + expect(res.headers.get("content-range")).toBe("bytes 2-5/10"); + expect(await res.text()).toBe("2345"); + }); + + it("serves the resolved proxy's bytes for ?hf-proxy=h264 on a hostile asset", async () => { + const project = tmpProject(); + writeFileSync(join(project.dir, "clip.mp4"), "original-hevc-bytes"); + const proxyPath = join(project.dir, "proxy.mp4"); + writeFileSync(proxyPath, "transcoded-h264-bytes"); + mocks.resolveProxy.mockResolvedValue(proxyPath); + const app = await buildApp(project, true); + + const res = await app.request("/composition/clip.mp4?hf-proxy=h264"); + + expect(res.status).toBe(200); + expect(await res.text()).toBe("transcoded-h264-bytes"); + expect(mocks.resolveProxy).toHaveBeenCalledWith(project.dir, join(project.dir, "clip.mp4")); + }); + + it("serves ?hf-proxy=h264 for a .mov hostile asset as Content-Type video/mp4 (the proxy IS mp4)", async () => { + const project = tmpProject(); + writeFileSync(join(project.dir, "clip.mov"), "original-prores-bytes"); + const proxyPath = join(project.dir, "proxy.mp4"); + writeFileSync(proxyPath, "transcoded-h264-bytes"); + mocks.resolveProxy.mockResolvedValue(proxyPath); + const app = await buildApp(project, true); + + const res = await app.request("/composition/clip.mov?hf-proxy=h264"); + + expect(res.status).toBe(200); + expect(res.headers.get("content-type")).toBe("video/mp4"); + expect(await res.text()).toBe("transcoded-h264-bytes"); + }); + + it.each(["mxf", "mts", "m2ts", "ts"])( + "recognizes .%s camera/container media as proxy-eligible video", + async (extension) => { + const project = tmpProject(); + writeFileSync(join(project.dir, `clip.${extension}`), "hostile-video-bytes"); + const proxyPath = join(project.dir, "proxy.mp4"); + writeFileSync(proxyPath, "transcoded-h264-bytes"); + mocks.resolveProxy.mockResolvedValue(proxyPath); + const app = await buildApp(project, true); + + const res = await app.request(`/composition/clip.${extension}?hf-proxy=h264`); + + expect(res.status).toBe(200); + expect(await res.text()).toBe("transcoded-h264-bytes"); + }, + ); + + it("answers 502 (not a silent failure) when the proxy transcode fails", async () => { + const project = tmpProject(); + writeFileSync(join(project.dir, "clip.mp4"), "original-hevc-bytes"); + mocks.resolveProxy.mockRejectedValue( + new FakeProxyTranscodeError("ffmpeg exited with code 1", 1), + ); + const app = await buildApp(project, true); + + const res = await app.request("/composition/clip.mp4?hf-proxy=h264"); + + expect(res.status).toBe(502); + }); + + it("answers a retryable 503 when the proxy queue is full", async () => { + const project = tmpProject(); + writeFileSync(join(project.dir, "clip.mp4"), "original-hevc-bytes"); + mocks.resolveProxy.mockRejectedValue(new mocks.ProxyCapacityError()); + const app = await buildApp(project, true); + + const res = await app.request("/composition/clip.mp4?hf-proxy=h264"); + + expect(res.status).toBe(503); + expect(res.headers.get("retry-after")).toBe("1"); + }); + + it("404s ?hf-proxy=h264 for a non-video asset without attempting a transcode", async () => { + const project = tmpProject(); + writeFileSync(join(project.dir, "image.png"), "not-a-video"); + const app = await buildApp(project, true); + + const res = await app.request("/composition/image.png?hf-proxy=h264"); + + expect(res.status).toBe(404); + expect(mocks.resolveProxy).not.toHaveBeenCalled(); + }); + + it("injects __HF_MEDIA_CODEC_MAP__ into served composition HTML", async () => { + const project = tmpProject(); + writeFileSync(join(project.dir, "index.html"), ""); + mocks.scanProjectMediaCodecMap.mockResolvedValue({ + "/clip.mp4": { + codecName: "hevc", + browserHostile: true, + representativeMime: 'video/mp4; codecs="hvc1.1.6.L120.B0"', + }, + }); + const app = await buildApp(project, true); + + const res = await app.request("/composition/index.html"); + const html = await res.text(); + + expect(html).toContain("__HF_MEDIA_CODEC_MAP__"); + expect(html).toContain("/clip.mp4"); + }); + + it("opt-out (autoProxy=false) skips codec-map injection and 404s the proxy param", async () => { + const project = tmpProject(); + writeFileSync(join(project.dir, "index.html"), ""); + writeFileSync(join(project.dir, "clip.mp4"), "original-hevc-bytes"); + mocks.scanProjectMediaCodecMap.mockResolvedValue({ + "/clip.mp4": { codecName: "hevc", browserHostile: true, representativeMime: null }, + }); + const app = await buildApp(project, false); + + const htmlRes = await app.request("/composition/index.html"); + expect(await htmlRes.text()).not.toContain("__HF_MEDIA_CODEC_MAP__"); + expect(mocks.scanProjectMediaCodecMap).not.toHaveBeenCalled(); + + const proxyRes = await app.request("/composition/clip.mp4?hf-proxy=h264"); + expect(proxyRes.status).toBe(404); + expect(mocks.resolveProxy).not.toHaveBeenCalled(); + }); +}); diff --git a/packages/cli/src/commands/play.ts b/packages/cli/src/commands/play.ts index ca23b55e5..c2b2af88f 100644 --- a/packages/cli/src/commands/play.ts +++ b/packages/cli/src/commands/play.ts @@ -12,11 +12,17 @@ export const examples: Example[] = [ "Open with CDP enabled (requires browser path + isolated profile)", "hyperframes play --browser-path /usr/bin/chromium --user-data-dir /tmp/hf-profile --remote-debugging-port 9222", ], + [ + "Disable auto-proxying of browser-hostile video codecs (HEVC, ProRes, AV1)", + "hyperframes play --no-proxy", + ], ]; import { resolve } from "node:path"; +import type { Hono } from "hono"; import * as clack from "@clack/prompts"; import { c } from "../ui/colors.js"; -import { resolveProject } from "../utils/project.js"; +import { resolveProject, type ProjectDir } from "../utils/project.js"; +import { resolveAutoProxy } from "../utils/projectConfig.js"; import { openBrowser, parseRemoteDebuggingPort, @@ -27,8 +33,19 @@ import { resolvePlayerPath, listenOnFreePort, injectRuntime, + injectMediaCodecMap, + buildRangeResponse, assetContentType, } from "../utils/compositionServer.js"; +import { + resolveProxy, + ProxyCapacityError, + ProxyTranscodeError, +} from "@hyperframes/studio-server/proxy-transcoder"; +import { + decideMediaProxyEligibility, + probeAssetCodec, +} from "@hyperframes/studio-server/media-codec-map"; export default defineCommand({ meta: { name: "play", description: "Play a composition in a lightweight browser player" }, @@ -52,6 +69,12 @@ export default defineCommand({ type: "string", description: "Chromium remote debugging port (requires --browser-path and --user-data-dir)", }, + proxy: { + type: "boolean", + description: + "Auto-transcode browser-hostile video codecs (HEVC, ProRes, AV1) to a cached H.264 proxy for preview (default: on; overrides hyperframes.json's media.autoProxy)", + negativeDescription: "Disable auto-proxying of browser-hostile video codecs", + }, }, async run({ args }) { const project = resolveProject(args.dir); @@ -107,7 +130,6 @@ export default defineCommand({ const { Hono } = await import("hono"); const { createAdaptorServer } = await import("@hono/node-server"); - const { isSafePath } = await import("@hyperframes/core/studio-api"); const app = new Hono(); @@ -127,23 +149,8 @@ export default defineCommand({ }); }); - // Serve composition files (HTML + assets) - app.get("/composition/*", (ctx) => { - const reqPath = ctx.req.path.replace("/composition/", ""); - const filePath = resolve(project.dir, reqPath); - - // Security: don't allow path traversal outside project dir. isSafePath - // canonicalizes symlinks and applies a trailing-separator guard, so neither - // an in-project symlink to an external target nor a sibling dir whose name - // shares the project-dir prefix (e.g. `-evil`) can escape. - if (!isSafePath(project.dir, filePath)) return ctx.text("Forbidden", 403); - if (!existsSync(filePath)) return ctx.text("Not found", 404); - // HTML gets the runtime injected; other assets pass through with a guessed type. - if (filePath.endsWith(".html")) { - return ctx.html(injectRuntime(readFileSync(filePath, "utf-8"))); - } - return ctx.body(readFileSync(filePath), 200, { "Content-Type": assetContentType(filePath) }); - }); + const autoProxy = resolveAutoProxy(project.dir, args.proxy as boolean | undefined); + await registerCompositionRoute(app, project, autoProxy); // Main page — the player wrapper app.get("/", (ctx) => { @@ -181,6 +188,76 @@ export default defineCommand({ }, }); +/** + * Registers the `/composition/*` route: serves composition HTML (runtime + + * `__HF_MEDIA_CODEC_MAP__` injected) and asset files, with byte-Range support + * (`play` previously did a whole-file `readFileSync`, so seeking/duration + * probing on media elements never worked) and a `?hf-proxy=h264` branch that + * serves the cached H.264 authoring proxy for a browser-hostile video asset + * (per docs/plans/2026-07-14-002-feat-transparent-media-proxies-plan.md, + * unit U4). Exported standalone (rather than inlined in `run()`) so tests can + * exercise it via `app.request(...)` without booting a real HTTP listener, + * `clack` UI, or `openBrowser`. + */ +export async function registerCompositionRoute( + app: Hono, + project: ProjectDir, + autoProxy: boolean, +): Promise { + const { isSafePath } = await import("@hyperframes/core/studio-api"); + + // fallow-ignore-next-line complexity + app.get("/composition/*", async (ctx) => { + const reqPath = ctx.req.path.replace("/composition/", ""); + const filePath = resolve(project.dir, reqPath); + + // Security: don't allow path traversal outside project dir. isSafePath + // canonicalizes symlinks and applies a trailing-separator guard, so neither + // an in-project symlink to an external target nor a sibling dir whose name + // shares the project-dir prefix (e.g. `-evil`) can escape. + if (!isSafePath(project.dir, filePath)) return ctx.text("Forbidden", 403); + if (!existsSync(filePath)) return ctx.text("Not found", 404); + + // HTML gets the runtime + codec-map injected; other assets pass through. + if (filePath.endsWith(".html")) { + let html = injectRuntime(readFileSync(filePath, "utf-8")); + if (autoProxy) { + html = await injectMediaCodecMap(html, project.dir, [{ html, compSrcPath: reqPath }]); + } + return ctx.html(html); + } + + const contentType = assetContentType(filePath); + if (ctx.req.query("hf-proxy") === "h264") { + // Opt-out (or a non-video asset) 404s the param without attempting a + // transcode; a missing asset already 404'd above. + if (!autoProxy || !contentType.startsWith("video/")) return ctx.text("Not found", 404); + try { + const eligibility = decideMediaProxyEligibility(await probeAssetCodec(filePath)); + if (!eligibility.eligible) { + return ctx.text(`Media proxy unavailable: ${eligibility.reason}`, 422); + } + const proxyPath = await resolveProxy(project.dir, filePath); + // The proxy IS an mp4 regardless of the source's extension (.mov, + // .mkv, ...) — serve its real type, matching the preview route. + return buildRangeResponse(proxyPath, "video/mp4", ctx.req.header("Range")); + } catch (err) { + if (err instanceof ProxyCapacityError) { + return ctx.text(`Proxy transcode deferred: ${err.message}`, 503, { + "Retry-After": "1", + }); + } + if (err instanceof ProxyTranscodeError) { + return ctx.text(`Proxy transcode failed: ${err.message}`, 502); + } + throw err; + } + } + + return buildRangeResponse(filePath, contentType, ctx.req.header("Range")); + }); +} + function buildPlayerPage(projectName: string): string { return ` diff --git a/packages/cli/src/commands/snapshot.test.ts b/packages/cli/src/commands/snapshot.test.ts index 4c4691567..76f466aac 100644 --- a/packages/cli/src/commands/snapshot.test.ts +++ b/packages/cli/src/commands/snapshot.test.ts @@ -45,6 +45,13 @@ describe("transparent snapshot capture", () => { 'page.screenshot({ path: framePath, type: "png", omitBackground: true })', ); }); + + it("exposes --proxy/--no-proxy and forwards the override to the static server", () => { + const source = readFileSync(new URL("./snapshot.ts", import.meta.url), "utf8"); + expect(source).toContain("proxy: {"); + expect(source).toContain("autoProxy: args.proxy as boolean | undefined"); + expect(source).toContain("opts.autoProxy"); + }); }); describe("resolveSnapshotVideoFrameTime", () => { diff --git a/packages/cli/src/commands/snapshot.ts b/packages/cli/src/commands/snapshot.ts index 3e827f609..55734654e 100644 --- a/packages/cli/src/commands/snapshot.ts +++ b/packages/cli/src/commands/snapshot.ts @@ -233,6 +233,7 @@ async function captureSnapshots( includeEnd?: boolean; zoom?: ZoomTarget; zoomScale?: number; + autoProxy?: boolean; }, ): Promise { const { bundleWithLocalizedFonts } = await import("../utils/bundleWithLocalizedFonts.js"); @@ -242,7 +243,7 @@ async function captureSnapshots( // Localize fonts (embed remote @font-face as data URIs, matching the render // path) so snapshots render the real font instead of a fallback sans. const html = await bundleWithLocalizedFonts(projectDir); - const server = await serveStaticProjectHtml(projectDir, html); + const server = await serveStaticProjectHtml(projectDir, html, undefined, [], opts.autoProxy); const savedPaths: string[] = []; @@ -604,6 +605,12 @@ export default defineCommand({ description: "Gemini vision frame analysis. Runs by default when GEMINI_API_KEY is set. Pass a custom question (e.g. --describe 'Is the logo visible in every beat?') to override the default prompt, or --describe false to opt out.", }, + proxy: { + type: "boolean", + description: + "Auto-transcode browser-hostile video codecs for snapshots (default: on; overrides hyperframes.json media.autoProxy)", + default: undefined, + }, }, async run({ args }) { const project = resolveProject(args.dir); @@ -652,6 +659,7 @@ export default defineCommand({ includeEnd: args.end !== false, zoom: zoomTarget, zoomScale, + autoProxy: args.proxy as boolean | undefined, }); if (paths.length === 0) { diff --git a/packages/cli/src/utils/compositionServer.ts b/packages/cli/src/utils/compositionServer.ts index dc497a1d1..047014e01 100644 --- a/packages/cli/src/utils/compositionServer.ts +++ b/packages/cli/src/utils/compositionServer.ts @@ -1,9 +1,20 @@ // Shared scaffolding for the lightweight composition servers used by `play` and // `present`: locating the built runtime/player/slideshow bundles, serving // composition asset files, and binding to a free port. -import { existsSync } from "node:fs"; +import { createReadStream, existsSync, statSync } from "node:fs"; import { resolve, dirname } from "node:path"; +import { Readable } from "node:stream"; import { fileURLToPath } from "node:url"; +import { getMimeType } from "@hyperframes/studio-server"; + +/** + * `window.__HF_MEDIA_CODEC_MAP__` injection + proxy pre-warm for HTML served + * by `play` and the static project server. Re-exported from the + * single shared implementation in + * `packages/studio-server/src/helpers/mediaProxyPreview.ts` (also used by the + * studio preview route) so injection behavior cannot drift between surfaces. + */ +export { injectMediaCodecMapIntoHtml as injectMediaCodecMap } from "@hyperframes/studio-server/media-proxy-preview"; /** Minimal surface of a listening server (satisfied by @hono/node-server's ServerType). */ interface PortBindable { @@ -60,26 +71,61 @@ export function injectRuntime(html: string): string { : html + `\n${runtimeTag}`; } -const ASSET_CONTENT_TYPES: Record = { - js: "application/javascript", - mjs: "application/javascript", - css: "text/css", - json: "application/json", - png: "image/png", - jpg: "image/jpeg", - jpeg: "image/jpeg", - svg: "image/svg+xml", - mp4: "video/mp4", - webm: "video/webm", - mp3: "audio/mpeg", - wav: "audio/wav", -}; - export function assetContentType(filePath: string): string { - const ext = filePath.split(".").pop() ?? ""; - // Own-property check so an ext like "__proto__" can't resolve to Object.prototype. - const type = Object.hasOwn(ASSET_CONTENT_TYPES, ext) ? ASSET_CONTENT_TYPES[ext] : undefined; - return type ?? "application/octet-stream"; + return getMimeType(filePath); +} + +/** + * Hono-native Range/206 response for a file on disk, mirroring the inline + * Range logic in `packages/studio-server/src/routes/preview.ts`'s static + * asset route. `staticProjectServer.ts`'s raw-`node:http` counterpart is + * `serveFileWithRange`; this version converts Node's bounded file stream to a + * Fetch API stream for Hono without allocating the whole media/proxy file. + */ +export function buildRangeResponse( + filePath: string, + contentType: string, + rangeHeader: string | undefined, +): Response { + const size = statSync(filePath).size; + const last = size - 1; + const match = rangeHeader ? /^bytes=(\d*)-(\d*)$/.exec(rangeHeader.trim()) : null; + + const body = (start: number, end: number): ReadableStream | null => + size === 0 + ? null + : (Readable.toWeb(createReadStream(filePath, { start, end })) as ReadableStream); + + if (!match) { + return new Response(body(0, last), { + status: 200, + headers: { + "Content-Type": contentType, + "Accept-Ranges": "bytes", + "Content-Length": String(size), + }, + }); + } + + const hasStart = match[1] !== ""; + const start = hasStart ? Number(match[1]) : Math.max(0, size - Number(match[2])); + const end = !hasStart ? last : match[2] !== "" ? Math.min(Number(match[2]), last) : last; + if (start > end || start > last) { + return new Response(null, { + status: 416, + headers: { "Content-Range": `bytes */${size}`, "Accept-Ranges": "bytes" }, + }); + } + + return new Response(body(start, end), { + status: 206, + headers: { + "Content-Type": contentType, + "Accept-Ranges": "bytes", + "Content-Range": `bytes ${start}-${end}/${size}`, + "Content-Length": String(end - start + 1), + }, + }); } /** diff --git a/packages/cli/src/utils/staticProjectServer.test.ts b/packages/cli/src/utils/staticProjectServer.test.ts index 830012eea..bb9bd23c6 100644 --- a/packages/cli/src/utils/staticProjectServer.test.ts +++ b/packages/cli/src/utils/staticProjectServer.test.ts @@ -1,9 +1,94 @@ -import { afterEach, describe, expect, it } from "vitest"; +import { afterEach, describe, expect, it, vi } from "vitest"; import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"; import { tmpdir } from "node:os"; import { join } from "node:path"; import { serveStaticProjectHtml, type StaticProjectServer } from "./staticProjectServer.js"; +// `serveStaticProjectHtml` reaches these two studio-server helpers via a +// absolute module regardless of which file's relative specifier reaches it). +// +// The error class lives inside this `vi.hoisted` block (not a plain top-level +// `class`) because `vi.mock` factories run during static-import resolution — +// before any of this file's own top-level statements execute — so a `class` +// declared below would still be in its temporal dead zone. +const mocks = vi.hoisted(() => { + class FakeProxyTranscodeError extends Error { + readonly exitCode: number | null; + readonly stderrTail: string; + constructor(message: string, exitCode: number | null = null, stderrTail = "") { + super(message); + this.name = "ProxyTranscodeError"; + this.exitCode = exitCode; + this.stderrTail = stderrTail; + } + } + class FakeProxyCapacityError extends FakeProxyTranscodeError { + constructor(message = "media proxy queue is full") { + super(message); + this.name = "ProxyCapacityError"; + } + } + return { + resolveProxy: vi.fn<(projectDir: string, absoluteSourcePath: string) => Promise>( + // 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. + async () => "/unused-prewarm-proxy-path", + ), + scanProjectMediaCodecMap: vi.fn< + ( + ...args: unknown[] + ) => Promise< + Record< + string, + { codecName: string; browserHostile: boolean; representativeMime: string | null } + > + > + >(async () => ({})), + probeAssetCodec: vi.fn(async () => ({ + codecName: "prores", + pixelFormat: "yuva444p10le", + hasAlpha: true, + browserHostile: true, + representativeMime: null, + })), + decideMediaProxyEligibility: vi.fn< + () => { eligible: true } | { eligible: false; reason: "alpha_source" } + >(() => ({ eligible: true })), + ProxyTranscodeError: FakeProxyTranscodeError, + ProxyCapacityError: FakeProxyCapacityError, + }; +}); +const FakeProxyTranscodeError = mocks.ProxyTranscodeError; + +vi.mock("@hyperframes/studio-server/proxy-transcoder", () => ({ + resolveProxy: mocks.resolveProxy, + ProxyTranscodeError: mocks.ProxyTranscodeError, + ProxyCapacityError: mocks.ProxyCapacityError, +})); + +vi.mock("@hyperframes/studio-server/media-codec-map", () => ({ + probeAssetCodec: mocks.probeAssetCodec, + decideMediaProxyEligibility: mocks.decideMediaProxyEligibility, +})); + +// The shared injection helper ships as a self-contained dist bundle (its copy +// of scanProjectMediaCodecMap is inlined), so it must be mocked wholesale — +// mocking the media-codec-map subpath can't reach inside it. The fake mirrors +// the real contract (scan → inject tag) via this file's scan mock so the +// injection assertions stay meaningful. Mirrors commands/play.test.ts. +vi.mock("@hyperframes/studio-server/media-proxy-preview", () => ({ + injectMediaCodecMapIntoHtml: vi.fn( + async (html: string, projectDir: string, htmlSources: unknown[]) => { + const map = await mocks.scanProjectMediaCodecMap(projectDir, htmlSources); + const tag = ``; + return html.includes("") + ? html.replace("", `${tag}\n`) + : `${tag}\n${html}`; + }, + ), +})); + let server: StaticProjectServer | undefined; let dir: string | undefined; @@ -12,6 +97,13 @@ afterEach(async () => { server = undefined; if (dir) rmSync(dir, { recursive: true, force: true }); dir = undefined; + mocks.resolveProxy.mockReset(); + mocks.resolveProxy.mockResolvedValue("/unused-prewarm-proxy-path"); + mocks.scanProjectMediaCodecMap.mockReset(); + mocks.scanProjectMediaCodecMap.mockResolvedValue({}); + mocks.probeAssetCodec.mockClear(); + mocks.decideMediaProxyEligibility.mockClear(); + mocks.decideMediaProxyEligibility.mockReturnValue({ eligible: true }); }); async function serveWith(bytes: Buffer): Promise<{ url: string }> { @@ -109,3 +201,149 @@ describe("serveStaticProjectHtml asset roots", () => { expect(res.status).toBe(404); }); }); + +describe("serveStaticProjectHtml transparent media proxies", () => { + const dirs: string[] = []; + const mk = (): string => { + const d = mkdtempSync(join(tmpdir(), "hf-static-proxy-")); + dirs.push(d); + return d; + }; + afterEach(() => { + for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true }); + }); + + it("injects __HF_MEDIA_CODEC_MAP__ into the served HTML", async () => { + mocks.scanProjectMediaCodecMap.mockResolvedValue({ + "/clip.mp4": { codecName: "hevc", browserHostile: true, representativeMime: null }, + }); + const projectDir = mk(); + server = await serveStaticProjectHtml(projectDir, ""); + + const res = await fetch(server.url); + const html = await res.text(); + expect(html).toContain("__HF_MEDIA_CODEC_MAP__"); + expect(html).toContain("/clip.mp4"); + }); + + it("lets an explicit proxy override win over hyperframes.json", async () => { + mocks.scanProjectMediaCodecMap.mockResolvedValue({ + "/clip.mp4": { codecName: "hevc", browserHostile: true, representativeMime: null }, + }); + const projectDir = mk(); + writeFileSync( + join(projectDir, "hyperframes.json"), + JSON.stringify({ media: { autoProxy: false } }), + ); + server = await serveStaticProjectHtml( + projectDir, + "", + undefined, + [], + true, + ); + + const html = await (await fetch(server.url)).text(); + expect(html).toContain("__HF_MEDIA_CODEC_MAP__"); + }); + + it("lets an explicit --no-proxy override suppress config-enabled proxying", async () => { + mocks.scanProjectMediaCodecMap.mockResolvedValue({ + "/clip.mp4": { codecName: "hevc", browserHostile: true, representativeMime: null }, + }); + const projectDir = mk(); + server = await serveStaticProjectHtml( + projectDir, + "", + undefined, + [], + false, + ); + + const html = await (await fetch(server.url)).text(); + expect(html).not.toContain("__HF_MEDIA_CODEC_MAP__"); + expect(mocks.scanProjectMediaCodecMap).not.toHaveBeenCalled(); + }); + + it("serves the resolved proxy's bytes for ?hf-proxy=h264 on a hostile video asset", async () => { + const projectDir = mk(); + writeFileSync(join(projectDir, "clip.mp4"), "original-hevc-bytes"); + const proxyPath = join(projectDir, "proxy.mp4"); + writeFileSync(proxyPath, "transcoded-h264-bytes"); + mocks.resolveProxy.mockResolvedValue(proxyPath); + server = await serveStaticProjectHtml(projectDir, ""); + + const res = await fetch(`${server.url}clip.mp4?hf-proxy=h264`); + expect(res.status).toBe(200); + expect(await res.text()).toBe("transcoded-h264-bytes"); + expect(mocks.resolveProxy).toHaveBeenCalledWith(projectDir, join(projectDir, "clip.mp4")); + }); + + it.each(["mxf", "mts", "m2ts", "ts", "mkv", "m4v"])( + "serves a proxy for .%s camera/container media", + async (extension) => { + const projectDir = mk(); + const sourcePath = join(projectDir, `clip.${extension}`); + writeFileSync(sourcePath, "original-hostile-bytes"); + const proxyPath = join(projectDir, "proxy.mp4"); + writeFileSync(proxyPath, "transcoded-h264-bytes"); + mocks.resolveProxy.mockResolvedValue(proxyPath); + server = await serveStaticProjectHtml(projectDir, ""); + + 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); + }, + ); + + it("rejects an alpha-bearing video before attempting a static-server proxy transcode", async () => { + const projectDir = mk(); + writeFileSync(join(projectDir, "clip.mov"), "prores-4444-alpha-bytes"); + mocks.decideMediaProxyEligibility.mockReturnValueOnce({ + eligible: false, + reason: "alpha_source", + }); + server = await serveStaticProjectHtml(projectDir, ""); + + const res = await fetch(`${server.url}clip.mov?hf-proxy=h264`); + + expect(res.status).toBe(422); + expect(await res.text()).toContain("alpha_source"); + expect(mocks.probeAssetCodec).toHaveBeenCalledWith(join(projectDir, "clip.mov")); + expect(mocks.resolveProxy).not.toHaveBeenCalled(); + }); + + it("answers 502 when the proxy transcode fails", async () => { + const projectDir = mk(); + writeFileSync(join(projectDir, "clip.mp4"), "original-hevc-bytes"); + mocks.resolveProxy.mockRejectedValue( + new FakeProxyTranscodeError("ffmpeg exited with code 1", 1), + ); + server = await serveStaticProjectHtml(projectDir, ""); + + const res = await fetch(`${server.url}clip.mp4?hf-proxy=h264`); + expect(res.status).toBe(502); + }); + + it("answers a retryable 503 when the proxy queue is full", async () => { + const projectDir = mk(); + writeFileSync(join(projectDir, "clip.mp4"), "original-hevc-bytes"); + mocks.resolveProxy.mockRejectedValue(new mocks.ProxyCapacityError()); + server = await serveStaticProjectHtml(projectDir, ""); + + const res = await fetch(`${server.url}clip.mp4?hf-proxy=h264`); + expect(res.status).toBe(503); + expect(res.headers.get("retry-after")).toBe("1"); + }); + + it("404s ?hf-proxy=h264 for a non-video asset without attempting a transcode", async () => { + const projectDir = mk(); + writeFileSync(join(projectDir, "image.png"), "not-a-video"); + server = await serveStaticProjectHtml(projectDir, ""); + + const res = await fetch(`${server.url}image.png?hf-proxy=h264`); + expect(res.status).toBe(404); + expect(mocks.resolveProxy).not.toHaveBeenCalled(); + }); +}); diff --git a/packages/cli/src/utils/staticProjectServer.ts b/packages/cli/src/utils/staticProjectServer.ts index ea26451af..0e928e38e 100644 --- a/packages/cli/src/utils/staticProjectServer.ts +++ b/packages/cli/src/utils/staticProjectServer.ts @@ -2,6 +2,17 @@ import { createServer, type ServerResponse } from "node:http"; import { createReadStream, existsSync, statSync } from "node:fs"; import { isAbsolute, relative, resolve } from "node:path"; import { getMimeType } from "@hyperframes/core/studio-api"; +import { resolveAutoProxy } from "./projectConfig.js"; +import { injectMediaCodecMap } from "./compositionServer.js"; +import { + resolveProxy, + ProxyCapacityError, + ProxyTranscodeError, +} from "@hyperframes/studio-server/proxy-transcoder"; +import { + decideMediaProxyEligibility, + probeAssetCodec, +} from "@hyperframes/studio-server/media-codec-map"; export interface StaticProjectServer { url: string; @@ -67,6 +78,55 @@ function serveFileWithRange( }); } +/** + * Serves `?hf-proxy=h264` for a media request: 404s (no transcode attempted) + * when auto-proxying is off or the asset isn't a video, resolves+serves the + * cached H.264 proxy with Range support on success, and answers 502 on a + * transcode failure (never a silent black frame). Shared by every one of + * `serveStaticProjectHtml`'s seven callers (check/snapshot/validate/compare/ + * grade-compare/motionShot/layout) — see the KTD in + * docs/plans/2026-07-14-002-feat-transparent-media-proxies-plan.md. + */ +async function serveProxyRequest( + projectDir: string, + filePath: string, + autoProxy: boolean, + rangeHeader: string | undefined, + res: ServerResponse, +): Promise { + const contentType = getMimeType(filePath); + if (!autoProxy || !contentType.startsWith("video/")) { + res.writeHead(404); + res.end(); + return; + } + try { + const eligibility = decideMediaProxyEligibility(await probeAssetCodec(filePath)); + if (!eligibility.eligible) { + res.writeHead(422, { "Content-Type": "text/plain" }); + res.end(`media proxy unavailable: ${eligibility.reason}`); + return; + } + const proxyPath = await resolveProxy(projectDir, filePath); + // The await above can span a whole transcode; the client may be gone. + if (res.writableEnded || res.destroyed) return; + serveFileWithRange(proxyPath, rangeHeader, res); + } catch (err) { + if (err instanceof ProxyCapacityError) { + res.writeHead(503, { "Content-Type": "text/plain", "Retry-After": "1" }); + res.end(`Proxy transcode deferred: ${err.message}`); + return; + } + if (err instanceof ProxyTranscodeError) { + res.writeHead(502, { "Content-Type": "text/plain" }); + res.end(`Proxy transcode failed: ${err.message}`); + return; + } + res.writeHead(500); + res.end(); + } +} + export async function serveStaticProjectHtml( projectDir: string, html: string, @@ -74,24 +134,43 @@ export async function serveStaticProjectHtml( // Extra dirs to resolve non-index requests against, after projectDir (e.g. a // temp dir of localized remote assets). assetRoots: readonly string[] = [], + // Explicit CLI --proxy/--no-proxy value. Undefined preserves the project's + // committed hyperframes.json setting. + autoProxyOverride?: boolean, ): Promise { const roots = [projectDir, ...assetRoots]; + // Codec-map injection lives here (not per-caller) so all seven callers of + // 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; + // fallow-ignore-next-line complexity const server = createServer((req, res) => { const url = req.url ?? "/"; if (url === "/" || url === "/index.html") { res.writeHead(200, { "Content-Type": "text/html" }); - res.end(html); + res.end(servedHtml); return; } - const requestPath = decodeURIComponent(url).replace(/^\//, ""); + const queryIndex = url.indexOf("?"); + const pathOnly = queryIndex === -1 ? url : url.slice(0, queryIndex); + const wantsProxy = + queryIndex !== -1 && + new URLSearchParams(url.slice(queryIndex + 1)).get("hf-proxy") === "h264"; + + const requestPath = decodeURIComponent(pathOnly).replace(/^\//, ""); for (const root of roots) { const filePath = resolve(root, requestPath); const rel = relative(root, filePath); if (rel.startsWith("..") || isAbsolute(rel)) continue; // traversal guard; try next root if (existsSync(filePath)) { - serveFileWithRange(filePath, req.headers.range, res); + if (wantsProxy) { + void serveProxyRequest(projectDir, filePath, autoProxy, req.headers.range, res); + } else { + serveFileWithRange(filePath, req.headers.range, res); + } return; } } diff --git a/packages/studio-server/src/helpers/mime.ts b/packages/studio-server/src/helpers/mime.ts index a8b59beca..2a4780733 100644 --- a/packages/studio-server/src/helpers/mime.ts +++ b/packages/studio-server/src/helpers/mime.ts @@ -12,7 +12,13 @@ export const MIME_TYPES: Record = { ".webp": "image/webp", ".ico": "image/x-icon", ".mp4": "video/mp4", + ".m4v": "video/mp4", ".mov": "video/quicktime", + ".mkv": "video/x-matroska", + ".mxf": "video/mxf", + ".mts": "video/mp2t", + ".m2ts": "video/mp2t", + ".ts": "video/mp2t", ".webm": "video/webm", ".mp3": "audio/mpeg", ".wav": "audio/wav",