fix(gcp): enforce effective BeginFrame capture

2026-09-24 00:08:03 +00:00 · 2026-07-27 00:02:37 +00:00
parent 44ea1fb5be
commit 05549e631b
21 changed files with 843 additions and 103 deletions
@@ -0,0 +1,80 @@
+import { describe, expect, it } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import {
+  _awaitBeforeDeadlineForTests,
+  _closeBrowserForProbeTests,
+  parseProbeArgs,
+} from "./probe-beginframe.js";
+
+describe("parseProbeArgs", () => {
+  it("defaults to the @sparticuz/chromium source", () => {
+    expect(parseProbeArgs([])).toEqual({});
+  });
+
+  it("accepts a standalone executable path", () => {
+    expect(parseProbeArgs(["--executable-path", "/opt/chrome/chrome-headless-shell"])).toEqual({
+      executablePath: "/opt/chrome/chrome-headless-shell",
+    });
+  });
+
+  it("accepts the equals form and resolves relative paths", () => {
+    expect(parseProbeArgs(["--executable-path=./chrome"])).toEqual({
+      executablePath: resolve("./chrome"),
+    });
+  });
+
+  it("loads exact production launch arguments from JSON", () => {
+    const dir = mkdtempSync(join(tmpdir(), "hf-probe-args-"));
+    const argsPath = join(dir, "args.json");
+    writeFileSync(argsPath, JSON.stringify(["--enable-begin-frame-control", "--no-sandbox"]));
+    try {
+      expect(parseProbeArgs(["--launch-args-json", argsPath])).toEqual({
+        launchArgs: ["--enable-begin-frame-control", "--no-sandbox"],
+      });
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("rejects missing values and unknown arguments", () => {
+    expect(() => parseProbeArgs(["--executable-path"])).toThrow(
+      "--executable-path requires a path",
+    );
+    expect(() => parseProbeArgs(["--source", "chrome"])).toThrow("Unknown argument: --source");
+    expect(() => parseProbeArgs(["--launch-args-json"])).toThrow(
+      "--launch-args-json requires a path",
+    );
+  });
+
+  it("bounds a CDP operation that never resolves", async () => {
+    const never = new Promise<never>(() => {});
+    await expect(
+      _awaitBeforeDeadlineForTests(never, Date.now() + 25, "screenshot beginFrame"),
+    ).rejects.toThrow("timeout during screenshot beginFrame");
+  });
+
+  it("force-kills and disconnects when graceful cleanup never resolves", async () => {
+    let killedWith: NodeJS.Signals | number | undefined;
+    let disconnected = false;
+    await _closeBrowserForProbeTests(
+      {
+        close: () => new Promise<never>(() => {}),
+        process: () => ({
+          kill: (signal) => {
+            killedWith = signal;
+            return true;
+          },
+        }),
+        disconnect: async () => {
+          disconnected = true;
+        },
+      },
+      25,
+    );
+
+    expect(killedWith).toBe("SIGKILL");
+    expect(disconnected).toBe(true);
+  });
+});
@@ -1,14 +1,13 @@
 #!/usr/bin/env tsx
+// fallow-ignore-file code-duplication
 /**
- * BeginFrame regression guard for `@sparticuz/chromium`.
+ * BeginFrame regression guard for a Chromium executable.
 *
- * The load-bearing assumption of `@hyperframes/aws-lambda` is that the
- * Chromium build shipped by `@sparticuz/chromium` honours CDP
- * `HeadlessExperimental.beginFrame` with `screenshot: true`. This script
- * boots that Chromium build (decompressing into `/tmp` per the library's
- * runtime contract), navigates to a tiny static page, issues one
- * `beginFrame` with a screenshot request, and asserts the response
- * carries a PNG buffer.
+ * With no arguments, this boots the build shipped by `@sparticuz/chromium`
+ * (decompressing into `/tmp` per the library's runtime contract). Passing
+ * `--executable-path /path/to/chrome-headless-shell` probes an arbitrary
+ * executable instead; the GCP image build uses that form against the exact
+ * binary copied into the image.
 *
 * The script is the contract test, not a one-shot verification — every
 * release should run it inside the Docker container at
@@ -17,15 +16,18 @@
 *
 * Exits 0 on pass, 1 on fail. Run via:
 *
- *   bun run --cwd packages/aws-lambda probe:beginframe          # host
- *   bun run --cwd packages/aws-lambda probe:beginframe:docker   # Lambda-like
+ *   bun run --cwd packages/aws-lambda probe:beginframe
+ *   bun run --cwd packages/aws-lambda probe:beginframe -- \
+ *     --executable-path /opt/chrome/chrome-headless-shell
+ *   bun run --cwd packages/aws-lambda probe:beginframe:docker
 */

-import { mkdtempSync, promises as fs } from "node:fs";
+import { mkdtempSync, promises as fs, readFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";

-interface ProbeResult {
+export interface ProbeResult {
  passed: boolean;
  durationMs: number;
  chromiumPath: string;
@@ -38,10 +40,140 @@ const PROBE_HTML = `<!doctype html>
 <html><head><meta charset="utf-8"><title>hf-beginframe-probe</title>
 <style>html,body{margin:0;background:#173;color:#fff;font:48px/1 sans-serif;display:flex;align-items:center;justify-content:center;height:100vh}</style>
 </head><body><div id="x">hf-beginframe-probe</div></body></html>`;
+const SCREENSHOT_ATTEMPTS = 10;
+const PROBE_OPERATION_TIMEOUT_MS = 5000;
+const PROBE_CLEANUP_TIMEOUT_MS = 250;
+
+export interface ProbeOptions {
+  executablePath?: string;
+  /** Exact launch arguments to probe instead of the standalone default profile. */
+  launchArgs?: string[];
+  /** Test override for the renderer/CDP operation deadline. */
+  timeoutMs?: number;
+}
+
+// The CLI accepts paired and equals forms for two independent path options.
+// fallow-ignore-next-line complexity
+export function parseProbeArgs(args: string[]): ProbeOptions {
+  let executablePath: string | undefined;
+  let launchArgs: string[] | undefined;
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--executable-path") {
+      const value = args[i + 1];
+      if (!value || value.startsWith("--")) {
+        throw new Error("--executable-path requires a path");
+      }
+      executablePath = resolve(value);
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith("--executable-path=")) {
+      const value = arg.slice("--executable-path=".length);
+      if (!value) throw new Error("--executable-path requires a path");
+      executablePath = resolve(value);
+      continue;
+    }
+    if (arg === "--launch-args-json") {
+      const value = args[i + 1];
+      if (!value || value.startsWith("--")) {
+        throw new Error("--launch-args-json requires a path");
+      }
+      launchArgs = readLaunchArgs(value);
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith("--launch-args-json=")) {
+      const value = arg.slice("--launch-args-json=".length);
+      if (!value) throw new Error("--launch-args-json requires a path");
+      launchArgs = readLaunchArgs(value);
+      continue;
+    }
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+  return {
+    ...(executablePath ? { executablePath } : {}),
+    ...(launchArgs ? { launchArgs } : {}),
+  };
+}
+
+function readLaunchArgs(path: string): string[] {
+  const resolved = resolve(path);
+  const value: unknown = JSON.parse(readFileSync(resolved, "utf-8"));
+  if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
+    throw new Error(`--launch-args-json must contain a JSON string array: ${resolved}`);
+  }
+  return value;
+}
+
+async function awaitBeforeDeadline<T>(
+  operation: Promise<T>,
+  deadline: number,
+  label: string,
+): Promise<T> {
+  const remainingMs = deadline - Date.now();
+  if (remainingMs <= 0) throw new Error(`BeginFrame probe timeout before ${label}`);
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      operation,
+      new Promise<never>((_, reject) => {
+        timeout = setTimeout(
+          () => reject(new Error(`BeginFrame probe timeout during ${label}`)),
+          remainingMs,
+        );
+      }),
+    ]);
+  } finally {
+    if (timeout) clearTimeout(timeout);
+  }
+}
+
+/** Test-only export for the standalone probe's bounded-operation contract. */
+export const _awaitBeforeDeadlineForTests = awaitBeforeDeadline;
+
+interface ProbeBrowserCleanup {
+  close(): Promise<void>;
+  disconnect(): Promise<void>;
+  process(): { kill(signal?: NodeJS.Signals | number): boolean } | null;
+}
+
+async function settleWithin(operation: Promise<unknown>, timeoutMs: number): Promise<boolean> {
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      operation.then(
+        () => true,
+        () => false,
+      ),
+      new Promise<false>((resolveTimeout) => {
+        timeout = setTimeout(() => resolveTimeout(false), timeoutMs);
+      }),
+    ]);
+  } finally {
+    if (timeout) clearTimeout(timeout);
+  }
+}
+
+async function closeBrowserForProbe(
+  browser: ProbeBrowserCleanup,
+  timeoutMs = PROBE_CLEANUP_TIMEOUT_MS,
+): Promise<void> {
+  if (await settleWithin(browser.close(), timeoutMs)) return;
+  try {
+    browser.process()?.kill("SIGKILL");
+  } catch {
+    // Best effort; disconnect below still releases Puppeteer's transport.
+  }
+  await settleWithin(browser.disconnect(), timeoutMs);
+}
+
+/** Test-only export for bounded standalone-probe cleanup. */
+export const _closeBrowserForProbeTests = closeBrowserForProbe;

 async function main(): Promise<void> {
  const start = Date.now();
-  const result = await probe();
+  const result = await probe(parseProbeArgs(process.argv.slice(2)));
  result.durationMs = Date.now() - start;
  console.log(JSON.stringify(result, null, 2));
  if (!result.passed) {
@@ -49,12 +181,21 @@ async function main(): Promise<void> {
  }
 }

-async function probe(): Promise<ProbeResult> {
+// This intentionally linear contract owns launch, renderer setup, CDP
+// validation, diagnostics, and cleanup in one fail-closed lifecycle.
+// fallow-ignore-next-line complexity
+export async function probe(options: ProbeOptions = {}): Promise<ProbeResult> {
  let chromiumPath = "";
+  let tmpHtmlDir = "";
  try {
-    const { default: chromium } = await import("@sparticuz/chromium");
-    chromiumPath = await chromium.executablePath();
-    const args = chromium.args;
+    let sourceArgs: string[] = [];
+    if (options.executablePath) {
+      chromiumPath = options.executablePath;
+    } else {
+      const { default: chromium } = await import("@sparticuz/chromium");
+      chromiumPath = await chromium.executablePath();
+      sourceArgs = chromium.args;
+    }

    const puppeteer = await import("puppeteer-core");

@@ -63,7 +204,7 @@ async function probe(): Promise<ProbeResult> {
    // Chrome-side issue. `mkdtempSync` (vs `tmpdir() + Date.now()`) gives
    // an unguessable directory name so two concurrent probes on the same
    // host don't collide and CodeQL's insecure-tempfile rule clears.
-    const tmpHtmlDir = mkdtempSync(join(tmpdir(), "hf-beginframe-"));
+    tmpHtmlDir = mkdtempSync(join(tmpdir(), "hf-beginframe-"));
    const htmlPath = join(tmpHtmlDir, "probe.html");
    await fs.writeFile(htmlPath, PROBE_HTML, "utf-8");

@@ -75,6 +216,11 @@ async function probe(): Promise<ProbeResult> {
    // ("Chrome's beginFrame with `screenshot` param always reports
    // hasDamage=true").
    const beginFrameFlags = [
+      "--no-sandbox",
+      "--disable-setuid-sandbox",
+      "--disable-dev-shm-usage",
+      "--enable-webgl",
+      "--ignore-gpu-blocklist",
      "--deterministic-mode",
      "--enable-begin-frame-control",
      "--disable-new-content-rendering-timeout",
@@ -89,55 +235,97 @@ async function probe(): Promise<ProbeResult> {
      "--use-gl=angle",
      "--use-angle=swiftshader",
      "--enable-unsafe-swiftshader",
+      // Distributed Linux rendering explicitly uses software compositing to
+      // avoid stale transformed layers in SwiftShader (see browserManager).
+      "--disable-gpu-compositing",
    ];

    const browser = await puppeteer.launch({
      executablePath: chromiumPath,
      headless: "shell",
-      args: [...args, ...beginFrameFlags],
+      args: options.launchArgs ?? [...sourceArgs, ...beginFrameFlags],
      defaultViewport: { width: 800, height: 600 },
    });
    try {
-      const page = await browser.newPage();
-      await page.goto(`file://${htmlPath}`, { waitUntil: "domcontentloaded", timeout: 30_000 });
-      const session = await page.createCDPSession();
-      await session.send("HeadlessExperimental.enable");
+      const timeoutMs = options.timeoutMs ?? PROBE_OPERATION_TIMEOUT_MS;
+      const deadline = Date.now() + timeoutMs;
+      const page = await awaitBeforeDeadline(browser.newPage(), deadline, "newPage");
+      await awaitBeforeDeadline(
+        page.goto(`file://${htmlPath}`, { waitUntil: "domcontentloaded", timeout: timeoutMs }),
+        deadline,
+        "navigation",
+      );
+      const session = await awaitBeforeDeadline(
+        page.createCDPSession(),
+        deadline,
+        "CDP session creation",
+      );
+      await awaitBeforeDeadline(
+        session.send("HeadlessExperimental.enable"),
+        deadline,
+        "HeadlessExperimental.enable",
+      );
      // Warm-up beginFrame with noDisplayUpdates: true — drives the
      // compositor without producing a screenshot, matching how the engine
      // primes a capture loop.
-      await session.send("HeadlessExperimental.beginFrame", {
-        frameTimeTicks: 0,
-        interval: 33,
-        noDisplayUpdates: true,
-      });
-      const response = await session.send("HeadlessExperimental.beginFrame", {
-        frameTimeTicks: 1000,
-        interval: 33,
-        screenshot: { format: "png" },
-      });
-      await fs.rm(tmpHtmlDir, { recursive: true, force: true }).catch(() => {});
-      const screenshot = response.screenshotData ?? "";
-      const bytes = screenshot ? Buffer.from(screenshot, "base64") : Buffer.alloc(0);
-      const isPng =
-        bytes.length >= 8 &&
-        bytes[0] === 0x89 &&
-        bytes[1] === 0x50 &&
-        bytes[2] === 0x4e &&
-        bytes[3] === 0x47;
+      await awaitBeforeDeadline(
+        session.send("HeadlessExperimental.beginFrame", {
+          frameTimeTicks: 0,
+          interval: 33,
+          noDisplayUpdates: true,
+        }),
+        deadline,
+        "warm-up beginFrame",
+      );
+      let hasDamage = false;
+      let bytes = Buffer.alloc(0);
+      let isPng = false;
+      let attempts = 0;
+      // A renderer-ready document can still need more than one controlled
+      // frame before it submits a screenshot surface. Chromium explicitly
+      // permits screenshotData to be absent during renderer initialization,
+      // so retry a small bounded sequence with monotonically increasing ticks.
+      for (attempts = 1; attempts <= SCREENSHOT_ATTEMPTS; attempts += 1) {
+        const response = await awaitBeforeDeadline(
+          session.send("HeadlessExperimental.beginFrame", {
+            frameTimeTicks: 1000 + (attempts - 1) * 33,
+            interval: 33,
+            screenshot: { format: "png" },
+          }),
+          deadline,
+          `screenshot beginFrame attempt ${attempts}`,
+        );
+        hasDamage = response.hasDamage;
+        const screenshot = response.screenshotData ?? "";
+        bytes = screenshot ? Buffer.from(screenshot, "base64") : Buffer.alloc(0);
+        isPng =
+          bytes.length >= 8 &&
+          bytes[0] === 0x89 &&
+          bytes[1] === 0x50 &&
+          bytes[2] === 0x4e &&
+          bytes[3] === 0x47;
+        if (isPng) break;
+        await awaitBeforeDeadline(
+          new Promise((resolveDelay) => setTimeout(resolveDelay, 10)),
+          deadline,
+          `screenshot retry delay ${attempts}`,
+        );
+      }
      return {
        passed: isPng && bytes.length > 0,
        durationMs: 0,
        chromiumPath,
        screenshotBytes: bytes.length,
-        hasDamage: response.hasDamage,
+        hasDamage,
        detail: isPng
-          ? "OK — BeginFrame returned a PNG buffer."
-          : `FAIL — BeginFrame returned ${bytes.length} bytes, PNG signature ${
+          ? `OK — BeginFrame returned a PNG buffer after ${attempts} attempt(s).`
+          : `FAIL — BeginFrame returned ${bytes.length} bytes after ${SCREENSHOT_ATTEMPTS} ` +
+            `attempts, PNG signature ${
              bytes.length >= 4 ? bytes.subarray(0, 4).toString("hex") : "<empty>"
            }`,
      };
    } finally {
-      await browser.close().catch(() => {});
+      await closeBrowserForProbe(browser);
    }
  } catch (err) {
    return {
@@ -148,10 +336,17 @@ async function probe(): Promise<ProbeResult> {
      hasDamage: false,
      detail: `FAIL — ${err instanceof Error ? err.message : String(err)}`,
    };
+  } finally {
+    if (tmpHtmlDir) {
+      await fs.rm(tmpHtmlDir, { recursive: true, force: true }).catch(() => {});
+    }
  }
 }

-void main().catch((err) => {
-  console.error("[probe-beginframe] unexpected:", err);
-  process.exit(2);
-});
+const invokedPath = process.argv[1] ? resolve(process.argv[1]) : "";
+if (invokedPath === fileURLToPath(import.meta.url)) {
+  void main().catch((err) => {
+    console.error("[probe-beginframe] unexpected:", err);
+    process.exit(2);
+  });
+}