mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-16 14:27:26 +00:00
feat(engine): a host can supply its own Chromium launcher
This commit is contained in:
@@ -1552,6 +1552,15 @@ npx hyperframes browser clear # remove the cached download
|
||||
`$(npx hyperframes browser path)`. Use `--force` when a download was
|
||||
interrupted and left a partial file behind.
|
||||
|
||||
A host can supply its own Chromium launcher instead. Set
|
||||
`HYPERFRAMES_BROWSER_LAUNCHER` to an ES module that exports
|
||||
`launch(options, puppeteer)` and returns a Puppeteer `Browser` whose `process()`
|
||||
is the browser it started. Every render, check and snapshot then starts its
|
||||
browser through that module, and nothing is downloaded. The launcher takes
|
||||
precedence over `HYPERFRAMES_BROWSER_PATH` and `PRODUCER_HEADLESS_SHELL_PATH`.
|
||||
Its browser is never headless-shell, so it does not use BeginFrame capture.
|
||||
When the variable is unset, browsers start as they always have.
|
||||
|
||||
### `docs`
|
||||
|
||||
Read documentation in the terminal.
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
import type { Browser, LaunchOptions, PuppeteerNode } from "puppeteer-core";
|
||||
import { launchRenderBrowser } from "@hyperframes/engine/chrome-host-ceiling";
|
||||
import {
|
||||
resolveCaptureBrowserGpuMode,
|
||||
type BrowserGpuMode,
|
||||
@@ -117,7 +118,13 @@ async function launchOwnedBrowser(
|
||||
const signal = options.signal ? AbortSignal.any([options.signal, abort.signal]) : abort.signal;
|
||||
const launchedAt = Date.now();
|
||||
const launch = untilLaunchOrAbort(
|
||||
puppeteer.launch({ ...options, pipe: true, signal, handleSIGINT: false, handleSIGTERM: false }),
|
||||
launchRenderBrowser(puppeteer, {
|
||||
...options,
|
||||
pipe: true,
|
||||
signal,
|
||||
handleSIGINT: false,
|
||||
handleSIGTERM: false,
|
||||
}),
|
||||
signal,
|
||||
);
|
||||
const limit = options.timeout ?? LAUNCH_TIMEOUT_MS;
|
||||
|
||||
@@ -273,6 +273,7 @@ describe("findBrowser — cache resolution", () => {
|
||||
value: "x64",
|
||||
configurable: true,
|
||||
});
|
||||
delete process.env["HYPERFRAMES_BROWSER_LAUNCHER"];
|
||||
delete process.env["HYPERFRAMES_BROWSER_PATH"];
|
||||
delete process.env["PRODUCER_HEADLESS_SHELL_PATH"];
|
||||
installChildProcessMocks();
|
||||
@@ -1196,6 +1197,21 @@ describe("findBrowser — cache resolution", () => {
|
||||
expect(result?.source).toBe("env");
|
||||
});
|
||||
|
||||
it("returns a launcher module over both paths, with nothing looked up or downloaded", async () => {
|
||||
const hfPath = "/opt/hf/chrome-headless-shell";
|
||||
installFsMocks({ existing: new Set([hfPath]) });
|
||||
installPuppeteerBrowsersMock();
|
||||
process.env["HYPERFRAMES_BROWSER_LAUNCHER"] = "/host/launcher.mjs";
|
||||
process.env["HYPERFRAMES_BROWSER_PATH"] = hfPath;
|
||||
|
||||
const { ensureBrowser } = await import("./manager.js");
|
||||
|
||||
await expect(ensureBrowser({ preferManagedChrome: true })).resolves.toEqual({
|
||||
executablePath: "/host/launcher.mjs",
|
||||
source: "launcher",
|
||||
});
|
||||
});
|
||||
|
||||
it("does NOT warn on macOS when falling back to system Chrome", async () => {
|
||||
// macOS Chrome still works fine for the screenshot path and the perf
|
||||
// claims around BeginFrame are Linux-only — keep the warning Linux-scoped
|
||||
|
||||
@@ -216,7 +216,7 @@ function releaseBrowserInstallLock(ownerToken: string): void {
|
||||
rmSync(INSTALL_LOCK_DIR, { recursive: true, force: true });
|
||||
}
|
||||
|
||||
export type BrowserSource = "env" | "cache" | "system" | "download";
|
||||
export type BrowserSource = "launcher" | "env" | "cache" | "system" | "download";
|
||||
|
||||
export interface BrowserResult {
|
||||
executablePath: string;
|
||||
@@ -299,11 +299,15 @@ function whichBinary(name: string): string | undefined {
|
||||
|
||||
// A caller-supplied browser, named by HYPERFRAMES_BROWSER_PATH or PRODUCER_HEADLESS_SHELL_PATH (the engine's
|
||||
// and the deploy docs' name). check, snapshot and compare honour it as render does; which name wins is
|
||||
// browserPathFromEnv's, so the engine launches what this resolved.
|
||||
// browserPathFromEnv's, so the engine launches what this resolved. A HYPERFRAMES_BROWSER_LAUNCHER module starts
|
||||
// the browser itself, so nothing is looked up or downloaded.
|
||||
function findFromEnv(): BrowserResult | undefined {
|
||||
const envPath = browserPathFromEnv()?.path;
|
||||
if (envPath && existsSync(envPath)) {
|
||||
return { executablePath: envPath, source: "env" };
|
||||
const fromEnv = browserPathFromEnv();
|
||||
if (fromEnv?.name === "HYPERFRAMES_BROWSER_LAUNCHER") {
|
||||
return { executablePath: fromEnv.path, source: "launcher" };
|
||||
}
|
||||
if (fromEnv && existsSync(fromEnv.path)) {
|
||||
return { executablePath: fromEnv.path, source: "env" };
|
||||
}
|
||||
return undefined;
|
||||
}
|
||||
|
||||
@@ -354,6 +354,26 @@ describe("runEnvironmentChecks — Chrome shared libraries (Linux/WSL)", () => {
|
||||
expect(result.outcomes.find((o) => o.name === "Chrome")).toMatchObject({ ok: true });
|
||||
});
|
||||
|
||||
it("passes a launcher module without running it as a browser binary", async () => {
|
||||
vi.spyOn(manager, "findBrowser").mockResolvedValue({
|
||||
executablePath: "/host/launcher.mjs",
|
||||
source: "launcher",
|
||||
});
|
||||
|
||||
const result = await runEnvironmentChecks({ includeBrowser: true });
|
||||
|
||||
expect(result.outcomes.find((o) => o.name === "Chrome")).toMatchObject({
|
||||
ok: true,
|
||||
detail: "launcher: /host/launcher.mjs",
|
||||
});
|
||||
expect(result.browser?.executablePath).toBe("/host/launcher.mjs");
|
||||
expect(runProcess).not.toHaveBeenCalledWith(
|
||||
"/host/launcher.mjs",
|
||||
expect.anything(),
|
||||
expect.anything(),
|
||||
);
|
||||
});
|
||||
|
||||
it("resolveRenderBrowser returns the browser the render check found", async () => {
|
||||
vi.spyOn(manager, "findBrowser").mockResolvedValue({
|
||||
executablePath: process.execPath,
|
||||
|
||||
@@ -286,6 +286,23 @@ async function chromeLaunchOutcome(
|
||||
}
|
||||
}
|
||||
|
||||
/** A launcher module is started by its host, so it has no binary to run `--version` on. */
|
||||
async function foundChromeOutcome(
|
||||
info: BrowserResult,
|
||||
signal?: AbortSignal,
|
||||
): Promise<EnvironmentCheckOutcome> {
|
||||
const found: EnvironmentCheckOutcome = {
|
||||
name: "Chrome",
|
||||
ok: true,
|
||||
level: "ok",
|
||||
detail: `${info.source}: ${info.executablePath}`,
|
||||
path: info.executablePath,
|
||||
};
|
||||
return info.source === "launcher"
|
||||
? found
|
||||
: chromeLaunchOutcome(info.executablePath, found, signal);
|
||||
}
|
||||
|
||||
async function checkChrome(
|
||||
browserPath?: string,
|
||||
signal?: AbortSignal,
|
||||
@@ -330,19 +347,7 @@ async function checkChrome(
|
||||
info = undefined;
|
||||
failure = normalizeErrorMessage(error);
|
||||
}
|
||||
if (info) {
|
||||
return chromeLaunchOutcome(
|
||||
info.executablePath,
|
||||
{
|
||||
name: "Chrome",
|
||||
ok: true,
|
||||
level: "ok",
|
||||
detail: `${info.source}: ${info.executablePath}`,
|
||||
path: info.executablePath,
|
||||
},
|
||||
signal,
|
||||
);
|
||||
}
|
||||
if (info) return foundChromeOutcome(info, signal);
|
||||
|
||||
return {
|
||||
name: "Chrome",
|
||||
|
||||
@@ -872,6 +872,21 @@ describe("resolveHeadlessShellPath", () => {
|
||||
}
|
||||
});
|
||||
|
||||
it("resolves no headless shell when a launcher module starts the browser", () => {
|
||||
const dir = mkdtempSync(join(tmpdir(), "hyperframes-engine-browser-env-"));
|
||||
try {
|
||||
const shell = join(dir, "chrome-headless-shell");
|
||||
writeFileSync(shell, "");
|
||||
process.env.PRODUCER_HEADLESS_SHELL_PATH = shell;
|
||||
process.env.HYPERFRAMES_BROWSER_LAUNCHER = join(dir, "launcher.mjs");
|
||||
|
||||
expect(resolveHeadlessShellPath({})).toBeUndefined();
|
||||
} finally {
|
||||
delete process.env.HYPERFRAMES_BROWSER_LAUNCHER;
|
||||
rmSync(dir, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
it("uses HYPERFRAMES_BROWSER_PATH when the CLI resolved a browser explicitly", () => {
|
||||
const dir = mkdtempSync(join(tmpdir(), "hyperframes-engine-browser-env-"));
|
||||
try {
|
||||
|
||||
@@ -18,6 +18,7 @@ import {
|
||||
compareBrowserVersionsDescending,
|
||||
exceedsChromeCeiling,
|
||||
isManagedChromeDir,
|
||||
launchRenderBrowser,
|
||||
pickSharedShell,
|
||||
} from "./chromeHostCeiling.js";
|
||||
import { DEFAULT_CONFIG, type EngineConfig } from "../config.js";
|
||||
@@ -120,7 +121,7 @@ async function probeHardwareWebGlInfo(
|
||||
};
|
||||
probeBrowser = options.probeLifecycle
|
||||
? await options.probeLifecycle.launch(ppt, launchOptions)
|
||||
: await ppt.launch(launchOptions);
|
||||
: await launchRenderBrowser(ppt, launchOptions);
|
||||
return await rejectAfter(
|
||||
readWebGlInfo(probeBrowser),
|
||||
GPU_PROBE_TIMEOUT_MS,
|
||||
@@ -253,6 +254,7 @@ export function resolveHeadlessShellPath(
|
||||
return config.chromePath;
|
||||
}
|
||||
const fromEnv = browserPathFromEnv();
|
||||
if (fromEnv?.name === "HYPERFRAMES_BROWSER_LAUNCHER") return undefined;
|
||||
if (fromEnv) {
|
||||
if (!existsSync(fromEnv.path)) {
|
||||
throw new Error(
|
||||
@@ -855,7 +857,7 @@ async function launchBrowser(
|
||||
let captureMode = fingerprint.requestedCaptureMode;
|
||||
let browser: Browser | undefined;
|
||||
try {
|
||||
browser = await ppt.launch({
|
||||
browser = await launchRenderBrowser(ppt, {
|
||||
...sigintLaunchOptions(),
|
||||
headless: true,
|
||||
args: [...fingerprint.args],
|
||||
@@ -888,7 +890,7 @@ async function launchBrowser(
|
||||
`${probe.detail}; falling back to screenshot mode.`,
|
||||
);
|
||||
captureMode = "screenshot";
|
||||
browser = await ppt.launch({
|
||||
browser = await launchRenderBrowser(ppt, {
|
||||
...sigintLaunchOptions(),
|
||||
headless: true,
|
||||
args: stripBeginFrameFlags([...fingerprint.args]),
|
||||
|
||||
@@ -1,5 +1,14 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
import { chromeMajorCeiling, exceedsChromeCeiling } from "./chromeHostCeiling.js";
|
||||
import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join } from "node:path";
|
||||
import type { Browser, LaunchOptions, PuppeteerNode } from "puppeteer-core";
|
||||
import { afterEach, describe, expect, it, vi } from "vitest";
|
||||
import {
|
||||
browserPathFromEnv,
|
||||
chromeMajorCeiling,
|
||||
exceedsChromeCeiling,
|
||||
launchRenderBrowser,
|
||||
} from "./chromeHostCeiling.js";
|
||||
|
||||
describe("chromeMajorCeiling", () => {
|
||||
it.each([
|
||||
@@ -22,3 +31,65 @@ describe("exceedsChromeCeiling", () => {
|
||||
expect(exceedsChromeCeiling(name, ceiling)).toBe(expected);
|
||||
});
|
||||
});
|
||||
|
||||
describe("browserPathFromEnv", () => {
|
||||
it("names a launcher module before either browser binary", () => {
|
||||
expect(
|
||||
browserPathFromEnv({
|
||||
HYPERFRAMES_BROWSER_LAUNCHER: "/host/launcher.mjs",
|
||||
HYPERFRAMES_BROWSER_PATH: "/opt/chrome",
|
||||
PRODUCER_HEADLESS_SHELL_PATH: "/opt/shell",
|
||||
}),
|
||||
).toEqual({ name: "HYPERFRAMES_BROWSER_LAUNCHER", path: "/host/launcher.mjs" });
|
||||
});
|
||||
});
|
||||
|
||||
describe("launchRenderBrowser", () => {
|
||||
const dirs: string[] = [];
|
||||
afterEach(() => {
|
||||
for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
|
||||
});
|
||||
const launcherModule = (source: string) => {
|
||||
const dir = mkdtempSync(join(tmpdir(), "hyperframes-launcher-"));
|
||||
dirs.push(dir);
|
||||
const file = join(dir, "launcher.mjs");
|
||||
writeFileSync(file, source);
|
||||
return file;
|
||||
};
|
||||
const browser = { marker: "browser" } as unknown as Browser;
|
||||
const options: LaunchOptions = { headless: true, args: ["--font-render-hinting=none"] };
|
||||
|
||||
it("calls puppeteer.launch with the options unchanged when no launcher is set", async () => {
|
||||
const launch = vi.fn(async () => browser);
|
||||
const puppeteer = { launch } as unknown as PuppeteerNode;
|
||||
|
||||
await expect(launchRenderBrowser(puppeteer, options, {})).resolves.toBe(browser);
|
||||
expect(launch).toHaveBeenCalledWith(options);
|
||||
});
|
||||
|
||||
it("hands the options and puppeteer to the launcher module instead", async () => {
|
||||
const file = launcherModule(
|
||||
"export async function launch(options, puppeteer) { return { options, puppeteer }; }",
|
||||
);
|
||||
const launch = vi.fn();
|
||||
const puppeteer = { launch } as unknown as PuppeteerNode;
|
||||
|
||||
const result = await launchRenderBrowser(puppeteer, options, {
|
||||
HYPERFRAMES_BROWSER_LAUNCHER: file,
|
||||
});
|
||||
|
||||
expect(result).toEqual({ options, puppeteer });
|
||||
expect(launch).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("says so when the module has no launch export", async () => {
|
||||
const file = launcherModule("export const start = () => {};");
|
||||
const puppeteer = { launch: vi.fn() } as unknown as PuppeteerNode;
|
||||
|
||||
await expect(
|
||||
launchRenderBrowser(puppeteer, options, { HYPERFRAMES_BROWSER_LAUNCHER: file }),
|
||||
).rejects.toThrow(
|
||||
`HYPERFRAMES_BROWSER_LAUNCHER="${file}" does not export launch(options, puppeteer).`,
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
@@ -1,6 +1,9 @@
|
||||
import { spawnSync } from "node:child_process";
|
||||
import { debuglog } from "node:util";
|
||||
import { release } from "node:os";
|
||||
import { resolve } from "node:path";
|
||||
import { pathToFileURL } from "node:url";
|
||||
import type { Browser, LaunchOptions, PuppeteerNode } from "puppeteer-core";
|
||||
|
||||
/** Chrome 151 dropped macOS 12 and older (Darwin < 22); 150 is the last major that launches there. */
|
||||
const MACOS_12_LAST_CHROME_MAJOR = 150;
|
||||
@@ -93,13 +96,42 @@ export function pickSharedShell(
|
||||
return undefined;
|
||||
}
|
||||
|
||||
/** The browser binary an env var names. The CLI and the engine both resolve it here, HYPERFRAMES_BROWSER_PATH first. */
|
||||
export function browserPathFromEnv(
|
||||
env: NodeJS.ProcessEnv = process.env,
|
||||
): { name: "HYPERFRAMES_BROWSER_PATH" | "PRODUCER_HEADLESS_SHELL_PATH"; path: string } | undefined {
|
||||
for (const name of ["HYPERFRAMES_BROWSER_PATH", "PRODUCER_HEADLESS_SHELL_PATH"] as const) {
|
||||
/** The browser an env var names. The CLI and the engine both resolve it here: a launcher module first, then a
|
||||
* binary, HYPERFRAMES_BROWSER_PATH before PRODUCER_HEADLESS_SHELL_PATH. */
|
||||
export function browserPathFromEnv(env: NodeJS.ProcessEnv = process.env):
|
||||
| {
|
||||
name:
|
||||
| "HYPERFRAMES_BROWSER_LAUNCHER"
|
||||
| "HYPERFRAMES_BROWSER_PATH"
|
||||
| "PRODUCER_HEADLESS_SHELL_PATH";
|
||||
path: string;
|
||||
}
|
||||
| undefined {
|
||||
for (const name of [
|
||||
"HYPERFRAMES_BROWSER_LAUNCHER",
|
||||
"HYPERFRAMES_BROWSER_PATH",
|
||||
"PRODUCER_HEADLESS_SHELL_PATH",
|
||||
] as const) {
|
||||
const path = env[name];
|
||||
if (path) return { name, path };
|
||||
}
|
||||
return undefined;
|
||||
}
|
||||
|
||||
/** Starts a render browser. With HYPERFRAMES_BROWSER_LAUNCHER set, the module it names starts it instead:
|
||||
* `export async function launch(options, puppeteer)` returns a Browser whose `process()` is the browser it started. */
|
||||
export async function launchRenderBrowser(
|
||||
puppeteer: PuppeteerNode,
|
||||
options: LaunchOptions,
|
||||
env: NodeJS.ProcessEnv = process.env,
|
||||
): Promise<Browser> {
|
||||
const path = env.HYPERFRAMES_BROWSER_LAUNCHER;
|
||||
if (!path) return puppeteer.launch(options);
|
||||
const launcher: { launch?: unknown } = await import(pathToFileURL(resolve(path)).href);
|
||||
if (typeof launcher.launch !== "function") {
|
||||
throw new Error(
|
||||
`HYPERFRAMES_BROWSER_LAUNCHER="${path}" does not export launch(options, puppeteer).`,
|
||||
);
|
||||
}
|
||||
return launcher.launch(options, puppeteer);
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user