mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 07:50:13 +00:00
fix(engine): keep Chrome's sandbox on for local renders where the host supports it (#7625)
* fix(engine): keep Chrome's sandbox on for local renders where the host supports it Chrome launched with --no-sandbox on every host. Keep the sandbox on macOS, Windows and non-root Linux outside containers; drop it as root, in Docker/Podman/Kubernetes, on Lambda and Cloud Run, and where Linux restricts unprivileged user namespaces. --no-zygote now ships only with --no-sandbox, since Chrome refuses it while sandboxed. A sandboxed Linux launch that fails at startup retries once without the sandbox and warns. HYPERFRAMES_CHROME_SANDBOX=1|0 overrides the choice. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test(cli): cover the Linux sandbox retry in managed browser launches The off-macOS closed-pipe case now passes --no-sandbox, so it still pins "no seatbelt relaunch" rather than the new Linux sandbox retry, which gets its own case. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(engine): honor HYPERFRAMES_CHROME_SANDBOX=1 and latch the fallback on clear evidence only With the override set to 1, a sandboxed launch Chrome refuses now fails instead of retrying unsandboxed. A bare startup exit (TargetCloseError) retries that launch without the sandbox but only latches the sandbox off after a second one, so a single unrelated early kill no longer disables it for the rest of a long-lived process. Chrome naming the sandbox in its error still latches at once. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5.5
parent
9c3258ccbf
commit
400a4e2285
@@ -561,6 +561,7 @@ export {
|
||||
pipeLaunchClosedOnMac,
|
||||
sandboxDeniedRemediation,
|
||||
} from "./services/sandboxLaunch.js";
|
||||
export { launchWithChromeSandboxFallback } from "./services/chromeSandbox.js";
|
||||
export {
|
||||
VariablesInvalidError,
|
||||
type VariablesIssue,
|
||||
|
||||
@@ -31,6 +31,7 @@ import {
|
||||
} from "./chromeHostCeiling.js";
|
||||
import { DEFAULT_CONFIG, type EngineConfig } from "../config.js";
|
||||
import { getSystemTotalMb, LOW_MEMORY_TOTAL_MB_THRESHOLD } from "./systemMemory.js";
|
||||
import { chromeSandboxArgs, launchWithChromeSandboxFallback } from "./chromeSandbox.js";
|
||||
import { describeWslGpuAccess, detectWsl, type WslHostFacts } from "./wslHost.js";
|
||||
import {
|
||||
BrowserLeasePool,
|
||||
@@ -923,16 +924,18 @@ async function launchBrowser(
|
||||
let captureMode = fingerprint.requestedCaptureMode;
|
||||
let browser: Browser | undefined;
|
||||
const launch = (args: readonly string[]) =>
|
||||
launchInsideSandbox(ppt, {
|
||||
...ownedLaunchOptions(),
|
||||
headless: true,
|
||||
args: withHyperframesBrowserMarker(args),
|
||||
defaultViewport: null,
|
||||
executablePath: fingerprint.executablePath,
|
||||
env,
|
||||
timeout: fingerprint.browserTimeoutMs,
|
||||
protocolTimeout: fingerprint.protocolTimeoutMs,
|
||||
}).catch(async (error: unknown) => {
|
||||
launchWithChromeSandboxFallback(args, (launchArgs) =>
|
||||
launchInsideSandbox(ppt, {
|
||||
...ownedLaunchOptions(),
|
||||
headless: true,
|
||||
args: withHyperframesBrowserMarker(launchArgs),
|
||||
defaultViewport: null,
|
||||
executablePath: fingerprint.executablePath,
|
||||
env,
|
||||
timeout: fingerprint.browserTimeoutMs,
|
||||
protocolTimeout: fingerprint.protocolTimeoutMs,
|
||||
}),
|
||||
).catch(async (error: unknown) => {
|
||||
const remediation =
|
||||
process.platform === "darwin" &&
|
||||
sandboxDeniedRemediation(error instanceof Error ? error.message : "");
|
||||
@@ -1105,6 +1108,7 @@ export interface BuildChromeArgsOptions {
|
||||
platform?: NodeJS.Platform;
|
||||
/** The composition declares `data-requires-webgpu`; forces the WebGPU flag even in "software" mode. */
|
||||
requiresWebGpu?: boolean;
|
||||
sandbox?: boolean;
|
||||
}
|
||||
|
||||
const CANVAS_DRAW_ELEMENT_FEATURE_FLAG = "--enable-features=CanvasDrawElement";
|
||||
@@ -1143,8 +1147,7 @@ export function buildChromeArgs(options: BuildChromeArgsOptions, config?: GpuCon
|
||||
// appear in Puppeteer's defaults, Playwright, Remotion, and Chrome's own
|
||||
// headless-shell guidance.
|
||||
const chromeArgs = [
|
||||
"--no-sandbox",
|
||||
"--disable-setuid-sandbox",
|
||||
...chromeSandboxArgs(options.sandbox),
|
||||
"--disable-dev-shm-usage",
|
||||
softwareWebGpu
|
||||
? `${CANVAS_DRAW_ELEMENT_FEATURE_FLAG},Vulkan`
|
||||
@@ -1175,7 +1178,6 @@ export function buildChromeArgs(options: BuildChromeArgsOptions, config?: GpuCon
|
||||
"--disable-domain-reliability",
|
||||
"--disable-print-preview",
|
||||
"--no-pings",
|
||||
"--no-zygote",
|
||||
// Memory — scale GPU budget to available system RAM
|
||||
`--force-gpu-mem-available-mb=${getGpuMemBudgetMb()}`,
|
||||
"--disk-cache-size=268435456",
|
||||
|
||||
@@ -0,0 +1,166 @@
|
||||
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
|
||||
import {
|
||||
_resetChromeSandboxFallbackForTests,
|
||||
chromeSandboxEnabled,
|
||||
launchWithChromeSandboxFallback,
|
||||
NO_SANDBOX_ARGS,
|
||||
type ChromeSandboxHost,
|
||||
} from "./chromeSandbox.js";
|
||||
import { buildChromeArgs } from "./browserManager.js";
|
||||
|
||||
function host(overrides: Partial<ChromeSandboxHost> = {}): ChromeSandboxHost {
|
||||
return {
|
||||
platform: "linux",
|
||||
env: {},
|
||||
uid: 1000,
|
||||
exists: () => false,
|
||||
read: () => undefined,
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
const withFile = (path: string) => (candidate: string) => candidate === path;
|
||||
const withSysctl = (path: string, value: string) => (candidate: string) =>
|
||||
candidate === path ? value : undefined;
|
||||
|
||||
describe("chromeSandboxEnabled", () => {
|
||||
it.each(["darwin", "win32"] as const)("keeps the sandbox on %s", (platform) => {
|
||||
expect(chromeSandboxEnabled(host({ platform }))).toBe(true);
|
||||
expect(chromeSandboxEnabled(host({ platform, uid: 0 }))).toBe(true);
|
||||
});
|
||||
|
||||
it("keeps the sandbox for a non-root Linux user outside containers", () => {
|
||||
expect(chromeSandboxEnabled(host())).toBe(true);
|
||||
expect(
|
||||
chromeSandboxEnabled(
|
||||
host({ read: withSysctl("/proc/sys/kernel/apparmor_restrict_unprivileged_userns", "0") }),
|
||||
),
|
||||
).toBe(true);
|
||||
});
|
||||
|
||||
it.each<[string, Partial<ChromeSandboxHost>]>([
|
||||
["root", { uid: 0 }],
|
||||
["AWS Lambda", { env: { AWS_LAMBDA_FUNCTION_NAME: "render" } }],
|
||||
["the Lambda runtime", { env: { AWS_EXECUTION_ENV: "AWS_Lambda_nodejs22.x" } }],
|
||||
["a Cloud Run service", { env: { K_SERVICE: "renderer" } }],
|
||||
["a Cloud Run job", { env: { CLOUD_RUN_JOB: "renderer" } }],
|
||||
["Kubernetes", { env: { KUBERNETES_SERVICE_HOST: "10.0.0.1" } }],
|
||||
["Docker", { exists: withFile("/.dockerenv") }],
|
||||
["Podman", { exists: withFile("/run/.containerenv") }],
|
||||
[
|
||||
"AppArmor-restricted user namespaces",
|
||||
{ read: withSysctl("/proc/sys/kernel/apparmor_restrict_unprivileged_userns", "1") },
|
||||
],
|
||||
[
|
||||
"disabled user namespaces",
|
||||
{ read: withSysctl("/proc/sys/kernel/unprivileged_userns_clone", "0") },
|
||||
],
|
||||
])("drops the sandbox on Linux under %s", (_, overrides) => {
|
||||
expect(chromeSandboxEnabled(host(overrides))).toBe(false);
|
||||
});
|
||||
|
||||
it("lets HYPERFRAMES_CHROME_SANDBOX override detection", () => {
|
||||
expect(chromeSandboxEnabled(host({ uid: 0, env: { HYPERFRAMES_CHROME_SANDBOX: "1" } }))).toBe(
|
||||
true,
|
||||
);
|
||||
expect(
|
||||
chromeSandboxEnabled(host({ platform: "darwin", env: { HYPERFRAMES_CHROME_SANDBOX: "0" } })),
|
||||
).toBe(false);
|
||||
expect(chromeSandboxEnabled(host({ env: { HYPERFRAMES_CHROME_SANDBOX: "yes" } }))).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe("buildChromeArgs sandbox flags", () => {
|
||||
const base = { width: 320, height: 240, platform: "linux" as const };
|
||||
|
||||
it("omits every no-sandbox flag, --no-zygote included, when the sandbox is on", () => {
|
||||
const args = buildChromeArgs({ ...base, sandbox: true });
|
||||
for (const flag of NO_SANDBOX_ARGS) expect(args).not.toContain(flag);
|
||||
});
|
||||
|
||||
it("keeps --no-zygote alongside --no-sandbox when the sandbox is off", () => {
|
||||
expect(buildChromeArgs({ ...base, sandbox: false })).toEqual(
|
||||
expect.arrayContaining(["--no-sandbox", "--disable-setuid-sandbox", "--no-zygote"]),
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe("launchWithChromeSandboxFallback", () => {
|
||||
const closedTarget = Object.assign(new Error("Protocol error: Target closed"), {
|
||||
name: "TargetCloseError",
|
||||
});
|
||||
let warn: ReturnType<typeof vi.spyOn>;
|
||||
|
||||
beforeEach(() => {
|
||||
_resetChromeSandboxFallbackForTests();
|
||||
warn = vi.spyOn(console, "warn").mockImplementation(() => {});
|
||||
});
|
||||
afterEach(() => warn.mockRestore());
|
||||
|
||||
it("retries a bare startup exit once without the sandbox, warns once, and latches on the second", async () => {
|
||||
const launch = vi
|
||||
.fn<(args: string[]) => Promise<string>>()
|
||||
.mockRejectedValueOnce(closedTarget)
|
||||
.mockResolvedValueOnce("browser")
|
||||
.mockRejectedValueOnce(closedTarget)
|
||||
.mockResolvedValue("browser");
|
||||
|
||||
await expect(launchWithChromeSandboxFallback(["--a"], launch, "linux", {})).resolves.toBe(
|
||||
"browser",
|
||||
);
|
||||
await launchWithChromeSandboxFallback(["--a"], launch, "linux", {});
|
||||
await launchWithChromeSandboxFallback(["--a"], launch, "linux", {});
|
||||
|
||||
expect(launch.mock.calls.map(([args]) => args)).toEqual([
|
||||
["--a"],
|
||||
["--a", ...NO_SANDBOX_ARGS],
|
||||
["--a"],
|
||||
["--a", ...NO_SANDBOX_ARGS],
|
||||
["--a", ...NO_SANDBOX_ARGS],
|
||||
]);
|
||||
expect(warn).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
|
||||
it("latches at once when Chrome names the sandbox in its error", async () => {
|
||||
const launch = vi
|
||||
.fn<(args: string[]) => Promise<string>>()
|
||||
.mockRejectedValueOnce(new Error("Failed to launch the browser process: No usable sandbox!"))
|
||||
.mockResolvedValue("browser");
|
||||
await expect(launchWithChromeSandboxFallback([], launch, "linux", {})).resolves.toBe("browser");
|
||||
await launchWithChromeSandboxFallback([], launch, "linux", {});
|
||||
expect(launch.mock.calls.map(([args]) => args)).toEqual([[], NO_SANDBOX_ARGS, NO_SANDBOX_ARGS]);
|
||||
});
|
||||
|
||||
it("never drops the sandbox when HYPERFRAMES_CHROME_SANDBOX=1 requires it", async () => {
|
||||
const refused = new Error("Running as root without --no-sandbox is not supported");
|
||||
const launch = vi.fn<(args: string[]) => Promise<string>>().mockRejectedValue(refused);
|
||||
const env = { HYPERFRAMES_CHROME_SANDBOX: "1" };
|
||||
await expect(launchWithChromeSandboxFallback([], launch, "linux", env)).rejects.toBe(refused);
|
||||
expect(launch).toHaveBeenCalledTimes(1);
|
||||
expect(warn).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it.each<[string, string[], NodeJS.Platform, Error]>([
|
||||
["an unrelated failure", [], "linux", new Error("spawn ENOENT")],
|
||||
["an unsandboxed launch", ["--no-sandbox"], "linux", closedTarget],
|
||||
["macOS", [], "darwin", closedTarget],
|
||||
["Windows", [], "win32", closedTarget],
|
||||
])("does not retry %s", async (_, args, platform, error) => {
|
||||
const launch = vi.fn<(args: string[]) => Promise<string>>().mockRejectedValue(error);
|
||||
await expect(launchWithChromeSandboxFallback(args, launch, platform, {})).rejects.toBe(error);
|
||||
expect(launch).toHaveBeenCalledTimes(1);
|
||||
expect(warn).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("surfaces the retry's own failure and tries the sandbox again next time", async () => {
|
||||
const retryError = new Error("retry failed");
|
||||
const launch = vi
|
||||
.fn<(args: string[]) => Promise<string>>()
|
||||
.mockRejectedValueOnce(closedTarget)
|
||||
.mockRejectedValueOnce(retryError)
|
||||
.mockResolvedValue("browser");
|
||||
await expect(launchWithChromeSandboxFallback([], launch, "linux", {})).rejects.toBe(retryError);
|
||||
await launchWithChromeSandboxFallback([], launch, "linux", {});
|
||||
expect(launch).toHaveBeenLastCalledWith([]);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,119 @@
|
||||
import { existsSync, readFileSync } from "node:fs";
|
||||
|
||||
export const NO_SANDBOX_ARGS = ["--no-sandbox", "--disable-setuid-sandbox", "--no-zygote"];
|
||||
|
||||
const SANDBOX_START_FAILURE =
|
||||
/No usable sandbox|Running as root without --no-sandbox|Failed to move to new namespace/;
|
||||
|
||||
export interface ChromeSandboxHost {
|
||||
platform: NodeJS.Platform;
|
||||
env: NodeJS.ProcessEnv;
|
||||
uid: number | undefined;
|
||||
exists: (path: string) => boolean;
|
||||
read: (path: string) => string | undefined;
|
||||
}
|
||||
|
||||
function readTrimmed(path: string): string | undefined {
|
||||
try {
|
||||
return readFileSync(path, "utf8").trim();
|
||||
} catch {
|
||||
return undefined;
|
||||
}
|
||||
}
|
||||
|
||||
const currentHost = (): ChromeSandboxHost => ({
|
||||
platform: process.platform,
|
||||
env: process.env,
|
||||
uid: process.getuid?.(),
|
||||
exists: existsSync,
|
||||
read: readTrimmed,
|
||||
});
|
||||
|
||||
const SERVERLESS_OR_ORCHESTRATED_ENV = [
|
||||
"AWS_LAMBDA_FUNCTION_NAME",
|
||||
"AWS_EXECUTION_ENV",
|
||||
"K_SERVICE",
|
||||
"CLOUD_RUN_JOB",
|
||||
"KUBERNETES_SERVICE_HOST",
|
||||
];
|
||||
const CONTAINER_MARKERS = ["/.dockerenv", "/run/.containerenv"];
|
||||
const USERNS_BLOCKED_SYSCTLS: ReadonlyArray<readonly [string, string]> = [
|
||||
["/proc/sys/kernel/apparmor_restrict_unprivileged_userns", "1"],
|
||||
["/proc/sys/kernel/unprivileged_userns_clone", "0"],
|
||||
];
|
||||
|
||||
function linuxCannotSandbox({ env, uid, exists, read }: ChromeSandboxHost): boolean {
|
||||
return (
|
||||
uid === 0 ||
|
||||
SERVERLESS_OR_ORCHESTRATED_ENV.some((name) => !!env[name]) ||
|
||||
CONTAINER_MARKERS.some((path) => exists(path)) ||
|
||||
USERNS_BLOCKED_SYSCTLS.some(([path, blocked]) => read(path) === blocked)
|
||||
);
|
||||
}
|
||||
|
||||
/** Chrome keeps its sandbox unless the host can't give it one: root, serverless, a container, or blocked user namespaces. */
|
||||
export function chromeSandboxEnabled(host: ChromeSandboxHost = currentHost()): boolean {
|
||||
const override = host.env.HYPERFRAMES_CHROME_SANDBOX;
|
||||
if (override === "0" || override === "1") return override === "1";
|
||||
return host.platform !== "linux" || !linuxCannotSandbox(host);
|
||||
}
|
||||
|
||||
export function chromeSandboxArgs(sandbox = chromeSandboxEnabled()): string[] {
|
||||
return sandbox ? [] : NO_SANDBOX_ARGS;
|
||||
}
|
||||
|
||||
function withoutChromeSandbox(args: readonly string[]): string[] {
|
||||
return [...args.filter((arg) => !NO_SANDBOX_ARGS.includes(arg)), ...NO_SANDBOX_ARGS];
|
||||
}
|
||||
|
||||
let sandboxRefused = false;
|
||||
let closedTargetRetries = 0;
|
||||
let warned = false;
|
||||
|
||||
export function _resetChromeSandboxFallbackForTests(): void {
|
||||
sandboxRefused = false;
|
||||
closedTargetRetries = 0;
|
||||
warned = false;
|
||||
}
|
||||
|
||||
function chromeNamedSandboxFailure(error: unknown): boolean {
|
||||
return error instanceof Error && SANDBOX_START_FAILURE.test(error.message);
|
||||
}
|
||||
|
||||
function sandboxStartFailure(error: unknown): boolean {
|
||||
// Over a pipe, a Chrome that exits at startup surfaces only as a closed target.
|
||||
return (
|
||||
chromeNamedSandboxFailure(error) ||
|
||||
(error instanceof Error && error.name === "TargetCloseError")
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* 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
|
||||
* bare startup exit (a single one may be an unrelated kill). HYPERFRAMES_CHROME_SANDBOX=1 never retries.
|
||||
*/
|
||||
export async function launchWithChromeSandboxFallback<T>(
|
||||
args: readonly string[],
|
||||
launch: (args: string[]) => Promise<T>,
|
||||
platform: NodeJS.Platform = process.platform,
|
||||
env: NodeJS.ProcessEnv = process.env,
|
||||
): Promise<T> {
|
||||
const sandboxed = platform === "linux" && !args.includes("--no-sandbox");
|
||||
const sandboxRequired = env.HYPERFRAMES_CHROME_SANDBOX === "1";
|
||||
if (sandboxed && sandboxRefused && !sandboxRequired) return launch(withoutChromeSandbox(args));
|
||||
try {
|
||||
return await launch([...args]);
|
||||
} catch (error) {
|
||||
if (!sandboxed || sandboxRequired || !sandboxStartFailure(error)) throw error;
|
||||
const browser = await launch(withoutChromeSandbox(args));
|
||||
if (chromeNamedSandboxFailure(error) || ++closedTargetRetries >= 2) sandboxRefused = true;
|
||||
if (!warned) {
|
||||
warned = true;
|
||||
console.warn(
|
||||
"[hyperframes] Chrome could not start with its sandbox on this host (user namespaces are likely restricted), so it runs without it. Set HYPERFRAMES_CHROME_SANDBOX=0 to skip the sandboxed attempt.",
|
||||
);
|
||||
}
|
||||
return browser;
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user