npm - @hyperframes/aws-lambda - Versions diffs - 0.7.72 → 0.7.74 - Mend

@hyperframes/aws-lambda 0.7.72 → 0.7.74

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (17) hide show

package/dist/events.d.ts +2 -0
package/dist/events.d.ts.map +1 -1
package/dist/handler.d.ts +2 -2
package/dist/handler.d.ts.map +1 -1
package/dist/handler.js +234 -111
package/dist/handler.js.map +4 -4
package/dist/index.d.ts +1 -0
package/dist/index.d.ts.map +1 -1
package/dist/index.js +243 -119
package/dist/index.js.map +4 -4
package/dist/s3PlanV2Publisher.d.ts +26 -0
package/dist/s3PlanV2Publisher.d.ts.map +1 -0
package/dist/s3Transport.d.ts.map +1 -1
package/dist/sdk/index.js.map +2 -2
package/package.json +2 -2
package/scripts/probe-beginframe.test.ts +80 -0
package/scripts/probe-beginframe.ts +246 -51

package/scripts/probe-beginframe.ts CHANGED Viewed

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