Skip to content

Commit f69c4a0

Browse files
committed
fix(engine): distinguish probe failure from a genuinely absent GPU
A probe that could not run is no evidence about the GPU, so pointing the operator at GPU passthrough hid broken Chrome installs behind a phantom problem. Carry a cause off the probe and emit the matching remediation. Also un-exports buildUnverifiedHardwareGpuWarning (Fallow: engine test files are not audit entry points, so a test-only import would not have counted as a consumer) and covers the non-linux branch via the spy.
1 parent 6703ea7 commit f69c4a0

2 files changed

Lines changed: 114 additions & 36 deletions

File tree

‎packages/engine/src/services/browserManager.test.ts‎

Lines changed: 58 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -275,6 +275,34 @@ describe("resolveBrowserGpuMode", () => {
275275
expect(warn).not.toHaveBeenCalled();
276276
});
277277

278+
it("gives non-linux hosts the generic remediation, not the Docker one", async () => {
279+
setMockWebGlProbe({
280+
hasWebGL: true,
281+
vendor: "Google Inc. (Google)",
282+
renderer: "ANGLE (Google, Vulkan 1.3.0 (SwiftShader Device))",
283+
});
284+
const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
285+
expect(await resolveBrowserGpuMode("hardware", { platform: "darwin" })).toBe("hardware");
286+
const warning = String(warn.mock.calls[0]?.[0]);
287+
expect(warning).toContain("host exposes a GPU");
288+
expect(warning).not.toContain("--gpus all");
289+
});
290+
291+
it("does not blame the GPU when the probe itself failed to launch", async () => {
292+
// A probe that could not run is NO evidence about the GPU. Sending this
293+
// operator to `--gpus all` would hide a broken Chrome install behind a
294+
// phantom passthrough problem.
295+
_setPuppeteerForTests({
296+
launch: vi.fn().mockRejectedValue(new Error("spawn ENOENT /bad/chrome")),
297+
} as unknown as PuppeteerNode);
298+
const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
299+
expect(await resolveBrowserGpuMode("hardware", { platform: "linux" })).toBe("hardware");
300+
const warning = String(warn.mock.calls[0]?.[0]);
301+
expect(warning).toContain("GPU probe could not run");
302+
expect(warning).toContain("hyperframes doctor");
303+
expect(warning).not.toContain("--gpus all");
304+
});
305+
278306
it("falls back to 'software' when the probe browser cannot launch", async () => {
279307
// No chromePath, env unset, and (in the test env) no system Chrome to find
280308
// → puppeteer.launch will throw → caller catches → software fallback.
@@ -306,27 +334,40 @@ describe("resolveBrowserGpuMode", () => {
306334
expect(third).toBe("hardware");
307335
});
308336

309-
it("deduplicates concurrent auto-mode probes by caching the in-flight Promise", async () => {
337+
it("deduplicates concurrent probes so only one Chrome launches", async () => {
310338
// Parallel coordinator fires N workers via Promise.all — without Promise-
311339
// level caching, a `--workers 4` render against a no-GPU host would launch
312-
// 4 simultaneous probe Chromes. Verify all concurrent callers get the
313-
// exact same Promise reference (proving the probe runs once, not N times).
314-
const p1 = resolveBrowserGpuMode("auto", {
315-
chromePath: "/definitely/not/a/real/chrome/binary",
316-
browserTimeout: 2000,
317-
});
318-
const p2 = resolveBrowserGpuMode("auto", {
319-
chromePath: "/definitely/not/a/real/chrome/binary",
320-
browserTimeout: 2000,
321-
});
322-
const p3 = resolveBrowserGpuMode("auto", {
323-
chromePath: "/definitely/not/a/real/chrome/binary",
324-
browserTimeout: 2000,
340+
// 4 simultaneous probe Chromes. Assert the launch count directly rather
341+
// than Promise identity: `"auto"` and `"hardware"` now each adapt the
342+
// shared cached Promise via `.then`, so identity is no longer the
343+
// invariant — "the probe browser starts exactly once" is.
344+
const { launch } = setMockWebGlProbe({
345+
hasWebGL: true,
346+
vendor: "Google Inc. (Google)",
347+
renderer: "ANGLE (Google, Vulkan 1.3.0 (SwiftShader Device))",
325348
});
326-
expect(p1).toBe(p2);
327-
expect(p2).toBe(p3);
328-
const results = await Promise.all([p1, p2, p3]);
349+
const results = await Promise.all([
350+
resolveBrowserGpuMode("auto", { browserTimeout: 2000 }),
351+
resolveBrowserGpuMode("auto", { browserTimeout: 2000 }),
352+
resolveBrowserGpuMode("auto", { browserTimeout: 2000 }),
353+
]);
329354
expect(results).toEqual(["software", "software", "software"]);
355+
expect(launch).toHaveBeenCalledTimes(1);
356+
});
357+
358+
it("shares the one probe across mixed 'auto' and 'hardware' callers", async () => {
359+
const { launch } = setMockWebGlProbe({
360+
hasWebGL: true,
361+
vendor: "NVIDIA",
362+
renderer: "NVIDIA GeForce RTX 3070",
363+
});
364+
const results = await Promise.all([
365+
resolveBrowserGpuMode("auto"),
366+
resolveBrowserGpuMode("hardware"),
367+
resolveBrowserGpuMode("auto"),
368+
]);
369+
expect(results).toEqual(["hardware", "hardware", "hardware"]);
370+
expect(launch).toHaveBeenCalledTimes(1);
330371
});
331372

332373
it.each([

‎packages/engine/src/services/browserManager.ts‎

Lines changed: 56 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -422,18 +422,34 @@ export const _probeBeginFrameSupportForTests = probeBeginFrameSupport;
422422
export const _closeBrowserAfterFailedProbeForTests = closeBrowserAfterFailedProbe;
423423

424424
/**
425-
* Cached *in-flight or resolved* probe Promise for `resolveBrowserGpuMode("auto", ...)`.
425+
* Outcome of the one-shot WebGL probe.
426+
*
427+
* `cause` distinguishes the two ways a probe lands on `"software"`, because
428+
* they need OPPOSITE remediation:
429+
* - `"no-gpu"` — the probe ran and Chrome reported a software renderer
430+
* (SwiftShader / llvmpipe). Remediation: GPU passthrough.
431+
* - `"probe-error"` — the probe itself failed (Chrome couldn't launch, bad
432+
* executable path, sandbox denied). We have NO evidence
433+
* about the GPU either way; telling the operator to fix GPU
434+
* passthrough would send them chasing the wrong problem.
435+
*/
436+
interface GpuProbeOutcome {
437+
mode: "software" | "hardware";
438+
cause?: "no-gpu" | "probe-error";
439+
}
440+
441+
/**
442+
* Cached *in-flight or resolved* probe Promise, shared by BOTH the `"auto"`
443+
* and explicit `"hardware"` entry points of `resolveBrowserGpuMode`.
426444
*
427445
* Caching the Promise (rather than the resolved value) deduplicates concurrent
428446
* callers — the parallel coordinator runs N workers via `Promise.all`, so a
429447
* `--workers 4` render against a no-GPU host would otherwise fire 4
430448
* simultaneous probe Chromes. The first call assigns the Promise and every
431449
* other concurrent caller awaits the same one, paying the ~240 ms probe cost
432450
* exactly once per process lifetime.
433-
*
434-
* Exported for tests; production callers go through `resolveBrowserGpuMode`.
435451
*/
436-
let _autoBrowserGpuModeCache: Promise<"software" | "hardware"> | undefined;
452+
let _autoBrowserGpuModeCache: Promise<GpuProbeOutcome> | undefined;
437453

438454
/** Test-only: reset the cached probe result. */
439455
export function _resetAutoBrowserGpuModeCacheForTests(): void {
@@ -479,15 +495,15 @@ async function probeAutoBrowserGpuMode(options: {
479495
chromePath?: string;
480496
browserTimeout?: number;
481497
platform?: NodeJS.Platform;
482-
}): Promise<"software" | "hardware"> {
498+
}): Promise<GpuProbeOutcome> {
483499
const platform = options.platform ?? process.platform;
484500
const browserTimeout = options.browserTimeout ?? DEFAULT_CONFIG.browserTimeout;
485501
const executablePath = options.chromePath ?? resolveHeadlessShellPath({});
486502
const ppt = await getPuppeteerOrNull();
487503

488504
if (ppt === null) {
489505
logResolvedBrowserGpuMode("software", "puppeteer unavailable");
490-
return "software";
506+
return { mode: "software", cause: "probe-error" };
491507
}
492508

493509
try {
@@ -498,10 +514,10 @@ async function probeAutoBrowserGpuMode(options: {
498514
});
499515
const resolved = resolveWebGlProbeMode(info);
500516
logResolvedBrowserGpuMode(resolved, describeWebGlProbe(info));
501-
return resolved;
517+
return resolved === "hardware" ? { mode: "hardware" } : { mode: "software", cause: "no-gpu" };
502518
} catch (err) {
503519
logResolvedBrowserGpuMode("software", formatProbeFailure(err));
504-
return "software";
520+
return { mode: "software", cause: "probe-error" };
505521
}
506522
}
507523

@@ -542,32 +558,53 @@ export function resolveBrowserGpuMode(
542558
if (mode === "software") return Promise.resolve(mode);
543559

544560
_autoBrowserGpuModeCache ??= probeAutoBrowserGpuMode(options);
545-
if (mode === "auto") return _autoBrowserGpuModeCache;
561+
if (mode === "auto") return _autoBrowserGpuModeCache.then((probed) => probed.mode);
546562

547563
return _autoBrowserGpuModeCache.then((probed) => {
548-
// Warn once per process, not once per caller: `createCaptureSession`
564+
// Warn once per cache lifetime, not once per caller: `createCaptureSession`
549565
// resolves the mode for the probe browser AND every parallel worker, so
550566
// an un-deduplicated warning prints N+1 times and buries itself.
551-
if (probed === "software" && !_unverifiedHardwareGpuWarned) {
567+
if (probed.mode === "software" && !_unverifiedHardwareGpuWarned) {
552568
_unverifiedHardwareGpuWarned = true;
553-
console.warn(buildUnverifiedHardwareGpuWarning(options.platform ?? process.platform));
569+
console.warn(
570+
buildUnverifiedHardwareGpuWarning(options.platform ?? process.platform, probed.cause),
571+
);
554572
}
555573
return "hardware";
556574
});
557575
}
558576

559-
/** One-shot latch for the explicit-hardware-probed-to-software warning. */
577+
/**
578+
* Latch for the explicit-hardware-probed-to-software warning: fires once per
579+
* cache lifetime (re-armed by `_resetAutoBrowserGpuModeCacheForTests`).
580+
*/
560581
let _unverifiedHardwareGpuWarned = false;
561582

562583
/**
563-
* Warning text for "you asked for hardware GPU, the probe found none".
584+
* Warning text for "you asked for hardware GPU and we could not confirm it".
564585
*
565-
* Names the observable symptom (the render still completes, just on CPU) and
566-
* the platform's actual remediation, so the operator doesn't have to infer it
567-
* from Chrome's `Automatic fallback to software WebGL` warning. Exported for
568-
* tests.
586+
* Splits on `cause` because the two failure shapes need opposite remediation.
587+
* A probe that RAN and saw SwiftShader is a GPU-passthrough problem. A probe
588+
* that could not run tells us nothing about the GPU — pointing that operator
589+
* at `--gpus all` would send them chasing a phantom while their Chrome
590+
* install is the actual fault.
569591
*/
570-
export function buildUnverifiedHardwareGpuWarning(platform: NodeJS.Platform | string): string {
592+
function buildUnverifiedHardwareGpuWarning(
593+
platform: NodeJS.Platform | string,
594+
cause: GpuProbeOutcome["cause"],
595+
): string {
596+
if (cause === "probe-error") {
597+
return (
598+
"[hyperframes] browserGpuMode=hardware was requested, but the GPU probe could not run, " +
599+
"so hardware acceleration is UNVERIFIED — if Chrome falls back to software WebGL the " +
600+
"capture will run at CPU speed. Honouring the explicit request anyway.\n" +
601+
" This is a probe failure, not evidence of a missing GPU: see the " +
602+
"`browserGpuMode probe → software (probe failed ...)` line above for the underlying " +
603+
"error, which usually means Chrome could not launch (bad HYPERFRAMES_BROWSER_PATH, " +
604+
"missing shared libraries, or a denied sandbox) rather than a GPU problem.\n" +
605+
" Run `hyperframes doctor` to check the Chrome install."
606+
);
607+
}
571608
const remediation =
572609
platform === "linux"
573610
? "Inside Docker, the container needs GPU passthrough: `--gpus all` with the NVIDIA " +

0 commit comments

Comments
 (0)