@hyperframes/aws-lambda 0.7.73 → 0.7.74

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/aws-lambda",
-  "version": "0.7.73",
+  "version": "0.7.74",
   "description": "AWS Lambda adapter for HyperFrames distributed rendering — handler, client-side SDK, and CDK construct.",
   "repository": {
     "type": "git",
@@ -45,7 +45,7 @@
     "ffprobe-static": "^3.1.0",
     "puppeteer-core": "^25.2.1",
     "tar": "^7.4.3",
-    "@hyperframes/producer": "^0.7.73"
+    "@hyperframes/producer": "^0.7.74"
   },
   "devDependencies": {
     "@types/aws-lambda": "^8.10.146",

package/scripts/probe-beginframe.test.ts

@@ -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);
+  });
+});

package/scripts/probe-beginframe.ts

@@ -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);
+  });
+}