Files
hyperframes/packages/engine/src/services/wslHost.ts
T
Miguel Ángel 38cfcdd56c fix(engine): renders under WSL reach the GPU on Chrome 150 and later (#5591)
* fix(engine): renders under WSL reach the GPU on Chrome 150 and later

Part of #5548.

* fix(engine): shorten the WSL browser env comment

* fix(engine): cite the Chromium bug in one line and allow the fallback test's removal

* fix(engine): drop WAYLAND_DISPLAY under WSL only when that is what reaches the GPU

* fix(engine): restore the WSL note from before the full-Chrome fallback

* test(engine): give the second worker's page load room on a busy Windows runner

* fix(engine): keep the Chromium bug comment under the line limit
2026-10-14 06:22:39 +00:00

103 lines
3.4 KiB
TypeScript

/**
* WSL host detection and what we can check about its GPU path when Chrome's
* GPU probe does not confirm a hardware GPU (heygen-com/hyperframes#5548).
*/
import { accessSync, constants, existsSync, readFileSync, statSync } from "node:fs";
import { platform, release } from "node:os";
export type RenderNodeAccess =
| { state: "missing" | "read-write" }
| { state: "denied"; group: string; userInGroup: boolean };
/** The host facts these checks read; tests pass a fake. */
export interface WslHostFacts {
platform: NodeJS.Platform;
release: string;
readProcVersion(): string;
renderNodeAccess(path: string): RenderNodeAccess;
}
function groupName(gid: number): string {
try {
const line = readFileSync("/etc/group", "utf-8")
.split("\n")
.find((entry) => entry.split(":")[2] === String(gid));
return line?.split(":")[0] || String(gid);
} catch {
return String(gid);
}
}
const realHost: WslHostFacts = {
get platform() {
return platform();
},
get release() {
return release();
},
readProcVersion: () => readFileSync("/proc/version", "utf-8"),
renderNodeAccess: (path) => {
if (!existsSync(path)) return { state: "missing" };
try {
accessSync(path, constants.R_OK | constants.W_OK);
return { state: "read-write" };
} catch {
const gid = statSync(path, { throwIfNoEntry: false })?.gid ?? -1;
return {
state: "denied",
group: groupName(gid),
userInGroup: process.getgroups?.().includes(gid) ?? false,
};
}
},
};
export function detectWsl(host: WslHostFacts = realHost): boolean {
if (host.platform !== "linux") return false;
try {
const osRelease = host.release.toLowerCase();
if (osRelease.includes("microsoft") || osRelease.includes("wsl")) return true;
const procVersion = host.readProcVersion().toLowerCase();
return procVersion.includes("microsoft") || procVersion.includes("wsl");
} catch {
return false;
}
}
const RENDER_NODE = "/dev/dri/renderD128";
const NATIVE_WINDOWS =
"render from native Windows (project copied to a Windows drive, run from PowerShell), " +
"where Chrome uses the GPU through Direct3D.";
/**
* Indented lines saying what we checked on the WSL GPU path and what to try,
* or null outside WSL. Says nothing about the render mode: callers own that.
*/
export function describeWslGpuAccess(host: WslHostFacts = realHost): string[] | null {
if (!detectWsl(host)) return null;
const access = host.renderNodeAccess(RENDER_NODE);
if (access.state === "denied" && !access.userInGroup) {
return [
` Your Linux user cannot read and write ${RENDER_NODE} and is not in its group ` +
`("${access.group}"), which can stop Mesa from reaching the GPU.`,
` Fix: run \`sudo usermod -aG ${access.group} $USER\`, then \`wsl --shutdown\` from ` +
"Windows, reopen WSL and render again.",
` Or ${NATIVE_WINDOWS}`,
];
}
if (access.state === "denied") {
return [
` Your Linux user is in the "${access.group}" group but still cannot read and write ` +
`${RENDER_NODE}; check its permissions with \`ls -l ${RENDER_NODE}\`.`,
` Or ${NATIVE_WINDOWS}`,
];
}
const seen = access.state === "missing" ? "does not exist" : "is readable and writable";
return [
` ${RENDER_NODE} ${seen}, so file permissions are not the cause.`,
` To use the GPU, ${NATIVE_WINDOWS}`,
];
}