Skip to content

fix(aws-lambda): chrome-headless-shell 158 in the arm64 video image, sparticuz 153 in the x86 ZIP - #8155

Merged
jrusso1020 merged 3 commits into
mainfrom
hf/lambda-chrome-headless-shell-158
Nov 18, 2026
Merged

jrusso1020 merged 3 commits into
mainfrom
hf/lambda-chrome-headless-shell-158

Conversation

@jrusso1020

@jrusso1020 jrusso1020 commented Nov 18, 2026 •

Copy link
Copy Markdown
Collaborator

What

The arm64 Lambda video image now runs Chrome for Testing's chrome-headless-shell 158.0.8127.36, pinned by sha256. The x86 handler ZIP stays on @sparticuz/chromium, bumped from 148 to 153. This PR also fixes the two bugs that kept --source=chrome-headless-shell from working, and moves the release workflow's arm64 image build onto an ARM runner.

Why

The rest of the repo pins chrome-headless-shell 158 (#8145), but the Lambda functions were still on Chromium 148 from @sparticuz/chromium.

The shell can't go in the x86 ZIP. Its folder is about 296 MB, which is over Lambda's 262,144,000-byte unzipped limit, and xz or brotli compression still leaves it 4 to 7 MB over. So the x86 ZIP takes sparticuz's newest release, 153, which builds at 258,502,222 bytes unzipped. The arm64 video function is a container image, which has no such limit, so it gets the real 158 shell.

Related work

Follows #8145.

How

  • arm64 image (packages/aws-lambda/image/Dockerfile): the image installs the linux-arm64 shell folder with curl -f and checks its sha256. The Lambda Node 22 base has none of the shell's shared libraries and no fonts, so the video stage installs them with microdnf at a pinned Amazon Linux release. The image sets HYPERFRAMES_LAMBDA_CHROME_SOURCE and HYPERFRAMES_LAMBDA_CHROME_PATH itself. The nested video function no longer passes ChromeSource, which would override them. stage-arm64-image.ts stops fetching the sparticuz arm64 pack.
  • x86 ZIP: @sparticuz/chromium 153.0.0 in bun.lock and the runtime lock. The audio and warm actions also launch Chrome on this function, so they stay on sparticuz too.
  • Fix: build-zip --source=chrome-headless-shell. It staged only the executable, which exits at launch with "Invalid file descriptor to ICU data". It now stages the whole shell folder.
  • Fix: HYPERFRAMES_LAMBDA_CHROME_PATH. src/chromium.ts requires it for the shell source, but nothing set it. The SAM template and the CDK stack now set it to the bundled shell when ChromeSource asks for the shell.
  • Release workflow (.github/workflows/publish.yml): pack built the arm64 image on ubuntu-latest without emulation, which worked only while the video stage just copied files. The new microdnf step runs arm64 code, so a new lambda-video-image job builds the image natively on ubuntu-24.04-arm. Pack downloads the OCI tarball, checks its sha256 against that job's output, and pins it as before.
  • Docs, README and the CLI deploy message now name the new Chrome versions. The unused @types/aws-lambda devDependency is gone; the dead-code audit flags it whenever this manifest changes.

Test plan

  • Unit tests added/updated: build-zip (whole shell folder staged), stage-arm64-image, the CDK stack snapshot (CHROME_PATH set only for the shell source), CLI deploy, and publish-workflow (the image builds on ARM, and pack pins only the digest that job built). The new publish test fails against the old workflow.
  • @hyperframes/aws-lambda: 277 pass. The 2 image/fetch.test.ts failures are local only: this machine's curl lacks --retry-all-errors, and this PR doesn't touch that file.
  • CLI src/commands/lambda: 105 pass. scripts/publish-workflow, publish-main-only-workflows and release-lambda-assets: 48 pass.
  • The x86 sparticuz 153 ZIP builds at 258,502,222 bytes unzipped.
  • Lambda arm64 image CI builds and smoke-runs the arm64 image on ARM. Its smoke handler reports HeadlessChrome/158.0.8127.36, ffmpeg 7.0.2, arch: arm64 and a non-empty screenshot.
  • A real arm64 deploy and render in us-east-2, then teardown:
    • hyperframes lambda deploy --video-arch arm64 with the CI-built image. The video function is an arm64 container image with no function-level Chrome variables, so the image's own shell settings apply. The render function is the x86_64 ZIP. The warm-up after deploy succeeded.
    • lambda render of producer/tests/distributed/mp4-h264-sdr (640x360, 30 fps, 15-frame chunks): SUCCEEDED, 60/60 frames in 4 beginframe chunks, an h264 MP4 with 60 frames.
    • lambda destroy, then the retained render bucket and the video log group by hand. Afterwards no stack, IAM role, ECR repository, bucket, function, state machine or log group from the run was left.
  • Documentation updated
  • Comments follow CONTRIBUTING.md "Comments"

🤖 Generated with Claude Code

jrusso1020 and others added 2 commits November 18, 2026 08:06
The arm64 video image now installs Chrome for Testing's linux-arm64 chrome-headless-shell
158.0.8127.36, pinned by sha256 and fetched with curl -f, as the whole shell folder. The Lambda
Node 22 base has none of the shared libraries the shell links and no fonts, so the image installs
them from the base's repository at the same pinned release. The image sets
HYPERFRAMES_LAMBDA_CHROME_SOURCE and HYPERFRAMES_LAMBDA_CHROME_PATH itself, and the nested video
function no longer passes ChromeSource, which would override them. stage-arm64-image.ts stops
fetching the sparticuz arm64 pack and drops the ZIP's x86 sparticuz Chrome instead.

The x86 handler ZIP stays on @sparticuz/chromium, bumped from 148.0.0 to 153.0.0. It builds at
258,502,222 bytes unzipped, under Lambda's 262,144,000-byte limit and the 248 MiB in-house gate.

Two fixes for --source=chrome-headless-shell:
- build-zip.ts staged only the executable, which exits at launch without its ICU data and .pak
  files. It now stages the whole shell folder at chrome-headless-shell-linux64/.
- Nothing set HYPERFRAMES_LAMBDA_CHROME_PATH, which src/chromium.ts requires for that source.
  The SAM template and the CDK stack now set it to the bundled shell when ChromeSource asks for it.

Drops the unused @types/aws-lambda devDependency, which the dead-code audit reports whenever this
package's manifest changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The video stage now installs Chrome's system libraries with microdnf, so it runs code for arm64.
The pack job built that image on ubuntu-latest with no emulation, which it could do only while the
stage copied files. A new lambda-video-image job builds it natively on ubuntu-24.04-arm, from the
handler zip whose sha256 the zip job reported, and reports the OCI tarball's sha256. Pack downloads
that tarball, checks the sha256 against the job's, and pins it as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mintlify

mintlify Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated
hyperframes 🟢 Ready View Preview Nov 18, 2026, 8:42 AM

💡 Tip: Enable Automations to automatically generate PRs for you.

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Edit accuracy: accurate 271 (base branch 271), smooth 63 of those

The gate passes.
Smoothness is reported in the artifact, not gated. A case fails only if it fails 2 of 3 runs.

Quarantined, measured but not gated (0)

Unstable (1)

  • seqplainkeys-none-center-r0-nested-z100: error / tracking 0.06, pressJump 0, drop 0, reload 0, render 0.03, renderKey -, undo true, teleport true / tracking 0.06, pressJump 0, drop 0, reload 0, render 0.03, renderKey -, undo true, teleport true

chromium.ts loses the two doc lines on BUNDLED_SHELL_DIR and BUNDLED_SHELL_PATH; the names and the
SAM template's comment already say what they are.

@hyperframes/aws-lambda's unpacked budget goes from 290,508 to 298,000 bytes. The package unpacks to
295,324 bytes, up from the shared chrome-headless-shell staging module the ZIP and image scripts now
import and from the README and docs that describe the two Chrome sources.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@miguel-heygen miguel-heygen left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Summary. The arm64 video image moves to chrome-headless-shell 158, built natively on ubuntu-24.04-arm. The x86 ZIP stays on @sparticuz/chromium, bumped to 153. build-zip --source=chrome-headless-shell now stages the whole shell folder.

Strengths

  • Every download on the release path is pinned and checked before unpacking:
    • the arm64 shell zip by version and SHA-256 (image/Dockerfile:45-53; sha256sum -c runs before unzip), and then the --version check;
    • the base image by digest (Dockerfile:4);
    • microdnf packages through --releasever=2023.12.20260914;
    • x86 Chromium through the lockfile;
    • fetch.sh checks the SHA-256 or git commit before tar (Rule 7 holds).
  • The image is built and checked by digest: lambda-video-image exports its OCI SHA-256, and pack refuses any other (publish.yml:269-330). The arm runner is GitHub's standard one, free for a public repo.
  • CI runs the image on ARM, not only builds it (lambda-arm64-image.yml:105-140).
  • No account ids, internal hosts or secrets in the diff.

Important

  1. scripts/_chromeHeadlessShell.ts:30 stages the newest Chrome in the Puppeteer cache, with no version or checksum check. A host that has 159 cached ships 159, even though the error text tells you to install 158. Check the version against 158.0.8127.36 and the folder's checksum. The PR body also says the folder (about 296 MB) can't fit a ZIP, so the SAM and CDK ChromeSource=chrome-headless-shell option it now wires up builds a ZIP that can never deploy. It should refuse up front, or its docs should say it's image-only.
  2. Headroom: the sparticuz 153 ZIP is 258,502,222 bytes against a 260,046,848-byte gate (build-zip.ts:81), so about 1.5 MB is left. Any dependency growth will fail the build at release time. Note the margin, or add a test that pins it.
  3. No proof that renders match before and after. The smoke only checks that a 64 px green square screenshots to more than 0 bytes (smoke-video.mjs:17-24), so it renders no text. The arm64 image installs only liberation-fonts, while sparticuz brings its own font set. CJK or emoji text could therefore render as boxes on arm64 while x86 looks fine. A frame compare of a mixed-script fixture, arm64 against x86, would settle it.

Verdict: approve, with items 1 to 3 as follow-ups.
Reasoning: the release path is pinned and verified end to end and runs on real ARM. The gaps are the unpinned fallback route, a thin size margin and no text-render comparison; none ships an unverified binary.

@jrusso1020
jrusso1020 added this pull request to the merge queue Nov 18, 2026
Merged via the queue into main with commit 81d73d2 Nov 18, 2026
144 checks passed
@jrusso1020
jrusso1020 deleted the hf/lambda-chrome-headless-shell-158 branch November 18, 2026 09:51

This branch was successfully deployed

1 active deployment
staging - docs — 3baaf5c3 Deployed Nov 18, 2026 by mintlify[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants