mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 11:26:02 +00:00
* fix(studio-server): previews with no fetch metadata on a LAN host count as another site Browsers send no Sec-Fetch-Site header over plain HTTP to a non-loopback name, such as a LAN address used with HYPERFRAMES_PREVIEW_HOST. The preview guards now count such a request as the Studio's own page only when its Referer names the same host. Otherwise the preview is marked and sandboxed, its validators are dropped, and the thumbnail, waveform, peaks and frame-token routes refuse it. * fix(cli): play marks and sandboxes compositions another site loads The play server's /composition/* route now applies the same another-site decision as the Studio preview. A load from another site comes back with the sandbox CSP and without validators, and its HTML carries the hyperframes-preview-for-another-site mark, so the runtime offers that site no editing port. The play page's own player is unchanged. * fix(player): send a same-origin Referer from the composition frame The player's composition iframe used no-referrer, so on a plain-HTTP LAN host its own composition load carried neither Sec-Fetch-Site nor Referer and the Studio and play servers sandboxed it as another site's load. same-origin sends the host page's URL only to a composition on the same origin, so another origin still learns nothing about the embedding page.
347 lines
12 KiB
TypeScript
347 lines
12 KiB
TypeScript
import { failUsage, setCommandExitCode } from "../utils/commandResult.js";
|
|
import { defineCommand } from "../utils/defineCommand.js";
|
|
import type { Example } from "./_examples.js";
|
|
import { existsSync, readFileSync } from "node:fs";
|
|
|
|
export const examples: Example[] = [
|
|
["Play the current project", "hyperframes play"],
|
|
["Play a specific project directory", "hyperframes play ./my-video"],
|
|
["Use a custom port", "hyperframes play --port 8080"],
|
|
["Start without opening the browser", "hyperframes play --no-open"],
|
|
["Open with a specific browser", "hyperframes play --browser-path /usr/bin/chromium"],
|
|
[
|
|
"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 { requestSubPath } from "@hyperframes/studio-server";
|
|
import * as clack from "../ui/prompts.js";
|
|
import { c } from "../ui/colors.js";
|
|
import { resolveProject, type ProjectDir } from "../utils/project.js";
|
|
import { resolveAutoProxy } from "../utils/projectConfig.js";
|
|
import { normalizeErrorMessage } from "../utils/errorMessage.js";
|
|
import { parsePort } from "../utils/port.js";
|
|
import {
|
|
openBrowser,
|
|
parseRemoteDebuggingPort,
|
|
validateRemoteDebuggingPortDeps,
|
|
} from "../utils/openBrowser.js";
|
|
import {
|
|
resolveRuntimePath,
|
|
resolvePlayerPath,
|
|
listenOnFreePort,
|
|
refuseUnknownHosts,
|
|
sandboxForAnotherSite,
|
|
injectRuntime,
|
|
injectMediaCodecMap,
|
|
buildRangeResponse,
|
|
revalidatedResponse,
|
|
assetContentType,
|
|
} from "../utils/compositionServer.js";
|
|
import { isPrivateCompositionFile } from "../utils/privateProjectFile.js";
|
|
import {
|
|
resolveProxy,
|
|
ProxyCapacityError,
|
|
ProxyTranscodeError,
|
|
} from "@hyperframes/studio-server/proxy-transcoder";
|
|
import {
|
|
decideMediaProxyEligibility,
|
|
isProxyVariantRequest,
|
|
probeAssetCodec,
|
|
recordProxyRequest,
|
|
resolveProxyVariantRequest,
|
|
PROXY_VARIANT_CONFIG,
|
|
} from "@hyperframes/studio-server/media-codec-map";
|
|
|
|
export default defineCommand({
|
|
meta: { name: "play", description: "Play a composition in a lightweight browser player" },
|
|
args: {
|
|
dir: { type: "positional", description: "Project directory", required: false },
|
|
port: { type: "string", description: "Port to run the player server on", default: "3003" },
|
|
open: {
|
|
type: "boolean",
|
|
default: true,
|
|
description: "Open browser automatically",
|
|
},
|
|
"browser-path": {
|
|
type: "string",
|
|
description: "Path to the browser executable to open",
|
|
},
|
|
"user-data-dir": {
|
|
type: "string",
|
|
description: "Chromium-compatible user data directory (requires --browser-path)",
|
|
},
|
|
"remote-debugging-port": {
|
|
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 authoring proxy for preview (default: on; overrides hyperframes.json's media.autoProxy)",
|
|
negativeDescription: "Disable auto-proxying of browser-hostile video codecs",
|
|
},
|
|
},
|
|
async run({ args }) {
|
|
let startPort: number;
|
|
try {
|
|
startPort = parsePort(args.port ?? "3003");
|
|
} catch (error) {
|
|
clack.log.error(normalizeErrorMessage(error));
|
|
failUsage();
|
|
}
|
|
const project = resolveProject(args.dir);
|
|
|
|
// Validation: --user-data-dir requires --browser-path
|
|
if (args["user-data-dir"] && !args["browser-path"]) {
|
|
clack.log.error("--user-data-dir requires --browser-path");
|
|
failUsage();
|
|
}
|
|
// Validation: --remote-debugging-port deps
|
|
const depsError = validateRemoteDebuggingPortDeps({
|
|
browserPath: args["browser-path"] as string | undefined,
|
|
userDataDir: args["user-data-dir"] as string | undefined,
|
|
remoteDebuggingPort: args["remote-debugging-port"] as string | undefined,
|
|
});
|
|
if (depsError) {
|
|
clack.log.error(depsError);
|
|
failUsage();
|
|
}
|
|
// Parse --remote-debugging-port before any server setup so an invalid value
|
|
// exits cleanly instead of leaving an orphan listening socket behind.
|
|
let remoteDebuggingPort: number | undefined;
|
|
try {
|
|
remoteDebuggingPort = parseRemoteDebuggingPort(
|
|
args["remote-debugging-port"] as string | undefined,
|
|
);
|
|
} catch (err) {
|
|
clack.log.error((err as Error).message);
|
|
failUsage();
|
|
}
|
|
|
|
// Resolve runtime path — same logic as studioServer.ts
|
|
const runtimePath = resolveRuntimePath();
|
|
if (!runtimePath) {
|
|
clack.log.error("HyperFrames runtime not found. Run `bun run build` first.");
|
|
setCommandExitCode(1);
|
|
return;
|
|
}
|
|
|
|
// Resolve player path
|
|
const playerPath = resolvePlayerPath();
|
|
if (!playerPath) {
|
|
clack.log.error(
|
|
"@hyperframes/player not found. Run `bun run --cwd packages/player build` first.",
|
|
);
|
|
setCommandExitCode(1);
|
|
return;
|
|
}
|
|
|
|
const { Hono } = await import("hono");
|
|
const { createAdaptorServer } = await import("@hono/node-server");
|
|
|
|
const app = new Hono();
|
|
refuseUnknownHosts(app);
|
|
|
|
// Serve the player JS
|
|
app.get("/player.js", (ctx) =>
|
|
revalidatedResponse(
|
|
readFileSync(playerPath, "utf-8"),
|
|
"application/javascript",
|
|
ctx.req.header("If-None-Match"),
|
|
),
|
|
);
|
|
|
|
// Serve the runtime JS
|
|
app.get("/runtime.js", (ctx) =>
|
|
revalidatedResponse(
|
|
readFileSync(runtimePath, "utf-8"),
|
|
"application/javascript",
|
|
ctx.req.header("If-None-Match"),
|
|
),
|
|
);
|
|
|
|
const autoProxy = resolveAutoProxy(project.dir, args.proxy as boolean | undefined);
|
|
await registerCompositionRoute(app, project, autoProxy);
|
|
|
|
// Main page — the player wrapper
|
|
app.get("/", (ctx) => {
|
|
return ctx.html(buildPlayerPage(project.name));
|
|
});
|
|
|
|
clack.intro(c.bold("hyperframes play"));
|
|
const s = clack.spinner();
|
|
s.start("Starting player...");
|
|
|
|
const server = createAdaptorServer({ fetch: app.fetch });
|
|
const actualPort = await listenOnFreePort(server, startPort);
|
|
|
|
const url = `http://localhost:${actualPort}`;
|
|
s.stop(c.success("Player running"));
|
|
console.log();
|
|
if (actualPort !== startPort) {
|
|
console.log(` ${c.warn(`Port ${startPort} is in use, using ${actualPort} instead`)}`);
|
|
}
|
|
console.log(` ${c.dim("Project")} ${c.accent(project.name)}`);
|
|
console.log(` ${c.dim("Player")} ${c.accent(url)}`);
|
|
console.log();
|
|
console.log(` ${c.dim("Press Ctrl+C to stop")}`);
|
|
console.log();
|
|
|
|
if (args.open) {
|
|
void openBrowser(url, {
|
|
browserPath: args["browser-path"] as string | undefined,
|
|
userDataDir: args["user-data-dir"] as string | undefined,
|
|
remoteDebuggingPort,
|
|
});
|
|
}
|
|
|
|
return new Promise<void>(() => {});
|
|
},
|
|
});
|
|
|
|
/**
|
|
* 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=` branch that
|
|
* serves the alpha-aware 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<void> {
|
|
const { isSafePath } = await import("@hyperframes/core/studio-api");
|
|
|
|
sandboxForAnotherSite(app, "/composition/*");
|
|
// fallow-ignore-next-line complexity
|
|
app.get("/composition/*", async (ctx) => {
|
|
const reqPath = requestSubPath(ctx.req.url, "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. `<dir>-evil`) can escape.
|
|
if (!isSafePath(project.dir, filePath)) return ctx.text("Forbidden", 403);
|
|
if (isPrivateCompositionFile(project.dir, filePath) || !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 revalidatedResponse(html, "text/html; charset=UTF-8", ctx.req.header("If-None-Match"));
|
|
}
|
|
|
|
const contentType = assetContentType(filePath);
|
|
// Edited text is caught by a content hash; an mtime tag can repeat for a same-size rewrite.
|
|
const mediaType = contentType.split(";")[0]!.trim();
|
|
const isText =
|
|
mediaType.startsWith("text/") ||
|
|
mediaType === "application/json" ||
|
|
mediaType === "image/svg+xml";
|
|
if (isText && !ctx.req.header("Range")) {
|
|
return revalidatedResponse(
|
|
readFileSync(filePath, "utf-8"),
|
|
contentType,
|
|
ctx.req.header("If-None-Match"),
|
|
);
|
|
}
|
|
const proxyParam = ctx.req.query("hf-proxy");
|
|
if (proxyParam !== undefined && isProxyVariantRequest(proxyParam)) {
|
|
// 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 facts = await probeAssetCodec(filePath);
|
|
const eligibility = decideMediaProxyEligibility(facts);
|
|
if (!eligibility.eligible) {
|
|
return ctx.text(`Media proxy unavailable: ${eligibility.reason}`, 422);
|
|
}
|
|
if (!facts) return ctx.text("Media proxy unavailable: unknown_codec", 422);
|
|
const proxyVariant = resolveProxyVariantRequest(proxyParam, facts);
|
|
if (!proxyVariant) {
|
|
return ctx.text("Media proxy variant does not match asset", 422);
|
|
}
|
|
recordProxyRequest();
|
|
const proxyPath = await resolveProxy(project.dir, filePath, proxyVariant);
|
|
return buildRangeResponse(
|
|
proxyPath,
|
|
PROXY_VARIANT_CONFIG[proxyVariant].contentType,
|
|
ctx.req.header("Range"),
|
|
ctx.req.header("If-None-Match"),
|
|
);
|
|
} 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"),
|
|
ctx.req.header("If-None-Match"),
|
|
);
|
|
});
|
|
}
|
|
|
|
function buildPlayerPage(projectName: string): string {
|
|
return `<!doctype html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="UTF-8" />
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
|
<title>${projectName} — HyperFrames Player</title>
|
|
<style>
|
|
* { margin: 0; padding: 0; box-sizing: border-box; }
|
|
body {
|
|
background: #0a0a0a; color: #fff;
|
|
font-family: system-ui, -apple-system, sans-serif;
|
|
height: 100vh; display: flex; flex-direction: column;
|
|
align-items: center; justify-content: center;
|
|
padding: 24px;
|
|
}
|
|
.player-wrap {
|
|
width: 100%; max-width: 1280px; aspect-ratio: 16/9;
|
|
border-radius: 8px; overflow: hidden;
|
|
}
|
|
hyperframes-player { width: 100%; height: 100%; }
|
|
.info {
|
|
margin-top: 16px; font-size: 12px; color: #444;
|
|
font-family: monospace;
|
|
}
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<div class="player-wrap">
|
|
<hyperframes-player src="/composition/index.html" controls muted></hyperframes-player>
|
|
</div>
|
|
<div class="info">${projectName} — hyperframes play</div>
|
|
<script src="/player.js"></script>
|
|
</body>
|
|
</html>`;
|
|
}
|