feat(engine): a host can supply its own Chromium launcher

This commit is contained in:
Miguel Angel Simon Sierra
2026-10-20 21:34:51 -04:00
parent c56e02e9bf
commit 8c4db038fd
10 changed files with 210 additions and 29 deletions
+9
View File
@@ -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.
+8 -1
View File
@@ -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;
+16
View File
@@ -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
+9 -5
View File
@@ -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,
+18 -13
View File
@@ -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);
}