fix(engine): the GPU, host-ceiling and HDR launches keep the sandbox where the host allows it (#8038)

* test(engine): the GPU, host-ceiling and HDR launches keep the sandbox where the host allows it

* fix(engine): the GPU, host-ceiling and HDR launches keep the sandbox where the host allows it

* test(engine): the host-ceiling stub shell runs only where /bin/sh does
This commit is contained in:
Miguel Ángel
2026-11-17 06:49:28 +00:00
committed by GitHub
parent 70820b386f
commit 7b27fbc84a
6 changed files with 135 additions and 62 deletions
@@ -768,6 +768,15 @@ describe("resolveBrowserGpuMode", () => {
},
);
it("probes the GPU with Chrome's sandbox where the host allows it, as the render runs", async () => {
const { launch } = setMockWebGlProbe({ hasWebGL: true, vendor: "NVIDIA", renderer: "NVIDIA" });
await resolveBrowserGpuMode("auto", { sandbox: true });
const args: string[] = launch.mock.calls[0]?.[0]?.args ?? [];
expect(args).toContain("--enable-webgl");
for (const flag of ["--no-sandbox", "--disable-setuid-sandbox", "--no-zygote"])
expect(args).not.toContain(flag);
});
it("lets a host own GPU probe launch and cleanup", async () => {
const { launch } = setMockWebGlProbe({ hasWebGL: true, vendor: "NVIDIA", renderer: "NVIDIA" });
const close = vi.fn(async (browser: Browser) => {
+23 -17
View File
@@ -43,8 +43,8 @@ import { removeTreeBestEffortAsync } from "@hyperframes/core/remove-tree";
import { getSystemTotalMb, LOW_MEMORY_TOTAL_MB_THRESHOLD } from "./systemMemory.js";
import {
chromeSandboxArgs,
chromeSandboxEnabled,
launchWithChromeSandboxFallback,
noSandboxUnlessRequired,
} from "./chromeSandbox.js";
import { describeWslGpuAccess, detectWsl, type WslHostFacts } from "./wslHost.js";
import {
@@ -113,6 +113,7 @@ interface GpuProbeOptions {
platform?: NodeJS.Platform;
probeLifecycle?: GpuProbeLifecycle;
wslHost?: WslHostFacts;
sandbox?: boolean;
}
const GPU_PROBE_TIMEOUT_MS = 15_000;
@@ -129,19 +130,21 @@ async function probeHardwareWebGlInfo(
): Promise<WebGlProbeInfo> {
let probeBrowser: Browser | undefined;
try {
const launchOptions: LaunchOptions = {
...ownedLaunchOptions(),
headless: true,
args: withHyperframesBrowserMarker(options.args),
defaultViewport: { width: 64, height: 64 },
executablePath: options.executablePath,
env: buildChromeLaunchEnv(options.env),
timeout: options.browserTimeout,
waitForInitialPage: false,
};
probeBrowser = options.probeLifecycle
? await options.probeLifecycle.launch(ppt, launchOptions)
: await ppt.launch(launchOptions);
probeBrowser = await launchWithChromeSandboxFallback(options.args, (args) => {
const launchOptions: LaunchOptions = {
...ownedLaunchOptions(),
headless: true,
args: withHyperframesBrowserMarker(args),
defaultViewport: { width: 64, height: 64 },
executablePath: options.executablePath,
env: buildChromeLaunchEnv(options.env),
timeout: options.browserTimeout,
waitForInitialPage: false,
};
return options.probeLifecycle
? options.probeLifecycle.launch(ppt, launchOptions)
: ppt.launch(launchOptions);
});
return await rejectAfter(
readWebGlInfo(probeBrowser),
GPU_PROBE_TIMEOUT_MS,
@@ -574,9 +577,9 @@ async function getPuppeteerOrNull(): Promise<PuppeteerNode | null> {
}
}
function getHardwareGpuProbeArgs(platform: NodeJS.Platform): string[] {
function getHardwareGpuProbeArgs(platform: NodeJS.Platform, sandbox: boolean): string[] {
return [
...noSandboxUnlessRequired(),
...chromeSandboxArgs(sandbox),
"--disable-dev-shm-usage",
"--enable-webgl",
"--ignore-gpu-blocklist",
@@ -626,7 +629,10 @@ async function probeWebGlMode(
): Promise<GpuProbeOutcome> {
try {
const info = await probeHardwareWebGlInfo(ppt, {
args: getHardwareGpuProbeArgs(options.platform ?? process.platform),
args: getHardwareGpuProbeArgs(
options.platform ?? process.platform,
options.sandbox ?? chromeSandboxEnabled(),
),
browserTimeout: options.browserTimeout ?? DEFAULT_CONFIG.browserTimeout,
executablePath: launchableBrowserPath({ chromePath: options.chromePath }),
probeLifecycle: options.probeLifecycle,
@@ -5,7 +5,11 @@ import { debuglog } from "node:util";
import { release } from "node:os";
import { dirname, join } from "node:path";
import { buildChromeLaunchEnv } from "@hyperframes/core/chrome-env";
import { noSandboxUnlessRequired } from "./chromeSandbox.js";
import {
chromeSandboxArgs,
chromeSandboxEnabled,
startsWithChromeSandboxFallback,
} from "./chromeSandbox.js";
/** Chrome 151 dropped macOS 12 and older (Darwin < 22); 150 is the last major that launches there. */
const MACOS_12_LAST_CHROME_MAJOR = 150;
@@ -157,18 +161,25 @@ const starts = new Map<string, boolean>();
const debug = debuglog("hyperframes:browser");
/** Whether a shell loads a blank page and exits: an old build can die at launch on a newer OS. Asked once per path. */
export function shellStarts(binary: string, timeoutMs = 10_000): boolean {
export function shellStarts(
binary: string,
timeoutMs = 10_000,
sandbox = chromeSandboxEnabled(),
): boolean {
let answer = starts.get(binary);
if (answer === undefined) {
const probe = [...noSandboxUnlessRequired(), "--dump-dom", "about:blank"];
answer =
spawnSync(binary, probe, {
env: buildChromeLaunchEnv(),
stdio: "ignore",
timeout: timeoutMs,
killSignal: "SIGKILL",
windowsHide: true,
})?.status === 0;
const probe = [...chromeSandboxArgs(sandbox), "--dump-dom", "about:blank"];
answer = startsWithChromeSandboxFallback(
probe,
(args) =>
spawnSync(binary, args, {
env: buildChromeLaunchEnv(),
stdio: "ignore",
timeout: timeoutMs,
killSignal: "SIGKILL",
windowsHide: true,
})?.status === 0,
);
if (!answer) debug("skipping %s: it did not start", binary);
starts.set(binary, answer);
}
@@ -1,12 +1,16 @@
import { chmodSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import {
_resetChromeSandboxFallbackForTests,
chromeSandboxEnabled,
launchWithChromeSandboxFallback,
NO_SANDBOX_ARGS,
noSandboxUnlessRequired,
startsWithChromeSandboxFallback,
type ChromeSandboxHost,
} from "./chromeSandbox.js";
import { shellStarts } from "./chromeHostCeiling.js";
import { buildChromeArgs } from "./browserManager.js";
import { buildHdrChromeArgs } from "./hdrCapture.js";
@@ -72,30 +76,58 @@ describe("chromeSandboxEnabled", () => {
});
});
describe("launches that always ran without the sandbox", () => {
it("keep it when HYPERFRAMES_CHROME_SANDBOX=1 requires it, and run as before otherwise", () => {
expect(noSandboxUnlessRequired({ HYPERFRAMES_CHROME_SANDBOX: "1" })).toEqual([]);
expect(noSandboxUnlessRequired({})).toEqual(["--no-sandbox", "--disable-setuid-sandbox"]);
describe("probe and HDR launches follow the same sandbox rule as the render", () => {
it("HDR capture keeps the sandbox where the host allows it, and drops all three flags together", () => {
const sandboxed = buildHdrChromeArgs(640, 360, true);
for (const flag of NO_SANDBOX_ARGS) expect(sandboxed).not.toContain(flag);
expect(buildHdrChromeArgs(640, 360, false)).toEqual(expect.arrayContaining(NO_SANDBOX_ARGS));
});
it("HDR capture keeps the sandbox when it is required, and drops --no-zygote with it", () => {
it("HDR capture keeps the sandbox when HYPERFRAMES_CHROME_SANDBOX=1 requires it", () => {
vi.stubEnv("HYPERFRAMES_CHROME_SANDBOX", "1");
try {
const args = buildHdrChromeArgs(640, 360);
expect(args).not.toContain("--no-sandbox");
expect(args).not.toContain("--no-zygote");
} finally {
vi.unstubAllEnvs();
}
vi.stubEnv("HYPERFRAMES_CHROME_SANDBOX", "");
try {
expect(buildHdrChromeArgs(640, 360)).toEqual(
expect.arrayContaining(["--no-sandbox", "--disable-setuid-sandbox", "--no-zygote"]),
);
for (const flag of NO_SANDBOX_ARGS) expect(buildHdrChromeArgs(640, 360)).not.toContain(flag);
} finally {
vi.unstubAllEnvs();
}
});
it.skipIf(process.platform === "win32")(
"the host-ceiling probe starts a shell with its sandbox where the host allows it",
() => {
const dir = mkdtempSync(join(tmpdir(), "hf-shell-starts-"));
try {
const shell = join(dir, "chrome");
const seen = join(dir, "args");
writeFileSync(shell, `#!/bin/sh\nprintf '%s\\n' "$@" >> "${seen}"\n`);
chmodSync(shell, 0o755);
expect(shellStarts(shell, 5_000, true)).toBe(true);
const args = readFileSync(seen, "utf8").trim().split("\n");
expect(args).toContain("--dump-dom");
for (const flag of NO_SANDBOX_ARGS) expect(args).not.toContain(flag);
} finally {
rmSync(dir, { recursive: true, force: true });
}
},
);
});
describe("startsWithChromeSandboxFallback", () => {
const refusesSandbox = (args: string[]) => args.includes("--no-sandbox");
it("tries a Linux start once more without the sandbox when the sandboxed one fails", () => {
const starts = vi.fn(refusesSandbox);
expect(startsWithChromeSandboxFallback(["--dump-dom"], starts, "linux", {})).toBe(true);
expect(starts.mock.calls.map(([args]) => args.includes("--no-sandbox"))).toEqual([false, true]);
});
it("never drops the sandbox when it is required, or off Linux", () => {
const starts = vi.fn(refusesSandbox);
const env = { HYPERFRAMES_CHROME_SANDBOX: "1" };
expect(startsWithChromeSandboxFallback(["--dump-dom"], starts, "linux", env)).toBe(false);
expect(startsWithChromeSandboxFallback(["--dump-dom"], starts, "darwin", {})).toBe(false);
expect(starts).toHaveBeenCalledTimes(2);
});
});
describe("buildChromeArgs sandbox flags", () => {
+11 -4
View File
@@ -58,10 +58,6 @@ export function chromeSandboxEnabled(host: ChromeSandboxHost = currentHost()): b
return host.platform !== "linux" || !linuxCannotSandbox(host);
}
export function noSandboxUnlessRequired(env: NodeJS.ProcessEnv = process.env): string[] {
return env.HYPERFRAMES_CHROME_SANDBOX === "1" ? [] : ["--no-sandbox", "--disable-setuid-sandbox"];
}
export function chromeSandboxArgs(sandbox = chromeSandboxEnabled()): string[] {
return sandbox ? [] : NO_SANDBOX_ARGS;
}
@@ -92,6 +88,17 @@ function sandboxStartFailure(error: unknown): boolean {
);
}
export function startsWithChromeSandboxFallback(
args: readonly string[],
starts: (args: string[]) => boolean,
platform: NodeJS.Platform = process.platform,
env: NodeJS.ProcessEnv = process.env,
): boolean {
if (starts([...args])) return true;
const sandboxed = platform === "linux" && !args.includes("--no-sandbox");
return sandboxed && env.HYPERFRAMES_CHROME_SANDBOX !== "1" && starts(withoutChromeSandbox(args));
}
/**
* A sandboxed Linux launch Chrome refuses at startup is retried once without the sandbox.
* The sandbox stays off for the process once Chrome names it as the cause, or after a second
+21 -13
View File
@@ -23,7 +23,11 @@ import { withHyperframesBrowserMarker } from "@hyperframes/core/browser-marker";
import { buildChromeLaunchEnv } from "@hyperframes/core/chrome-env";
import type { Page, Browser, PuppeteerNode } from "puppeteer-core";
import { resolveFullChromePath, ownedLaunchOptions } from "./browserManager.js";
import { noSandboxUnlessRequired } from "./chromeSandbox.js";
import {
chromeSandboxArgs,
chromeSandboxEnabled,
launchWithChromeSandboxFallback,
} from "./chromeSandbox.js";
// ── PQ (SMPTE 2084) OETF ─────────────────────────────────────────────────────
@@ -248,13 +252,16 @@ export async function launchHdrBrowser(
);
}
const browser = await ppt.launch({
...ownedLaunchOptions(),
headless: false,
executablePath: chromePath,
env: buildChromeLaunchEnv(),
args: withHyperframesBrowserMarker(buildHdrChromeArgs(width, height)),
});
const launcher = ppt;
const browser = await launchWithChromeSandboxFallback(buildHdrChromeArgs(width, height), (args) =>
launcher.launch({
...ownedLaunchOptions(),
headless: false,
executablePath: chromePath,
env: buildChromeLaunchEnv(),
args: withHyperframesBrowserMarker(args),
}),
);
const page = await browser.newPage();
await page.setViewport({ width, height });
@@ -262,12 +269,14 @@ export async function launchHdrBrowser(
return { browser, page };
}
export function buildHdrChromeArgs(width: number, height: number): string[] {
const noSandbox = noSandboxUnlessRequired();
const noZygoteOnlyWithoutSandbox = noSandbox.length > 0 ? ["--no-zygote"] : [];
export function buildHdrChromeArgs(
width: number,
height: number,
sandbox = chromeSandboxEnabled(),
): string[] {
return [
"--enable-unsafe-webgpu",
...noSandbox,
...chromeSandboxArgs(sandbox),
"--window-position=-10000,-10000",
`--window-size=${width},${height}`,
"--disable-background-timer-throttling",
@@ -278,7 +287,6 @@ export function buildHdrChromeArgs(width: number, height: number): string[] {
"--disable-component-update",
"--disable-default-apps",
"--disable-sync",
...noZygoteOnlyWithoutSandbox,
"--force-gpu-mem-available-mb=4096",
"--autoplay-policy=no-user-gesture-required",
];