feat(cli): name a caller's owner id on the browsers and warm check it starts (#7687)

A caller that runs several renders at once sets HYPERFRAMES_OWNER to a per-run id; every browser the CLI or
engine launches and the warm check server carry --hyperframes-owner=<id>, so the caller can tell one run's
leftovers from another's.
This commit is contained in:
Miguel Ángel
2026-11-14 02:42:11 +00:00
committed by GitHub
parent 49623307ce
commit 798c241e4d
7 changed files with 82 additions and 9 deletions
+3 -2
View File
@@ -13,18 +13,19 @@ import {
frameForwarder,
frameReader,
keyed,
parseWarmServerArgs,
sameProof,
warmCheckEndpoint,
type WarmRequest,
} from "./warmCheckProtocol.js";
const [idleMs = "0", ...checkArgs] = process.argv.slice(2);
const { idleMs, checkArgs } = parseWarmServerArgs(process.argv.slice(2));
const endpoint = warmCheckEndpoint();
if (!endpoint) process.exit(0);
const { address, token } = endpoint;
const startDigest = envDigest(token, process.env);
const exit = process.exit.bind(process);
const idle = setTimeout(() => exit(0), Number(idleMs));
const idle = setTimeout(() => exit(0), idleMs);
registerRootExitRequester(exit);
let listening = false;
let served: Socket | undefined;
+2 -2
View File
@@ -9,13 +9,13 @@ import { fileURLToPath } from "node:url";
import {
Frame,
HANDSHAKE_TIMEOUT_MS,
WARM_IDLE_MS,
encodeFrame,
envDigest,
frameReader,
keyed,
sameProof,
warmCheckEndpoint,
warmServerArgs,
type WarmRequest,
} from "./warmCheckProtocol.js";
@@ -136,7 +136,7 @@ export async function runWarmCheck(endpoint = warmCheckEndpoint(launchEnv)): Pro
export function startNextWarmCheck(endpoint = warmCheckEndpoint(launchEnv)): void {
if (!endpoint) return;
const args = [String(WARM_IDLE_MS), ...process.argv.slice(3)];
const args = warmServerArgs(process.argv.slice(3), launchEnv);
spawn(process.execPath, [join(distDir, "warmCheck.js"), ...args], {
cwd: process.cwd(),
env: launchEnv,
@@ -7,8 +7,10 @@ import {
envDigest,
frameForwarder,
frameReader,
parseWarmServerArgs,
warmCheckDirectory,
warmCheckEndpoint,
warmServerArgs,
} from "./warmCheckProtocol.js";
const TOKEN = "a".repeat(64);
@@ -112,3 +114,17 @@ describe("frameForwarder", () => {
expect(seen).toEqual(["one ", "two ", "thrée"]);
});
});
// fails without the fix: a caller running several renders at once could not tell whose warm check server was whose.
describe("the warm server's command line", () => {
it("names the caller's owner and hands the check its own args back", () => {
const argv = warmServerArgs(["--json", "./film"], { HYPERFRAMES_OWNER: "run-7" });
expect(argv).toContain("--hyperframes-owner=run-7");
expect(parseWarmServerArgs(argv)).toEqual({ idleMs: 300_000, checkArgs: ["--json", "./film"] });
});
it("names no owner when the caller sets none or one that is not a plain id", () => {
for (const owner of [undefined, "", "a b", "x".repeat(65)])
expect(warmServerArgs(["."], { HYPERFRAMES_OWNER: owner })).toEqual(["300000", "."]);
});
});
+14
View File
@@ -5,9 +5,23 @@ import { join } from "node:path";
import { Writable } from "node:stream";
import { fileURLToPath } from "node:url";
import { hyperframesCacheDir } from "@hyperframes/core/cache-dir";
import { hyperframesOwnerArgs, withoutHyperframesOwner } from "@hyperframes/core/browser-marker";
export const WARM_IDLE_MS = 5 * 60_000;
export const HANDSHAKE_TIMEOUT_MS = 2_000;
export const warmServerArgs = (
checkArgs: readonly string[],
source: NodeJS.ProcessEnv,
): string[] => [String(WARM_IDLE_MS), ...hyperframesOwnerArgs(source), ...checkArgs];
export function parseWarmServerArgs(argv: readonly string[]): {
idleMs: number;
checkArgs: string[];
} {
const [idleMs = "0", ...checkArgs] = withoutHyperframesOwner(argv);
return { idleMs: Number(idleMs), checkArgs };
}
const MAX_FRAME_BYTES = 64 * 1024 * 1024;
export const Frame = {
+18 -3
View File
@@ -1,10 +1,14 @@
import { describe, expect, it } from "vitest";
import { HYPERFRAMES_BROWSER_MARKER_ARG, withHyperframesBrowserMarker } from "./browserMarker.js";
import {
HYPERFRAMES_BROWSER_MARKER_ARG,
withHyperframesBrowserMarker,
withoutHyperframesOwner,
} from "./browserMarker.js";
describe("withHyperframesBrowserMarker", () => {
it("appends the marker to a copy of the args", () => {
const args = ["--no-sandbox"];
expect(withHyperframesBrowserMarker(args)).toEqual([
expect(withHyperframesBrowserMarker(args, {})).toEqual([
"--no-sandbox",
HYPERFRAMES_BROWSER_MARKER_ARG,
]);
@@ -12,8 +16,19 @@ describe("withHyperframesBrowserMarker", () => {
});
it("adds the marker once when a wrapper marks already-marked args", () => {
expect(withHyperframesBrowserMarker(withHyperframesBrowserMarker())).toEqual([
expect(withHyperframesBrowserMarker(withHyperframesBrowserMarker([], {}), {})).toEqual([
HYPERFRAMES_BROWSER_MARKER_ARG,
]);
});
// fails without the fix: a caller running several renders at once could not tell whose browser was whose.
it("names the caller's owner once, and only a plain id", () => {
const owned = { HYPERFRAMES_OWNER: "run-7" };
const args = withHyperframesBrowserMarker(withHyperframesBrowserMarker([], owned), owned);
expect(args).toEqual([HYPERFRAMES_BROWSER_MARKER_ARG, "--hyperframes-owner=run-7"]);
expect(withoutHyperframesOwner(args)).toEqual([HYPERFRAMES_BROWSER_MARKER_ARG]);
expect(
withHyperframesBrowserMarker([], { HYPERFRAMES_OWNER: "x --remote-debugging-port=9" }),
).toEqual([HYPERFRAMES_BROWSER_MARKER_ARG]);
});
});
+20 -2
View File
@@ -1,8 +1,26 @@
/** An inert Chrome switch on every browser HyperFrames launches, so orphan cleanup can tell its own from other tools'. */
export const HYPERFRAMES_BROWSER_MARKER_ARG = "--hyperframes-owned-browser";
export function withHyperframesBrowserMarker(args: readonly string[] = []): string[] {
return args.includes(HYPERFRAMES_BROWSER_MARKER_ARG)
/** Set by a caller that runs several renders at once, so each one's browsers and warm checks name it. */
export const HYPERFRAMES_OWNER_ENV = "HYPERFRAMES_OWNER";
export const HYPERFRAMES_OWNER_ARG = "--hyperframes-owner";
export function hyperframesOwnerArgs(source: NodeJS.ProcessEnv = process.env): string[] {
const owner = source[HYPERFRAMES_OWNER_ENV];
return owner && /^[\w.-]{1,64}$/.test(owner) ? [`${HYPERFRAMES_OWNER_ARG}=${owner}`] : [];
}
const isOwnerArg = (arg: string) => arg.startsWith(`${HYPERFRAMES_OWNER_ARG}=`);
export function withHyperframesBrowserMarker(
args: readonly string[] = [],
source: NodeJS.ProcessEnv = process.env,
): string[] {
const marked = args.includes(HYPERFRAMES_BROWSER_MARKER_ARG)
? [...args]
: [...args, HYPERFRAMES_BROWSER_MARKER_ARG];
return marked.some(isOwnerArg) ? marked : [...marked, ...hyperframesOwnerArgs(source)];
}
export const withoutHyperframesOwner = (args: readonly string[]): string[] =>
args.filter((arg) => !isOwnerArg(arg));
@@ -58,6 +58,15 @@ describe("every engine Chrome carries the HyperFrames marker", () => {
expect(args).toEqual(["--no-sandbox"]);
});
// fails without the fix: a caller running several renders at once could not tell whose browser was whose.
it("names the caller's owner on the capture browser", async () => {
vi.stubEnv("HYPERFRAMES_OWNER", "run-7");
const launch = fakeChrome();
const lease = await acquireBrowser([], { forceScreenshot: true });
await lease.release();
expect(launchedArgs(launch)[0]).toContain("--hyperframes-owner=run-7");
});
it.runIf(process.platform === "linux")(
"marks the screenshot relaunch after a failed beginFrame probe",
async () => {